Skill Creator

Skill Creator

Helps author skills that live in skills/<name>/SKILL.md in this repo, so they work correctly across Claude Code, Codex, Cursor, and any other Agent Skills-compatible client.

When to use this

• The user says "make this a skill", "turn this into a skill", "create a skill for X".
• The user asks you to review, clean up, or fix an existing SKILL.md.
• You're scaffolding this repo's own tooling-adjacent skills.

Instructions

1. Clarify the task the skill captures. Ask (or infer from context): what triggers this skill, and what should the agent actually do once activated? A skill should cover one coherent capability — split unrelated workflows into separate skills.

2. Pick the name. Lowercase, hyphenated, 1–64 chars, no leading/trailing/double hyphens (e.g. pdf-processing, not PDF-Processing or -pdf). The folder name under skills/ must match frontmatter.name exactly.

3. Scaffold it. Run:

   npm run new <skill-name>
   

   This copies templates/skill-template/SKILL.md into skills/<skill-name>/ with the name pre-filled.

4. Write the description first — it matters most. Agents only see name and description at startup (progressive disclosure, stage 1). A vague description means the skill never activates. State both what it does and when to use it, with concrete keywords a real task would mention.

   • Weak: Helps with PDFs.
   • Strong: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.

5. Write the body for an agent, not a human reader. Step-by-step instructions, concrete examples, and edge cases. Keep it under ~500 lines / ~5000 tokens — this whole file is loaded into context once the skill activates (progressive disclosure, stage 2). See references/skill-spec.md for the full frontmatter rules.

6. Push detail out of SKILL.md. Anything long, occasionally-needed, or reference-y (API details, exhaustive option lists, background reading) goes in references/, and is loaded only if the agent follows a link there (stage 3). Executable helpers go in scripts/; templates or static files go in assets/. Keep file references one level deep from SKILL.md — don't chain references to references.

7. Validate.

   npm run validate
   

   Fixes anything it flags: name/folder mismatch, missing/oversized description, oversized body, dangling file references.

8. Self-review against the checklist in references/checklist.md before calling the skill done.

9. Update the README table:

   npm run sync-readme
   

Reviewing an existing skill

Read the target SKILL.md, then walk it against references/checklist.md and references/skill-spec.md. Report concrete fixes (not just "looks fine") — e.g. "the description doesn't say when to use this skill" or "this 800-line body should move its API reference into references/".

Reference files

• references/skill-spec.md — condensed Agent Skills frontmatter/layout spec.
• references/checklist.md — pre-flight checklist for a finished skill.