Generates Claude Code skills from requirements using adaptive interview, complexity classification, and iterative validation. Use when creating new skills, scaffolding skill structure, or generating skills with sub-agent orchestration.
Installation
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Generates Claude Code skills from requirements using adaptive interview, complexity classification, and iterative validation. Use when creating new skills, scaffolding skill structure, or generating skills with sub-agent orchestration.
Generates a complete Claude Code skill from a description or requirements document. Conducts an adaptive interview to understand the skill's purpose, classifies it into one of 7 archetypes (Generator, Tool Wrapper, Pipeline, Research, Script-driven, Reviewer, Inversion), surfaces candidate sub-patterns for the chosen archetype, spawns a Sonnet sub-agent to generate the files, validates with anthropic-validator, and presents the scaffold with architectural decisions.
When to Use This Skill
Load this skill when the user request matches ANY of these patterns:
Trigger Pattern
Example User Request
Skill creation
"Create a new skill", "Make a skill for X"
Scaffolding
"Scaffold a skill", "Set up a new skill"
Generation
"Generate a skill that does X"
Skill design
"Design a skill for X", "I need a skill that does X"
scripts/grade.ts returns SKIPPED for fuzzy assertions and emits a manual-invoke directive pointing at this agent. The orchestrator (or a future automation step) invokes the grader against evidence_paths to complete grading.
Eval comparator agent
agents/skill-eval-comparator.md
Bundled (no external load)
Blind A/B comparison of two grading runs. Invoked manually with two grading-<timestamp>.json paths; not auto-spawned by grade.ts.
Fallback behavior:
If a template file is missing: Use the closest available template, note mismatch in diagnostics
If content-guidance is missing: Proceed without it, note in diagnostics (output quality will be lower)
Runtime Prerequisites
The eval framework (Layer 2 infrastructure shipped in scripts/run-loop.ts + scripts/grade.ts) requires the bun runtime on PATH. Invocation via just eval-skill <path>.
Interim contract (until P10.11 ships): users must install bun manually. See bun.sh/install. Bulwark's scaffold/init flow does not auto-install bun yet — formal installer scoped as P10.11 (plans/task-briefs/P10.11-bun-runtime-installer.md).
If you are scaffolding a skill into an environment without bun, generated evals/ data still ships, but just eval-skill will fail until bun is installed.
<description-or-name> — Free-text description of the desired skill, or a skill name to start from
--doc <path> — Path to a requirements document. Extracts interview answers from it instead of asking fresh.
--from-template <archetype> <skill-name> — Fast path for experienced authors. Skips the Stage 0 interview and uses archetype defaults. Valid archetypes: Generator, Tool Wrapper, Pipeline, Research, Reviewer, Script-driven, Inversion. Stage 1 (classification confirmation), Stage 2 (generation), and Stage 3 (validation) all still run.
Examples:
/create-skill a skill that audits dependency versions — Start from description
/create-skill --doc plans/task-briefs/P5.4-create-skill.md — Start from requirements doc
/create-skill changelog-generator — Start from a name
/create-skill --from-template Generator slug-from-title — Skip interview, use Generator defaults
Mandatory Execution Checklist (BINDING)
Every item below is mandatory. No deviations. No substitutions. No skipping.
This skill uses a 6-stage pipeline. You are the orchestrator. Follow every item in order. Do NOT return to the user until all applicable items are checked.
Stage 1 — Classify: Primary archetype determined per decision-framework.md (1 of 7) + context mode
Stage 1 — Classify: Candidate sub-patterns for the archetype looked up; default-ON sub-patterns pre-checked
Stage 1 — Classify: Default grading_mode resolved per archetype (objective for Generator/Tool Wrapper/Pipeline/Reviewer/Script-driven; subjective for Research/Inversion); author may override at Stage 1 confirmation
Stage 1 — Classify: bundles_scripts resolved (true for Script-driven canonical; ask follow-up for non-Script-driven archetypes; default false)
Stage 1 — Classify: Classification (archetype + selected sub-patterns + context + grading_mode + bundles_scripts) presented to user and confirmed via AskUserQuestion
Stage 2 — Generate: Sonnet sub-agent spawned via Task tool (you do NOT generate the files yourself)
Stage 2 — Generate: Generated files verified to exist in working directory
Stage 2 — Generate: evals/evals.json and evals/triggers.json scaffolded per references/eval-scaffolding.md (always)
Stage 2 — Generate: evals/compliance.json scaffolded if grading_mode = subjective (Research, Inversion, or override)
Stage 2 — Generate: scripts/.gitkeep scaffolded if bundles_scripts = true; SKILL.md documents ${CLAUDE_PLUGIN_ROOT} invocation convention per references/scripts-conventions.md
Stage 2 — Generate: If Pipeline archetype — sub-agent files generated in {working-directory}/agents/
Stage 3 — Validate: just check-description {working-directory}/SKILL.md invoked via Bash (E.1 description quality gate — exits 1 on multi-line / over-length)
Stage 3 — Validate: just check-skill-size {working-directory}/SKILL.md invoked via Bash (E.3 tiered cap enforcement — exits 1 on hard cap with refactor proposal)
Stage 3 — Validate: /anthropic-validator invoked via Skill tool (manual review is NOT a substitute)
Stage 3 — Validate: If Pipeline archetype — /anthropic-validator invoked on each sub-agent file
Stage 3 — Validate: Validator output read and findings counted
Stage 3 — Validate: Cross-file consistency check completed — if skill bundles templates/, references/, or scripts/, scan SKILL.md for content that mirrors or references those files; verify both sides agree on rules, schemas, character sets, error conditions (per references/content-guidance.md → Cross-File Consistency)
Stage 3 — Validate: Sub-pattern review soft prompt presented to user IF (sub-patterns selected at Stage 1 > 0) OR (archetype has default-ON sub-patterns that were opted out — Research, Inversion). SKIP entirely for Generator/Tool Wrapper/Reviewer/Script-driven/Pipeline when 0 sub-patterns selected (per references/content-guidance.md → Sub-Pattern Catalog)
Stage 4 — Refine: If validation found critical/high issues, Sonnet sub-agent spawned to fix (max 2 retries)
Stage 5 — Deploy & Present: Skill files deployed from working directory to target directory
Stage 5 — Deploy & Present: If Pipeline archetype — sub-agent files deployed to .claude/agents/
Stage 5 — Deploy & Present: Working directory cleaned up
Stage 0: Pre-Flight
├── Parse arguments (description, name, --doc path, or --from-template <archetype> <name>)
├── Load references/decision-framework.md
├── Load references/content-guidance.md
├── Load subagent-prompting skill
├── If --from-template provided (E.2 escape hatch):
│ ├── Validate <archetype> against the 7-set (Generator, Tool Wrapper, Pipeline,
│ │ Research, Reviewer, Script-driven, Inversion). Case-insensitive match;
│ │ normalize to canonical form
│ ├── If invalid: print valid options + exit (do NOT scaffold)
│ ├── Skip interview entirely
│ ├── Load classification with archetype defaults:
│ │ ├── primary_archetype = <archetype>
│ │ ├── selected_sub_patterns = default-ON only (Research → reviewer-validated;
│ │ │ Inversion → generator-coupled; others → empty)
│ │ ├── context_mode = fork if archetype ∈ {Pipeline, Research} else inline
│ │ ├── grading_mode = archetype default per references/eval-scaffolding.md
│ │ └── bundles_scripts = (archetype = Script-driven)
│ └── Stage 1 still runs (classification confirmation prompt presented to user)
├── Elif --doc provided:
│ ├── Read the requirements document
│ ├── Extract answers to Q1-Q5 from the document
│ └── Present extracted answers to user for confirmation via AskUserQuestion
├── If no --doc and no --from-template:
│ └── AskUserQuestion: Present all 5 core questions from decision-framework.md
│ ├── Q1: What does this skill do? (2-3 concrete invocation examples)
│ ├── Q2: Primary action? (Audit / Create / Document / Orchestrate / Wrap script — routes to archetype)
│ ├── Q3: If creating: CLI/state inputs OR AskUserQuestion-driven? (Generator vs Inversion)
│ ├── Q4: If orchestrating: sequential stages OR parallel viewpoints? (Pipeline vs Research)
│ └── Q5: Needs conversation history, or can run in isolation? (context: inline vs fork)
├── If sub-pattern disambiguation needed (Round 2):
│ └── AskUserQuestion: Follow-up questions per decision-framework.md
│ ├── Q6: Reviewer sub-pattern? (standalone / pipeline-stage / multi-source)
│ ├── Q7: Generator sub-pattern? (single-template / multi-template / configuration-emitting)
│ ├── Q8: Tool Wrapper sub-pattern? (context-injected / schema-convention / methodology / pattern-catalog / curated-data-library)
│ ├── Q9: Pipeline sub-pattern? (reviewer-orchestrating / research-orchestrating / generator-orchestrating)
│ ├── Q10: Research — reviewer-validated default ON; opt out?
│ └── Q11: Script-driven — hook-orchestrated?
├── Determine target directory for generated skill
│ └── Default: skills/{skill-name}/ (or user-specified path)
├── Set working directory: tmp/create-skill/{skill-name}/
│ └── All generation and refinement happens here to avoid .claude/ edit approval storms
│ Files are deployed to the target directory only after validation passes (Stage 5)
└── Token budget check (warn if >30% consumed)
Interview behavior: Maximum 2 AskUserQuestion rounds. Present Q1-Q5 together in round 1. Follow-ups (if needed) in round 2. Do NOT ask questions one at a time.
Stage 1: Classify (Orchestrator)
Apply the archetype classification from references/decision-framework.md:
Stage 1: Classify
├── Decision: Primary archetype (1 of 7) — per Decision Tree → Primary Archetype in decision-framework.md
│ ├── Q2 = Audit/score → Reviewer
│ ├── Q2 = Document conventions → Tool Wrapper
│ ├── Q2 = Wrap external script → Script-driven
│ ├── Q2 = Create + Q3 = CLI/state → Generator
│ ├── Q2 = Create + Q3 = AskUserQuestion → Inversion
│ ├── Q2 = Orchestrate + Q4 = sequential → Pipeline
│ └── Q2 = Orchestrate + Q4 = parallel viewpoints → Research
├── Decision: Context mode (orthogonal to archetype)
│ ├── Q5 = needs conversation → inline (no fork)
│ ├── Q5 = isolation OK + (Pipeline OR Research) → context: fork (recommended for orchestrators)
│ └── Otherwise → inline (warn if fork requested for non-orchestrator)
├── Lookup: Candidate sub-patterns for chosen archetype (per decision-framework.md → Sub-Pattern Lookup)
│ ├── Default-ON: Research → reviewer-validated; Inversion → generator-coupled
│ └── Pre-check default-ON sub-patterns in user prompt; user may opt out
├── Decision: Default `grading_mode` for evals scaffolding (per references/eval-scaffolding.md → Default grading_mode Per Archetype)
│ ├── objective: Generator, Tool Wrapper, Pipeline, Reviewer, Script-driven
│ ├── subjective: Research, Inversion
│ └── Author may override at the classification confirmation prompt below (rare — typical override is Pipeline → subjective when synthesis-quality grading is wanted)
├── Decision: `bundles_scripts` for scripts/ scaffolding (per references/scripts-conventions.md → When a Skill Bundles Scripts)
│ ├── true: Archetype = Script-driven (canonical — always bundles a script)
│ ├── ask: Archetype ∈ {Generator, Tool Wrapper, Pipeline, Reviewer, Research, Inversion}
│ │ └── AskUserQuestion: "Will this skill bundle executable scripts (TypeScript via bun, or shell scripts)? [Yes / No]"
│ │ └── Answer = bundles_scripts (default No if unanswered or ambiguous)
│ └── If true and archetype ∉ {Script-driven}, note "non-canonical scripts bundling" in diagnostics for review
├── Map archetype → template (1 of 7 from decision-framework.md → Archetype → Template Mapping)
└── Present classification to user via AskUserQuestion:
├── "Primary archetype: {archetype} — {one-line reason from Q2}"
├── "Template: {template-name}"
├── "Context: {inline/fork} — {reason}"
├── "Default grading_mode: {objective/subjective} — {reason from archetype default}"
├── "Bundles scripts: {Yes/No} — {reason}"
├── "Candidate sub-patterns for {archetype}:"
│ └── For each: "{sub-pattern}: {one-line definition from content-guidance.md → Sub-Pattern Catalog}"
├── "Which sub-patterns apply? (Select 0-N — default-ON pre-checked)"
└── "Proceed with generation? [Yes / Adjust grading_mode / Adjust bundles_scripts / Adjust sub-patterns / Adjust]"
MANDATORY: Wait for user confirmation before proceeding to Stage 2. If user selects "Adjust", re-classify with their feedback. Selected sub-patterns + final grading_mode are passed to Stage 2 generator as CONSTRAINTS — generator MUST document each selected sub-pattern in the generated SKILL.md and emit eval data per the resolved grading_mode.
Stage 2: Generate (Sonnet sub-agent)
Stage 2: Generate
├── Read the selected template from references/template-{type}.md
├── Construct prompt using 4-part template (GOAL/CONSTRAINTS/CONTEXT/OUTPUT):
│ ├── GOAL: Generate a complete, structurally correct skill matching the
│ │ classification. The skill must activate reliably and instruct clearly.
│ ├── CONSTRAINTS:
│ │ ├── Follow the template structure exactly
│ │ ├── Description MUST be a single line (multi-line breaks discovery)
│ │ ├── Description MUST be ≤250 chars (over-length silently truncates per Issue #881)
│ │ ├── Description MUST use "Use when..." trigger framing
│ │ ├── Frontmatter MUST include `version: 1.0.0` for the new skill (E.4 — semver-flavored;
│ │ │ patch=typo/wording, minor=new feature, major=breaking. Migration guidance in
│ │ │ references/content-guidance.md → "Skill version + migration checklist")
│ │ ├── Frontmatter MUST include `author:` field. Default to `"Ashay Kubal @ Qball Inc."`
│ │ │ for first-party Bulwark generation; prompt the user during interview if
│ │ │ generating in an external repo.
│ │ ├── Include "When to Use" table with ≥3 trigger patterns
│ │ ├── Include "DO NOT use for" section with ≥2 anti-triggers
│ │ ├── MUST include "## Mandatory Execution Checklist (BINDING)" at top of
│ │ │ SKILL.md with SC1-SC3 reference — bottom checklists are advisory and
│ │ │ ignored (see references/content-guidance.md → "Top-of-File Execution
│ │ │ Checklist" pattern)
│ │ ├── Checklist placement: after frontmatter → overview → When-to-Use →
│ │ │ Dependencies → optional Usage, BEFORE Pipeline/Stages body
│ │ ├── If skill has sub-agents: include subagent-prompting in skills: dependency
│ │ ├── Do NOT add unnecessary files (no README, CHANGELOG, LICENSE)
│ │ ├── Do NOT use emojis in generated content
│ │ ├── Keep total SKILL.md under target line count for the archetype:
│ │ │ ├── Tool Wrapper: 150, Generator: 200, Reviewer: 250
│ │ │ ├── Inversion: 350, Pipeline: 400, Research: 400, Script-driven: 400
│ │ │ └── Tiered enforcement (memo D8 amended S107):
│ │ │ ├── 200 lines = Advisory — emit a soft note in return summary suggesting modularization
│ │ │ ├── 500 lines = Strong warn — emit a loud warning recommending split into references/
│ │ │ └── 600 lines = HARD CAP — STOP. Do NOT emit a single SKILL.md exceeding 600 lines.
│ │ │ Return a refactor proposal listing which sections should move to
│ │ │ references/{name}.md or examples/{name}.md, then await user direction.
│ │ ├── Cross-file consistency (memo D11, S107):
│ │ │ If the skill bundles templates/, references/, or scripts/, any rules,
│ │ │ algorithms, schemas, or validation logic in those files MUST agree with rules
│ │ │ stated in SKILL.md. Before returning, scan for cross-file claims (character sets,
│ │ │ error conditions, output formats, validation rules) and confirm both sides agree.
│ │ │ Disagreements are HIGH-severity functional bugs. Canonical example: a slug
│ │ │ algorithm in templates/ that preserves Unicode while SKILL.md validation accepts
│ │ │ only ASCII — both files individually compile clean; together they fail silently
│ │ │ on non-ASCII input. Fix BEFORE returning, do not defer to validation.
│ │ ├── For each selected sub-pattern, include a documented section in the generated SKILL.md:
│ │ │ ├── Quote the canonical definition from references/template-{archetype}.md → ## Common Sub-Patterns
│ │ │ └── Apply the sub-pattern's shape directives (e.g., context-injected → user-invocable: false + hook setup docs)
│ │ ├── Eval scaffolding (Layer 1 DATA — per references/eval-scaffolding.md):
│ │ │ ├── ALWAYS emit {working-directory}/evals/evals.json + {working-directory}/evals/triggers.json
│ │ │ ├── If grading_mode = subjective → ALSO emit {working-directory}/evals/compliance.json
│ │ │ ├── grading_mode follows the archetype default unless explicitly overridden in CONTEXT
│ │ │ ├── Use the matching archetype section in eval-scaffolding.md as the JSON shape
│ │ │ ├── Substitute placeholders (<<SKILL_NAME>>, <<SKILL_PATH>>, <<INVOCATION_EXAMPLE_1>>, etc.)
│ │ │ │ from the classification + interview state — see eval-scaffolding.md → Placeholder Substitution Guide
│ │ │ ├── Seed at least ONE concrete starter test in evals.json from Q1 examples
│ │ │ ├── Seed 3-5 should-trigger and 3-5 should-not-trigger queries in triggers.json from Q1;
│ │ │ │ leave remaining slots as explicit <<TODO>> placeholders for the user
│ │ │ ├── For subjective: seed compliance.json stage_id entries from the SKILL.md pipeline
│ │ │ │ (one stage_id per declared pipeline stage); deterministic evidence preferred
│ │ │ └── Apply sub-pattern × eval impact additions per eval-scaffolding.md → Sub-Pattern × Eval Impact
│ │ └── Scripts scaffolding (per references/scripts-conventions.md):
│ │ ├── If bundles_scripts = true → emit {working-directory}/scripts/.gitkeep (empty file)
│ │ ├── If bundles_scripts = true → SKILL.md MUST document the `${CLAUDE_PLUGIN_ROOT}/skills/<name>/scripts/`
│ │ │ invocation convention (do NOT use `$CLAUDE_PLUGIN_DIR` — non-existent latent bug source)
│ │ ├── If bundles_scripts = true and any script is TS-via-bun → SKILL.md MUST include a "Runtime Prerequisites" section
│ │ │ noting bun on PATH (cross-link to P10.11 bun installer brief)
│ │ ├── If bundles_scripts = true → SKILL.md MUST include a "Permissions Setup" section
│ │ │ listing required Bash(bun:*), Bash(bash:*), Bash(just:*) entries per scripts-conventions.md
│ │ ├── If bundles_scripts = true and SKILL.md emits Justfile recipe examples → quote `${CLAUDE_PLUGIN_ROOT}`
│ │ │ AND all parameters per SEC-008 (unquoted opens command-injection vectors when invoked from automation)
│ │ └── Do NOT generate concrete script files — only .gitkeep. Script content is author-supplied
│ │ (generate-and-customize contract; refer to existing skills for starter patterns)
│ ├── CONTEXT:
│ │ ├── Classification from Stage 1 (primary archetype + selected sub-patterns + context mode + template + grading_mode + bundles_scripts)
│ │ ├── User's interview answers (concrete examples from Q1)
│ │ ├── Selected template: references/template-{archetype}.md
│ │ ├── Content guidance: references/content-guidance.md (incl. Sub-Pattern Catalog)
│ │ ├── Eval scaffolding guide: references/eval-scaffolding.md (per-archetype evals/ emission)
│ │ ├── Eval schema lock: references/eval-shape.md (when in doubt about field shapes)
│ │ ├── If bundles_scripts = true: references/scripts-conventions.md (scripts/ scaffolding + invocation convention + Justfile recipe pattern + bun runtime prerequisite)
│ │ ├── Selected sub-patterns: explicit list passed from Stage 1 (0-N — generator MUST document each)
│ │ ├── Sub-pattern definitions: references/template-{archetype}.md → ## Common Sub-Patterns
│ │ ├── If Pipeline archetype: references/agent-template.md (sub-agent file structure)
│ │ ├── If Pipeline archetype: references/agent-conventions.md (system-prompt register, frontmatter)
│ │ ├── Instruction: "Read 1-2 existing skills of the same archetype from the
│ │ │ codebase for structural reference (use Glob to find skills/*/SKILL.md)"
│ │ ├── If Pipeline archetype: "Read 1-2 existing agents from .claude/agents/*.md
│ │ │ for sub-agent structural reference"
│ │ ├── Target output directory (final deployment location)
│ │ └── Working directory: tmp/create-skill/{skill-name}/
│ └── OUTPUT:
│ ├── Write SKILL.md to {working-directory}/SKILL.md
│ ├── Write reference files to {working-directory}/references/ (if applicable)
│ ├── Write template files to {working-directory}/templates/ (if applicable)
│ ├── Write script files to {working-directory}/scripts/ (if applicable)
│ ├── Write {working-directory}/evals/evals.json (always — per eval-scaffolding.md archetype section)
│ ├── Write {working-directory}/evals/triggers.json (always — 20-query format)
│ ├── If grading_mode = subjective: Write {working-directory}/evals/compliance.json (stage execution checks)
│ ├── If bundles_scripts = true: Write {working-directory}/scripts/.gitkeep (empty file — preserves directory in git)
│ ├── If Pipeline archetype: Write sub-agent files to {working-directory}/agents/
│ │ ├── One .md file per pipeline stage: {skill-name}-{stage-name}.md
│ │ ├── Each sub-agent follows agent-template.md structure
│ │ ├── Each sub-agent uses system-prompt register (agent-conventions.md)
│ │ └── Orchestrating SKILL.md references sub-agents by Task(subagent_type="{name}")
│ └── Return summary: list of files created with line counts (include evals/* paths)
├── Spawn: Task(description="Generate skill files", subagent_type="general-purpose",
│ model="sonnet", prompt=...)
├── Read generator output (file list + summary)
└── Verify files were created (Glob for {working-directory}/**)
Stage 3: Validate (Orchestrator)
Stage 3: Validate
├── PRE-FLIGHT scripts (E.1 + E.3 deterministic gates — run BEFORE anthropic-validator):
│ ├── Bash: `just check-description {working-directory}/SKILL.md`
│ │ ├── Exit 0 → continue
│ │ ├── Exit 1 → BLOCK; route to Stage 4 with the FAIL findings as directives
│ │ └── Exit 2 → infrastructure error; surface to user
│ └── Bash: `just check-skill-size {working-directory}/SKILL.md`
│ ├── Exit 0 → continue (advisory / strong-warn notes captured for Stage 5 summary)
│ └── Exit 1 (HARD CAP) → BLOCK; route to Stage 4 with the refactor proposal as directive
├── FIRST: Invoke /anthropic-validator (this is the PRIMARY validation — NOT optional)
│ ├── Use the Skill tool: Skill(skill="anthropic-validator", args="{working-directory}/")
│ ├── Do NOT substitute manual review for this step
│ └── Do NOT proceed past this node until the Skill tool has been invoked
├── If Pipeline archetype: Also validate each sub-agent file in {working-directory}/agents/
│ └── Run /anthropic-validator on each {skill-name}-{stage-name}.md
├── Read validator output
├── Check for critical/high findings:
│ ├── 0 critical AND 0 high → proceed to Stage 5 (skip Stage 4)
│ └── Any critical or high → proceed to Stage 4 (refine)
├── THEN: Manual checks (these supplement the validator, they do NOT replace it)
│ ├── Check description is single-line (read SKILL.md, verify no multiline description)
│ ├── If Pipeline archetype: Check each sub-agent uses system-prompt register
│ ├── Check no unnecessary files (no README.md, CHANGELOG.md, etc.)
│ ├── Check evals/evals.json exists and parses as valid JSON with the resolved grading_mode
│ ├── Check evals/triggers.json exists and parses as valid JSON
│ ├── If grading_mode = subjective: Check evals/compliance.json exists and parses as valid JSON
│ ├── Check evals/* placeholder substitutions: no leftover <<SKILL_NAME>>, <<SKILL_PATH>>,
│ │ <<SKILL_VERSION>>, <<GRADING_MODE>>, or <<INVOCATION_EXAMPLE_*>> markers (literal <<TODO>>
│ │ slots are permitted — they are explicit user-fill placeholders for additional tests/queries)
│ ├── If bundles_scripts = true: Check scripts/.gitkeep exists
│ └── If bundles_scripts = true: Check SKILL.md documents `${CLAUDE_PLUGIN_ROOT}` invocation convention
│ (grep for `${CLAUDE_PLUGIN_ROOT}`; ensure no `$CLAUDE_PLUGIN_DIR` references — non-existent var, latent bug)
├── THEN: Cross-file consistency check (memo D11, S107 — defense-in-depth for Stage 2 CONSTRAINT)
│ ├── If skill bundles templates/, references/, or scripts/:
│ │ Scan SKILL.md for content that mirrors or references those files.
│ │ For each mirror (validation rules, character sets, error conditions, output schemas,
│ │ algorithm descriptions), verify SKILL.md and the referenced file agree.
│ │ Canonical disagreement shape: Unicode-preserving algorithm + ASCII-only validation
│ │ step (S107 slug-from-title probe). Read references/content-guidance.md →
│ │ Cross-File Consistency for the full pattern catalog.
│ ├── If a disagreement is found: Treat as HIGH finding. Route to Stage 4 refinement
│ │ with directive to align both files. Do NOT proceed to Stage 5.
│ └── If no supporting files OR no disagreements: Note "no cross-file claims" in diagnostics, proceed.
├── THEN: Sub-pattern review soft prompt (B.6 — Path A — conditional per memo D12, S107)
│ ├── DECISION TREE:
│ │ ├── If sub-patterns selected at Stage 1 > 0:
│ │ │ Present full prompt — "Your skill is archetype {archetype}. Selected sub-patterns
│ │ │ at Stage 1: {list}. Common sub-patterns for this archetype that were NOT
│ │ │ selected: {remaining_list}. Review the generated SKILL.md — should any
│ │ │ additional sub-pattern apply?"
│ │ ├── Elif 0 sub-patterns selected AND archetype has default-ON sub-patterns
│ │ │ that were opted out (Research → reviewer-validated; Inversion → generator-coupled):
│ │ │ Present LIGHT confirmation only — "You opted out of {default-ON list}. Confirm
│ │ │ exclusion intentional? [Yes / Re-enable]". Do NOT re-present the full sub-pattern
│ │ │ catalog.
│ │ └── Else (0 selected AND no default-ON in archetype — Generator, Tool Wrapper,
│ │ Reviewer, Script-driven, Pipeline):
│ │ SKIP the soft prompt entirely. The 0-selection at Stage 1 already represents
│ │ an explicit user choice; re-asking adds friction without surfacing new info.
│ │ Note "soft prompt skipped — 0 sub-patterns selected for non-default-ON archetype"
│ │ in diagnostics.
│ ├── If user identifies a missed sub-pattern OR re-enables a default-ON: trigger Stage 4
│ │ with directive to add the documentation
│ ├── If user confirms (or skip path triggers): proceed to Stage 5
│ └── Reference: content-guidance.md → ## Sub-Pattern Catalog for full definitions
└── Stage 3 exit gate:
├── [ ] `just check-description` exited 0 (or all FAIL findings routed to Stage 4 and resolved)
├── [ ] `just check-skill-size` exited 0 (HARD CAP refactor proposal, if any, applied via Stage 4)
├── [ ] /anthropic-validator was invoked via the Skill tool (not manual review)
├── [ ] Validator output was read and findings counted
├── [ ] Cross-file consistency check completed (or N/A if no supporting files)
├── [ ] Sub-pattern review soft prompt presented OR skipped per D12 decision tree (with diagnostic note)
├── [ ] evals/evals.json exists and parses as valid JSON with the resolved grading_mode
├── [ ] evals/triggers.json exists and parses as valid JSON
├── [ ] If grading_mode = subjective: evals/compliance.json exists and parses as valid JSON
├── [ ] No leftover non-TODO placeholders in evals/* (<<SKILL_NAME>>, <<SKILL_PATH>>, <<SKILL_VERSION>>, <<GRADING_MODE>>, <<INVOCATION_EXAMPLE_*>> all substituted)
├── [ ] If bundles_scripts = true: scripts/.gitkeep exists
├── [ ] If bundles_scripts = true: SKILL.md uses `${CLAUDE_PLUGIN_ROOT}` (not `$CLAUDE_PLUGIN_DIR`) for script invocation paths
└── If any is unchecked, Stage 3 is NOT complete — go back and complete the missing step
Stage 4: Refine (Sonnet sub-agent, conditional, max 2 retries)
This stage only runs if Stage 3 found critical or high issues.
Stage 4: Refine (attempt {N} of 2)
├── Construct prompt using 4-part template:
│ ├── GOAL: Fix all critical and high findings from anthropic-validator
│ ├── CONSTRAINTS:
│ │ ├── Only fix the specific issues identified — do not restructure
│ │ ├── Preserve the existing skill content and structure
│ │ └── Description must remain single-line
│ ├── CONTEXT:
│ │ ├── Validator findings (critical and high items with descriptions)
│ │ ├── Current generated files (read from working directory)
│ │ └── Content guidance: references/content-guidance.md
│ └── OUTPUT: Edit files in {working-directory}/ to fix findings
├── Spawn: Task(description="Fix validator findings", subagent_type="general-purpose",
│ model="sonnet", prompt=...)
├── Re-run Stage 3 (validate)
├── If still failing after 2 retries:
│ └── Proceed to Stage 5 with caveats noted
└── Token budget check
Stage 5: Deploy & Present (Orchestrator)
Stage 5: Deploy & Present
├── Deploy skill: Move skill files from {working-directory}/ to {target-directory}/
│ ├── Copy directory tree preserving structure (SKILL.md, references/, templates/, scripts/, evals/)
│ └── This is the ONLY point where skill files are written to the final location
├── If Pipeline archetype: Deploy sub-agents
│ ├── Move {working-directory}/agents/*.md to .claude/agents/
│ └── Each sub-agent file: .claude/agents/{skill-name}-{stage-name}.md
├── Clean up: Remove {working-directory}/ after successful copy
├── Read all generated files for summary
├── Present to user:
│ ├── "Generated skill at: {target-directory}/"
│ ├── If pipeline: "Generated sub-agents at: .claude/agents/"
│ ├── "Files created:"
│ │ └── List each file with line count (skill files + evals/* + sub-agent files)
│ ├── "Architectural decisions:"
│ │ ├── "Context: {fork/inline} — {reason}"
│ │ ├── "Sub-agents: {none/sequential/parallel/AT} — {reason}"
│ │ ├── "grading_mode: {objective/subjective} — {reason}"
│ │ ├── "Bundles scripts: {Yes/No} — {reason}"
│ │ └── "Supporting files: {list} — {reason}"
│ ├── "Skill type: {template used}"
│ ├── "Validation: {pass/fail with details}"
│ ├── If caveats: "Unresolved issues: {list}"
│ ├── If pipeline: "Sub-agent permissions to configure:"
│ │ └── {List tool permissions for each sub-agent that must be added to settings.json}
│ └── "Next steps:"
│ ├── "1. Review and customize the generated instructions"
│ ├── "2. Test activation by asking Claude to invoke it"
│ ├── "3. Iterate on trigger patterns until activation is reliable"
│ ├── "4. Add domain-specific content to reference files"
│ ├── "5. Fill in evals/ <<TODO>> placeholders with concrete test prompts and trigger queries"
│ ├── "6. Run `just eval-skill {target-directory}` to baseline behavior (requires bun on PATH)"
│ └── If pipeline: "7. Configure tool permissions for sub-agents in .claude/settings.json"
└── Note: This is a scaffold, not production-ready output (generate-and-customize contract). evals/ ships with one starter test + 3-5 seeded triggers; user fills the rest.
Stage 6: Diagnostics (REQUIRED)
MANDATORY: Write diagnostic output after every invocation. This cannot be skipped.
Stage 6: Diagnostics
├── Write to: $PROJECT_DIR/logs/diagnostics/create-skill-{YYYYMMDD-HHMMSS}.yaml
│ └── Use templates/diagnostic-output.yaml schema
└── Include:
├── Input: description/name/doc path
├── Interview: questions asked, rounds completed
├── Classification: all three decisions + template selected
├── Generation: files created, line counts, model used
├── Validation: pass/fail, findings count, retry count
└── Outcome: success/partial/failure
Error Handling
Scenario
Action
Generator sub-agent returns empty output
Re-spawn once with reinforced instructions. If still empty, STOP: "Generation failed. Please try with a more detailed description."
anthropic-validator finds critical issues
Stage 4 retry (max 2). After 2 retries, present with caveats.
anthropic-validator unavailable
Skip validation, note in diagnostics, warn user: "Validation skipped — run /anthropic-validator manually."
