Skills Checklist

Copy this into your PR or ticket. Each block maps to a step in the step-by-step guide.

1. Define

• Problem statement written (who, what, what good looks like)
• 3–5 real example requests collected
• Baseline run without the skill; outputs saved
• Gaps list written (what the agent got wrong)

2. Mechanism

• Walked the decision tree; a skill is the lightest mechanism that works
• Not duplicating an existing skill, rule, or MCP server

3. Name & description

• name is lowercase / digits / hyphens, ≤64 chars, descriptive, no claude / anthropic
• description is third person, ≤1024 chars, no XML tags
• Description says what it does and when to use it
• Description includes the trigger words users actually type
• Invocation decided: automatic, or disable-model-invocation: true

4. Location

• Location matches the audience (personal / project / plugin / Claude.ai)
• Folder name exactly equals name
• Not inside ~/.cursor/skills-cursor/

5. Scaffold

• Created from a template
• YAML frontmatter parses
• Host lists the skill (/ menu or settings)

6. Body

• Starts with a Quick start / Workflow section
• Contains only what the model wouldn’t know
• Multi-step work includes a copyable progress checklist
• Degree of freedom matches fragility
• Consistent terminology throughout
• No time-sensitive statements
• Under 500 lines

7. Resources

• Detailed material lives in references/, templates in assets/
• Every resource is linked directly from SKILL.md with a when to read cue
• References are one level deep
• Reference files over ~100 lines have a table of contents

8. Scripts (if any)

• Each script handles errors and prints actionable messages
• SKILL.md gives the exact command and says run or read
• Dependencies documented
• Forward-slash, relative paths only
• Validation loop in place (run → fix → re-run)
• Scripts reviewed for safety (no unexpected network or destructive actions)

9. Test

• npm run qa (static checks) passes
• All should-trigger prompts load the skill (fresh chat each)
• No near-miss prompt loads it
• /skill-name works
• Outputs meet the rubric and beat the baseline
• Tested on every supported host (Claude Code / Cursor / Claude.ai)
• Tested with the models users actually use
• Eval set saved alongside the skill

10. Iterate

• Observed at least one real session
• Fixes made against specific observed failures
• Eval set re-run after changes; no regressions

11. Ship

• No secrets or machine-specific paths
• Version and changelog recorded
• Owner assigned
• Announcement or README with 2–3 example prompts
• A colleague installed it and triggered it successfully
• Decision logged in your project’s decision log (for example DECISIONS.md)