skill-authoring

1# Skill Authoring Guide
2 
3You are authoring a SKILL.md for an AI coding agent. A well-written skill provides clear, actionable guidance that agents can follow consistently.
4 
5## Core Principle
6 
7**A skill's description triggers it; the body teaches it.**
8 
9The description tells the agent WHEN to use the skill. The content tells the agent HOW to execute it.
10 
11## Skill Anatomy
12 
13### SKILL.md Structure
14 
15```markdown
16---
17name: [lowercase-hyphenated-name]
18description: [Concrete actions + "Use when..." clause]
19version: [Semantic version]
20triggers:
21  - [keyword 1]
22  - [keyword 2]
23tags:
24  - [tag 1]
25---
26 
27# [Skill Title]
28 
29[Introduction paragraph explaining purpose]
30 
31## Core Principle
32 
33**[Single most important rule in bold]**
34 
35## [Main Content Sections]
36 
37## [Decision Points]
38 
39## [Verification Checklist]
40```
41 
42### Frontmatter Fields
43 
44| Field | Required | Constraints |
45|-------|----------|-------------|
46| name | Yes | Lowercase alphanumeric + hyphens, 1–64 chars |
47| description | Yes | Must include "Use when..." clause; 1–1024 chars |
48| version | Yes | Semantic version (e.g. `1.0.0`) |
49| triggers | Recommended | Natural-language phrases that activate the skill |
50| tags | Recommended | Categorization tags |
51 
52## Writing Effective Triggers
53 
54Triggers should be phrases users naturally type.
55 
56**Good triggers:**
57- "write tests first"
58- "tdd"
59- "test driven development"
60 
61**Bad triggers:**
62- "testing methodology" (too vague)
63- "red-green-refactor-cycle-for-test-driven-development" (too specific)
64…