Skill authoring best practices
This article outlines best practices for creating effective Skills that Claude can discover and utilize successfully. It guides users on how to author these skills to ensure optimal functionality and integration within the Claude ecosystem.
Curator note
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 tokensRecipe (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)