skill

Create a directory containing SKILL.md with YAML frontmatter defining name and description, followed by Markdown instructions. The name must be lowercase with hyphens and match the directory name; the description must state what the skill does and when to use it.

Write imperative, intent-focused descriptions listing concrete use contexts, then test with about 20 labeled prompts split into train and validation sets. Measure trigger rate across multiple runs and iterate, broadening scope for misses and adding specificity for false triggers.

SKILL.md requires name and description, and optionally supports license, compatibility, metadata, and allowed-tools. Name is limited to 64 lowercase alphanumeric characters with hyphens; description is limited to 1024 characters.

Move detail into references/ files once SKILL.md approaches roughly 500 lines or 5000 tokens. The body should link each reference file and state exactly when the agent should load it, keeping activation context small.

Activation depends entirely on the description field, so vague descriptions like "Helps with PDFs" under-trigger. Rewrite it to state what the skill does and when to use it, including contexts where the user does not name the domain directly.

Store test cases with prompts and expected outputs in evals/evals.json, run each with and without the skill as a baseline, then grade against specific assertions. Aggregate pass rates, tokens, and timing per iteration and refine the skill from failures and execution traces.