skill-creator-primer

Files (18)

• CHANGELOG.md
• CLAUDE.md
• SKILL.md
• skill-template.md · assets/
• trigger.json · evals/
• html-report.md · references/
• steering.md · references/
• trigger-evals.md · references/
• ruff.toml
• eval_triggering.py · scripts/
• hook_report_skill_tokens.py · scripts/
• list_descriptions.py · scripts/
• render_report.py · scripts/
• report_assets.py · scripts/
• report_model.py · scripts/
• validate_skill.py · scripts/
• test_render_report.py · tests/
• test_validate_skill.py · tests/

SKILL.md (first lines)

# 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

Before drafting, settle:

- **Scope** - ask the user whether the skill owns the task asked for or the outcome above it ("fix this crash" vs "keep the app crash-free"). Owning the outcome needs access: list the data sources, environments and mappings the agent needs to act and verify unaided.
- **Method** - for the skill's domain, answer: what a top practitioner does that the user didn't ask for; the rawest material they start from; the methods and tools they use; what, other than the agent, shows the result is right. Encode the answers as steps (see "Persona over method" and "Self-grading" in Failure Modes).

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:

```bash
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:

From sammcj/agentic-coding, Apache-2.0.

More from sammcj/agentic-coding