skill-creator

name	skill-creator
description	Create new skills, modify and improve existing skills, sync skills across Claude Code, Codex, and CommandCode, and measure skill performance. Use when users want to create a skill from scratch, edit or optimize an existing skill, run evals, benchmark skill performance, improve trigger descriptions, or ensure a skill lives in claude-code-private and is exposed to all local agent runtimes.

Create, iterate, and optimize Claude Code skills through a draft → test → review → improve loop. Figure out where the user is in the process and help them progress. 1. **Capture intent** — understand what the skill should do 2. **Interview** — nail down edge cases, formats, dependencies 3. **Write SKILL.md** — following body conventions below 4. **Test cases** — 2-3 realistic prompts, save to `evals/evals.json` 5. **Run evals** — read `references/eval-pipeline.md`, spawn with-skill + baseline runs 6. **Evaluate** — generate benchmark + viewer, collect user feedback 7. **Improve** — revise skill, rerun evals (see eval-pipeline.md iteration loop) 8. **Repeat** until satisfied or feedback empty 9. **Optimize description** — read `references/description-optimization.md` 10. **Package** — deliver final skill with symlinks 11. **Runtime audit** — run coupling check, declare targets, fix or document issues 12. **Model recommendation** — declare the model tier the skill's task needs, flag delegation, tell the user (see ``)

<canonical_storage> Source of truth: ~/DEV/claude-code-private/skills/<category>/<skill-name>/SKILL.md

Symlink to all runtimes:

~/.claude/skills/<skill-name> -> ~/DEV/claude-code-private/skills/<category>/<skill-name>
~/.codex/skills/<skill-name>  -> (same target)
~/.commandcode/skills/<skill-name> -> (same target)

Slash commands: do NOT create by default. Create only when user explicitly asks, workflow needs stable command UX, or command orchestrates multiple skills.

If command needed: ~/DEV/claude-code-private/commands/<command>.md, symlink to ~/.claude/commands/ and ~/.commandcode/commands/.

Validate after creating: ls -l ~/.claude/skills/<skill-name> ~/.codex/skills/<skill-name> ~/.commandcode/skills/<skill-name> </canonical_storage>

<capture_intent> If conversation already contains a workflow to capture ("turn this into a skill"), extract from history first: tools used, step sequence, corrections, input/output formats.

Key questions:

1. What should this skill enable Claude to do?
2. When should it trigger? (phrases, contexts, file types)
3. Expected output format?
4. Test cases needed? (objective output → yes, subjective → optional)

Proactively ask about edge cases, formats, success criteria, dependencies. </capture_intent>

<skill_body_conventions> CRITICAL: defines how every SKILL.md body MUST be structured.

XML tags only. No markdown headings (##, ###) in body.

Required tags (minimum):

• <objective> — what the skill does, 1-3 sentences
• <success_criteria> — measurable conditions for success

Common tags: <workflow>, <inputs>, <output>, <boundaries>, <design_system>

Frontmatter vs body:

• Triggers/phrases → description: ONLY. Never repeat in body.
• "Why this skill exists" → nowhere. Description implies it.

Lean-prompt style: agent-facing content. Drop articles, fragments OK, → for causality. Read ~/.claude/skills/lean-prompt/SKILL.md before generating. Frontmatter description: stays matchable.

User input — portability rule: prefer Ask the user: [question] as a plain instruction over explicit AskUserQuestion tool calls. Plain instructions work in all runtimes (Claude uses AskUserQuestion naturally when appropriate; Codex asks conversationally). Reserve AskUserQuestion only when the structured option-selection UI is essential to the UX. If used, add a <codex_note>ask conversationally: "[question]"</codex_note> sibling tag.

Token budget: loaded every invocation.

• Under 200 lines: ideal
• 200-500: acceptable for complex skills
• Over 500: MUST split into router + references/

Instructions: imperative form. MUST/NEVER for critical rules. Each step says WHAT, not "handle appropriately". Explain WHY behind non-obvious rules.

Progressive disclosure (3 levels):

1. Metadata (name + description) — always loaded
2. SKILL.md body — loaded on trigger
3. references/ — loaded on demand </skill_body_conventions>

<skill_anatomy>

skill-name/
├── SKILL.md          (YAML frontmatter + XML body)
├── scripts/          (deterministic tasks)
├── references/       (on-demand docs)
└── assets/           (templates, fonts)

Frontmatter:

• name (required): kebab-case, 1-4 words, matches directory
• description (required): what + when + trigger words. Specific enough to not over-trigger, broad enough to not under-trigger.

Multi-variant skills: one SKILL.md router, variant refs in references/ (e.g., aws.md, gcp.md). </skill_anatomy>

<test_cases> After draft, create 2-3 realistic prompts. Share with user before running.

Save to evals/evals.json:

{
  "skill_name": "example-skill",
  "evals": [
    {"id": 1, "prompt": "User's task prompt", "expected_output": "Description", "files": []}
  ]
}

Full schema: references/schemas.md. </test_cases>

<blind_comparison> Optional A/B comparison. Read agents/comparator.md and agents/analyzer.md. </blind_comparison>

If `present_files` available: `python -m scripts.package_skill `

<runtime_audit> Step 11: after packaging, declare coupling level and fix or document issues.

Coupling levels:

• portable — no Claude-specific syntax; symlink-safe for all three runtimes
• lightly-coupled — some Claude syntax; symlink works but degrades in Codex/CommandCode
• Claude-locked — depends on Claude-only primitives; NEVER symlink into other runtimes without adaptation

Check for coupling patterns:

• AskUserQuestion → replace with plain "Ask the user: [question]" instruction (works everywhere)
• mcp__claude-in-chrome__*, mcp__claude_ai_* → Claude-only; move to a guarded block or document as Claude-only feature
• EnterPlanMode / ExitPlanMode → Claude-only; replace with inline planning prose
• TeamCreate / TeamDelete / shutdown_request → Claude-only; collapse to sequential steps
• present_files built-in → replace with Bash ls
• Hardcoded ~/.claude/ paths (outside of canonical_storage examples) → parameterize with $SKILLS_ROOT or relative path
• Explicit Skill-tool chaining ("Use the Skill tool to invoke...") → replace with direct CLI call

Actions:

1. If portable → log "✓ portable — safe for all runtimes" and confirm symlinks cover Claude, Codex, CommandCode
2. If lightly-coupled → fix what can be fixed in <30 min (AskUserQuestion, hardcoded paths); document the rest in a <runtime_targets> tag
3. If Claude-locked → add <runtime_targets>claude-code only</runtime_targets> to SKILL.md, skip Codex/CommandCode symlinks
4. If conversion needed → run polyskill build to generate per-runtime variants (CLI available at ~/DEV/tools/polyskill)

Add to SKILL.md frontmatter if lightly-coupled or Claude-locked:

runtime-targets: claude-code          # or: claude-code, codex, commandcode
coupling: lightly-coupled             # or: Claude-locked

The PostToolUse hook in this repo fires automatically on every SKILL.md write and runs the same checks — treat its output as a first-pass signal, not the final word. </runtime_audit>

<model_recommendation> Step 12: runtime audit answers WHERE the skill lives; this answers WHICH MODEL runs it. Classify the skill's own work by reasoning load and tell the user, so the model matches the task instead of defaulting to the most capable (and most expensive) one.

Tiers:

• haiku / sonnet — mechanical or bulk: scrape, reformat, rename, extract, tabulate, API glue, deterministic transforms. No deep judgment.
• sonnet — DEFAULT: structured work, classification, following clear conventions, most content/CRUD skills.
• opus — reasoning-heavy: architecture, ambiguous synthesis, first-principles judgment, adversarial review.

Delegation: if the skill spawns its own subagents or shells out, push the heavy mechanical work to a cheaper model or Codex, and keep only the judgment step on Opus. Mirror the create-workflow pattern: per-agent model override, not a whole-session upgrade.

Actions:

1. Declare the tier in frontmatter: recommended-model: sonnet (or haiku, opus, or sonnet, opus-for-<step>).
2. Tell the user the tier + a one-line why, e.g. "Mechanical scrape + reformat → runs fine on Sonnet, no need for Opus." </model_recommendation>

<environment_adaptations> Non-Claude-Code environments → read relevant reference before proceeding:

• Claude.ai: references/claude-ai.md
• Cowork: references/cowork.md </environment_adaptations>

Agents (read when spawning): - `agents/grader.md`, `agents/comparator.md`, `agents/analyzer.md`

References:

• references/schemas.md — JSON structures
• references/eval-pipeline.md — full eval + iteration mechanics
• references/description-optimization.md — trigger optimization loop
• references/claude-ai.md, references/cowork.md — environment adaptations

<success_criteria>

• SKILL.md: XML tags, no markdown headings, triggers in frontmatter only
• Under 500 lines (under 200 preferred)
• Test cases pass or user satisfied qualitatively
• Description triggers reliably
• Symlinks in place for declared runtime targets (not blindly for all three if Claude-locked)
• Coupling level declared (<runtime_targets> tag or frontmatter) for lightly-coupled/locked skills
• Model tier declared (recommended-model frontmatter) and stated to the user with a one-line reason; heavy mechanical work flagged for delegation
• AskUserQuestion replaced with conversational instruction where portability matters
• User approved final version </success_criteria>