Skill Creator Guide.

# Skill Creator

A skill for creating new skills and iteratively improving them.

At a high level, the process of creating a skill goes like this:

- Decide what you want the skill to do and roughly how it should do it
- Write a draft of the skill
- Create a few test prompts and run them to see what Claude does
- Evaluate the results both qualitatively and quantitatively
- Rewrite the skill based on feedback
- Repeat until you're satisfied
- Expand the test set and try again at larger scale

Your job when using this skill is to figure out where the user is in this process and then jump in and help them progress through these stages.

---

## Creating a skill

### Capture Intent

Start by understanding the user's intent. The current conversation might already contain a workflow the user wants to capture (e.g., they say "turn this into a skill"). If so, extract answers from the conversation history first.

1. What should this skill enable Claude to do?
2. When should this skill trigger? (what user phrases/contexts)
3. What's the expected output format?
4. Should we set up test cases to verify the skill works?

### Interview and Research

Proactively ask questions about edge cases, input/output formats, example files, success criteria, and dependencies. Wait to write test prompts until you've got this part ironed out.

### Write the SKILL.md

Based on the user interview, fill in these components:

- **name**: Skill identifier (lowercase, hyphenated)
- **description**: When to trigger, what it does. Include both what the skill does AND specific contexts for when to use it. Make the description slightly "pushy" — Claude tends to under-trigger skills.
- **the rest of the skill body**: Full instructions in markdown.

---

## Anatomy of a Skill

```
skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description required)
│   └── Markdown instructions
└── Bundled Resources (optional)
    ├── scripts/    - Executable code for deterministic/repetitive tasks
    ├── references/ - Docs loaded into context as needed
    └── assets/     - Files used in output (templates, icons, fonts)
```

Skills use a three-level loading system:
1. **Metadata** (name + description) — Always in context
2. **SKILL.md body** — In context whenever skill triggers (keep under 500 lines)
3. **Bundled resources** — As needed

---

## Writing Patterns

Use the imperative form in instructions.

**Defining output formats:**
```markdown
## Report structure
ALWAYS use this exact template:
# [Title]
## Executive summary
## Key findings
## Recommendations
```

**Examples pattern:**
```markdown
## Commit message format
**Example 1:**
Input: Added user authentication with JWT tokens
Output: feat(auth): implement JWT-based authentication
```

### Writing Style

- Explain the why behind everything you're asking the model to do
- Use theory of mind — make the skill general, not narrow to specific examples
- If you find yourself writing ALWAYS or NEVER in all caps, try reframing with reasoning instead
- Keep the prompt lean. Remove anything that isn't pulling its weight.

---

## Test Cases

After writing the skill draft, come up with 2-3 realistic test prompts — the kind of thing a real user would actually say.

Run each test case with the skill active. Compare results with and without the skill.

---

## Improving the skill

### How to think about improvements

1. **Generalise from the feedback.** Don't put in narrow or overfitted changes. If there's a stubborn issue, try different metaphors or patterns of working.

2. **Keep the prompt lean.** Remove things that aren't pulling their weight. Read the transcripts — if the skill is making Claude waste time on unproductive steps, remove those parts.

3. **Explain the why.** Try to understand what the user actually needs and transmit that understanding into the instructions.

4. **Look for repeated work across test cases.** If all test cases result in Claude writing the same helper script, bundle that script in scripts/ and tell the skill to use it.

---

## Description Optimisation

The description field is the primary mechanism that determines whether Claude invokes a skill. After creating or improving a skill, optimise the description for better triggering accuracy.

### Generate trigger eval queries

Create 20 eval queries — a mix of should-trigger and should-not-trigger:

```json
[
  {"query": "the user prompt", "should_trigger": true},
  {"query": "another prompt", "should_trigger": false}
]
```

For **should-trigger** queries (8-10): different phrasings of the same intent — some formal, some casual. Include cases where the user doesn't explicitly name the skill but clearly needs it.

For **should-not-trigger** queries (8-10): near-misses — queries that share keywords with the skill but actually need something different.

### Review and iterate

Test the current description against these queries. Note failures. Rewrite the description to improve accuracy. Repeat until triggering is reliable.

---

## How skill triggering works

Skills appear in Claude's available_skills list with their name + description. Claude decides whether to consult a skill based on that description alone.

Key insight: Claude only consults skills for tasks it can't easily handle on its own. Simple, one-step queries may not trigger a skill even if the description matches perfectly. Complex, multi-step, or specialised queries reliably trigger skills when the description matches.

This means your eval queries should be substantive enough that Claude would actually benefit from consulting a skill.

---

## The core loop

1. Figure out what the skill is about
2. Draft or edit the skill
3. Run test prompts with the skill active
4. Evaluate outputs — compare with and without the skill
5. Improve the skill based on what failed
6. Repeat until the skill is working well
7. Optimise the description for triggering accuracy
8. Package the final skill