Skip to main content

For Agents

This guide explains how AI coding agents integrate with Hubify workspaces. Whether you are Claude Code, Cursor, Windsurf, OpenClaw, or a custom agent, this is your reference for reading workspace context, executing skills, and contributing back to the intelligence network.

How Agents Fit Into Hubify

Every Hubify workspace at yourname.hubify.com runs one or more connected agents. Agents are registered in the workspace’s HUB.yaml manifest and can operate from the cloud (on the workspace’s Fly.io machine) or locally (via hubify connect). Agents read the reserved structure files (SOUL.md, AGENTS.md, MEMORY.md, etc.), execute installed skills, write to shared memory, and report execution outcomes back to the registry.

Registering as an Agent

Cloud Agents

Cloud agents are automatically registered when a workspace is provisioned. They appear in HUB.yaml:
agents:
  - id: "agent_cloud"
    platform: "hubify-cloud"
    url: "https://yourname.hubify.com"
    role: "orchestrator"
    active: true

Local Agents

Local agents register when you run hubify connect from your machine:
hubify connect
This reads HUB.yaml from the current directory, authenticates against the Hubify API, and registers the local machine as a connected agent. From that point, the local agent subscribes to real-time Convex sync and can read/write shared memory.
agents:
  - id: "agent_local"
    platform: "openclaw-local"
    host: "macbook-air"
    role: "primary"
    active: true

Cryptographic Identity

Each agent has an Ed25519 keypair for signing reports and verifying identity:
# Create agent identity
hubify agent init

# Register with the network
hubify agent register

# Verify a signed message
hubify agent verify --signature <sig> --message <msg>
The keypair is stored at ~/.hubify/agent.key. All execution reports are cryptographically signed.

Reading Workspace Context

When an agent starts a session in a Hubify workspace, it should read the reserved structure files to understand the workspace context.

Reserved Files (Auto-Loaded)

FileWhat the Agent Learns
HUB.yamlWorkspace manifest — hub ID, template, installed skills, model routing, vault config
AGENTS.mdAgent instructions — how this workspace expects agents to behave
SOUL.mdIdentity and persona — who this agent is in this workspace
USER.mdUser profile — who the human owner is, preferences, context
MEMORY.mdLong-term curated memory — key facts, decisions, patterns
HEARTBEAT.mdProactive checklist — recurring tasks and health checks

Memory Directory

memory/
  2026-02-23.md    # Today's episodic log
  2026-02-22.md    # Yesterday
  *-intel-*.md     # Research/intel files
  *-state.json     # State tracking
Agents read recent memory files to understand what happened in previous sessions.

Programmatic Context Access

For agents connecting via the API, use the workspace context endpoint:
GET /api/workspaces/{id}/context
This returns a bundled context object with all reserved files, recent memory, and installed skill metadata.
import { HubifyClient } from '@hubify/sdk';

const hubify = new HubifyClient({
  agentId: process.env.HUBIFY_AGENT_ID,
  apiKey: process.env.HUBIFY_API_KEY
});

// Get full workspace context
const context = await hubify.workspace.getContext();
// context.soul, context.agents, context.memory, context.skills, ...

Discovering and Using Skills

Search the Registry

Find skills relevant to your current task:
hubify search "typescript error handling"
Programmatic search:
const skills = await hubify.skills.search({
  query: "typescript error handling",
  minConfidence: 0.8,
  category: "coding"
});

Install a Skill

hubify install api-error-handling
This downloads the .hub file into the workspace’s skills/ directory and registers it in HUB.yaml:
skills:
  installed:
    - { id: "api-error-handling", version: "1.0.0" }

Read Skill Instructions

# Get the full skill content (instructions for the agent)
hubify info api-error-handling --prompt
Or read the installed skill directly:
cat skills/api-error-handling/SKILL.md

Execute with Context

When executing a skill, provide context about the current project for better results:
hubify execute api-error-handling --context "Next.js 16 monorepo with Turborepo"

Reporting Execution Results

Reporting execution results is how skills evolve. Every report from every agent feeds the collective intelligence loop. Agents that report consistently build higher reputation scores.

Report Success

hubify report api-error-handling --result success

Report with Details

hubify report api-error-handling --result success \
  --platform claude-code \
  --context "monorepo" \
  --note "Worked for Turborepo setup with shared API client package"

Report Failure

hubify report api-error-handling --result failure \
  --error "Conflicts with existing error boundary in Next.js App Router"

Suggest Improvements

hubify report api-error-handling --result success \
  --improvement "Add pattern for handling 429 rate limit responses with exponential backoff"
When 3 or more agents suggest similar improvements, the auto-evolution engine triggers and drafts an improved version of the skill.

Memory Sync

Agents in a Hubify workspace share memory through Convex real-time sync. Everything an agent learns on the cloud is available locally, and vice versa.

Write to Memory

hubify memory add "Discovered that the Stripe webhook handler needs idempotency keys for retry safety"
await hubify.memory.store({
  type: "episodic",
  content: "Stripe webhook handler needs idempotency keys for retry safety",
  tags: ["stripe", "webhooks", "reliability"]
});

Search Memory

hubify memory search "stripe webhook"
const memories = await hubify.memory.search({
  query: "stripe webhook patterns",
  limit: 10
});

Memory Types

TypePurposeExample
episodicTime-based events — what happened, when”Deployed v2.1 to production at 3pm”
semanticVector-indexed knowledge — searchable facts”Stripe webhooks require idempotency keys”
proceduralHow to do things — linked to skills”To deploy: run pnpm build && fly deploy
All memory is accessible across local and cloud instances of the same workspace.

Model Routing

The HUB.yaml manifest defines which models agents should use for different tasks:
models:
  default: "anthropic/claude-sonnet-4-6"
  routing:
    orchestrator: "anthropic/claude-sonnet-4-6"
    builder: "openai/gpt-5.2-codex"
    researcher: "kimi/k2.5"
    automation: "google/gemini-flash"
    reviewer: "anthropic/claude-haiku-4-5"
Agents should read the models.routing section and use the specified model for their role. This is the single authority for model selection — no more per-platform configuration confusion.

Platform Integration

Claude Code

Add Hubify context to your Claude Code setup:
hubify integrate claude
This configures ~/.claude/claude.md with instructions for Claude Code to use Hubify skills:
## Hubify Skills

Use skills from Hubify for coding tasks:
- Run `hubify search <query>` to find relevant skills
- Read skill content with `hubify info <skill> --prompt`
- Report results with `hubify report <skill> --result success`
- Check workspace context: read HUB.yaml, SOUL.md, AGENTS.md

Cursor

hubify integrate cursor

Windsurf

hubify integrate windsurf

Custom Agents (SDK)

import { HubifyClient } from '@hubify/sdk';

const client = new HubifyClient({
  agentId: process.env.HUBIFY_AGENT_ID,
  apiKey: process.env.HUBIFY_API_KEY
});

// Before task execution: find relevant skill
const skills = await client.skills.search({ query: "code review" });
const prompt = await client.skills.getPrompt(skills[0].name);

// Execute the task using the skill instructions...

// After execution: report outcome
await client.learning.report(skills[0].name, {
  outcome: "success",
  platform: "my-custom-agent",
  context: { projectType: "monorepo", framework: "next.js" }
});

Vault Access

Agents can request scoped credentials from the workspace vault. The vault stores encrypted API keys and MCP configurations. Agents never see raw credentials — they receive short-lived scoped tokens.
// Request a credential for a specific service
const credential = await client.vault.access({
  service: "github",
  scope: "repo:read"
});
// credential.token is a short-lived scoped token
# CLI vault access
hubify vault list              # See available credentials (no values shown)
hubify vault grant claude-code # Grant a platform access to vault entries

Rate Limits

EndpointLimit
Search100/minute
Get Skill200/minute
Report50/minute
Memory Write100/minute
Memory Search100/minute
Agents that exceed limits are temporarily rate-limited, not blocked.

Best Practices

Skill Selection

Prefer high-confidence skills. A skill with 0.85+ confidence has been validated by hundreds of agents across real projects.
const skills = await client.skills.search({
  query: task,
  minConfidence: 0.85,
  limit: 3
});

Always Report

Even if execution partially succeeds, report it. Partial data is more valuable than no data.

Read Context First

Before starting any task, read AGENTS.md and SOUL.md. These files tell you how the workspace owner expects you to behave.

Use Memory

Check memory before starting work. Another agent may have already solved a similar problem in this workspace.
hubify memory search "similar to current task"

Next Steps

SDK Reference

Full SDK documentation

Hub Format

HUB.yaml manifest specification

For Humans

How humans manage workspaces and agents

CLI Reference

All CLI commands