| name | m-create-skill |
| description | Author a new Claude Code skill — folder + SKILL.md + frontmatter, lean 50–120 lines, grounded in the host project's real files and conventions, integrated with sibling skills. Triggers: create skill, new skill, add skill, write skill, skill for, author skill, scaffold skill. |
Create Skill
TL;DR — Idea (1) → classify (2) → folder + frontmatter (3) → draft phases (4) → ground against THIS project + review (5).
Skills auto-load from .claude/skills/<name>/SKILL.md (project) or ~/.claude/skills/<name>/SKILL.md (global). No registration step.
Phase 1 — Expand the idea
State the skill's purpose in one sentence:
<name>: <verb> <topic> — <what it produces>.
If the idea overlaps an existing skill, stop — extend that skill rather than fragmenting. Before writing, list the skills already installed (project + global) and check for overlap.
Phase 2 — Classify
| Type | Shape |
|---|
| Orchestrator | multi-phase, plan-first, routes to other skills |
| Audit | sweep + report with severity buckets |
| Pattern guide | how to use one pattern correctly, with a code example |
| Workflow | tool-driven procedure (git, build, deploy) |
Phase 3 — Folder + frontmatter
mkdir -p .claude/skills/<name>
SKILL.md opens with:
---
name: <name>
description: "<one-line purpose>. Triggers: kw1, kw2, kw3."
---
# <Title>
> **TL;DR** — <one sentence>.
…
name MUST match the folder name.description ends with a Triggers: list — 5–15 lowercase, comma-separated keywords/phrases users actually type.- Decide scope: a global skill must be framework-agnostic (it loads in every project); a project skill may hardcode that project's stack.
Phase 4 — Draft
Outline by type:
Orchestrator: Plan → Place → Implement → Verify → Finalize → Never
Audit: Sweep → Findings buckets → Report shape → Never
Pattern: When to use → Pattern (code) → Edge cases → Never
Use tables to compress constraints. Keep code examples in the project's actual language. Cite real file paths (or clearly-illustrative placeholders for a global skill).
Phase 5 — Ground & review
Before saving, walk through:
- Ground to the host project. Read its
CLAUDE.md / conventions / manifest. Every cited path exists or follows its conventions; every example uses tools the project actually allows; no example recommends something the project bans.
- For a global skill: strip all project-specific names/paths; use neutral placeholders so it's safe in any repo.
- Does it end with a
## Never list (3–6 bullets)?
- Length 50–120 lines? If over, trim — skills are reference cards.
Then audit the draft with /m-review-skill.
Pitfalls
| Pitfall | Fix |
|---|
| Trigger list too narrow | Add synonyms users actually type |
| Trigger list too broad | Skill fires on unrelated work; tighten |
| Global skill hardcodes one project's stack | Genericize or scope it to that project |
| Duplicates an existing skill | Defer to it; add only what's new |
| No routing to a sibling skill | Add a handoff line |
Never
- Register a skill anywhere — the
SKILL.md file is sufficient.
- Ship a global skill that names one project's packages, paths, or stack.
- Recommend, in any example, a tool the host project bans.
- Skip the
## Never list.
- Exceed 120 lines without a strong reason — trim first.
- Copy another skill verbatim — reference it instead.
