skill-authoring

# Skill Authoring Guide You are authoring a SKILL.md for an AI coding agent. A well-written skill provides clear, actionable guidance that agents can follow consistently. ## Core Principle **A skill's description triggers it; the body teaches it.** The description tells the agent WHEN to use the skill. The content tells the agent HOW to execute it. ## Skill Anatomy ### SKILL.md Structure ```markdown --- name: [lowercase-hyphenated-name] description: [Concrete actions + "Use when..." clause] version: [Semantic version] triggers: - [keyword 1] - [keyword 2] tags: - [tag 1] --- # [Skill Title] [Introduction paragraph explaining purpose] ## Core Principle **[Single most important rule in bold]** ## [Main Content Sections] ## [Decision Points] ## [Verification Checklist] ``` ### Frontmatter Fields | Field | Required | Constraints | |-------|----------|-------------| | name | Yes | Lowercase alphanumeric + hyphens, 1–64 chars | | description | Yes | Must include "Use when..." clause; 1–1024 chars | | version | Yes | Semantic version (e.g. `1.0.0`) | | triggers | Recommended | Natural-language phrases that activate the skill | | tags | Recommended | Categorization tags | ## Writing Effective Triggers Triggers should be phrases users naturally type. **Good triggers:** - "write tests first" - "tdd" - "test driven development" **Bad triggers:** - "testing methodology" (too vague) - "red-green-refactor-cycle-for-test-driven-development" (too specific) - "skill-...