Skill Creator Primer

Skill Creator Primer

Note: If the skill-creator skill is missing: stop and ask the user to install skill-creator@claude-plugins-official (registering the marketplace first via /plugin marketplace add anthropics/claude-plugins-official if needed), or to clone https://github.com/anthropics/skills and link its skills directory into their local skills directory.

Route to an entry point by the task in front of you (which-one routing per "Routing when branches multiply", not a content index):

• Creating a new skill -> start at "Capture Intent from Conversation" and work forward.
• Editing an existing skill -> the sections covering what you're changing, then the "Self-Review Protocol".
• Reviewing a skill, or a diff to one -> "Reviewing a Skill".
• Tuning a description or its triggering -> "Writing Effective Descriptions".
• Producing a report, page or visual of a skill's findings -> references/html-report.md.

Predictable Process, Not Identical Output

A skill wrangles determinism out of a stochastic system where applicable. What it makes predictable is the process - the agent taking the same steps each run - not the output. A brainstorming skill should predictably diverge: its tokens vary, its behaviour doesn't. This is the lens for the rest of this primer: triggering, structure, steering, and pruning are all levers on process consistency; cost and maintainability follow. Judge any change by whether it makes the agent behave more consistently, given what that particular skill is for.

Track Each Step as a Task

Before you create, update, or review a skill, create a task (todo) for each step of the work - the primer sections you'll apply, plus a self-review pass - each phrased with its completion criterion, then work them to completion.

• This is the primer's own defence against premature completion: with the finish line in view, the agent tends to make the visible edit and skip the review. Tracked tasks keep the whole process in front of you.
• Scale the ceremony to the change: substantial skill work warrants a task per step; a trivial edit still earns its description update, a trigger-conflict check, and a self-review pass, tracked or not.

How Skills Actually Work

Skills are prompt-based context modifiers. When invoked, a skill:

1. Injects SKILL.md instructions into the conversation context
2. Modifies execution context by changing tool permissions and optionally switching models
3. Guides the agent's behaviour through concise instructions

Skill selection happens through pure LLM reasoning. No algorithmic matching, keyword search, or intent classification (the optional paths frontmatter, a file-glob gate, is the sole exception). The agent reads descriptions in the Skill tool's prompt and reasons about which matches. This makes the description field the single most critical element.

Branches decide what to disclose. Inline what every branch of the skill needs; push behind a context pointer (a bundled file) only what a single branch reaches. A pointer's wording, not its target, decides whether the agent follows it - a must-have target behind a weak pointer is a variance bug, so sharpen the wording before settling for inlining. When in doubt for this primer, keep almost-certainly-needed material inline so the agent never has to decide whether to read it.

Routing when branches multiply. When a skill fans out to many references, write the load decision as a decision tree: each branch a one-line qualifier, each leaf a reference pointer.

• Phrase the qualifier as the task's need, not the target's name - the agent routes by matching its task against it: "key-value (config, sessions, cache) -> references/kv.md".
• Keep the tree one level deep with mutually exclusive branches - every routing hop is a decision the agent can get wrong.
• Below a handful of references, skip the tree - plain pointers with sharp wording cost less than a routing layer.
• Trees carry which-one decisions only - reference material wants tables, sequences want numbered lists.

Invocation mode is a trade-off - choose it deliberately.

• Model-invoked: the description sits in the agent's context on every request and competes for attention, and the agent may decline to fire even a well-matched skill - so write trigger evals to confirm it fires (see "Testing Skill Triggering").
• User-invoked (disable-model-invocation: true): the description stays out of every agent session, but the user must remember the skill exists and trigger it with a slash command.

Default to model-invoked for mid-task discovery; switch to user-invoked when the skill is occasional and the user will reliably reach for it. When the right mode isn't obvious, give the user both options with a one-line pro/con each.

Skills vs Custom Agents

Before writing a skill, confirm a skill is the right vehicle:

• Skill - knowledge, a detailed workflow, or helper tools the agent loads on demand within its current context.
• Custom agent - a persona with its own context window and world view, carrying at most a lightweight workflow. Adversarial or fresh-perspective work (review, red-teaming, premise-checking) belongs here precisely because the separate context stops it inheriting the caller's assumptions.
• They compose - an agent can load skills, so shared knowledge still lives in a skill even when a persona needs its own context.

Prefer One Skill Over Many Closely Related Skills

When a request spans several related capabilities, default to a single skill that uses progressive disclosure rather than a separate skill per capability:

• Why one wins - every extra skill adds a description that is always in every agent's context, competes with the others at selection time, and risks overlapping triggers. This is skill bloat.
• How to consolidate - fold the related behaviours into one SKILL.md and push each one's detail into bundled references/ the agent loads on demand.
• When to split - only when the skills trigger on genuinely distinct intents or carry conflicting tool or permission needs.

Capture Intent from Conversation

When a user says "turn this into a skill", extract the workflow from the current conversation before asking questions. Look for:

• Tools used and the sequence of steps taken
• Corrections the user made along the way
• Input/output formats observed
• Patterns that repeated across the conversation

Fill gaps with the user, then proceed to skill creation.

Draft inside the primer's assets/skill-template.md: copy it into the new skill directory as SKILL.md, fill the placeholders, delete unused sections.

Writing Effective Descriptions

The description is the single most important part of a skill to get right. It shares a token budget with every other skill's description and is always active in the agent's context.

Skill Description Checklist

Create a task per item below, judge each pass/fail; done when all pass. Re-check the set after any edit - one fix can break another (an added clause can blow the word cap):

1. Be concise. Skills are for agent consumption; agents need clear, high-signal triggers, not verbose prose.
2. Keep it to 1-2 sentences. The validator's word cap is a ceiling, never a target to fill: the description is charged to every turn of every session whether it fires or not, so over-cap outranks anything in the body.
3. Descriptions are solely for the agent deciding whether to load the skill. No instructions for after activation, and no summary of the skill's content or inner workings - a workflow summary invites the agent to act on the summary and skip the skill's branches.
4. Ensure the description is distinct. It must not be confusable with neighbouring skills - similar names, the same verb/object, or overlapping situational triggers. The co-active set varies per deployment, so distinctiveness comes from a tight, specific trigger; when the neighbours are enumerable, run "Check for Description Trigger Conflicts" below.
5. Use imperative phrasing. Frame the description as an instruction to the agent: Use this skill when rather than This skill does. The agent is deciding whether to act, so tell it when to act.
6. Focus on user intent, not implementation. Describe what the user is trying to achieve, not the skill's internal mechanics. The agent matches against what the user asked for.
7. Front-load the leading word. The description is where a leading word does its invocation work, so lead with it. If the same word lives in the user's prompts, docs, and code, invocation lands harder.
8. One trigger per branch, no synonym padding. Give one trigger for each distinct branch the skill handles; synonyms that rename a single branch are duplication that spends context without widening coverage. Cut identity already stated in the skill body.
9. When a skill over-fires, add a negative-trigger exclusion clause. Name the neighbouring intent and where it belongs instead - "Do NOT use for X, use Y instead" - so the agent can route away from the skill as well as toward it.

Check for Description Trigger Conflicts

Two skills conflict when an agent, reading both descriptions, cannot reliably tell which one a request should load - that is the only thing this check looks for; skills covering related ground are fine. Run the check against the neighbours you can enumerate: the skills installed beside it, or the repo it is being contributed to.

To compare a new or edited description against a set of skills, list each skill's directory, name, and description:

python3 <skill-creator-primer>/scripts/list_descriptions.py <skills-root>

Group skills sharing a verb or object (create/edit, diagram, review, test), then compare pairwise for shared intent without a disambiguator - not merely shared words.

A pair is ACCEPTABLE when a clear disambiguator is present in the trigger:

• Different target tool, language, or file type - the agent routes on it. Intentional families on a shared template (go/rust/python: "activate when working on <language> projects") are fine; the language is the routing signal, so do not flatten it.
• Different phase or scope of the same activity (plan vs implement; one file vs the whole repo).
• One is a primer or sub-skill the other explicitly names.

A pair is a CONFLICT when:

• The triggers are interchangeable: either could match the same request equally.
• One description is a verbatim subset of the other with no added distinction.
• They claim the same activity on the same object with no routing signal between them.

ACCEPTABLE - near-identical wording, but the tool name routes cleanly:

mermaid-diagrams: "...creating or updating mermaid diagrams. Provides guidance on mermaid best practices." excalidraw-diagrams: "...create or update Excalidraw diagrams. Provides guidance on Excalidraw best practices."

CONFLICT - one trigger is a verbatim subset of the other, with no distinguishing "use when":

domain-model: "Grilling session that challenges your plan against the existing domain model. Use when user wants to stress-test a plan against their project's language..." grill-with-docs: "Grilling session that challenges your plan against the existing domain model..." (identical opening, no distinguishing trigger)

On a real conflict, pick the lightest fix: sharpen one description's "use when" to name what is distinct, narrow one skill's scope, or merge genuinely identical skills. Leave descriptions that already route cleanly alone, however alike they read.

Testing Skill Triggering

A skill activates purely on its description - the agent reads descriptions and reasons about which to load. To measure whether a description fires on the right requests and stays quiet on the rest - especially when over- or under-triggering is a risk - write trigger evals: realistic queries, each labelled with whether the skill should activate, scored against the live description.

Place an eval set at evals/<set>.json beside the skill and run it with the bundled scripts/eval_triggering.py. Read references/trigger-evals.md before writing or running skill evals.

Degrees of Freedom

Match specificity to the task's fragility and variability:

High freedom (text instructions): Multiple approaches valid, decisions depend on context, heuristics guide approach.

Medium freedom (pseudocode/parameterised scripts): Preferred pattern exists, some variation acceptable, configuration affects behaviour.

Low freedom (specific scripts, few parameters): Operations fragile and error-prone, consistency critical, specific sequence required.

Think of the agent exploring a path: a narrow bridge with cliffs needs guardrails (low freedom), an open field allows many routes (high freedom).

Skill Writing Tips

Selecting content

• Don't state the obvious. the agent already knows a lot about coding and has default opinions. Focus skill content on information that pushes the agent out of its normal way of thinking. If the agent would reliably do the right thing without your skill, that content is wasting tokens.
• Knowing is not doing. The test for cutting is not "does the agent know this?" but "would the agent reliably do this, in this order, every time, without being told?" Cut declarative knowledge that lives in training data (well-known APIs, design patterns, standard syntax) - it's recalled reliably. Keep required workflow: the agent may know each step yet still default to its own approach or skip the sequence unless the skill commits it. Enforcement, ordering constraints, gates, and checklists earn their tokens by changing what the agent does, not teaching it something new.
• Don't pre-document a tool's failures. Listing a validator's error codes so the agent can avoid them makes the skill responsible for the validator's changelog, and a partial list is worse than none - the agent reads the gaps as "not checked". Ship the run-and-read loop instead. When failures are expensive enough that pre-empting them is tempting, the fix is in the tool: add a mode that reports what is still owed, so the agent can ask instead of being told.
• Build a Gotchas section. The highest-signal content in any skill is a Gotchas section listing common failure points the agent hits when using the skill. Build this up from real failures over time. A good Gotchas section often delivers more value than pages of general instructions.

Structuring the skill

• Structure over prose. Write instructions as numbered steps or bullets, one action each, a single short sentence; reserve paragraphs for concepts. Prose buries the logic the agent has to act on. The same applies to frontmatter, argument-hint, and JSON-schema description fields: a few precise words, not a paragraph. Telegraphic fragments (dropped articles, error -> fix pairs) are fine for gotchas, checklists, and fact lists; avoid fragments where they'd blur a concept, sequence, or steering nuance. See the second pair under "Examples".
• Co-locate a concept's parts. Keep a concept's definition, rules, and caveats under one heading rather than scattered, so reading one part brings its neighbours. The test: a skill should read like documentation written for the agent. This differs from duplication (one meaning repeated in two places); scattering fragments a single meaning across many.
• Build with sub-agents in mind. Sub-agents parallelise independent work and keep bulky intermediate output out of the main conversation. Where steps could fan out (per-item passes, independent research questions, read-only sweeps), mark the hand-off: what each sub-agent needs and what it returns (a summary, verdict, or file path - not a raw dump). Suggest fan-out points rather than prescribing orchestration; the model running the skill may coordinate better than the one authoring it.
• Think through the setup. Some skills need user-specific configuration (e.g. which Slack channel, which database, API keys). Pattern: on first run, check for a config file; if missing, ask the user and store their answers. This avoids hardcoding values that differ per user or environment.
• Do not add inline scripts within markdown. Single commands / simple one liners are fine, but scripts should be their own files; the validator flags fenced blocks over 10 lines. When a skill bundles scripts, write them well (see "Writing Scripts" below).
• Avoid deeply nested references.
• For reference files (references/*.md) longer than 100 lines, include a concise table of contents at the top, so the agent sees the full scope even under partial reads.

Steering the agent

• Avoid railroading the agent. Skills are reused across many prompts and contexts, so overly rigid instructions (heavy MUSTs, exact step sequences) break when the context shifts. Give the agent the information it needs and leave flexibility to adapt. Calibrate prescriptiveness with "Degrees of Freedom" above.
• Avoid pink elephant guidance. Naming specific unwanted behaviour activates it ("Never use the word delve" plants delve). Prefer positive instructions stating the desired behaviour. If you must prohibit something, pair it with the concrete alternative so the agent has somewhere to land. Specific banned-item lists (e.g. exact phrases to avoid) are fine when paired with replacements.
• Steer with leading words. Pick one plain pretrained, meaning-dense term per concept and repeat it throughout (always "field", never a mix of "field", "box", "element"); the agent echoes the term in its reasoning and its prior steers behaviour - a coined term carries no prior. Read references/steering.md when a skill won't comply (ignored instruction, skipped or early-finished step), when choosing or strengthening a leading word, or when multi-step procedures need completion criteria - it covers leading words, completion criteria, and defending against premature completion.
• Make task-tracking the first step of any encoded workflow. Write the workflow's first step as an instruction to the agent: create a task (todo) per step, phrased with its completion criterion, then work them to completion - the same defence against premature completion this primer applies to itself (see "Track Each Step as a Task").

Writing Scripts

When a skill bundles scripts:

• Solve, don't punt. Handle error conditions in the script rather than failing and leaving the agent to improvise. A script that creates a missing file or falls back to a sensible default is more reliable than one that throws.
• No voodoo constants. Justify and document config values in a comment. If you can't explain why a timeout is 30s, the agent can't either.
• One-line header. A script's name, --help and code already say what it does; an opening comment block restating them is duplication that costs every reader. One line of purpose at the top; put the why (a non-obvious constraint, a chosen constant) beside the line it explains.
• Put usage in --help, not the skill. Give scripts named arguments and a --help that explains each one; the skill names the script and when to run it, and the agent reads --help for the rest. Argument prose in SKILL.md is always loaded and goes stale the first time the script changes.
• State execution intent. Make clear whether to run the script ("Run extract_fields.py to pull form fields") or read it as reference ("See extract_fields.py for the extraction algorithm"). Execution is usually preferred.
• Lean on the standard library; declare real deps inline. A stdlib-only script runs anywhere with no setup, so prefer it. When a script genuinely needs a third-party package, run it with uv and declare the dependency in PEP-723 inline metadata at the top of the script, so the dependency travels with the file.

Token Budget Guidance

Challenge each piece: "Does the agent need this, and does it justify its token cost?"

• Aim for <4k tokens in the main SKILL.md; move detailed content to references.
• A reference loads whole when its branch fires: many small branch-gated references are cheap; one huge reference costs its branch the full amount - split or thin it like an oversized SKILL.md.
• The quality bar (blobs, deletion test, failure modes) applies to every referenced file equally.
• The 4k aim assumes branchy content: when almost every activation needs almost every section, a larger SKILL.md is the correct trade, judged by the deletion test rather than the count (this primer qualifies; see "Branches decide what to disclose").
• Measure with the bundled validator (see "Validating a Skill").

Examples

Good example (concise, actionable):

## Extract PDF text

Use pdfplumber for text extraction:

`python scripts/extract_pdf_text.py <pdf-file>`

Bad example (verbose, wrapped):

## Extract PDF text

PDF (Portable Document Format) files are a common file format that contains
text, images, and other content. To extract text from a PDF, you'll need to
use a library. There are many libraries available for PDF processing, but
pdfplumber is recommended because it's easy to use and handles most cases well.
First, you'll need to install it using pip. Then you can use the code below...

Good example (instructions as structure):

1. Run the skill's evals if present.
2. On failure, tune the description and re-run.

Bad example (the same instructions, buried in prose, wrapped):

When you begin the review you should first check whether the skill has evals,
and if it does, run them before anything else, keeping in mind that failures
may mean the description needs tuning, in which case you should revisit it
and run them again.

Bundled File Layout

Standardise where bundled files live so skills stay predictable across the toolkit:

• references/ - Markdown the agent reads as reference (the loaded-on-demand layer of progressive disclosure).
• scripts/ - executable scripts the agent runs.
• assets/ - templates the agent copies or fills in, plus non-text artefacts like SVGs and icons. Prefer referencing these from an external source over committing them; bundled binaries add weight and context overhead with no benefit to the agent.
• CHANGELOG.md - a skill is a non-code project, so date headings (## YYYY-MM-DD, newest first), no version numbers. Keeps the skill's history out of the body (see "Fossilised diff"). The update rule goes in both the file's <!-- AI agents: ... --> comment and the skill's own CLAUDE.md: log reader-visible changes only, one line each, squash same-day edits. If a changelog-setup skill is available, use it.
• When references/ spans many sibling domains, give each domain the same file set (e.g. <domain>/patterns.md, <domain>/gotchas.md, omitting any that would be empty) so the agent knows what exists at the next level without reading an index.