Skill Creator

Skill Creator

A skill for creating new skills and iteratively improving them. The agent's context budget is the primary constraint, so this SKILL.md links out to focused reference files.

The core loop:

1. Decide what the skill should do and how it should do it
2. Write a draft
3. Run test prompts against claude-with-access-to-the-skill
4. Evaluate results with the user (qualitative review via eval-viewer/generate_review.py, plus quantitative evals)
5. Revise the skill based on feedback and benchmarks
6. Repeat until satisfied; expand the test set and try again at scale

Identify where the user is in this loop and jump in there. New skill from scratch → start at step 1. Existing draft → jump to step 3 or 4. User wants to vibe-iterate without formal evals → support that. After the skill stabilizes, optionally run the description improver to optimize triggering.

Two entry paths

The skill supports two distinct workflows. Identify which one the user is on before you do anything else — they don't share a starting step.

• Path A — Create a new skill from scratch. The user wants to capture a workflow, codify a pattern, or build a new capability. Start at "Creating a skill" below (Capture Intent → Interview → Write SKILL.md → Test → Eval).
• Path B — Improve an existing skill. The user points to a skill that already exists and wants it brought up to standard, fixed, optimized, or iterated based on eval feedback. Do not start with Capture Intent — the intent is already encoded in the existing SKILL.md. Start at "Improving an existing skill" below.

If the request is ambiguous ("can you look at this skill?"), assume Path B and confirm before interviewing as if it were new. Path B also fires when /skill-creator is invoked on a skill directory or file.

Both paths share the mandatory rules below: Repo Sync Before Edits, Dependency Preflight, Version Management, YAML Frontmatter Safety, and Frontmatter Audit on Review/Evaluation. Both close with the Run stats block. Both paths end at the same skill standard.

The skill standard (both paths)

One bar for a created skill and an updated one — references/skill-standard.md holds the detail:

• Gate 1 — must-pass floor. quick_validate.py clean, the Frontmatter Audit, body under 500 lines and 3000 words, a negative-trigger clause, version and author, the README notice, script errors, dependency preflight when another skill is invoked, and the five human-review checks.
• Gate 2 — asm-eval floor. overallScore > 85 AND min(categories) >= 8.

PASS only when both gates pass; anything else after the loop caps is a BLOCKER naming each failing check. Without asm on PATH, Gate 2 is not measured and the run never reports PASS. The predictability rubric stays advisory on both paths.

Step Completion Reports

After each major step, print a compact status block — √ pass, × fail, — context, a Criteria line, and a Result: PASS | FAIL | PARTIAL line — with checks tied to commands, file states, or counts. The block format and the per-phase checks (Intent Capture, Skill Writing, Testing, Iteration, Closing check) are in references/writing-guide.md → Step Completion Reports.

Run stats (mandatory)

Every run that creates or updates a skill closes its summary with a run-stats block — the last thing printed, after the final Step Completion Report. It reports what the run cost, and nothing the run already reported.

Capture run_started_epoch once, in the same shell as the skill's first command — cmd; ec=$?; date +%s >&2; exit "$ec" — reading the epoch off stderr so stdout and the exit code stay intact. Set it there, not later: without the anchor elapsed prints n/a, and the block still has to print on an early stop.

  ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
  Run stats   elapsed 6m 04s · tokens 128,400 · cost $0.42
              agents 3 · skills 1 · tool calls 47

Fields are fixed and in this order — never reordered, renamed, or added to: elapsed, tokens, cost, agents, skills, tool calls. Per-field formatting: references/run-stats.md.

• tokens and cost are omitted entirely when the host reported no figure — no dangling ·, no placeholder. Never estimate one, and never reconstruct one from host transcripts or logs.
• elapsed, agents, skills, and tool calls always print. A value that cannot be determined prints the literal n/a; 0 is a determined value and is correct where it is true (a run that spawned no subagents prints agents 0).
• A missing optional figure never suppresses the rest of the block.

Print it on every path that finishes a create or update — Path A, Subpath B1, Subpath B2, and Subpath B3 — and at every terminal outcome: a PASS, a BLOCKER, the Phase 0 early exit, a failed prerequisite, an aborted run. Only a run that produced no output at all has no block.

Communicating with the user

Users span a wide range of technical familiarity. Match jargon to context cues — terms like "JSON" or "assertion" need evidence the user knows them; briefly define terms when in doubt.

Mandatory Rule for Repo-Mutating Skills

When creating or updating any skill that changes files in a git repository (code, docs, config, commits, publishing), include this rule in that skill's SKILL.md:

• Add a "Repo Sync Before Edits (mandatory)" section near the top requiring branch="$(git rev-parse --abbrev-ref HEAD)"; git fetch origin && git pull --rebase origin "$branch" before modifications.
• If the working tree is dirty: stash, sync, then pop.
• If origin is missing or conflicts occur: stop and ask the user before continuing.

Do not ship repo-mutating skills without this pre-sync guardrail.

Mandatory Rule for Skills That Invoke Other Skills

Establish, for every skill you author or retrofit, whether it invokes, delegates to, or reads another skill. Ask it in the interview — Does this skill invoke other skills? is Capture Intent question 6 — and confirm the answer against the draft: prose naming /another-skill, or a read under ~/.claude/skills/, is a dependency even when the author said there were none.

• It does → declare each optional dependency in the frontmatter dependencies list and ship a ## Dependency Preflight (mandatory) section above the first step that changes anything. The main agent acquires only a dependency whose branch it reaches with asm deps acquire ... --session <caller-session-id>, uses the returned path directly, and releases the session in caller-owned finally/shutdown handling.
• It does not → add nothing. No empty preflight section, no "no dependencies" placeholder.

Read references/dependency-preflight.md for the copyable template and the on-miss behavior. The skill standard's Gate 1 checks this same rule on both paths, so a skill that ships without a required gate fails its closing check.

Frontmatter rules (mandatory)

Read references/frontmatter-rules.md for the full mandatory rules:

• Version Management — set metadata.version: 1.0.0 on creation; bump patch/minor/major on every edit.
• YAML Frontmatter Safety — double-quote any string value containing YAML-special characters (full list in the reference).
• Frontmatter Audit on Review/Evaluation — required-field check, name/dir match, allowed top-level keys, metadata.version, metadata.author, YAML safety, and consistency with docs/README.md. Run python scripts/quick_validate.py <skill-path> first; it catches mechanical issues without LLM reasoning.

These rules apply on every write. Always confirm them before saving.

Creating a skill

Capture Intent

Read references/intent-interview.md and work it top to bottom. It carries:

• The gate — a skill earns its place only when the workflow is repeated, non-obvious, and stable. Recommend against creating it otherwise; the user can override.
• The seven interview questions — purpose, triggers, the expected output format, test cases, subagents (including per-step context delegation), skill dependencies, and model-invoked vs. user-invoked (/skill-name is orchestration the user runs deliberately — a pipeline, or an expensive or destructive action they confirm first).
• Interview and research — edge cases, example files, success criteria, available MCPs.
• Branch mapping before drafting — name the distinct modes the skill runs in, so branch-specific material is disclosed only on the branch that uses it.

Extract what the conversation already answers before asking the user anything; they fill the gaps and confirm.

Write the SKILL.md

Before drafting, skim references/exemplars.md and imitate the archetype closest to this skill — workflow, knowledge, or orchestrator. Then, based on the user interview, fill in:

• name: 1-64 chars, lowercase letters/digits/hyphens, no consecutive hyphens, exactly matches parent directory. Enforced by scripts/quick_validate.py.
• description: When to trigger and what it does. Primary triggering mechanism. Single line, no newlines. Claude tends to undertrigger — make descriptions a little "pushy", with negative triggers.
• effort (optional): low | medium | high | xhigh | max. Defaults to high.
• metadata.version: Semver string (see frontmatter rules).
• compatibility: Required tools or dependencies (rare).

Writing a good description

Read references/description-guide.md for the full guide: the pushy + negative-triggers pattern (a "Don't use for ..." clause naming 2–3 adjacent domains), one trigger per branch, and the three length limits. The rule that bites first: target ≤250 characters — Claude Code's /skills listing truncates tail-first beyond that, chopping the negative-trigger clause. scripts/quick_validate.py warns (non-fatal) when the negative clause looks missing.

Skill Writing Guide

Read references/writing-guide.md for the full guide. It covers anatomy (where agents/, references/, scripts/, assets/, docs/ go), progressive disclosure and the 500-line SKILL.md cap, the Principle of Lack of Surprise, writing and workflow patterns, bundled-script error messages, Step Completion Reports, writing style, docs/README.md generation (references/readme-template.md), the 5-prompt test-case floor saved to evals/evals.json (references/schemas.md), and the pre-eval LLM validation phases (references/validation-prompts.md).

Write for execution and human review

Apply the controlled-language rules in references/writing-guide.md → Controlled instructions when drafting or revising instructions. Define a human-review output contract for every skill using references/human-review.md. Read that reference when choosing the output format or evaluating whether the user can understand the result. Apply these standards on both creation and improvement paths.

For skill-creator's own final response, state the skill changes, checks actually run, untested behavior, and any decision requiring approval. If no approval is needed, say so. Keep this concise; retain the Step Completion Reports and final Run stats block.