Map / Outline
Skills
Instruction files loaded on demand, so routing knowledge costs nothing until it is needed.
What it is and why it exists
What
A skill is a Markdown file with a one-line description and a body of instructions for one class of task. The harness matches a request to at most one skill and injects the body into the prompt.
Why
A base prompt that holds every rule is expensive on every turn and gets ignored. Skills keep the base short and load detail only when relevant. They also carry routing: which tool to use for which question.
How it works
- Each file has frontmatter with a description, then the body.
- Matching started as keyword overlap with the description and later added routing exemplars: real requests each skill should handle, plus a list that should match none.
- Only one skill is loaded per request. Most requests match none.
- The same files are linked into the coding agent's skills folder, so one edit changes both surfaces.
- A separate gold set scores routing. When a request is misrouted, an exemplar is added.
Where it sits in the build order
Needs first
- Harness engineeringA skill is text injected during prompt composition. Without the composition step there is nowhere to load it.Build out of order Stub it with: Paste the skill body into the system prompt by hand.
Unlocks
- Multi-agent patternsRoles are defined by scoped instructions. Skills are the mechanism for scoping them.
In the reference build
| Path | Role |
|---|---|
| apps/agent-server/skills/loader.py | Parse, match, and return at most one skill. |
| apps/agent-server/skills/routing.json | Routing exemplars per skill. |
| apps/agent-server/skills/*.md | The skills. |
| .claude/skills/ | Links to the same files for the coding agent. |
The same idea on other platforms
| Platform | How this module maps |
|---|---|
| Databricks | No native skill format. Store skill files in a volume and load them in your agent code, or register prompts in the prompt registry. |
| IBM watsonx | Agent instructions and per-agent guidelines play this role. Narrow agents as collaborators are the platform's way to scope instructions. |
| Codex | Skills are supported as folders with a SKILL.md. The reference skill bodies can be moved with small edits. |
| Cursor | Rules files scoped by path or description, plus skills. The description line does the same matching job. |
| Claude Code / Agent SDK | Native. A folder per skill with a SKILL.md whose description decides when it loads. |
| Another machine | Markdown files and a 100-line loader. Fully portable. |
Explain it back
Answer aloud first. Then open the answer and compare.
Why at most one skill per request?
A strong answerA skill is a narrow instruction set. Stacking several dilutes each and raises prompt cost on every turn.
What is the difference between a skill and a tool?
A strong answerA tool does something and returns data. A skill tells the model how to approach a class of task, including which tools to use and in what order.
From the live build
Recent changes and files the sync job filed under this module.
- Search returns one copy of a paragraph that is in several files; same@10 and distinct@10 in the retrieval eval; dated scheduler log; notice when a no-query draft is replaced; skill: a status is half an answer
- Guard: on a spending turn a draft sourced from a web search alone is rejected and sent to the spending tools; skill says the same
- Stream eval in the weekly cycle and the report; spending skill: a follow-up means another query; tests keep out of the production guard log; wiki watcher drops queued triggers; tuner skips manual-only sources
- Answer guard: dollar figures must come from tool results (both answer paths); follow-ups inherit the skill; multi-turn chat eval
- Skills: route by natural-language examples only (descriptions as fallback)
- Skills: '_none' margin for embedding routing; default chosen by the eval
- Skills: embedding routing, up to two skills per request, routing eval
- Runbook — making the Claude Code CLI smart about the agency
- Merged into spending-investigation.md on 2026-08-15.
- BUILD-HOST — Cognitive Architecture & Self-Evolving Learning Loop
- 08 — Extending the Harness Agent
- Step 3: skills router (AGENT_SERVER_GUIDE_v2.md §4). Each file in this directory is a plain Markdown skill: a `---`-delimited frontmatter block with a one-line `description:`, then the skill body below the closing `---`.
- does the router load the right skills? (2026-09-30) Gold: evals/skills/gold_v1.json, 58 hand-labelled requests (15 FINANCE, 15 spending, 12 K12, 4 that need two skills, 12 that need none).