Skill Creator

Skill Creator

Create, evaluate, and iterate on high-quality agent skills. This skill covers the whole lifecycle: planning what the skill should do, writing SKILL.md and reference files, scoring quality against a rubric, and iterating until the skill meets production standards.

Philosophy: A great skill is precise, not long. Its description routes the right requests to it. Its body gives the model the context it can't get anywhere else — the environment, tool contracts, defaults, domain judgment, and the reasons behind each constraint — and leaves out what a capable model already does on its own. Current Claude models follow instructions closely and literally, so every line gets acted on: an over-scripted or shouting skill produces rigid, over-cautious output, while a clear goal and quality bar let the model plan the work itself. references/writing-guide.md covers this in detail.

Runtime adaptation: Skills that touch external tools should detect what is installed, authenticated, and reachable at runtime and adapt, rather than assuming a single method. Offer fallback paths where real alternatives exist. See references/dynamic-calling.md for the pattern catalog.

Step 1: Understand What the User Wants

Classify the request into one of these modes:

If ambiguous, ask: "Do you want to create a new skill, improve an existing one, or evaluate one?"

Gather Requirements (for Create mode)

Before writing anything, answer these questions (ask the user if unclear):

Step 2: Plan the Skill Architecture

Before writing SKILL.md, plan the structure. Read references/architecture-patterns.md for detailed guidance on each pattern.

Choose a Structural Pattern

Plan the Outline

Every skill has three parts:

1. Setup / detection — detect available tools, auth state, and runtime environment, and decide which method to use. Skills with no external dependencies can skip this.
2. The work — numbered steps where the order genuinely matters (fetch before compute, a gate that can end the analysis), plus the judgment the model has to exercise, stated as goals, criteria, and domain heuristics rather than a script.
3. Respond to the user — the output contract: what the answer leads with, what it must contain, which caveats apply, and any verdict scale.

If a skill needs more than about nine steps, split it or use the Router pattern.

Plan the Detection Flow

Skills that touch external tools should start with a runtime detection flow. Read references/dynamic-calling.md for all patterns. The detection flow answers:

The detection output feeds a decision tree that the rest of the skill follows — check rather than assume.

Plan Reference Files

Decide what goes in SKILL.md vs references/:

Step 3: Write the SKILL.md

Read references/writing-guide.md for detailed instructions on writing each section. Read references/frontmatter-guide.md for the complete YAML field reference.

Key Rules

1. Frontmatter first: name (lowercase-hyphenated, max 64 chars) and description (max 1024 chars, no angle brackets) are required. The description is routing text that rides along in every request: say what the skill does, name the categories of requests it serves and the distinctive vocabulary users will use (methods, tools, data types, entities), and point to sibling skills for neighboring requests. Name intent categories instead of listing near-synonymous phrasings.

2. Detection flow for external dependencies: use !command`` probes with fallback sentinels to detect tools, auth state, and runtime, then route to a method. Offer a second path where a real alternative exists (CLI vs Python library vs built-in tool). See references/dynamic-calling.md.

3. Match specificity to fragility: give exact commands, flags, and code for fragile operations — installs, auth, CLI syntax, API contracts, calculations that must be right. For judgment work — analysis, interpretation, writing — state the goal, the criteria, and the domain heuristics, and let the model plan. Put a pass/fail gate wherever a failed check really ends the analysis.

4. Defaults table: give every parameter the user might omit an explicit default, so the skill never stalls waiting for input.

5. Output contract in the final step: what to lead with, what the answer must contain, which caveats apply, and any verdict or grade scale. Pin a section-by-section template only where the format itself matters (scorecards, widgets, checklists). Describe length qualitatively rather than with word or sentence counts, and label examples as illustrative rather than filling them with made-up figures for real companies.

6. Plain register: state each constraint once, with its reason. Leave out capitalized MUST/NEVER/CRITICAL, repeated warnings, and instructions current models follow by default ("be thorough", "think step by step", "double-check your answer") — they cause over-triggering and over-checking rather than better work. Keep real policy constraints (read-only, no trade execution, privacy) in plain words.

7. Keep volatile facts honest: fetch live data where you can, date-stamp anything that will go stale, and keep dated datasets in references/. Verify API names and response shapes against the current library before shipping.

See references/skill-examples.md for annotated examples of each pattern.

Step 4: Write Reference Files

Read references/writing-guide.md for the full reference file authoring guide.