Skill files are not meant to be a static prompt. Think of it more as writing a program that is a deterministic loader specification for what should be in context, when, and at what cost.
Skills Runtime
Goal: protect the context window by deferring content until the exact moment it is needed.
The Metadata
YAML file that is always loaded for routing.
Description that tells agent when to trigger and not how to do the task.
Cost ~100 tokens
Recipe (skill)
Procedural instructions and loaded on trigger.
- Focus less on deep reference data.
- Assume that the AI is intelligent and only include context that it doesn't have.
- Avoid excessive "don't" warnings or architecture over-exploration. Pair every don't with a do
- Focus on "what", not "why" in architecture descriptions.
- Consider including procedural workflows, decision tables, and real codebase examples.
Recommended ceiling: 500 lines.
Binder and Mixer (references and scripts)
Executable code and deep docs. Loaded strictly on demand.
Never put YAML frontmatter on reference file (/references/*.md).
Unlimited size
Agent Abstraction Layers
Goal: Finding a sematic layer where agents already reason best can save massive amounts of context and unlocks creative potential.
Bundle executable code instead of explaining a clumsy workflow. Give the agent a script
Don't hardcode workspace paths, let the agent to discover the environment (e.g. find the package.json)