Why Rocky splits agents and skills
Agents are the short front door. Skills are deep reference loaded only when needed. That split keeps a disciplined Rocky session around 4-6k handbook tokens instead of dumping the whole corpus.
This is about how the Rocky handbook is built, not whether MCP saves tokens on your app repo. For that, see the value report.
Source: why-agents-and-skills-are-split.md.
The idea in one sentence
Agents are the short front door. Skills are the deep reference you load only when the task needs templates or long checklists.
How agents are built
Handbook agents come from two sources:
- Devkit-native playbooks: discovery (
codebase-discovery), quality gate (pr-quality-gate), graphify onboarding, stack-specific implementers (nextjs-developer,node-api-developer, ...). - ai-driven playbooks: hexagonal implementers and test writers (
react-hexagonal,nestjs-hexagonal,fastapi-hexagonal,vitest-writer, ...), aligned with the ai-driven agent set.
Every agent shares the same skeleton:
| Section | Purpose |
|---|---|
| Frontmatter | name, description, optional skills: ... |
| Local project graph | graphify plus optional Understand Anything (same policy everywhere) |
| Do / Don't | What to enforce on this task |
| Deep reference | Pointer to skill(s) or sibling agents |
| When invoked | Short checklist |
Agents are registered as MCP resources (devkit://handbook/agents/...) and listed via devkit then list_handbook.
Why we split agents and skills
| If everything lived in the agent file | What happens |
|---|---|
| Long templates (Vitest, Jest, Playwright, hexagonal checklists) | Every invoke loads thousands of tokens before the model reads your code |
Duplicate agents (vitest-writer + test-writer-react) | Two front doors, drift, wasted context |
| Prompt dumps all handbook URIs | Model treats the index as a reading list |
| With agent + skill split | What happens |
|---|---|
| Agent about 40-60 lines | Role, discovery, routing. Fits in one glance. |
Skill SKILL.md | Examples and checklists load only when needed |
One React test agent (vitest-writer) + vitest-react skill | Single entry point for Vitest/RTL |
Rule of thumb: about 1,244 lines across 24 agents on disk. A disciplined session reads about 4k-6k tokens of handbook, not the whole corpus.
Skill layer (depth)
Skills hold implementation depth that does not belong in every turn: react-hexagonal, vitest-react, jest-nestjs, pytest-hexagonal, playwright-e2e, nextjs-app-router, node-api-layered, and more.
Frontmatter skills: foo tells the host the skill exists. It is not automatically pasted into context unless the workflow attaches it.
Prompts and routing
devkit-start-task uses a router table (task area to agent + rules) and a cap: read at most 2-3 handbook resources. It does not embed all 37 rule/agent URIs.
devkit-review-code points to exactly three resources: code-reviewer, human-readable-code, tests.
Where things live
| Path | Role |
|---|---|
src/mcp/agents/ | Short MCP handbook agents |
src/mcp/skills/ | Deep skills (Cursor + devkit) |
src/mcp/rules/ | Team rules (.mdc) |