QBall-Inc Create Skill
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" |
DO NOT use for:
- Editing existing skills (edit directly)
- Creating standalone sub-agents (use
create-subagent) - Debugging skill issues (use
issue-debugging) - Validating existing skills (use
anthropic-validator)
Dependencies
| Category | Files | Requirement | When to Load |
|---|---|---|---|
| Decision framework | references/decision-framework.md |
REQUIRED | Load at Stage 0 for interview + classification |
| Content guidance | references/content-guidance.md |
REQUIRED | Include in Stage 2 generator prompt |
| Skill templates | references/template-*.md |
REQUIRED | Load the matching template at Stage 2 |
| Agent template | references/agent-template.md |
REQUIRED | Include in Stage 2 prompt when archetype = Pipeline |
| Agent conventions | references/agent-conventions.md |
REQUIRED | Include in Stage 2 prompt when archetype = Pipeline |
| Diagnostic template | templates/diagnostic-output.yaml |
REQUIRED | Use at Stage 6 |
| Subagent prompting | subagent-prompting skill |
REQUIRED | Load at Stage 0 for 4-part prompt template |
| Eval shape | references/eval-shape.md |
REQUIRED when scaffolding evals/ data |
Schema for evals.json / triggers.json / compliance.json (Layer 1 DATA) |
| Eval scaffolding | references/eval-scaffolding.md |
REQUIRED | Per-archetype emission guide for Stage 2 — defines default grading_mode, assertion templates, sub-pattern × eval impact, placeholder substitution markers |
| Scripts conventions | references/scripts-conventions.md |
REQUIRED when bundles_scripts = true (Stage 1) |
Per-skill scripts/ directory invocation convention (${CLAUDE_PLUGIN_ROOT} pattern), Justfile recipe pattern, bun runtime prerequisite |
| Eval grader agent | agents/skill-eval-grader.md |
Bundled (no external load) | 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.
Usage
/create-skill <description-or-name>
/create-skill --doc <requirements-document>
/create-skill --from-template <archetype> <skill-name>
Arguments:
<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 0 — Pre-Flight: Arguments parsed (description, name, --doc, or --from-template)
- Stage 0 — Pre-Flight: Decision framework and content guidance loaded
- Stage 0 — Pre-Flight: If
--from-template <archetype> <name>: archetype validated against 7-set; interview SKIPPED; defaults loaded - Stage 0 — Pre-Flight: Else: Adaptive interview conducted (1-2 rounds via AskUserQuestion)
- 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_moderesolved 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_scriptsresolved (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.jsonandevals/triggers.jsonscaffolded per references/eval-scaffolding.md (always) - Stage 2 — Generate:
evals/compliance.jsonscaffolded if grading_mode = subjective (Research, Inversion, or override) - Stage 2 — Generate: Sub-pattern × eval impact applied per references/eval-scaffolding.md → Sub-Pattern × Eval Impact
- Stage 2 — Generate:
scripts/.gitkeepscaffolded 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.mdinvoked via Bash (E.1 description quality gate — exits 1 on multi-line / over-length) - Stage 3 — Validate:
just check-skill-size {working-directory}/SKILL.mdinvoked via Bash (E.3 tiered cap enforcement — exits 1 on hard cap with refactor proposal) - Stage 3 — Validate:
/anthropic-validatorinvoked via Skill tool (manual review is NOT a substitute) - Stage 3 — Validate: If Pipeline archetype —
/anthropic-validatorinvoked on each sub-agent file - Stage 3 — Validate: Validator output read and findings counted
- Stage 3 — Validate: Manual checks completed (single-line description, no unnecessary files)
- Stage 3 — Validate: Cross-file consistency check completed — if skill bundles
templates/,references/, orscripts/, 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 5 — Deploy & Present: Post-generation summary presented with architectural decisions
- Stage 5 — Deploy & Present: If Pipeline archetype — sub-agent permissions communicated
- Stage 5 — Deploy & Present: Next steps communicated (this is a scaffold, not production-ready output)
- Stage 6 — Diagnostics: Diagnostic YAML written to
$PROJECT_DIR/logs/diagnostics/
Pipeline
// create-skill pipeline
PreFlight(args) // Stage 0: Orchestrator — parse input, adaptive interview
|> Classify(interview_answers) // Stage 1: Orchestrator — three independent decisions
|> Generate(classification, template, examples) // Stage 2: Sonnet sub-agent — produce skill files
|> Validate(generated_output) // Stage 3: Orchestrator — run anthropic-validator
|> Refine(validator_findings) // Stage 4: Sonnet sub-agent (conditional, max 2 retries)
|> DeployAndPresent(working_dir, target_dir) // Stage 5: Orchestrator — deploy to target + post-generation summary
|> Diagnostics() // Stage 6: Orchestrator — write YAML
Stage Definitions
Stage 0: Pre-Flight (Orchestrator)
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." |
| Interview answers are ambiguous | Ask 1-2 follow-up questions (max 2 AskUserQuestion rounds total). |
| User requests Agent Teams | Include experimental warning: "Agent Teams requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. This is an experimental feature." |
| Token budget exceeded | Stop at current stage, present partial output with explanation. |
| Target directory already exists | AskUserQuestion: "Directory {path} already exists. Overwrite / Choose different name / Cancel?" |
| Working directory already exists | Silently remove and recreate tmp/create-skill/{skill-name}/ (working dirs are ephemeral) |
| User rejects classification | Re-classify with user's feedback. Max 2 classification rounds. |
Token Budget Management
| Checkpoint | Threshold | Action |
|---|---|---|
| After Pre-Flight | >30% consumed | Warn: "Pipeline agents will consume significant context." |
| After Generate | >55% consumed | Warn: "Approaching budget. Validation + refinement may be limited." |
| After Validate | >65% consumed | Skip refinement if needed, present as-is with caveats. |