nimadorostkar 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".
- Input one.
- Input two.
Outputs
What the user gets. Concrete artifacts, not "improved code quality".
- Output one.
- Output two.
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.