Writing Skills Liauw Media

---
name: writing-skills
description: "Use when creating reusable process documentation. Apply TDD: baseline without skill → document failures → write skill → test → iterate. Four types: Discipline, Technique, Pattern, Reference. Iron Law: No skill without failing test first."
---

# Writing Skills

## Core Principle

Skills are reusable process documentation. Write them like code: test-first, iterative, validated.

## When to Use This Skill

- Discovered a useful process
- Want to codify knowledge
- Pattern worth sharing
- Repeatedly solving same problem
- Need consistent approach
- Team needs standard practices
- Contributing to community

## The Iron Law

**NO SKILL WITHOUT A FAILING TEST FIRST.**

If you can't demonstrate the problem the skill solves, you don't need the skill yet.

## Why Write Skills?

**Benefits:**
✅ Codifies tacit knowledge
✅ Creates consistency
✅ Accelerates learning
✅ Reduces mistakes
✅ Enables scaling
✅ Builds institutional memory

**Without documented skills:**
❌ Knowledge stays in heads
❌ Inconsistent approaches
❌ Repeat mistakes
❌ Slow onboarding
❌ Can't scale

## TDD for Skill Writing

### Step 1: Baseline (RED Phase)

```
🔴 RED: Establish baseline without skill

Observation: Debugging takes too long, focuses on symptoms

Evidence gathering:
1. Observe current behavior (without skill)
2. Document specific failures
3. Collect multiple examples
4. Identify patterns

Example baseline observation:
---
Scenario: Debug slow API endpoint

Current approach (no skill):
1. User adds caching ← Treats symptom
2. Performance improves temporarily
3. Real issue (N+1 queries) remains
4. Problem returns as data grows
5. Multiple "fixes" accumulate
6. Root cause never found

Failures observed:
- ❌ Fixed symptom, not cause
- ❌ No systematic investigation
- ❌ Didn't trace to origin
- ❌ Quick fix instead of proper solution
- ❌ Problem will recur

Baseline documented ✅
Need: Systematic debugging process
---

This baseline PROVES we need the skill.
```

**Baseline requirements:**
- Real scenarios (not hypothetical)
- Specific failures (not vague problems)
- Multiple examples (not one-offs)
- Clear pattern (not random)

### Step 2: Document Failures (Still RED)

```
Failure catalog from baseline:

Failure 1: Stopping at symptoms
Example: Added caching instead of fixing N+1 queries
Impact: Problem returns later
Frequency: 8/10 debugging sessions

Failure 2: No systematic process
Example: Random changes until something works
Impact: Wastes time, creates new bugs
Frequency: 7/10 sessions

Failure 3: Not tracing to origin
Example: Found slow query but not why it's slow
Impact: Incomplete understanding
Frequency: 9/10 sessions

Failure 4: Quick fixes under pressure
Example: "Just make it work for demo"
Impact: Technical debt
Frequency: 5/10 sessions

Failures documented ✅
These define what skill must address
```

### Step 3: Write Skill (GREEN Phase)

```
🟢 GREEN: Write skill to address failures

Skill name: systematic-debugging

Must address documented failures:
- Failure 1 → Need process that finds root causes
- Failure 2 → Need step-by-step methodology
- Failure 3 → Need techniques for tracing origins
- Failure 4 → Need guidance for handling pressure

Skill structure:

1. Core Principle
   "Debug methodically, not randomly."
   ← Addresses Failure 2

2. When to Use This Skill
   - Encountering bugs
   - Unexpected behavior
   - Tests failing
   ← Clear trigger conditions

3. The Iron Law
   "NEVER try random things until it works."
   ← Directly counters Failure 2

4. The 5-Step Process
   1. Reproduce
   2. Isolate
   3. Identify (root cause)
   4. Fix
   5. Verify
   ← Addresses Failures 1, 2, 3

5. Examples
   - Performance degradation
   - Data corruption
   - Intermittent failures
   ← Real scenarios from baseline

6. Handling Pressure
   "Time pressure is when you MOST need systematic approach"
   ← Addresses Failure 4

7. Common Mistakes
   - Trying random things
   - Fixing symptoms
   - Not verifying
   ← Directly from failure catalog

8. Integration with Other Skills
   - Use with TDD
   - Use with code-review
   ← Shows how it fits

9. Authority
   - Scientific method
   - Professional practices
   - Research evidence
   ← Builds credibility

10. Your Commitment
    Checklist of commitments
    ← Creates accountability

11. Bottom Line
    One-sentence summary
    ← Memorable takeaway

Skill written ✅
```

### Step 4: Test the Skill (GREEN Validation)

```
Test skill with baseline scenarios:

Scenario 1: Slow API endpoint (same as baseline)
- Give fresh subagent task + skill
- Observe behavior

Result:
✅ Follows 5-step process
✅ Reproduces issue
✅ Isolates to N+1 queries
✅ Identifies root cause
✅ Makes proper fix
✅ Verifies with tests

Improvement: Fixed root cause, not symptom ✅

Scenario 2: Intermittent test failure
- Give fresh subagent task + skill
- Observe behavior

Result:
✅ Reproduces reliably
✅ Isolates to timing issue
✅ Identifies race condition
✅ Fixes architecture
✅ Verifies fix

Improvement: Found and fixed root cause ✅

Skill solves documented failures ✅
```

### Step 5: Iterate and Refine (REFACTOR)

```
🔵 REFACTOR: Test edge cases, find loopholes

Edge case 1: Time pressure
Test: Give skill + "Fix this in 10 minutes"
Result: ❌ Subagent skips process, makes quick fix

LOOPHOLE! Skill doesn't hold under time pressure.

Fix: Strengthen time pressure guidance:
"Time pressure is when you MOST need systematic approach.
Quick fixes create 10x more work later."

Updated skill ✅

Retest: ✅ Now handles time pressure

Edge case 2: Exhaustion
Test: Give skill + "You've been debugging for 6 hours"
Result: ❌ Subagent shortcuts process

LOOPHOLE! Skill doesn't address exhaustion.

Fix: Add exhaustion guidance:
"Exhaustion impairs judgment. The process protects you
when judgment fails. Follow it systematically."

Updated skill ✅

Retest: ✅ Now handles exhaustion

Edge case 3: "Works on my machine"
Test: Give skill + environment-specific bug
Result: ✅ Process finds environment differences

No loophole ✅

All edge cases tested ✅
Loopholes closed ✅
Skill refined ✅
```

## The Four Types of Skills

### Type 1: Discipline

**What it is:** Commitment to a practice

**Structure:**
- Iron Law (the discipline)
- Why it matters
- How to maintain it
- What to avoid

**Examples:**
- test-driven-development (Test first, code second)
- database-backup (Always backup before tests)
- code-review (Never merge without review)

**Writing guide:**
```
Focus on:
- The commitment required
- Why shortcuts fail
- How to stay disciplined
- Handling pressure to skip it
```

### Type 2: Technique

**What it is:** Step-by-step process

**Structure:**
- When to use
- Step-by-step instructions
- Examples for each step
- Common mistakes

**Examples:**
- systematic-debugging (5-step process)
- root-cause-tracing (Backward tracing)
- git-bisect (Binary search for bugs)

**Writing guide:**
```
Focus on:
- Clear steps
- Decision points
- What to do at each step
- How to know you're done
```

### Type 3: Pattern

**What it is:** Reusable solution

**Structure:**
- The problem
- The solution
- When to use it
- Variations

**Examples:**
- condition-based-waiting (Wait for condition, not timeout)
- dependency-injection (Pass dependencies in)
- repository-pattern (Abstract data access)

**Writing guide:**
```
Focus on:
- Problem it solves
- How the pattern works
- Implementation examples
- When NOT to use it
```

### Type 4: Reference

**What it is:** Conceptual knowledge

**Structure:**
- Core concepts
- Principles
- Guidelines
- Best practices

**Examples:**
- testing-anti-patterns (What NOT to do)
- anthropic-best-practices (Prompt engineering)
- persuasion-principles (Influence techniques)

**Writing guide:**
```
Focus on:
- Key concepts
- Principles to follow
- Examples of each
- Common misunderstandings
```

## Skill Document Structure

### Required Sections

```markdown
---
name: skill-name
description: "One-line description: when to use and what it does"
---

# Skill Name

## Core Principle
One-sentence essence of the skill

## When to Use This Skill
- Bullet list of trigger conditions
- Specific scenarios
- Clear indicators

## The Iron Law
**BOLD STATEMENT OF CORE RULE**

Clear, unambiguous, memorable

## Why [Skill Name]?
**Benefits:**
✅ List of benefits

**Without [skill]:**
❌ List of problems

## [Main Content]
Detailed explanation, process, or technique
- Step-by-step if technique
- Principles if reference
- Examples throughout

## Examples
Real-world examples showing:
- Before (without skill)
- After (with skill)
- Improvement demonstrated

## Common Mistakes
What NOT to do
Why mistakes happen
How to avoid them

## Integration with Skills
Which skills this works with
When to combine them
How they complement each other

## Authority
Based on:
- Research
- Industry standards
- Expert recommendations
- Proven practices

## Your Commitment
Checklist format:
- [ ] I will...
- [ ] I will...

## Bottom Line
---
**Bottom Line**: One sentence summary that captures essence
```

### Optional Sections

```markdown
## Red Flags
Warning signs this skill is needed

## Checklist
Step-by-step checklist for applying skill

## Advanced Techniques
Beyond basics, for experienced users

## Troubleshooting
Common issues and solutions

## Real-World Case Studies
Detailed examples from actual usage
```

## Writing Style Guidelines

### Guideline 1: Be Specific

```
❌ BAD (vague):
"Write good tests"

✅ GOOD (specific):
"Write tests that verify behavior, not implementation.
Test through public API only."
```

### Guideline 2: Use Examples

```
❌ BAD (abstract):
"Follow the debugging process"

✅ GOOD (concrete):
"Example debugging session:
1. Bug: Login fails
2. Reproduce: Happens every time
3. Isolate: Error in AuthController
4. Identify: Missing database table
5. Fix: Run migrations
6. Verify: Login now works"
```

### Guideline 3: Show Before/After

```
❌ BAD (only after):
"Here's how to do it right..."

✅ GOOD (both):
"Before: Random debugging, symptoms fixed
After: Systematic process, root causes found"
```

### Guideline 4: Address Resistance

```
❌ BAD (ignore objections):
"Just follow the process"

✅ GOOD (handle objections):
"Common objection: 'No time for TDD'
Reality: TDD is faster because bugs caught immediately,
not after deployment. Follow the process."
```

### Guideline 5: Make It Scannable

```
❌ BAD (wall of text):
Long paragraphs with no structure, hard to scan,
can't find key points quickly...

✅ GOOD (structured):
- Use bullets
- Use headings
- Use code blocks
- Use bold for key points
- Use checkboxes for processes
```

## Skill Testing Protocol

### Test 1: Baseline Without Skill

```
1. Create 3-5 realistic scenarios
2. Fresh subagent for each
3. NO skill provided
4. Observe and document failures
5. Catalog specific problems

Pass criteria: Clear failures documented
```

### Test 2: Improvement With Skill

```
1. Same scenarios as baseline
2. Fresh subagent for each
3. Include skill
4. Observe and document improvements
5. Verify failures addressed

Pass criteria: Measurable improvement in all scenarios
```

### Test 3: Pressure Testing

```
1. Test with time constraints
2. Test with sunk cost
3. Test with exhaustion
4. Test with authority pressure

Pass criteria: Skill holds up under all pressures
```

### Test 4: Integration Testing

```
1. Test skill with related skills
2. Verify compatibility
3. Check for conflicts
4. Document integrations

Pass criteria: Works well with other skills
```

## Skill Maintenance

### When to Update

```
Update when:
- Loophole discovered
- Better technique found
- Feedback received
- Edge case encountered
- Integration issue found

Update process:
1. Document the issue
2. Update skill content
3. Re-test all scenarios
4. Verify improvement
5. Update version/date
```

### Versioning

```
Track changes:
- Major update: Core process changed
- Minor update: Examples added, refinements
- Patch: Typos, clarifications

Document:
- What changed
- Why changed
- Test results
```

## Common Skill Writing Mistakes

### Mistake 1: No Baseline

```
❌ BAD:
Write skill based on theory
No proof of need
Assume problem exists

Result: Skill solves non-existent problem

✅ GOOD:
Establish baseline first
Document actual failures
Prove skill is needed
Create from reality
```

### Mistake 2: Too Abstract

```
❌ BAD:
"Follow best practices"
No specifics
No examples
Just platitudes

Result: No one knows how to apply it

✅ GOOD:
Specific steps
Concrete examples
Clear instructions
Actionable guidance
```

### Mistake 3: Not Tested

```
❌ BAD:
Write skill
Ship it
Hope it works

Result: Loopholes in production

✅ GOOD:
Write skill
Test thoroughly
Find loopholes
Fix them
Then ship
```

### Mistake 4: Missing Authority

```
❌ BAD:
"Trust me, this works"
No sources
No evidence
Just opinion

Result: No credibility

✅ GOOD:
Based on research
Industry standards
Expert recommendations
Proven practices
```

## Example: Complete Skill Writing Process

```
🔴 RED PHASE

Problem observation:
Tests failing when run together, passing alone

Baseline testing (no skill):
Scenario 1: Test pollution
- Observe: Developers add retries
- Result: Masks problem
- Failure: Pollution not fixed

Scenario 2: Test isolation
- Observe: Developers can't find polluter
- Result: Comment out tests
- Failure: Lost test coverage

Scenario 3: Database state
- Observe: Manual cleanup added
- Result: Brittle, incomplete
- Failure: Still has pollution

Failures documented:
- Can't find polluter
- Mask instead of fix
- Manual cleanup instead of isolation

Baseline proves need for skill ✅

---

🟢 GREEN PHASE

Write skill: test-pollution-detection

Sections:
1. Core Principle: "Tests must be independent"

2. Iron Law: "Find and fix polluter, don't mask"

3. Detection process:
   - Binary search for polluter
   - Isolate problematic test
   - Fix root cause

4. Examples from baseline:
   - Database state pollution
   - Global variable pollution
   - File system pollution

5. Tools:
   - find-polluter.sh script
   - Test isolation patterns
   - Proper cleanup

6. Common mistakes (from baseline):
   - Adding retries (masking)
   - Manual cleanup (brittle)
   - Commenting out tests (lost coverage)

Skill written ✅

---

🔵 REFACTOR PHASE

Test with skill:
Scenario 1: ✅ Uses binary search, finds polluter
Scenario 2: ✅ Fixes root cause, not symptoms
Scenario 3: ✅ Implements proper isolation

Improvement verified ✅

Pressure testing:
Time pressure: ❌ Skips proper fix, adds retry

LOOPHOLE! Add to skill:
"Masking pollution takes 10x longer to fix later.
Find and fix polluter, even under pressure."

Updated ✅

Retest: ✅ All scenarios pass

Integration test:
- Works with TDD ✅
- Works with systematic-debugging ✅
- Works with CI/CD ✅

Skill validated ✅
Ready to use ✅
```

## Integration with Skills

**Required:**
- `testing-skills-with-subagents` - Test every skill

**Use with:**
- `test-driven-development` - Apply TDD to skills
- `code-review` - Review skills like code
- `sharing-skills` - Share validated skills

**Enables:**
- Consistent practices
- Knowledge transfer
- Quality processes

## Skill Writing Checklist

Before writing:
- [ ] Problem clearly identified
- [ ] Baseline established (RED)
- [ ] Failures documented
- [ ] Multiple examples collected

While writing:
- [ ] Core principle clear
- [ ] Iron Law memorable
- [ ] Step-by-step if technique
- [ ] Real examples included
- [ ] Common mistakes addressed
- [ ] Integration documented
- [ ] Authority cited
- [ ] Commitment section included

After writing:
- [ ] Tested with baseline scenarios
- [ ] Improvement verified
- [ ] Pressure tested
- [ ] Loopholes found and fixed
- [ ] Integration tested
- [ ] Ready for use

## Authority

**This skill is based on:**
- Technical writing best practices
- Test-Driven Development (Kent Beck)
- Process documentation standards
- Knowledge management research
- Anthropic best practices for prompt engineering

**Research**: Studies show documented processes are followed 5x more consistently than undocumented.

**Social Proof**: All professional organizations maintain process documentation.

## Your Commitment

When writing skills:
- [ ] I will establish baseline first (RED)
- [ ] I will document specific failures
- [ ] I will write skill to address failures (GREEN)
- [ ] I will test thoroughly (REFACTOR)
- [ ] I will find and close loopholes
- [ ] I will include real examples
- [ ] I will cite authority
- [ ] I will only share tested skills

---

**Bottom Line**: Skills are code for humans. Write them test-first: baseline (RED) → write skill (GREEN) → test and refine (REFACTOR). No skill without a failing test first.