Agent Capabilities Design
Agent Capabilities Design Date: 2026 04 27 Status: Draft Scope: How skills and plugins are defined, stored, and allocated to agents in the RedKey platform Problem Agents currently receive two things at runtime: a persona (inline text) and an MCP config (a file picked by naming convention). There is no structured concept of what an agent can do beyond its ide...
Date: 2026-04-27 Status: Draft Scope: How skills and plugins are defined, stored, and allocated to agents in the RedKey platform
---
Agents currently receive two things at runtime: a persona (inline text) and an MCP config (a file picked by naming convention). There is no structured concept of what an agent *can do* beyond its identity text. Skills don't exist. Plugin assignment is implicit — mcp-engine.json exists because someone created it manually; there's no declaration in the agent definition that engine uses engine-tools.
This becomes a problem as the agent roster grows and capabilities multiply. Which agents can post to HCS? Which can browse the web? Which have access to git tooling? Today you have to read the MCP file and the persona string to find out. There's no single place to declare it.
---
- Every discrete skill (how to do something) lives as a versioned markdown file
- Every plugin (a tool that calls something external) has an explicit config
- Each agent definition declares exactly which skills and plugins it gets
- The runner loads the right content at startup with no manual MCP file management
---
Three distinct layers. Each has a different form, ownership model, and runtime role.
| Layer | What it is | Form | Runtime role | |---|---|---|---| | Skill | Instructions for HOW to do something | Markdown file | Injected into system prompt after persona | | Plugin | Executable tool that calls something external | MCP server + config | Passed to Claude as MCP server | | Agent | Autonomous actor with identity and role | Definition JSON + persona | The entity that loads skills and calls plugins |
An agent loads skills to know *how* to do work. It calls plugins to *actually* do it. Skills are context. Plugins are capability.
---
``
capabilities/
skills/
<name>.md # plain markdown, injected into system prompt
plugins/
<name>/
config.json # MCP server config stub
``
Plugin config.json points to existing JS server files in agents/shared/mcp/. The JS does not move as part of this design — that is a separate concern.
Example plugin config (capabilities/plugins/hedera-tools/config.json):
``json
{
"server": "hedera-tools",
"command": "node",
"args": ["agents/shared/mcp/hedera-tools.js"]
}
``
The server field becomes the key in the assembled mcpServers object. Runner produces: { "mcpServers": { "hedera-tools": { "command": "node", "args": [...] } } }.
---
Two new optional arrays added to each agent definition JSON:
``json
{
"slug": "quinn",
"name": "Quinn",
"department": "dev",
"model": "claude-sonnet-4-6",
"schedule_seconds": 120,
"roles": ["developer"],
"skills": ["git-workflow", "spec-reading"],
"plugins": ["hedera-tools"],
"persona": "..."
}
``
skills— names resolving tocapabilities/skills/<name>.mdplugins— names resolving tocapabilities/plugins/<name>/config.json- Both are optional. An agent with neither behaves exactly as today.
- Declaration is explicit per agent. No role-based defaults, no bundles, no inheritance. If Quinn and Arlo share the same skills, they both list them. Abstraction comes later if repetition warrants it.
---
At agent startup the runner does, in order:
1. Read skills and plugins arrays from agent_definitions in Supabase
2. For each skill: read capabilities/skills/<name>.md, append to system prompt after persona under a ## Skills section header
3. For each plugin: read capabilities/plugins/<name>/config.json, assemble into a single mcpServers object, write to a temp file, pass to Claude
Skills are additive — they extend what the agent knows, they don't replace identity. Plugin assembly replaces the current mcp-{agent_id}.json file convention.
---
| What | Source of truth | Runtime read |
|---|---|---|
| Skill/plugin names per agent | Definition JSON → synced to Supabase agent_definitions | Supabase (same as roles, persona) |
| Skill content | capabilities/skills/<name>.md | File, at startup |
| Plugin config | capabilities/plugins/<name>/config.json | File, at startup |
Supabase holds arrays of names. File content is never synced to Supabase.
---
| Current | Replaced by |
|---|---|
| agents/shared/mcp.json (default) | Explicit plugins array in each definition |
| agents/shared/mcp-engine.json | "plugins": ["engine-tools"] in engine.json |
| agents/shared/mcp-atlas.json | "plugins": ["atlas-tools"] in atlas.json |
| _mcp_config_path() naming convention in runner | Plugin assembly loop reading from capabilities/ |
Old mcp-*.json files are deleted after migration is complete.
---
- Moving MCP JS server files to
capabilities/plugins/— file co-location is a separate cleanup - Role-based capability defaults or bundle grouping — premature until repetition patterns are clear
- Capability discovery or marketplace indexing — future concern, not runtime allocation
- Skill versioning or conflict resolution — not needed yet