Vol. V · The Harness · V.2
Skills and Progressive Disclosure
A skill is a folder with a SKILL.md. Metadata always sits in context; the body loads on trigger; scripts and references load on demand. This is how you scale expertise without flooding the window.
8 min read
Doctrine
- name + description must say what it does and when to use it. Under-triggering is the default failure.
- Keep SKILL.md under ~500 lines. Push depth to references/ and deterministic work to scripts/.
- Write in imperative form. Explain why. Do not staple ALWAYS/NEVER to every line.
The three layers
Anthropic's skill-creator and public skills repo define the loading system. Layer 1: frontmatter in the system prompt (~100 words each). Layer 2: body when the description matches. Layer 3: bundled files when the body points at them. Addy Osmani's agent-skills and the context-engineering pack show what 'production-grade' content looks like at layers 2–3.
Skills as the encyclopedia format
This encyclopedia is itself a skill body: the atlas is layer 1 (what exists), the article is layer 2 (when to apply it), the repo READMEs are layer 3 (load on demand). Agents should not ingest forty READMEs up front. They should load Canon, then open one volume.
Anti-patterns
- A 4,000-line SKILL.md that is always loaded.
- Descriptions that only name the skill ('use for frontend') without trigger contexts.
- Skills that duplicate each other so the model picks none.