A rigorous 10-step methodology for creating expert-level Claude skills. Use when developing new skills that require deep domain expertise, when existing skills feel like 'instruction manuals' rather than expertise transfer, or when skills need systematic quality improvement. Implements the 4 Core Truths: Expertise Transfer (not instructions), Flow (not friction), Voice Matches Domain, and Focused Beats Comprehensive.
73%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Passed
No findings from the security scan
Fix and improve this skill with Tessl
tessl review fix ./SKILL.mdEvery decision in skill creation filters through these principles:
| Truth | What It Means |
|---|---|
| Expertise Transfer, Not Instructions | Make Claude think like an expert, not follow steps |
| Flow, Not Friction | Produce output, not intermediate documents |
| Voice Matches Domain | Sound like a practitioner, not documentation |
| Focused Beats Comprehensive | Constrain ruthlessly. Every section earns its place |
UNDERSTAND → EXPLORE → RESEARCH → SYNTHESIZE → DRAFT → SELF-CRITIQUE → ITERATE → TEST → FINALIZEBefore writing a single line, understand the domain deeply.
Define the skill's purpose with precision:
## Skill Definition Worksheet
**Skill Name**: _______________
**One-sentence purpose**: What does an expert do that Claude cannot do unaided?
**Success looks like**: Describe the ideal output a user would receive
**Failure looks like**: What happens without this skill?
**Target user says**: "I need Claude to _______________"Critical step. Actually test Claude without the skill:
Record failures in worksheets/exploration-log.md. These failures become your skill's requirements.
Become the expert (or consult one):
Sources: practitioner blogs, conference talks, Stack Overflow debates, expert interviews, professional standards documents.
Transform research into transferable expertise:
## Synthesis Output
**Mental Model**: How does an expert think about this problem space?
**Key Decisions**: What are the 3-5 critical decision points?
**Common Mistakes**: What do novices get wrong?
**Quality Markers**: How do you recognize excellent output?
**Vocabulary**: What terms must Claude use correctly?Use the template at templates/SKILL-TEMPLATE.md. Key principles:
Expertise Transfer, Not Instructions
# BAD (Instructions)
1. First, analyze the input
2. Then, identify the key elements
3. Next, apply the transformation
4. Finally, format the output
# GOOD (Expertise Transfer)
Think like a senior [domain] professional reviewing this for the first time.
Your instinct is to [key behavior]. Watch for [common pitfall] which
signals [underlying issue].Flow, Not Friction
# BAD (Friction)
Before proceeding, create a plan document outlining your approach.
Then create an analysis document. Then create your output.
# GOOD (Flow)
Produce the [output] directly. Internal reasoning happens silently.Voice Matches Domain
# BAD (Documentation voice)
The system shall process the input according to the specified parameters.
# GOOD (Practitioner voice)
When the data looks messy, trust the timestamps over the labels—
labels get copy-pasted wrong constantly.Focused Beats Comprehensive
Before including any section, ask: "If I delete this, does the skill get worse?" If uncertain, delete it.
Run through the Quality Checklist (references/quality-checklist.md):
Systematic improvement cycle:
Execute the skill against your original test cases from Step 2:
## Test Protocol
For each test case:
1. Use the skill exactly as written
2. Document: Did it produce expert-quality output?
3. If not: What went wrong? What's missing?
4. Update the skill based on findingsTest against edge cases practitioners would recognize but novices wouldn't anticipate.
Final structure optimization:
skill-name/
├── SKILL.md # Core expertise (under 500 lines)
├── references/ # Deep details loaded on-demand
│ ├── examples.md # Input/output pairs
│ └── edge-cases.md # Non-obvious situations
├── scripts/ # Reusable code
└── assets/ # Templates, images, etc.| Anti-Pattern | Why It Fails | Instead |
|---|---|---|
| Comprehensive coverage | Bloats context, buries signal | Ruthlessly focus on what Claude doesn't know |
| Step-by-step instructions | Creates mechanical following, not expertise | Transfer mental models and decision frameworks |
| Generic voice | Sounds like documentation | Use domain-specific vocabulary and reasoning |
| Intermediate artifacts | Wastes tokens on process, not output | Go directly to deliverable |
| "Best practices" lists | Too abstract to apply | Concrete examples of good vs. bad |
At every decision point, ask:
If any answer is wrong, revise.
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.