| name | skill-creator |
| description | Meta-skill for authoring new workspace skills and auditing existing ones against the 8-pattern checklist. Two modes — CREATE scaffolds a new skill end-to-end (SKILL.md + references/ + tools/<name>/ + assets/ + .claude/settings.json allowlist), AUDIT walks an existing skill (or fans out across all skills) and produces a plan document under workareas/skills-audit/<name>.md. Use when the user wants to add a workspace skill or assess an existing one (triggers: "scaffold skill <name>", "skill-create <name>", "new workspace skill <name>", "audit skill <name>", "audit skills", "review skill <name> against patterns"). Disambiguated from Claude Code's built-in /init (which scaffolds CLAUDE.md, not workspace skills). NOT for editing skills you already understand — open the SKILL.md and edit directly. NOT for reviewing code correctness/security — use `review`; NOT for JS lint/style review — use `code-style` (AUDIT mode assesses a skill's own structure against the 8-pattern checklist, not the code a skill produces). |
| context | inline |
| allowed-tools | ["Bash","Read","Glob","Grep","Task","Edit","Write"] |
| argument-hint | <trigger phrase including skill name> |
The meta-skill. Captures the 8-pattern checklist for workspace
skills under ~/git/defra/trade-imports-animals-workspace/.claude/skills/
and applies it two ways:
- CREATE — interview the user, produce a full scaffold with
TODO placeholders.
- AUDIT — walk the checklist against existing skill(s), write
plan documents under
workareas/skills-audit/.
Stops at audit. Improvement work is judgment-heavy; the user
resolves Open Questions on the plan and hand-writes the
implementer prompt.
Path conventions
Cross-workspace paths use the literal home-relative form —
~/git/defra/trade-imports-animals-workspace/tools/<domain>/,
~/git/defra/trade-imports-animals-workspace/docs/best-practices/,
~/git/defra/trade-imports-animals-workspace/workareas/. Bash
expands ~ automatically. Skill-internal references stay
relative (references/<NAME>.md, assets/<NAME>.md).
Bash call hygiene — one command per Bash call. Full rule table: docs/agent-skills.md → "Bash call hygiene".
Session start — Read these references
Before either mode, Read these into context (the checklist must
be live; anti-patterns drift over time):
~/git/defra/trade-imports-animals-workspace/docs/best-practices/skills/patterns.md
— the 8-pattern checklist (canonical reference).~/git/defra/trade-imports-animals-workspace/docs/best-practices/skills/anti-patterns.md
— known mis-applications. Grows over time.~/git/defra/trade-imports-animals-workspace/docs/best-practices/skills/scaffold-template.md
— only Read in CREATE mode (the SKILL.md skeleton + decisions.md
sidecar).
When to use
| Trigger | Mode | What to follow |
|---|
"scaffold skill <name>", "skill-create <name>", "new workspace skill <name>" | CREATE | Step 0 dispatch → references/INTERVIEWER.md (parent-loaded) |
"audit skill <name>", "review skill <name> against patterns" | AUDIT (single) | Step 0 dispatch → spawn one AUDITOR worker |
| "audit skills" (no name) | AUDIT (all) | Step 0 dispatch → enumerate skills, fan out one AUDITOR per skill |
Disambiguated from Claude Code's built-in /init (which
scaffolds CLAUDE.md). Use one of the trigger phrases above —
none of them match the /init keyword.
NOT for hand-editing a skill you already understand — open
SKILL.md and edit. NOT for adding a worker reference to an
existing skill — edit the skill's references/ folder directly.
Worker references
| Persona | Loaded by | Spawn model | Artifact |
|---|
references/INTERVIEWER.md | CREATE mode parent session | parent-loaded (no Task spawn) | populates decisions.json then invokes scaffold-skill.sh |
references/AUDITOR.md | AUDIT mode parent session | Task subagent_type: general-purpose, one per skill | per-skill plan at workareas/skills-audit/<name>.md |
Spawn idiom for AUDITOR — prompt begins:
Follow the instructions in ~/git/defra/trade-imports-animals-workspace/.claude/skills/skill-creator/references/AUDITOR.md.
**Target skill:** <name>
**SKILL.md path:** ~/git/defra/trade-imports-animals-workspace/.claude/skills/<name>/SKILL.md
**Output path:** ~/git/defra/trade-imports-animals-workspace/workareas/skills-audit/<name>.md
general-purpose carries Tools: * so the worker can Read /
Write / Bash freely — required because the AUDITOR doesn't see
this SKILL.md (it has its own hygiene block at the top of
AUDITOR.md).
Step 0: Dispatch
~/git/defra/trade-imports-animals-workspace/tools/skill-creator/start-skill-creator.sh "<trigger phrase>"
The dispatcher writes MODE: CREATE, MODE: AUDIT_ONE, or
MODE: AUDIT_ALL as the first stdout line, then prints a JSON
payload with mode-specific parameters (skill_name, targets[],
decisions_path).
Branch on the mode:
MODE: CREATE → CREATE flow below.MODE: AUDIT_ONE → AUDIT flow, single target.MODE: AUDIT_ALL → AUDIT flow, fan-out.
CREATE flow
The parent session loads references/INTERVIEWER.md and follows
it. The interviewer:
- Walks the 8 shape questions one at a time (serial, not batched).
- Records each answer atomically via
interview-add-answer.sh
into workareas/skill-creator/<name>/decisions.json.
- When all 8 are answered, invokes
scaffold-skill.sh --run-id <name> which materialises the full
scaffold (.claude/skills/<name>/, tools/<name>/, allowlist
entries, decisions.md sidecar).
- Prints the artifact paths and a short list of TODO markers the
user must fill in before the skill is shippable.
CREATE does not auto-fill the skill's actual logic. The
scaffold is structural placeholders; the user takes the scaffold
and writes the prose.
CREATE completion output
Skill scaffolded: <name>
Paths:
.claude/skills/<name>/SKILL.md
.claude/skills/<name>/references/<WORKER>.md (if fan-out)
.claude/skills/<name>/assets/... (if JSON state)
tools/<name>/start-<name>.sh (if dispatcher)
tools/<name>/<other helpers>.sh
Allowlist entries appended to .claude/settings.json.
Decisions sidecar: .claude/skills/<name>/decisions.md
TODO markers remaining: N
Next: open .claude/skills/<name>/SKILL.md and fill in the TODOs.
AUDIT flow
Step A1: Enumerate targets
AUDIT_ONE — targets is a single skill name from the trigger.
AUDIT_ALL — start-skill-creator.sh already listed every
.claude/skills/*/SKILL.md (excluding skill-creator itself) in
the JSON payload's targets[].
Step A2: Spawn one AUDITOR per target
Spawn general-purpose Task subagents in parallel (up to one per
target). Each spawn prompt:
Emit ALL Task calls in a single assistant response — do NOT spawn one, await the result, then spawn the next. Parallelism only works when calls are batched in one turn.
Follow the instructions in ~/git/defra/trade-imports-animals-workspace/.claude/skills/skill-creator/references/AUDITOR.md.
**Target skill:** <name>
**SKILL.md path:** ~/git/defra/trade-imports-animals-workspace/.claude/skills/<name>/SKILL.md
**Output path:** ~/git/defra/trade-imports-animals-workspace/workareas/skills-audit/<name>.md
Wait for all workers to finish (the harness emits
task-notification per worker — wait for the completed set, do
not poll).
Step A3: Aggregate
Read each workareas/skills-audit/<name>.md produced. Emit a
summary table:
# Skill audit — <date>
| Skill | Plan | Pattern gaps | Open questions |
|---|---|---|---|
| <name> | [<name>.md](workareas/skills-audit/<name>.md) | <N> | <K> |
AUDIT completion output
Audit complete for <N> skill(s).
Plans:
workareas/skills-audit/<name>.md (pattern gaps: G, open questions: Q)
...
Headline gaps (top 3 by severity):
- <skill>: <one-line summary>
...
Next: read each plan. Resolve Open Questions, then hand-write the
implementer prompt (no auto-chaining audit → implement).
Scripts cheat-sheet
All under ~/git/defra/trade-imports-animals-workspace/tools/skill-creator/:
| Script | Purpose |
|---|
start-skill-creator.sh | Step 0 dispatcher — parses trigger, emits MODE: ... + JSON payload |
scaffold-skill.sh | CREATE step 3 — reads decisions.json, writes the scaffold + allowlist entries + decisions.md |
interview-add-answer.sh | CREATE — atomic mutation of decisions.json (one shape question per call) |
render-interview.sh | CREATE — markdown view of decisions.json (used for decisions.md sidecar and mid-interview recaps) |
