| name | skill-name |
| description | Use when <the situation, in the words a user would actually use>. Covers <scope>. Trigger on "<phrasing>", "<phrasing>". Do not use for <adjacent case> — see the <other> skill. |
| metadata | {"category":"<one of the 17 category directories>","version":"1.0.0","tags":["three","to","six","tags"]} |
Skill Name
Purpose
What this makes possible, and — more usefully — what failure it prevents. Two or three sentences. Do not paraphrase the title.
When to Use
Concrete situations, phrased as a user would describe them. Not "when performing database optimization" but "a query is slow and you do not know why".
- Situation one.
- Situation two.
- Situation three.
Capabilities
What the skill actually covers. A short list. This is scope, not marketing.
- Capability one.
- Capability two.
Inputs
What the skill needs in order to be useful. Be specific: "the actual execution plan, not a guess about it".
Outputs
What the user gets. Concrete artifacts, not "improved code quality".
Workflow
Numbered steps, in the order they must happen. The order is usually the most important thing in the skill — measure before optimizing, reproduce before fixing, validate before trusting.
- Step name — What to do, and why this step comes first.
- Step name — What to do.
- Step name — What to do.
Best Practices
Rules, with consequences. Not preferences. Each line must earn its place — if it could appear in any skill, cut it.
- A rule stated as a rule, with the reason it matters.
- The specific way people get this wrong, named.
- A default that is safe, and why the alternative is not.
Examples
Real, runnable code, or a worked case. Show the failure alongside the fix — the wrong version teaches more than the right one alone. Never a toy example, never an elided ... where the difficult part should be.
What the mistake looks like:
// The wrong version, with a comment naming exactly what is wrong.
What to do instead:
// The right version. It should be obvious why it is better.
Notes
The non-obvious. Version caveats. The trap that catches everyone. The thing a competent practitioner would not already know.
If this section is generic, the skill is probably not worth including — an author who cannot name a surprising detail usually has not worked with the subject long enough to write about it.
- A version-specific caveat.
- A trap, and why it is so common.
- A pointer to the adjacent skill, where the boundary is genuinely fuzzy.
