/skill-creator

name: skill-creator
description: "Create and iteratively improve skills through eval-driven validation."
agent: toolkit-governance-engineer
routing:
  force_route: true
  triggers:
    - create skill
    - create a skill
    - create new skill
    - new skill
    - scaffold skill
    - scaffold a skill
    - build a skill
    - skill template
    - skill design
    - test skill
    - improve skill
    - optimize description
    - skill eval
  not_for: "comparing or evaluating existing agents (use agent-comparison skill) — this skill scaffolds new skills from scratch"
  pairs_with:
    - agent-evaluation
    - verification-before-completion
  complexity: Complex
  category: meta
allowed-tools:
  - Read
  - Edit
  - Write
  - Bash
  - Glob
  - Grep
  - Agent

Skill Creator

Create skills and iteratively improve them through measurement.

Output style directive (applies to every generated skill/agent)

Generated SKILL.md and agent bodies must be written as **dense informational text focused on accuracy**. Minimize prose, maximize signal, no filler.

• No motivational framing, no pep talk, no "this will help you...".
• No repeated restatement of the same constraint in different words.
• Prefer tables, numbered phases, and bullet lists over paragraphs.
• Every sentence must carry information the model will act on; cut anything

that is only atmosphere.

• Explanations of "why" stay short and attached to the rule they justify --

one clause, not a paragraph.

New and edited skill files are written to the **Dense-Complete Writing standard**: `skills/shared-patterns/dense-complete-writing.md`. That file is the canonical rule; the bullets above are its application to skill scaffolding.

This is a generation constraint on the outputs of this skill, not a style note for this skill's own prose. Enforce it during the "Write the SKILL.md" phase and during any agent scaffolding.

The process:

• Decide what the skill should do and how it should work
• Write a draft of the skill
• Create test prompts and run claude-with-the-skill on them
• Evaluate the results -- both with agent reviewers and optionally human review
• Improve the skill based on what the evaluation reveals
• Repeat until the skill demonstrably helps

Figure out where the user is in this process and help them progress. If they say "I want to make a skill for X", help narrow scope, write a draft, write test cases, and run the eval loop. If they already have a draft, go straight to testing.

---

Creating a skill

Capture intent

Start by understanding what the user wants. The current conversation might already contain a workflow worth capturing ("turn this into a skill"). If so, extract:

1. What should this skill enable Claude to do? 2. When should this skill trigger? (what user phrases, what contexts) 3. What is the expected output? 4. Are the outputs objectively verifiable (code, data transforms, structured files) or subjective (writing quality, design aesthetics)? Objectively verifiable outputs benefit from test cases. Subjective outputs are better evaluated by human review.

Duplicate Domain Check

Before creating any new skill, check whether an existing umbrella skill already covers this domain. This is mandatory -- skipping it leads to system prompt bloat and routing degradation.

**Step 1**: Search for existing domain coverage.

grep -i "<domain-keyword>" skills/INDEX.json
ls skills/ | grep "<domain-prefix>"

**Step 2**: If a domain skill exists, determine whether the new skill's scope is a sub-concern of the existing skill. Sub-concerns MUST be added as reference files on the existing skill, not created as separate skills.

Pattern (correct): `skills/perses/references/plugins.md` Incorrect (creates domain overlap): `skills/perses-plugin-creator/SKILL.md`

**Step 3**: If no domain skill exists and the domain has multiple sub-concerns, create the skill with a `references/` directory from the start.

**One domain = one skill + many reference files. Never create multiple skills for the same domain.**

Only proceed to writing a new SKILL.md if no existing skill covers the domain, or if the user explicitly confirms creating a new skill after reviewing the overlap.

Research

Read `docs/PHILOSOPHY.md` before writing any component. The philosophy contains binding architectural decisions — not suggestions — that govern how agents carry knowledge, how skills structure workflows, how references are organized, and how content is framed. Components that violate the philosophy will fail review.

Read the repository CLAUDE.md before writing anything. Project conventions override default patterns.

Write the SKILL.md

Based on the user interview, create the skill directory and write the SKILL.md.

**Skill structure:**

skill-name/
├── SKILL.md              # Required -- the workflow
├── SPEC.md               # Optional -- contract for complex/high-impact skills
├── EVAL.md               # Optional -- repeatable eval cases for complex/high-impact skills
├── scripts/              # Deterministic CLI tools the skill invokes
├── agents/               # Subagent prompts used only by this skill
├── references/           # Deep context loaded on demand
└── assets/               # Templates, viewers, static files

**Maintenance artifacts** -- For Complex skills, security-sensitive skills, router-facing skills, PR/release workflows, and skills likely to be iterated over time, create `SPEC.md` and `EVAL.md` alongside SKILL.md:

• `SPEC.md`: purpose, scope, non-goals, invariants, dependencies, and success

criteria. It is the contract maintainers use when changing the skill.

• `EVAL.md`: representative prompts/cases, expected routing or behavior,

known failure modes, and pass/fail checks. It is the regression suite for skill behavior.

Do not create `SOURCES.md` as a standard artifact. Provenance belongs in docs, ADRs, citations, or research files when it matters. If the LLM does not need the fi