skill-maker

What this skill does

<intake>

# Create, Audit, or Consolidate Skills

Create agent skills following the [Agent Skills open standard](https://agentskills.io/specification).

What do you need to do?

1. **Audit an existing skill** — Review, improve, or debug a SKILL.md
2. **Create a new skill** — Interview, draft, and review from scratch
3. **Consolidate skills** — Merge multiple skills into fewer

**Wait for response before proceeding.**
</intake>

<routing>

| Response | Workflow |
|----------|----------|
| 1, "audit", "review", "check", "fix", "improve" | Audit Workflow (Step 1–4 in this file) |
| 2, "create", "write", "build", "new", "draft" | Phases 1–5 (Interview → Draft → Description → Scripts → Review) in this file |
| 3, "consolidate", "merge", "combine" | `references/consolidation-guide.md` — return to Phase 5 for final checklist |

</routing>

## Audit Workflow

Use this workflow when reviewing, improving, or debugging an existing skill.

### Step 1: Locate and read the skill

Read the full SKILL.md and list all files in the skill directory (`references/`, `scripts/`, `templates/`, `assets/`).

### Step 2: Run the audit checklist

Check each category. Note issues as you go.

**Frontmatter:**

- [ ] `name` matches the directory name, lowercase+hyphens, max 64 chars
- [ ] `description` is under 1024 chars, non-empty, third person
- [ ] `description` includes trigger phrases (not just a summary of what the skill does)
- [ ] `description` covers edge phrasings users would actually say

**Structure:**

- [ ] SKILL.md body is under 500 lines
- [ ] Essential principles are inline in SKILL.md (not only in a reference file)
- [ ] All referenced files exist (check every path in the SKILL.md)
- [ ] References are one level deep (no nested chains: A → B → C)

**Content quality:**

- [ ] No rigid ALWAYS/NEVER rules without reasoning (explain WHY)
- [ ] No explanations of things the agent already knows from training
- [ ] Steps are specific and verifiable (not "handle errors appropriately")
- [ ] Success criteria are observable and testable
- [ ] Examples use fake data where appropriate

**Router pattern** (if applicable):

- [ ] Intake question asks what the user wants before routing
- [ ] Router table maps commands to reference files
- [ ] All referenced workflow/reference files exist
- [ ] Essential principles are in SKILL.md, not only in sub-command references
- [ ] If skill has multiple semantic sections, consider XML tags for structure (see `references/xml-structure-guide.md`)

**Scripts** (if present):

- [ ] Scripts have shebangs, `--help`, and structured output
- [ ] No interactive prompts (all input via flags/env/stdin)
- [ ] Cross-platform paths (pathlib, no hardcoded separators)
- [ ] Error messages explain what went wrong and what to do

Read `references/anti-patterns.md` for the full catalog of common failures.

### Step 3: Generate the report

Present findings grouped by severity:

1. **Critical** — skill won't trigger or produces wrong output
2. **Important** — structural issues, missing files, spec violations
3. **Minor** — style, conciseness, optimization opportunities

For each finding, state the issue, cite the specific line or section, and recommend a fix.

### Step 4: Offer fixes

Ask the user which findings to fix. Apply changes surgically — don't rewrite sections that aren't broken. Run the Phase 5 review checklist on the modified skill before finishing.

## Phase 1: Interview

Interview the user about every aspect of this skill until reaching shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.

### Interview cadence

Ask **one question at a time**. Wait for the answer before asking the next. Adapt follow-ups based on what you learn. Each question should provide clear benefit toward building a better skill — cut questions the codebase can answer for you.

If a question can be answered by exploring the codebase, explore the codebase instead of asking.

Focus areas, roughly in order:

1. **Purpose and audience.** What task does this skill cover? What specific problem does it solve? What does the user do today without it?
2. **Scope boundaries.** What should this skill NOT do? What adjacent tasks belong to other skills?
3. **Input/output.** What does the user provide? What does the skill produce? Specific formats?
4. **Edge cases.** What goes wrong? Common mistakes? Gotchas for new users?
5. **Success criteria.** How do you know the skill worked correctly?
6. **What can be scripted?** Look for deterministic operations that should be code, not LLM instructions. Scripts are cheaper, faster, and more reliable.
7. **References needed?** Domain knowledge too large for SKILL.md that should live in separate files?
8. **Existing patterns.** Similar skills or workflows to draw from? Check the codebase.
9. **Platform constraints.** macOS, Windows, and Linux? Scripts must handle path separators, temp directories, and shell differences.
10. **External services and APIs.** Does the skill call external APIs or services? If yes, read `references/api-skill-patterns.md` — it covers credential handling, schema discovery, instance-specific values, and error placement.

### Architecture decision tree

After the interview questions above, decide the architecture. Most skills are simple — only escalate when the answers demand it.

**Question 1: How many distinct things can a user want to do?**

- One specific thing → **Simple skill** (single SKILL.md, under 200 lines)
- Multiple things with shared principles → continue to Q2

**Question 2: Is there shared domain knowledge across those operations?**

- No, each operation is self-contained → **Simple skill** (or multiple separate simple skills)
- Yes, multiple operations share knowledge → **Router skill** (SKILL.md + `references/`)

**Question 3: Does it cover a full lifecycle (build, debug, test, ship)?**

- No → **Router skill** is sufficient
- Yes → **Domain expertise skill** (exhaustive references, full lifecycle workflows)

| What you're building | Pattern |
|---|---|
| "A skill that commits with a conventional message" | Simple |
| "A skill that manages PRs — create, review, merge, close" | Router |
| "A skill for building and shipping macOS apps" | Domain expertise |
| "A skill that audits other skills" | Simple (upgrade to Router if it grows) |

For Router and Domain expertise patterns, also ask:

- **Does the skill need project-level context?** If every command needs the same background, design a context file pattern with a loader script.
- **Are there mandatory setup gates?** Steps that must pass before any work begins. Gates prevent generic output.
- **Does behavior vary by task type?** If so, design a register/mode system that classifies the task first, then loads different references.

Read `references/architecture-patterns.md` for implementation details of each pattern.

**Consolidation signal check:** If the interview reveals the new skill overlaps significantly with existing skills (shared scripts, cross-references, linear pipeline), consider consolidating instead of creating. Read `references/consolidation-guide.md` for the signals and workflow.

Do not proceed to Phase 2 until the user confirms the scope is complete.

## Phase 2: Draft the SKILL.md

Write the skill following the spec. Read `references/spec-guide.md` for the full format reference before drafting.

**Starter templates:** Use `templates/simple-skill.md` for single-purpose skills, `templates/router-skill.md` for multi-command skills using markdown headings, or `templates/router-skill-xml.md` for multi-command skills using XML structure. Copy the template as a starting point, then customize.

### Frontmatter

```yaml
---
name: skill-name        # lowercase, hyphens, max 64 chars
description: |           # max 1024 chars — this is the ONLY triggering mechanism
  What the skill does. Use when [specific triggers].
  Also use when [ad