How do I give an agent a new capability?
A capability extension is a named skill or behavior that can be attached to one or more agents. Capabilities let you build a library of reusable reasoning patterns — code review checklists, domain-specific knowledge, communication styles — and apply them selectively without rewriting system prompts.
When would I use a capability?
Use a capability when you want to give an agent a well-defined, reusable skill that goes beyond its base behavior. Good candidates:
- Code review — a checklist of patterns to flag: security issues, naming conventions, missing tests
- Domain knowledge — a body of facts or rules the agent should apply in a specific domain
- Reasoning style — instruct the agent to think step-by-step, cite sources, or assume a specific persona
- Output formatting — require structured output like JSON, a specific table format, or a standardized report shape
- Safety rules — constraints that should apply to a specific agent or context
Capabilities are additive — they augment an agent’s behavior. They are not for replacing an agent’s identity (use the agent’s system.md for that) or for scheduling work (use a job extension).
How do I create one by chatting?
Tell Daemion which agent you want to extend and what skill to add:
You: Give the opus agent a code-review capability
Daemion: I’ll create a code-review capability and attach it to the opus agent.
Done — the opus agent now applies a code review checklist when reviewing code: security vulnerabilities, type safety, missing tests, naming consistency, and performance concerns. Want to customize the checklist?
You: Add a check for missing error handling
Daemion: Added — the opus agent now also flags functions that don’t handle error cases.
The capability is stored in SQLite and linked to the agent immediately. No restart needed.
How do I create one via the API?
The API is the programmatic path — for scripts or agents creating capabilities at runtime. Chat is the primary path for humans.
curl -X POST http://localhost:3001/extensions
-H “Authorization: Bearer $DAEMION_TOKEN”
-H “Content-Type: application/json”
-d ’{
“type”: “capability”,
“name”: “code-review”,
“description”: “Applies a structured code review checklist to any code the agent examines.”,
“definition”: {
“applies_to”: [“opus”],
“instruction”: “When reviewing code, always check for: (1) security vulnerabilities including injection and auth issues, (2) missing or incorrect type annotations, (3) functions without error handling, (4) missing tests for public functions, (5) naming inconsistencies. Report each finding with severity: critical, warning, or suggestion.”,
“triggers_on”: [“code_review_request”, “code_paste”]
},
“source”: “user”,
“enabled”: true
}’
The gateway validates the envelope against ExtensionSchema and stores the record. The definition field is open (GenericDefinitionSchema) — structure it to describe which agents the capability applies to and what instruction or knowledge it injects.
What does the capability schema look like?
Capability extensions use the generic definition schema. The top-level envelope (shared across all 12 extension types):
interface Extension { id: string; // e.g. “ext_09def789” — assigned by gateway on creation type: “capability”; name: string; // unique per type, kebab-case, 1-100 chars description: string; // human-readable, max 500 chars definition: Record<string, unknown>; // capability-specific config source: “built-in” | “user” | “agent” | “community”; enabled: boolean; created_at: string; // ISO 8601 updated_at: string; // ISO 8601 }
A typical definition for a capability:
// Example definition shape — adapt to your capability interface CapabilityDefinition { applies_to?: string[]; // agent names this capability is active for; omit for all agents instruction: string; // the behavior, rule, or knowledge to inject triggers_on?: string[]; // optional: context signals that activate this capability priority?: number; // optional: ordering when multiple capabilities apply (higher = first) [key: string]: unknown; }
Frequently asked questions
system.md) defines its core identity — who it is and how it behaves by default. A capability is additive and composable — it layers a specific skill on top of the base identity, and can be shared across multiple agents or toggled on/off without touching the system prompt.applies_to, or omit the field entirely to apply the capability to all agents. This is useful for cross-cutting concerns like output formatting rules or safety constraints./extensions with source: "agent". Agent-created capabilities start disabled — the user enables them. This lets Daemion propose new skills as it discovers gaps during a conversation.applies_to matches the current agent are injected as additional instructions.PATCH /extensions/:id to update fields or DELETE /extensions/:id to remove it. See the Extensions API for the full reference.What can go wrong
400 {"error": "validation failed"} — The envelope failed ExtensionSchema validation. Check that type is exactly "capability", name is 1-100 characters, and description is under 500 characters.
401 {"error": "unauthorized"} — The Authorization header is missing or the bearer token doesn’t match. The token is in ~/.daemion/.gateway-token. Use $DAEMION_TOKEN in your shell.
403 {"error": "cannot disable essential extensions"} — Essential built-in extensions cannot be disabled. Create a new capability with source: "user" to customize behavior.
403 {"error": "cannot delete essential extensions"} — Essential extensions cannot be deleted.
What’s next?
- How do I create an agent extension? — define a full agent identity with a system prompt
- How do I create a control extension? — system-wide configuration that applies globally
- Extensions API — full CRUD reference