skill-authoringlisted

# skill-authoring A skill is a folder: `SKILL.md` plus optional `scripts/`, `references/`, `assets/`. Agents load metadata always, body on match, files and scripts only when needed. Write for that loading order. ## Frontmatter contract ```yaml --- name: kebab-case-name # ≤64, matches folder, [a-z0-9-] description: What it does. Use when ... Trigger phrases. Differentiator vs sibling skills. # ≤1024 license: Apache-2.0 metadata: author: ... --- ``` - Quote the description if it contains `: ` so strict YAML parsers do not see a nested map. - Avoid `<` `>` in frontmatter; they can leak into prompts. - Invalid YAML often fails silently (skill never loads). ## Description is the router The model sees only name + description before deciding to open the file. | Include | Avoid | |---|---| | What the skill does | Step-by-step “how” (model will follow the short version and skip the body) | | When to use (triggers, file types, user phrasings) | Empty praise (“helps with projects”) | | Differentiator from a sibling skill | Competing skills’ full menus | Pattern: `X via Y. Use for [situations]. [When not / other skill instead if needed].` If it does not trigger: fix description first (95% of the time). If it triggers wrong: narrow or add negatives. Fix the body only when explicit invocation produces wrong work. ## Progressive disclosure layout ```text my-skill/ SKILL.md # workflow, checklists, pointers references/*.md # deep detail, one level deep