Expertise Distiller

Expertise Distiller: Principle-Driven Skill Design

This skill guides you through creating skills that transfer expertise, not just list instructions.

The 4 Core Truths

Every skill you create must embody these principles:

When to Use This Skill

Use this skill when:

• Creating a new skill from scratch
• A skill isn't performing well and needs rethinking
• You want to understand why certain patterns work
• You need to make tough trade-offs about what to include

Don't use this for:

• Quick iterations on working skills (use the standard skill-creator)
• Just packaging an existing skill (use packaging scripts directly)

The 10-Step Process

UNDERSTAND the problem
    ↓
EXPLORE Claude's failures  
    ↓
RESEARCH domain expertise
    ↓
SYNTHESIZE principles
    ↓
DRAFT the skill
    ↓
SELF-CRITIQUE rigorously
    ↓
ITERATE on feedback
    ↓
TEST on real scenarios
    ↓
FINALIZE structure
    ↓
PACKAGE for distribution

1. UNDERSTAND → What skill? What problem?

Start by crystallizing the core need:

• What specific capability gap exists? (Not "documentation" but "Claude rewrites the same 50-line parsing script every time")
• What does success look like? (Concrete examples of before/after)
• Who benefits and how? (Time saved? Quality improved? Consistency achieved?)

Good examples:

• "Engineers spend 20 minutes each time formatting API responses to match our schema"
• "Claude generates valid SQL but doesn't know our table relationships"
• "We need Claude to follow our 47-point brand guidelines without a wall of text"

Bad examples:

• "Make Claude better at X" (too vague)
• "Help with documents" (too broad)

Output: A crisp problem statement you could explain in 30 seconds.

2. EXPLORE → See where Claude fails without guidance

Critical step - don't skip this. You need to observe the failure mode, not imagine it.

Try the task without the skill: 1. Give Claude a representative request 2. Note where it struggles, hesitates, or produces suboptimal output 3. Try 3-5 variations to see if it's consistent

Document:

• What did Claude do wrong?
• What knowledge was it missing?
• What did it waste time on?
• When did it ask for clarification vs. guess?

Example observations:

• "Claude generated working code but used pandas when our stack is polars"
• "Claude wrote a 200-line form instead of using our 10-line template"
• "Claude asked what format we wanted - it should know we always use ISO 8601"

Why this matters: You're designing for actual failure modes, not theoretical ones. This prevents over-specifying (wasting tokens) or under-specifying (skill doesn't help).

3. RESEARCH → Go deep on the domain

Now that you know what fails, understand why success looks like and what experts know.

For technical domains:

• What mental models do experts use?
• What are the key decision points?
• What patterns repeat across scenarios?
• What's stable vs. what varies?

For workflow domains:

• What's the expert's internal checklist?
• What do they check for quality?
• What shortcuts do they know?
• What mistakes do novices make?

Research sources:

• Interview domain experts
• Review high-quality examples
• Read practitioner documentation (not beginner tutorials)
• Analyze your own expert behavior

Output: A list of insights that would make Claude competent, not just capable.

4. SYNTHESIZE → Extract principles from research

Transform observations into teachable principles.

Pattern recognition:

• What do all good examples have in common?
• What varies based on context?
• What rules have exceptions? (Document both)
• What can be expressed as "if X then Y"?

Compression:

• Can 5 bullet points become 1 principle?
• Can 3 examples show a pattern?
• Can a decision tree replace prose?

Example synthesis:

Raw research:
- Example 1 uses indentation for hierarchy
- Example 2 uses bullet points for parallel items
- Example 3 uses numbered lists for sequences
- Example 4 combines all three appropriately

Synthesized principle:
"Match structure to meaning: indent for hierarchy, bullets for parallelism, numbers for sequence."

Output: Distilled principles that transfer expertise, not just information.

5. DRAFT → Write initial skill

Now you can draft. Structure using progressive disclosure:

skill-name/
├── SKILL.md          # Core workflow + principles (<500 lines)
│   ├── YAML frontmatter (name, description)
│   └── Essential instructions
├── references/       # Deep knowledge (loaded as needed)
│   ├── patterns.md
│   └── examples.md
├── scripts/          # Executable code
│   └── helper.py
└── assets/           # Templates, not documentation
    └── template.json

Frontmatter:

---
name: skill-name
description: >
  What the skill does + when to trigger it. Be specific about use cases.
  Good: "Process medical transcripts following HIPAA guidelines, including
  de-identification and structured output formatting."
  Bad: "Help with medical documents."
---

SKILL.md structure:

# Skill Name

[One paragraph: what problem this solves]

## Core Approach

[The mental model - how an expert thinks about this domain]

## When [Most Common Scenario]

[Direct instructions using imperative form]
[Include only essential decision points]
[Reference detailed guides in references/ as needed]

## When [Second Most Common Scenario]

[...]

## Quality Checks

[What good output looks like - help Claude self-evaluate]

Key drafting principles:

1. Imperative mood: "Extract text" not "You should extract text" 2. Example over explanation: Show one good example > describe in prose 3. Decision points explicit: "If X then Y, otherwise Z" 4. Offload detail: "See references/advanced.md" not "here's 500 words" 5. Quality criteria: Help Claude know when it's done

6. SELF-CRITIQUE → Review against quality criteria

Now be ruthlessly critical. For each section, ask:

Expertise Transfer Test:

• [ ] Does this make Claude think like an expert or just act like one?
• [ ] Would a domain expert recognize this approach?
• [ ] Are we teaching patterns or prescribing steps?

Flow Test:

• [ ] Can Claude go straight to output?
• [ ] Do we force intermediate artifacts Claude doesn't need?
• [ ] Would an expert work this way?

Voice Test:

• [ ] Does this sound like domain documentation or AI instructions?
• [ ] Would a practitioner say "execute step 3" or just do it?
• [ ] Are we narrating process or enabling work?

Focus Test:

• [ ] Can we delete this section and still succeed? (If yes, delete it)
• [ ] Is this addressing observed failure modes? (If no, question it)
• [ ] Could this be a one-line reference instead?

Token Efficiency Test:

• [ ] Would this information surprise Claude? (If no, cut it)
• [ ] Is this stable knowledge vs. variable context?
• [ ] Should this be in SKILL.md or references/?

Progressive Disclosure Test:

• [ ] Do we force-load information Claude might not need?
• [ ] Can variations go in separate reference files?
• [ ] Are scripts documented or just executable?

Red flags:

• Phrases like "you should", "make sure to", "don't forget"
• Apologetic language: "This might seem complex but..."
• Meta-commentary: "The next step is to..."
• Over-specification: Dictating every detail when heuristics suffice
• Under-specification: Vague guidance on fragile operations

7. ITERATE → Fix gaps, get feedback, improve

Testing approaches:

1. Yourself: Use the skill on real scenarios - note friction 2. Others: Have someone else try it - watch where they struggle 3. Claude: Have Claude use it - monitor for confusion or errors

Feedback loop:

Use skill → Note issue → Hypothesis on why → Update skill → Test again

Common improvements:

• Too much guidance: Claude over-thinks → Trust Claude more, delete text
• Too little guidance: Claude guesses wrong → Add decision framework
• Wrong abstraction: Scenarios don't map cleanly → Reorganize around real patterns
• Missing context: Claude lacks key info → Move knowledge from your head to references/

Iteration triggers:

• Claude asks questions that the skill should answer
• Output quality varies unexpectedly
• Claude ignores parts of the skill
• You find yourself adding ad-hoc instructions in chat

8. TEST → Use skill on a real scenario

Final validation with a realistic task:

1. Pick a task that's representative but not used during design 2. Use the skill as if you're a new user 3. Document:

• Did it work on first try?
• Where did Claude hesitate?
• What did you need to clarify?
• Was anything missing?
• Was anything unused?

Success criteria:

• Claude produces quality output without ad-hoc guidance
• The skill handles expected variations naturally
• Token usage is reasonable (<2000 tokens loaded typically)
• Claude doesn't ask questions the skill should answer

9. FINALIZE → Codify into optimal structure

Polish for production:

SKILL.md:

• Remove TODOs and draft artifacts
• Verify all references exist and are linked
• Ensure imperative mood throughout
• Trim any remaining cruft

References:

• Organize by use case (not by type)
• Add grep-able patterns for large files
• Include only what Claude might need

Scripts:

• Test thoroughly
• Include docstrings (Claude might read them)
• Consider: should this be a reference instead?

Assets:

• Only include files that are used in output
• Remove examples/samples unless they're templates

Validation:

# Use the packaging script - it validates automatically
scripts/package_skill.py /path/to/skill-folder

10. PACKAGE → Share the skill

Once validated:

# Creates skill-name.skill file
scripts/package_skill.py /path/to/skill-folder /output/directory

The .skill file is a zip with a .skill extension containing your complete skill structure.

Common Skill Patterns

High-Level Guide with Deep References

When: Complex domain with many variations

SKILL.md:

## Core workflow

[Essential steps + decision points]

For detailed guidance:
- **Pattern library:** See references/patterns.md
- **Full examples:** See references/examples.md  
- **API reference:** See references/api.md

Benefit: SKILL.md stays focused; Claude loads depth only when needed

Script-Heavy with Minimal Instructions

When: Fragile operations requiring exact execution

SKILL.md:

## Rotating PDFs

Use scripts/rotate_pdf.py:

\`\`\`bash
python scripts/rotate_pdf.py input.pdf --angle 90 --output rotated.pdf
\`\`\`

The script handles edge cases and validation.

Benefit: Deterministic, token-efficient, no "reinventing the wheel"

Template-Based with Examples

When: Output follows a strict format

SKILL.md:

## Report format

ALWAYS use this structure:

# [Title]

## Executive Summary
[One paragraph]

## Key Findings  
- Finding 1 [with data]
- Finding 2 [with data]

## Recommendations
1. Specific action
2. Specific action

Benefit: Claude produces consistent output without guessing

Anti-Patterns to Avoid

Degrees of Freedom Framework

Match instruction specificity to task fragility:

High Freedom (General Guidance)

• Use when: Multiple valid approaches exist
• Format: Principles + examples
• Example: "Write engaging product copy"

Medium Freedom (Preferred Patterns)

• Use when: Best practices exist but context varies
• Format: Decision framework + examples
• Example: "Structure SQL queries for readability"

Low Freedom (Exact Execution)

• Use when: Operations are fragile or compliance-critical
• Format: Scripts or strict templates
• Example: "Fill IRS tax forms"

Working with Existing Skills

To improve a skill:

1. Use it on real tasks - note where it fails 2. Check: Is this a skill problem or wrong use case? 3. Run through EXPLORE phase again 4. Apply targeted fixes (resist full rewrites) 5. Test that fixes don't break existing use cases

To merge skills:

Only if they share 80%+ overlap. Otherwise keep separate - Claude can use multiple skills.

To split a skill:

When SKILL.md exceeds 500 lines or covers truly distinct workflows. Split at natural boundaries, update descriptions.

Quick Reference: Skill Creation Checklist

• [ ] Problem clearly defined with concrete examples
• [ ] Observed Claude's actual failure modes (not assumed)
• [ ] Researched domain to extract expert mental models
• [ ] Synthesized principles, not just collected facts
• [ ] SKILL.md under 500 lines
• [ ] Description is specific about when to trigger
• [ ] Imperative mood throughout
• [ ] Progressive disclosure: SKILL.md → references → scripts
• [ ] Every section justified by observed need
• [ ] Tested on realistic scenarios
• [ ] No README, CHANGELOG, or meta-docs
• [ ] Packaged and validated

References

For detailed patterns:

• Workflow patterns: See the standard skill-creator's references/workflows.md
• Output patterns: See the standard skill-creator's references/output-patterns.md

Tools

Use the standard skill-creator scripts:

• scripts/init_skill.py - Initialize skill structure
• scripts/package_skill.py - Validate and package
• scripts/quick_validate.py - Check structure only

Final Wisdom

The best skill is the one that disappears. When Claude uses it, it should feel like Claude "just knows" how to do the task - not like it's following a manual.

If your skill makes Claude sound like it's reading instructions, you've created friction. If Claude sounds like a domain expert who happens to have expertise in this area, you've transferred expertise.

That's the difference.

Diagnosing and Fixing Skill Problems

When a skill isn't working well, the issue usually falls into one of these categories.

Problem: Claude Ignores Parts of the Skill

Symptoms

• Skill is loaded but Claude doesn't follow guidance
• Claude asks questions the skill should answer
• Output quality is inconsistent

Diagnosis

Why does Claude ignore instructions?
├─ Too much text → Claude skips walls of text
├─ Wrong abstraction → Instructions don't map to actual task
├─ Buried information → Key info hidden in middle
└─ Conflicting guidance → Multiple valid interpretations

Fixes

If text wall:

❌ Bad:
## Formatting Guidelines
When formatting documents, you should ensure that all headers 
are properly capitalized and that... [500 words]

✅ Good:
## Format Standards
- Headers: Title case
- Lists: Parallel structure  
- See references/style-guide.md for edge cases

If wrong abstraction:

❌ Bad (organized by file type):
## For JSON files
[instructions]
## For YAML files  
[instructions]

✅ Good (organized by task):
## When validating config
[applies to JSON, YAML, TOML]
## When generating config
[applies to JSON, YAML, TOML]

If buried information:

❌ Bad:
We recommend various approaches depending on context. 
Sometimes it's useful to consider alternative methods, 
especially when... [critical info in paragraph 3]

✅ Good:
**Critical: Always validate inputs before processing**

Context and alternatives: [...]

---

Problem: Claude Asks Too Many Questions

Symptoms

• Constant "should I..." or "what format..." questions
• Claude hesitates on decisions it should make
• Flow is interrupted by clarifications

Diagnosis

Why the questions?
├─ Missing decision criteria → No framework for choices
├─ False choices → Offering options that have defaults
├─ Uncertainty language → "Consider" without clear defaults
└─ Under-specified → Genuinely ambiguous requirements

Fixes

If missing decision criteria:

❌ Bad:
"Choose an appropriate data structure"

✅ Good:
**Data structure selection:**
- <1K items, frequent lookup → dict
- >1K items, frequent insertion → deque
- Need ordering + uniqueness → OrderedDict
- Default if unsure → list (it's fine)

If false choices:

❌ Bad:
"Would you like me to include error handling?"

✅ Good:
"Always include error handling. Use try/except for I/O, 
check for None on optional params."

If uncertain language:

❌ Bad:
"You might want to consider adding tests"

✅ Good:
"Include tests for:
- Edge cases (empty, single item, max size)
- Error conditions
Skip tests for: obvious getters/setters"

---

Problem: Output Quality Varies Unexpectedly

Symptoms

• Sometimes great, sometimes poor
• Different users get different results
• Hard to predict when it works

Diagnosis

What causes inconsistency?
├─ Context-dependent behavior → Works for some inputs only
├─ Missing examples → Claude guesses format
├─ Vague quality criteria → "Good" means different things
└─ Hidden assumptions → Works when Claude happens to guess right

Fixes

If context-dependent:

❌ Bad:
"Generate appropriate documentation"

✅ Good:
**Documentation by context:**

API functions:
\`\`\`python
def process(data: List[str]) -> Dict:
    """
    Args: data - Non-empty list of strings
    Returns: Dict with keys 'processed', 'failed'
    Raises: ValueError if data is empty
    """
\`\`\`

Internal helpers: Brief docstring only
\`\`\`python
def _normalize(s: str) -> str:
    """Convert to lowercase, strip whitespace"""
\`\`\`

If missing examples:

❌ Bad:
"Create a well-structured report"

✅ Good:
**Report format (use exactly):**

# [Title]

## Summary  
[2-3 sentences with key finding]

## Recommendations
1. [Specific action] - Expected impact: [X]
2. [Specific action] - Expected impact: [Y]

See references/report-examples.md for 5 complete examples

If vague quality criteria:

❌ Bad:
"Ensure high code quality"

✅ Good:
**Code quality checklist:**
- [ ] No magic numbers (use constants)
- [ ] Functions <50 lines (split if larger)
- [ ] Error messages include context
- [ ] No commented-out code in final version

---

Problem: Skill Works But Wastes Tokens

Symptoms

• Skill loads 2K+ tokens every time
• Much of loaded content is unused
• Context fills up quickly

Diagnosis

Why the bloat?
├─ Everything in SKILL.md → Should split to references
├─ Verbose explanations → Claude already knows basics
├─ Repeated examples → One example + pattern > many examples
└─ No progressive disclosure → Everything loads upfront

Fixes

If everything in SKILL.md:

❌ Bad: 800-line SKILL.md with all info

✅ Good:
SKILL.md (200 lines):
## Core workflow
[Essential steps]

## Detailed references
- **API patterns:** references/patterns.md
- **Full examples:** references/examples.md  
- **Troubleshooting:** references/debug.md

Claude loads references only when needed

If verbose explanations:

❌ Bad:
"A function is a reusable block of code that performs a 
specific task. Functions are important because they help 
organize code and reduce repetition..."

✅ Good:
"Use functions for repeated logic (>2 times)"

If repeated examples:

❌ Bad: 10 examples showing slight variations

✅ Good: 
**Pattern:**
\`\`\`
[Type] [Name]: [Description]
- Key point 1
- Key point 2
\`\`\`

**Examples:**
Feature Login: Adds OAuth authentication
- Implements token refresh
- Includes session management

Fix ProfilePage: Corrects avatar upload bug  
- Validates image format
- Adds error messaging

---

Problem: Claude Reinvents Solutions

Symptoms

• Claude writes code that scripts should handle
• Redoes work on every invocation
• Ignores provided scripts/templates

Diagnosis

Why not using resources?
├─ Scripts unclear → Doesn't know what they do
├─ Scripts fragile → Doesn't trust them
├─ Templates hidden → Doesn't know they exist
└─ Instructions unclear → Doesn't know when to use them

Fixes

If scripts unclear:

❌ Bad:
"See scripts/ for utilities"

✅ Good:
**PDF operations (use scripts, don't rewrite):**

Rotation: `python scripts/rotate_pdf.py input.pdf 90`
Merging: `python scripts/merge_pdfs.py file1.pdf file2.pdf`  
Forms: `python scripts/fill_form.py template.pdf data.json`

These scripts handle edge cases and validation.
Writing custom PDF code usually introduces bugs.

If templates hidden:

❌ Bad:
"Templates are in assets/"

✅ Good:
**Component templates (copy and customize):**

\`\`\`bash
cp assets/react-component-template.tsx components/MyComponent.tsx
\`\`\`

Template includes:
- TypeScript types
- Props interface  
- Basic styling structure
- Standard exports

Modify the template, don't write from scratch.

If instructions unclear:

❌ Bad:
"Use the template when appropriate"

✅ Good:
**When to use vs. write from scratch:**

Use template when:
- Standard CRUD operation
- Follows existing patterns
- <50 lines of custom logic

Write from scratch when:
- Novel integration
- Complex state management
- Template would need 50%+ changes

---

Diagnostic Process

When a skill isn't working:

1. Observe failure mode

• What specifically goes wrong?
• Is it consistent or intermittent?
• Which part of the skill is involved?

2. Form hypothesis

• Which category above?
• What evidence supports it?
• What would disprove it?

3. Test with minimal change

• Change one thing
• Try the task again
• Did it improve, worsen, or stay same?

4. Iterate

• If better: commit change, look for similar issues
• If worse: revert, try different hypothesis
• If same: hypothesis was wrong, try different category

---

Prevention: Design Patterns That Work

These patterns reduce common problems:

Decision framework pattern:

## When [Scenario A]
[Specific guidance]

## When [Scenario B]  
[Specific guidance]

## When unsure
[Safe default]

Quality checklist pattern:

Before finishing:
- [ ] [Specific criterion]
- [ ] [Specific criterion]
- [ ] [Specific criterion]

Progressive detail pattern:

## Quick start (most common case)
[Minimal viable guidance]

## Advanced scenarios
See references/advanced.md for:
- [Specific scenario]
- [Specific scenario]

Script-first pattern:

## [Task name]

\`\`\`bash
python scripts/task.py [args]
\`\`\`

Script handles: [what's automated]  
You provide: [what needs customization]

Manual approach only if: [specific exception]

---

Quick Diagnostic Questions

When skill isn't working, ask:

1. Is Claude reading it? Check: Is skill triggered? Add logging in thinking.

2. Is it too much? Check: Token count. If >500 in SKILL.md, likely too much.

3. Is it too little? Check: Does Claude ask for information skill should provide?

4. Is it wrong level? Check: Are instructions for novices when Claude is advanced?

5. Is it the right structure? Check: Do sections map to how Claude needs to think?

Most problems fall into one of the five categories above. Start there before rewriting.

Example Skill: Commit Messages

This is a minimal but complete skill demonstrating the four core truths.

The Skill

---
name: commit-messages
description: Generate clear, contextual git commit messages following conventional commits format. Use when writing commits, reviewing commit history, or explaining changes in git workflows.
---

# Commit Messages

Write commits that communicate intent, not just what changed.

## Format

[type]([scope]): [subject]

[body - optional but recommended for non-trivial changes]

## Type Selection

**Think about impact:**

fix → Code is broken, now it works  
feat → Users can do something new
refactor → Same behavior, better internals
perf → Same behavior, measurably faster
docs → Changed documentation only
test → Changed tests only
chore → Build/tooling, not affecting users

If uncertain: `feat` for additions, `fix` for corrections, `refactor` for changes

## Subject Line Rules

**Imperative mood:** "Add feature" not "Added feature" or "Adds feature"
**No period:** Subjects are titles, not sentences
**50 chars:** Force clarity

Bad: "Updated the user authentication system to use JWT tokens instead of sessions"
Good: "feat(auth): replace session auth with JWT"

## Body (When to Include)

Skip body for:
- One-line changes
- Obvious modifications  
- Isolated fixes

Include body when:
- Change affects multiple areas
- Context isn't obvious from diff
- Breaking changes or migrations

Body structure:
- What changed (if not obvious)
- Why (most important)
- Side effects or considerations

## Examples

**Feature:**

feat(api): add rate limiting to public endpoints

Implements token bucket algorithm with 100 req/min limit. Prevents abuse while allowing normal usage patterns. Redis stores rate limit state across instances.

**Bug fix:**

fix(reports): correct timezone conversion in date filters

UTC timestamps were compared to local datetime objects, causing off-by-one errors for users in negative UTC zones.

**Refactor:**

refactor(db): replace ORM queries with raw SQL for reports

ORM generated inefficient joins causing 5s+ response times. Raw SQL with proper indexing reduces to ~200ms.

**Trivial change:**

docs: fix typo in README installation section

## Quality Check

Before committing, ask:
- Can someone understand what I did without seeing the diff?
- Is the type accurate for the impact?
- Would I understand this in 6 months?

---

Analysis: How This Skill Demonstrates Core Truths

Truth 1: Expertise Transfer, Not Instructions

What it does:

• Teaches thinking: "Think about impact" when choosing type
• Includes why: "Force clarity" for 50-char limit
• Shows trade-offs: When to skip vs include body

What it doesn't do:

• List steps: "Step 1: Choose type, Step 2: Write subject..."
• Over-explain: Doesn't explain what git commits are
• Dictate: Doesn't mandate every field always

Expert recognition: A senior engineer would say "yes, that's how I think about commits"

Truth 2: Flow, Not Friction

What it does:

• Direct to output: Type → subject → body → commit
• No intermediate artifacts: Doesn't say "first make a plan"
• Contextual decisions: "If X, skip body; if Y, include it"

What it doesn't do:

• Force planning: "Before writing, create an outline..."
• Require verification: "Now review your commit message..."
• Add ceremony: "Fill out this commit template..."

Flow check: User goes from "I made changes" to "I have a good commit" with no stops

Truth 3: Voice Matches Domain

What it does:

• Developer language: "off-by-one errors", "ORM generated joins"
• Natural phrasing: "Code is broken, now it works"
• Tool-specific context: "Redis stores rate limit state"

What it doesn't do:

• Meta-narration: "You should write commits that..."
• AI-speak: "According to best practices..."
• Over-formality: "It is recommended that one should..."

Voice check: Reads like internal developer documentation, not AI instructions

Truth 4: Focused Beats Comprehensive

Token count: ~500 words in full skill

What it includes:

• Type selection (non-obvious, Claude might guess wrong)
• Subject line rules (specific constraints)
• When to include body (decision framework)
• 4 complete examples (showing patterns)

What it excludes:

• Git basics (Claude knows how to use git)
• Why commits matter (not needed for task execution)
• Advanced features like trailers (rarely used)
• Team-specific conventions (those go in custom skills)

Focus check: Every section addresses a decision point or common mistake

---

What Makes This Skill Effective

1. Loaded only when relevant

• Description triggers on "commit", "git", "changes"
• ~500 words total, reasonable token cost
• No references needed (domain is small enough)

2. Decisions are clear

• Type selection has framework, not exhaustive list
• "If uncertain" fallback provided
• Examples show pattern, not every variation

3. Respects intelligence

• Doesn't explain what git is
• Doesn't list every commit type
• Trusts Claude to apply patterns

4. Sound like practitioner

• "Force clarity" not "brevity is important"
• "Code is broken, now it works" not "repairs defects"
• Shows real scenarios with technical context

5. Enables flow

• Read skill → write commit → done
• No "now review", "now edit", "now verify"
• Includes quality check, but as self-check not gate

---

Contrast With Poor Version

For comparison, here's what this skill might look like without the core truths:

❌ Poor Version:
---
name: commit-messages
description: Help with git commits
---

# How to Write Git Commit Messages

Git commit messages are important for tracking changes in your codebase. This guide will help you write good commit messages.

## What is a Commit Message?

A commit message is text that describes the changes you made in a commit. It helps other developers (and your future self) understand what you did and why.

## Steps to Write a Commit Message

1. First, think about what you changed
2. Then, decide on an appropriate type
3. Write a short subject line describing the change
4. If needed, write a longer body explaining the details
5. Review your message to make sure it's clear
6. Make any necessary edits
7. Finally, commit your changes

## Types of Commits

Here are all the types you might use:

- feat: A new feature
- fix: A bug fix  
- docs: Documentation changes
- style: Formatting, no code change
- refactor: Code restructuring
- perf: Performance improvement
- test: Adding tests
- build: Build system changes
- ci: CI configuration changes
- chore: Other changes
- revert: Reverting a commit

You should choose the type that best matches your change.

## Subject Line

The subject line should be clear and concise. Try to keep it under 50 characters if possible. Don't use a period at the end.

## Body (Optional)

You can add a body to provide more details about your change. This is optional but can be helpful for complex changes.

## Examples

Here's an example of a commit message:
\`\`\`
feat: add user login
\`\`\`

Here's another example:
\`\`\`
fix: correct database query
\`\`\`

Problems with poor version:

• Instructions, not expertise: "Steps to write" is mechanical
• Friction: Forces process (think → decide → write → review → edit)
• Wrong voice: "This guide will help you" is AI-speak
• Unfocused: Explains what commits are (not needed), lists all types (overwhelming)
• Missing decisions: "Choose the type that best matches" (no framework)
• Weak examples: Don't show why or how to think

---

Key Takeaway

The effective version:

• Takes ~2 minutes to read
• Produces good commits on first try
• Feels like Claude "knows" how to write commits

The poor version:

• Takes ~3 minutes to read
• Requires iteration and review
• Feels like Claude is "following instructions"

That difference — between knowing and following — is expertise transfer.

Expertise Transfer: Before & After Examples

This reference shows the difference between instruction-following and expertise transfer.

Example 1: SQL Query Skill

❌ Instruction-Following Approach

## How to Write Queries

1. First, identify the tables you need
2. Then, write the SELECT statement
3. Add appropriate JOINs
4. Include WHERE clauses for filtering
5. Don't forget to add GROUP BY if aggregating
6. Review the query for correctness

Problems:

• Reads like a checklist, not expertise
• Claude already knows SQL syntax
• Doesn't teach when or why
• Wastes tokens on process narration

✅ Expertise Transfer Approach

## Query Design Principles

**Start from the answer:** What question does this query answer? Write the SELECT first.

**Join economics:** Avoid many-to-many joins - they explode row counts. If unavoidable, aggregate before joining.

**Filter early:** Push WHERE conditions into subqueries when possible. Don't filter 1M rows when you can filter 10K.

**For performance:** 
- Indexes: Filter columns, JOIN keys
- No wildcards: `SELECT *` forces Claude to read all columns
- Prefer EXISTS over IN for correlated subqueries

Example:
\`\`\`sql
-- Efficient: Filter early, aggregate, then join
SELECT u.name, COUNT(o.id) 
FROM users u
LEFT JOIN (SELECT * FROM orders WHERE status = 'complete') o
  ON u.id = o.user_id
GROUP BY u.name;
\`\`\`

Why it works:

• Teaches mental models ("join economics", "filter early")
• Focuses on non-obvious knowledge
• Includes the "why" behind practices
• Expert would recognize this thinking

---

Example 2: Document Formatting Skill

❌ Instruction-Following Approach

## Formatting Documents

You should format documents as follows:
1. Start with a title
2. Add section headers
3. Make sure to use bullet points for lists
4. Remember to check spelling
5. Ensure consistent spacing
6. Don't forget page numbers

Problems:

• Patronizing (Claude knows what a title is)
• No decision guidance
• Assumes Claude needs reminding
• Sounds like AI talking to itself

✅ Expertise Transfer Approach

## Document Structure

Match structure to purpose:

**Persuasive (proposals, pitches):**
- Lead with conclusion, not methodology
- One idea per paragraph
- Bold for emphasis, not decoration

**Reference (documentation, reports):**
- Hierarchy reveals relationships
- Parallel structure for scanability
- Link terms to definitions on first use

**Quality signals:**
- White space creates hierarchy
- Consistent indentation = consistent meaning
- Numbers for sequences, bullets for sets

Example transformation:
\`\`\`
Bad: "We should do X because of Y and Z which relates to A..."
Good: "Recommendation: Do X. [paragraph] Supporting data: Y shows... Z indicates..."
\`\`\`

Why it works:

• Teaches document thinking, not mechanics
• Contextual guidance (persuasive vs. reference)
• Shows good/bad without being prescriptive
• Practitioner would recognize these patterns

---

Example 3: Code Review Skill

❌ Instruction-Following Approach

## Code Review Process

Follow these steps:
1. Read through the code
2. Check for syntax errors
3. Look for logic errors
4. Verify naming conventions
5. Ensure proper comments
6. Test edge cases
7. Provide feedback

Problems:

• Generic advice (what junior reviewers do)
• No prioritization
• Doesn't teach risk assessment
• Mechanical, not thoughtful

✅ Expertise Transfer Approach

## Code Review Heuristics

**Risk-based scanning:**

High impact areas (scan first):
- Auth/permissions logic
- Data persistence/transactions
- Error handling in critical paths

Low impact areas (scan last):
- Styling choices
- Minor refactors
- Comment quality

**Red flags by category:**

*Logic:*
- Mutations during iteration
- Silent failures (empty catches)
- Implicit type conversions

*Maintainability:*
- Nested ternaries (rewrite as if/else)
- Magic numbers without constants
- Function names that don't match behavior

**Feedback framing:**

Risk: "This could cause X if Y" (not "this is wrong")
Suggestion: "Consider Z pattern for clarity" (not "do Z")
Nitpick: "(nitpick) Style preference: ..." (label low-priority items)

Why it works:

• Prioritization framework (risk-based)
• Specific red flags, not generic advice
• Includes social aspects (feedback framing)
• Senior engineer would recognize this approach

---

Pattern Recognition: What Makes Expertise Transfer?

---

Self-Check Questions

When reviewing your skill, ask:

1. Would an expert do it this way? If you're prescribing steps an expert would skip or combine, you're not transferring expertise.

2. What am I teaching vs. instructing? Teaching: patterns, mental models, trade-offs. Instructing: "do step 1, then step 2"

3. Am I respecting Claude's intelligence? If you're explaining what a function is, you're probably under-estimating the baseline.

4. Could I delete this and still succeed? If yes, the section isn't transferring unique expertise.

5. Does this sound like documentation or like thinking out loud with a colleague? Aim for the latter.

---

The Litmus Test

Show your skill to a domain expert. Ask:

• "Would you approach it this way?"
• "What's missing from how you actually think about this?"
• "What here is obvious vs. insightful?"

If they say "this is how I think about it" - you've transferred expertise. If they say "yes, those are the steps" - you've written instructions.

Quick Reference: Core Principles

Use this as a checklist during skill creation and iteration.

The 4 Core Truths

┌─────────────────────────────────────────────────────────────┐
│ 1. EXPERTISE TRANSFER, NOT INSTRUCTIONS                     │
│    Make Claude think like an expert, not follow steps       │
│    ✓ Mental models  ✓ Trade-offs  ✓ Decision frameworks    │
│    ✗ Checklists     ✗ Recipes     ✗ "Step 1, Step 2..."    │
├─────────────────────────────────────────────────────────────┤
│ 2. FLOW, NOT FRICTION                                       │
│    Produce output, not intermediate documents               │
│    ✓ Direct to deliverable  ✓ Contextual decisions         │
│    ✗ "Write a plan first"  ✗ "Now review your work"        │
├─────────────────────────────────────────────────────────────┤
│ 3. VOICE MATCHES DOMAIN                                     │
│    Sound like a practitioner, not documentation             │
│    ✓ Domain language  ✓ Natural phrasing                   │
│    ✗ "You should..."  ✗ "Make sure to..."                  │
├─────────────────────────────────────────────────────────────┤
│ 4. FOCUSED BEATS COMPREHENSIVE                              │
│    Every section must justify its token cost                │
│    ✓ Only non-obvious info  ✓ Split to references          │
│    ✗ Explaining basics     ✗ "Just in case" sections       │
└─────────────────────────────────────────────────────────────┘

Progressive Disclosure Structure

YAML (always loaded)
├─ name: Short identifier
└─ description: When to trigger (specific!)

SKILL.md (<500 lines)
├─ Core mental model
├─ Common scenarios  
├─ Decision frameworks
└─ Links to references

references/ (load as needed)
├─ patterns.md: Detailed patterns
├─ examples.md: Complete examples
└─ advanced.md: Edge cases

scripts/ (execute, rarely read)
└─ Deterministic operations

assets/ (copy/use, never read)
└─ Templates, fonts, images

Quality Checks by Truth

Truth 1: Expertise Transfer Test

Read random section. Ask:
→ Does this teach HOW to think?
→ Would an expert recognize this?
→ Are we showing patterns or steps?

Red flags:
• "Follow these steps..."
• "Make sure to..."
• Explaining what Claude already knows

Truth 2: Flow Test

Walk through skill. Ask:
→ Can we go input → output directly?
→ Do we force planning artifacts?
→ Are decisions made inline?

Red flags:
• "First, create an outline..."
• "Review your work and revise..."
• Multiple verification steps

Truth 3: Voice Test

Read aloud. Ask:
→ Does this sound like domain docs?
→ Natural phrasing or stilted?
→ Meta-narration about process?

Red flags:
• "You should consider..."
• "This is important because..."
• "The next step is to..."

Truth 4: Focus Test

For each section, ask:
→ Would Claude fail without this?
→ Is this addressing observed gaps?
→ Could this be a one-line reference?

Red flags:
• Sections >200 words without split
• Information "just in case"
• Repeated similar examples

Token Budget Guidelines

SKILL.md target sizes:
┌──────────────────┬──────────┬─────────────────┐
│ Complexity       │ Target   │ If Exceeding    │
├──────────────────┼──────────┼─────────────────┤
│ Simple task      │ <200     │ Cut explanations│
│ Medium workflow  │ 200-500  │ Split references│
│ Complex domain   │ 500-800  │ Multiple refs   │
│ Multi-domain     │ 800+     │ Split skills    │
└──────────────────┴──────────┴─────────────────┘

If SKILL.md > 500 lines:
1. Move examples → references/examples.md
2. Move patterns → references/patterns.md  
3. Move edge cases → references/advanced.md
4. Keep only: core flow + decision points

Common Patterns

Decision Framework Pattern

## When [Scenario A]
[Specific approach]

## When [Scenario B]
[Different approach]  

## Default (when unsure)
[Safe fallback]

Principle + Example Pattern

## [Principle name]

**Core idea:** [One sentence]

**In practice:**
- [Specific application]
- [Specific application]

**Example:**
[Concrete demonstration]

Quality Checklist Pattern

## Quality Check

Before finishing:
- [ ] [Specific, measurable criterion]
- [ ] [Specific, measurable criterion]
- [ ] [Specific, measurable criterion]

Red Flag Phrases

If you see these, revise:

INSTRUCTION LANGUAGE:
✗ "You should..."
✗ "Make sure to..."
✗ "Don't forget..."
✗ "Remember that..."
✗ "It's important to..."

REVISION →
✓ Just state it: "Use X for Y"
✓ Or explain why: "X prevents Y"

PROCESS NARRATION:
✗ "The first step is..."
✗ "Now that you've..."
✗ "Next, you need to..."
✗ "After completing..."

REVISION →
✓ Direct: "Extract text"
✓ Conditional: "If X, then Y"

VAGUE GUIDANCE:
✗ "Choose appropriately"
✗ "Use best practices"
✗ "Ensure quality"
✗ "Optimize as needed"

REVISION →
✓ Criteria: "Use X when Y"
✓ Examples: "Like this: [example]"

Iteration Triggers

Revise the skill when you observe:

CLAUDE BEHAVIOR:
• Asks questions skill should answer
• Ignores parts of skill
• Inconsistent output quality
• Rewrites code scripts should handle

SYMPTOM → LIKELY CAUSE:
• Questions → Missing decision criteria
• Ignores → Too much text / buried info
• Inconsistent → Vague quality criteria  
• Rewrites → Scripts unclear / not trusted

Pre-Package Checklist

Structure:
[ ] SKILL.md exists with valid frontmatter
[ ] name and description are present
[ ] No README, CHANGELOG, or meta-docs

Content:
[ ] SKILL.md <500 lines (split if larger)
[ ] Imperative mood throughout
[ ] All references are linked from SKILL.md
[ ] No "you should" or instruction language
[ ] Examples show patterns, not just format

Quality:
[ ] Tested on 3+ realistic scenarios
[ ] Addresses observed failure modes
[ ] Every section justified by need
[ ] Would pass the 4 truth tests

References:
[ ] Split by use case, not type
[ ] Include grep patterns for large files
[ ] Referenced from SKILL.md with "when to use"

Scripts:
[ ] Tested and working
[ ] Clear when to use them
[ ] Include basic usage examples

Assets:
[ ] Only files used in output
[ ] No examples unless they're templates

The One-Minute Test

Read your skill. Time yourself. After one minute, can you: 1. Explain the core approach in one sentence? 2. Recall two key decision points? 3. Remember when to use a reference vs. SKILL.md?

If no → Too unfocused, needs ruthless editing If yes → Probably well-structured

Final Self-Check

The best skills feel invisible. Ask:

Does Claude sound like it:
[ ] Has expertise in this domain?
OR
[ ] Is following an instruction manual?

If it sounds like Claude is:
• "Checking the manual" → Too procedural
• "Thinking through it" → Good expertise transfer
• "An expert who knows" → Excellent

---

Emergency Simplification

If skill isn't working and you're stuck:

1. Delete everything 2. Write 3 sentences:

• What's the core mental model?
• What's the most common scenario?
• What's the biggest gotcha?

3. Add minimal examples 4. Test 5. Only then add back what's missing

Simple skills that work > complex skills that don't.