create-skill

name	create-skill
description	Scaffold or review agent skills with best-practice frontmatter, progressive disclosure, token-aware structure, optional multi-mode support, and the agent-skills.git symlink + inventory wiring. Walks through requirements, picks single-file vs multi-file layout, generates `SKILL.md` plus optional `rules/`, `references/`, and `templates/`, then runs a quality checklist. Modes: `scaffold` (default — new skill), `review` (audit existing skill), `upgrade` (split a single-file skill into multi-file). Triggers on "create a skill", "scaffold a skill", "make a new skill", "new SKILL.md", "review this skill", "audit my skill", "upgrade this skill", "split this skill", "/create-skill".
disable-model-invocation	true
license	MIT
metadata	{"author":"mthines","version":"1.0.0","workflow_type":"scaffolder-and-advisory","tags":["skill-authoring","scaffolding","meta","progressive-disclosure","token-optimization","frontmatter","best-practices"]}

Create Skill

Author new agent skills — and audit existing ones — against the best practices distilled from Anthropic's official Skill authoring guide and the patterns already in this repo. Output is a complete skill directory plus the agent-skills.git symlink wiring and inventory updates.

This SKILL.md is a thin index. Detailed authoring rules live in rules/*.md and load on demand. Worked examples live in references/*.md. Literal scaffolding templates live in templates/*.md. Reading them all up-front would burn tokens you do not need yet — load only what the current phase asks for.

---

Mode Detection

Parse $ARGUMENTS (first token) and detect the mode:

Mode	Default	Trigger
scaffold	yes	Default. "create", "scaffold", "new skill", or no mode argument.
review		"review", "audit", "check this skill", or $0 == "review".
upgrade		"upgrade", "split", "convert to multi-file", or $0 == "upgrade".

If the user typed a path or skill name as $ARGUMENTS, treat it as the target for review/upgrade; for scaffold it is the proposed skill name.

State the detected mode and target in one line before continuing. Example:

Mode: scaffold
Target: skills/<proposed-name>/

---

Scaffold Workflow (default)

A six-phase pipeline. Each phase has a gate; do not proceed until it passes.

Phase	Name	Gate
0	Requirements	User confirmed name, description, modes, structure choice
1	Structure decision	Single-file vs multi-file decided with reasoning
2	Frontmatter draft	Name + description + flags pass validation
3	File generation	All planned files written, none over budget
4	Wiring & inventories	Symlinks created (if local-dev), CLAUDE.md + README.md updated
5	Self-check	Every checklist item in rules/quality-checklist.md passes

Phase 0 — Requirements (interview)

Ask the user — in one message, batched, so they answer once:

1. Working name (kebab-case, ≤ 64 chars). What should the directory and name: field be?
2. One-line purpose — what does this skill do? Phrased as a third-person action ("Reviews X for Y", not "Helps you with X").
3. Trigger phrases — what would the user (or another agent) type to reach for this skill? Collect 3–8 phrases.
4. Invocation control — slash-only (disable-model-invocation: true), model-invokable (default), or hidden background (user-invocable: false)? See rules/invocation-control.md.
5. Modes — does the skill have one mode or several? If several, list them with a one-line description each.
6. Inputs — does the skill take $ARGUMENTS? Positional ($0, $1)? None?
7. Tools — should allowed-tools pre-approve any specific tools (e.g. Bash(git *))? Default: leave unset.
8. Scope — is this an advisory skill (read-only), an applied skill (writes code), an orchestrator (calls other skills), a slash command, or a workflow companion?

Confirm the answers back to the user verbatim before moving on. Do not guess any of these.

Phase 1 — Structure decision

Decide: single-file or multi-file? Apply this decision flow before generating anything — see rules/structure-decision.md for the full rubric.

Quick decision table:

Signal	Pick
Body fits comfortably under 200 lines	Single-file
Body would exceed 500 lines (the hard cap)	Multi-file
3+ orthogonal concerns (e.g. naming + architecture + tests)	Multi-file (one rule per concern)
Worked examples > 100 lines	Move to references/
Reusable boilerplate the skill emits literally	Move to templates/
One mode and one concern	Single-file

Output the chosen layout as a tree before writing files:

skills/<name>/
├── SKILL.md
├── rules/...
├── references/...
└── templates/...

Phase 2 — Frontmatter draft

Draft the YAML frontmatter using rules/frontmatter.md and rules/description-writing.md. Validate before writing:

• name is kebab-case, ≤ 64 chars, no reserved words (anthropic, claude).
• description is third-person, ≤ 1024 chars, includes both what and when (trigger phrases), front-loaded with the most important keywords.
• disable-model-invocation: true is set if the user picked slash-only.
• metadata.tags are populated (5–10 specific terms).

Phase 3 — File generation

Write each planned file. For each one:

• SKILL.md — start from templates/SKILL.minimal.md (single-file) or templates/SKILL.multi-file.md (index pattern). Keep body ≤ 500 lines.
• rules/<concern>.md — start from templates/rule.md. One file per concern. Keep each rule self-contained; each must be loadable in isolation.
• references/<topic>.md — start from templates/reference.md. Add a table of contents at the top if the file exceeds 100 lines (Claude partial-reads long files; the TOC is the safety net).
• templates/<artefact>.md — literal text the skill emits. No prose meta-commentary inside templates.

After each file, verify:

• Code fences declare a language identifier.
• Sentences end with full stops.
• One sentence per line (semantic line breaks) — repo prose rule.
• No backslash-style paths. No time-sensitive claims ("after August 2025").

Phase 4 — Wiring & inventories

If the user runs the local-dev symlink chain (the default for this repo), follow rules/repository-conventions.md to:

1. Create the cross-tool symlink: ln -s "$REPO/skills/<name>" "$HOME/.agents/skills/<name>".
2. Create the Claude Code symlink: ln -s "$HOME/.agents/skills/<name>" "$HOME/.claude/skills/<name>".
3. Verify both with readlink.
4. Append a row to the inventory in CLAUDE.md (under "Slash commands" or the appropriate section).
5. Append a row to the table in README.md and add the skill to the "Repository Structure" tree at the bottom of the README.

If the user is publishing the skill via npx skills add only, skip steps 1–3 but still update the inventories.

Phase 5 — Self-check

Run the full checklist in rules/quality-checklist.md. Treat any unchecked item as a defect — fix it before declaring the skill done.

Report the result inline as:

Self-check: PASS (28/28)

or, on failure:

Self-check: FAIL — fix these:
- [ ] description over 1024 chars (currently 1180)
- [ ] rules/architecture.md over 500 lines without TOC

---

Review Workflow

For review mode, do not write any files. Read the target skill (the path or skill name from $ARGUMENTS) and produce a structured report:

1. Load rules/quality-checklist.md.
2. Read the target SKILL.md. If it has rules/, references/, templates/, list each file with line count.
3. For every checklist item, mark PASS / WARN / FAIL with one line of evidence (file path + line number where applicable).
4. End with a prioritised "Top 3 fixes" list — biggest token / clarity wins first.

Do not mutate the skill in review mode.

Upgrade Workflow

For upgrade mode, take a single-file skill and split it into multi-file:

1. Read the target SKILL.md.
2. Identify orthogonal concerns (each H2 section is a candidate).
3. Propose a layout tree (rules/, references/, templates/) and show it to the user for approval before writing.
4. Move each concern into its own rule file. Replace the section in SKILL.md with a one-line pointer + link to the new file.
5. Re-run the Phase 5 self-check.

---

Required Reading by Phase

Load these on demand — do not preload them all.

Phase	Files
0	rules/description-writing.md, rules/invocation-control.md
1	rules/structure-decision.md, rules/progressive-disclosure.md
2	rules/frontmatter.md, rules/description-writing.md
3	rules/token-economics.md, rules/anti-patterns.md, plus templates in templates/
4	rules/repository-conventions.md
5	rules/quality-checklist.md

Worked examples in references/skill-archetypes.md are optional — load only when the user asks "what does an X-shaped skill look like?".

---

Core Principles

1. Concise is key. The context window is a public good. Every line in SKILL.md is a recurring token cost once loaded — write nothing Claude already knows. See rules/token-economics.md.
2. Progressive disclosure beats one big file. Three tiers: metadata (always loaded), SKILL.md (loaded on trigger), supporting files (loaded on demand). Keep references one level deep.
3. Description is the discovery surface. Third person, what + when, front-loaded with trigger keywords. The first 1024 chars decide whether Claude even loads the rest.
4. Match degrees of freedom to the task. Prescriptive scripts for fragile sequences; high-freedom prose for judgment calls. See rules/structure-decision.md.
5. One skill, one job. Resist the mega-skill. Split into companions and compose with Skill() calls.
6. Test the skill end-to-end before declaring done. Run the Phase 5 checklist; if you can, dispatch a fresh agent to use the skill on a sample task and observe.

---

Anti-patterns (one-liner — full list in rules/anti-patterns.md)

• Vague descriptions ("Helps with documents").
• First-person voice in description ("I can help you …").
• Time-sensitive claims ("after August 2025 …").
• Deeply nested references (SKILL.md → a.md → b.md → c.md).
• Mega-skills doing five jobs.
• Backslash paths.
• Reserved words (anthropic, claude) in the name.

---

Definition of Done

A scaffold run is done when:

• All planned files written and within their line caps.
• name and description validate against the rules in rules/frontmatter.md.
• Symlinks resolve (local-dev) or npx skills install path documented.
• Inventory rows in CLAUDE.md and README.md added.
• Phase 5 self-check is PASS.
• One sentence summary delivered to the user with the install command they can run to start using the skill.