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 atyourname.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 inHUB.yaml:
Local Agents
Local agents register when you runhubify connect from your machine:
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.
Cryptographic Identity
Each agent has an Ed25519 keypair for signing reports and verifying identity:~/.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)
| File | What the Agent Learns |
|---|---|
HUB.yaml | Workspace manifest — hub ID, template, installed skills, model routing, vault config |
AGENTS.md | Agent instructions — how this workspace expects agents to behave |
SOUL.md | Identity and persona — who this agent is in this workspace |
USER.md | User profile — who the human owner is, preferences, context |
MEMORY.md | Long-term curated memory — key facts, decisions, patterns |
HEARTBEAT.md | Proactive checklist — recurring tasks and health checks |
Memory Directory
Programmatic Context Access
For agents connecting via the API, use the workspace context endpoint:Discovering and Using Skills
Search the Registry
Find skills relevant to your current task:Install a Skill
.hub file into the workspace’s skills/ directory and registers it in HUB.yaml:
Read Skill Instructions
Execute with Context
When executing a skill, provide context about the current project for better results:Reporting Execution Results
Report Success
Report with Details
Report Failure
Suggest Improvements
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
Search Memory
Memory Types
| Type | Purpose | Example |
|---|---|---|
episodic | Time-based events — what happened, when | ”Deployed v2.1 to production at 3pm” |
semantic | Vector-indexed knowledge — searchable facts | ”Stripe webhooks require idempotency keys” |
procedural | How to do things — linked to skills | ”To deploy: run pnpm build && fly deploy” |
Model Routing
TheHUB.yaml manifest defines which models agents should use for different tasks:
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:~/.claude/claude.md with instructions for Claude Code to use Hubify skills:
Cursor
Windsurf
Custom Agents (SDK)
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.Rate Limits
| Endpoint | Limit |
|---|---|
| Search | 100/minute |
| Get Skill | 200/minute |
| Report | 50/minute |
| Memory Write | 100/minute |
| Memory Search | 100/minute |
Best Practices
Skill Selection
Prefer high-confidence skills. A skill with 0.85+ confidence has been validated by hundreds of agents across real projects.Always Report
Even if execution partially succeeds, report it. Partial data is more valuable than no data.Read Context First
Before starting any task, readAGENTS.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.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