Skill creator

Skill Creator

A skill is a reusable, opinionated expert guide that makes an AI agent dramatically better at a specific domain. Not a prompt. Not a template. A skill is a production-grade system that encodes deep domain expertise, principled workflows, concrete examples, and an unambiguous definition of done — so the agent executes it the same way every time, without the user having to re-explain.

Your job in this skill is to help the user go from "I want a skill for X" to a skill that works reliably in the real world.

---

Skill Creator Principles

• Understand before writing. A skill written without understanding the user's intent produces generic instructions that could apply to anything. Ask the right questions first.
• Skills generalize — test cases are just accelerants. You iterate on 3–5 examples because it's fast. But the skill needs to work on the 10,000th prompt that nobody has seen yet. Avoid overfitting rules to the specific examples.
• Explain the why, not just the what. Instructions that say "always do X" without explanation get followed blindly in the wrong context. Instructions that say "do X because Y" get applied with judgment. Smart models respond better to reasoning than to commandments.
• Lean beats padded. Remove every instruction that isn't actively improving outputs. A 600-line skill where 200 lines are filler produces worse results than a tight 300-line skill where every line earns its place. If you find yourself writing ALWAYS/NEVER in all caps, step back — try explaining the reasoning instead.
• The description field is a trigger, not a summary. The description is what the agent reads to decide whether to load the skill. It must contain explicit trigger conditions: "Use when the user asks to..." — not just what the skill is about.
• Test against reality, not intuition. You cannot know if a skill works without running it. Gut-feel improvements compound errors. Run test cases. Look at the outputs. Iterate on evidence.

---

The Skill Creation Loop

Understand intent
       ↓
Write draft skill
       ↓
Run test prompts → review outputs
       ↓
Improve skill based on feedback
       ↓
Repeat until quality is satisfactory
       ↓
Optimize description for triggering accuracy
       ↓
Ship

Jump into this loop wherever the user is. If they already have a draft, skip to testing. If they're still fuzzy on intent, start at understanding. Always be flexible — if they want to skip evals and iterate by feel, that's a valid choice.

---

Phase 1: Capture Intent

If the user says "turn this workflow into a skill"

Read the conversation history. Extract:

• What tools or steps were used
• What corrections the user made along the way (these reveal requirements that weren't stated)
• What the final output looked like
• What the user seemed satisfied with

Then confirm:

It looks like this skill is about [X]. It should:
1. [Core step 1]
2. [Core step 2]
3. Produce [output type]

Does that match what you have in mind? Anything I'm missing?

If the user is starting from scratch

Ask up to 5 focused questions — not all at once, unless the user is clearly experienced:

1. What is the one job this skill does? Name it in a single sentence.
2. Who triggers it? What does a user say or do that should activate this skill?
3. What does the output look like? A document, code, analysis, structured data?
4. What does "good" look like? What separates a 10/10 output from a 6/10?
5. What does "bad" look like? What specific failure modes must this skill avoid?

If the user is non-technical, avoid terms like "JSON", "assertions", "eval pipeline" — use plain language equivalents:

• "test cases" not "evals"
• "checking the results" not "running assertions"
• "try it on some examples" not "benchmark"

---

Phase 2: Write the Draft Skill

Required SKILL.md Structure

Every skill must have this structure, in this order:

---
name: skill-name-in-kebab-case
description: [See description rules below]
---

# Skill Title

[Opening paragraph: mindset and approach. What kind of expert does this well and why does their approach produce better outcomes.]

---

## [Skill Name] Principles

[5–8 load-bearing beliefs. These are the "why" behind the entire skill.
Each principle should be a thing that, if violated, produces a noticeably worse output.
Not rules. Beliefs. The agent applies judgment from principles — not from rule-lookup.]

---

## Step 0: Ground the Work Before Starting

[What to establish, ask, or read before taking any action.
This section prevents the skill from diving in before understanding the situation.
The most common failure mode in any skilled domain is premature action.]

---

## [Main execution sections]

[The workflow, patterns, templates, examples, code snippets.
Each section should have a clear job. If a section's purpose is unclear, cut it or merge it.]

---

## Definition of Done

[Checkbox checklist. Every item must be:
- Verifiable — the agent or user can confirm it is met
- Specific — no vague items like "quality looks good"
- Necessary — if removing the item wouldn't affect quality, remove it]

Description Field Rules

The description field is the most important line in the file. It determines when the skill gets loaded.

Rules:

• Maximum 2 sentences
• Must include explicit trigger conditions: "Use when the user asks to...", "Use when the user mentions..."
• Must name the domain + the specific action, not just the domain
• Must distinguish this skill from adjacent skills

Bad description:

Helps with writing documents.

Good description:

Structured co-authoring workflow for PRDs, design docs, RFCs, and proposals.
Use when the user wants to write a PRD, design doc, RFC, or any structured
document where quality and completeness matter — goes deeper than general
writing help by guiding through context gathering, section refinement,
and reader testing.

Template:

[What it does — domain + specific action + key method].
Use when the user [trigger condition 1], [trigger condition 2], or [trigger condition 3].

---

Phase 3: Write Test Cases

Write 3–5 test prompts that a real user would send. These should:

• Cover the core use case (what the skill is for)
• Cover at least one edge case (unusual input, partial information)
• Cover at least one failure-adjacent case (something that sounds like the skill's domain but isn't quite)
• Use realistic language — not "test the skill on a widget factory", but something a real user in the target audience would actually type

Test case format:

## Test Cases — [Skill Name]

### Test 1: Core use case
**Prompt:** [Realistic user prompt]
**Expected output:** [What a good response looks like]
**Pass criteria:**
- [ ] [Specific, checkable criterion]
- [ ] [Specific, checkable criterion]

### Test 2: Edge case
**Prompt:** [Edge case prompt]
**Expected output:** [What a good response looks like]
**Pass criteria:**
- [ ] [Criterion]

### Test 3: Failure-adjacent
**Prompt:** [Something that might accidentally trigger the skill but shouldn't, or should trigger a graceful handling]
**Expected output:** [What the skill should do here]
**Pass criteria:**
- [ ] [Criterion]

---

Phase 4: Run and Review

After writing the draft skill and test cases:

1. Run each test prompt with the skill active
2. Read the full output — not just whether it looked OK, but whether every pass criterion was met
3. Look for patterns across test cases:
   • Did the agent do the same unnecessary thing on every test? The skill is probably prompting it.
   • Did the agent skip the same important step on every test? The skill is missing something.
   • Did the outputs vary wildly in quality? The skill's instructions are ambiguous.

Qualitative Review Questions

For each test output, ask:

• Does the output match what a domain expert would produce?
• Is anything present that shouldn't be? (filler, repetition, unnecessary preamble)
• Is anything missing that should be? (the skill's core value-add)
• Did the agent explain its reasoning at the right level, or was it either too shallow or too verbose?
• Would the target user be satisfied with this output? Why or why not?

---

Phase 5: Improve the Skill

How to think about improvements

Generalize, don't overfit. If the skill only works on the 3 test cases and nobody else's prompts, it's useless. When fixing a problem that appeared in a specific test case, ask: "Is this a specific fix or a general principle?" Prefer general principles.

Read the execution trace, not just the output. The most revealing information is the process the agent followed. Did it take a pointless detour? Did it repeat itself? Did it do something that wasn't in the skill instructions but should have been? The trace tells you what to add or remove.

Remove before adding. Before adding a new instruction, check if the problem can be fixed by removing an instruction that is creating the wrong behavior. Shorter is usually better.

When you find yourself writing ALWAYS or NEVER in all caps: Pause. Ask if you can explain the underlying principle instead. "ALWAYS check X" → "Check X because Y will fail if you don't — the most common failure mode in this domain is Z". The second version produces better judgment.

Common improvement patterns

Problem observed	Likely cause	Fix
Agent starts with a long preamble every time	Step 0 asks too many questions	Tighten Step 0 to only essential questions
Output quality varies wildly	Principles are vague	Make each principle concrete with an example of what violating it looks like
Agent skips a critical step	Step not in the skill	Add it with an explanation of why it matters
Agent does something unhelpful on every test	Skill instructions cause it	Remove or reframe the instruction
Output is technically correct but feels wrong	Missing voice/tone guidance	Add a "How to write" section with examples
Agent over-explains its process	Skill says to explain everything	Add "show your work only when it adds value for the reader"

---

Phase 6: Optimize the Description

After the skill body is solid, optimize the description for triggering accuracy.

The description has two jobs:

1. Load when it should — the agent recognizes the right moment to invoke it
2. Not load when it shouldn't — the agent doesn't mistakenly invoke it for adjacent tasks

Description optimization process

1. Write 5 prompts that should trigger this skill
2. Write 5 prompts that should not trigger this skill (but are close)
3. Read your description and check: does it distinguish between the two sets?
4. Rewrite until it does

Example — doc-coauthoring description optimization:

Should trigger:

• "Help me write a PRD for the new payments feature"
• "I need to draft a design doc for the auth refactor"
• "Can you help me write up a technical spec?"

Should NOT trigger (close but different):

• "Write a quick Slack message about the deployment" → use internal-comms
• "Update the README with the new API endpoints" → use technical-writer
• "Summarize this design doc for me" → general task, no skill needed

Revised description: adds "PRD, design doc, RFC" explicitly + "goes deeper than general writing help" to distinguish from technical-writer.

---

Phase 7: Final Quality Gate

Before declaring the skill done, run this checklist:

Skill body quality

• Opening paragraph establishes the mindset — not just "what it does" but "how an expert approaches it"
• 5–8 principles that are genuinely load-bearing (removing any one would degrade outputs)
• Step 0 grounds the work before any action — prevents premature execution
• All main sections have a clear, named purpose
• Examples are realistic — not widget factories or foo/bar placeholders
• Code snippets (if any) are correct and runnable
• Definition of Done has ≥ 8 specific, verifiable, necessary items
• No ALWAYS/NEVER all-caps commandments — reasoning used instead
• Minimum 200 lines — if shorter, the skill probably lacks depth

Description quality

• ≤ 2 sentences
• Names the domain + the specific action
• Contains explicit trigger phrases: "Use when the user asks to..."
• Distinguishes this skill from the 2–3 most similar skills
• Tested against 5 should-trigger and 5 should-not-trigger prompts

Test quality

• At least 3 test cases written
• Core use case covered
• At least 1 edge case covered
• Pass criteria are specific and checkable — not "output looks good"
• All 3 test cases pass at an acceptable quality level

---

Skill File Location

Save new skills at:

SKILL/<skill-name>/SKILL.md

Skill name rules:

• lowercase-kebab-case
• Describes the role not the task: database-architect not write-sql
• Unique — check existing skills before naming

---

Quick Reference: The 5 Signs of a Good Skill

1. You can name its single job in one sentence — if you need two sentences, it's two skills
2. The description triggers on the right prompts and not on the wrong ones
3. The principles explain the why, not just the what
4. Step 0 prevents the #1 failure mode in this domain
5. The Definition of Done is a checklist you can actually check — every item is specific and verifiable