# Writing Skills

> Use when creating new skills, editing existing skills, or verifying skills work before deployment

- Skill: `oyi77/writing-skills` (Agent Skill)
- Install (CLI): `npx skillmds add oyi77/writing-skills`
- Raw SKILL.md: https://api.skillmd.com/api/skills/oyi77/writing-skills/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: Apache-2.0
- Author: oyi77 (https://skillmd.com/u/oyi77)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/oyi77/writing-skills

---




# Writing Skills

## Overview
Writing skills IS Test-Driven Development applied to process documentation.


## Anti-Rationalization Table

| Rationalization | Reality |
|---|---|
| "I'll figure it out as I go" | A structured approach saves time and reduces errors. Follow the workflow in this skill rather than improvising. |
| "I already know this topic" | Familiarity breeds shortcuts. Use the checklist to verify you haven't missed critical steps. |
| "This doesn't apply to my situation" | The patterns here generalize across contexts. Adapt, don't skip — the underlying principles hold. |
| "One more tool will fix it" | Adding complexity rarely solves process gaps. Master the core workflow first. |

## When to Use

**Trigger phrases:**
- "writing skills"
- "Creating new skills"
- "Editing existing skills"
- "Verifying skills work before deployment"

- Creating new skills
- Editing existing skills
- Verifying skills work before deployment

## When NOT to Use
- Just documenting what you did (that's narrative, not skill)
- Technique isn't proven/reproducible
- Haven't pressure-tested with subagents

## Quick Reference

**TDD Cycle:** RED → GREEN → REFACTOR

## Common Mistakes
- Writing skill before running baseline test
- Not documenting exact agent failures
- Making skills too generic
- Skipping refactor/loophole-closing phase
- Not using lint harness

## What is a Skill?
A skill is a reference guide for proven techniques, patterns, or tools.

**Skills are:** Reusable techniques, patterns, tools
**Skills are NOT:** Narratives about one-off solutions

## TDD Mapping
| TDD | Skills |
|-----|--------|
| Test case | Pressure scenario |
| RED | Agent violates without skill |
| GREEN | Agent complies with skill |
| Refactor | Close loopholes |

## SKILL.md Structure

**Frontmatter:**
- `name`: letters, numbers, hyphens only
- `description`: Start with "Use when..." (trigger, not workflow)

```markdown
---
name: skill-name
description: Use when [specific triggering conditions]
---
```

**Required sections:**
- ## Overview
- ## When to Use
- ## When NOT to Use
- ## Quick Reference
- ## Common Mistakes

## Common Mistakes
What goes wrong + fixes

## Real-World Impact (optional)
Concrete results
```


## Claude Search Optimization (CSO)

**Critical for discovery:** Future Claude needs to FIND your skill

### 1. Rich Description Field

**Purpose:** Claude reads description to decide which skills to load for a given task. Make it answer: "Should I read this skill right now?"

**Format:** Start with "Use when..." - trigger only, NOT workflow

**CRITICAL:** Description = When to Use, NOT What It Does

```yaml
# ❌ BAD: Summarizes workflow
description: Use when executing plans - dispatches subagent with code review

# ✅ GOOD: Just triggering conditions
description: Use when executing implementation plans with independent tasks
```

**Content:**
- Use concrete triggers and situations
- Describe the problem, not language-specific symptoms
- Keep triggers technology-agnostic unless skill is tech-specific
- Write in third person (injected into system prompt)

**Name by what you DO:**
- ✅ `condition-based-waiting` > `async-test-helpers`
- ✅ `root-cause-tracing` > `debugging-techniques`

**Cross-reference skills explicitly:**
- ✅ `REQUIRED: Use superpowers:test-driven-development`
- ❌ Avoid @ links (force-loads, burns context)
```

**Use flowcharts ONLY for:**
- Non-obvious decision points
- Process loops where you might stop too early
- "When to use A vs B" decisions

## Flowcharts & Examples
- Flowcharts: only for non-obvious decisions
- Examples: one excellent example, not multi-language
- Code: complete, runnable, from real scenario

## File Organization
- **Inline:** All content fits in SKILL.md
- **With tool:** SKILL.md + reusable code file
- **Heavy reference:** SKILL.md + separate reference files

## The Iron Law
```
NO SKILL WITHOUT A FAILING TEST FIRST
```
Write skill before testing? Delete it. Start over.

## Testing Skill Types

**Discipline skills (TDD, verification):**
- Test: pressure scenarios, rationalization counters
- Success: agent follows rule under pressure

**Technique skills (how-to):**
- Test: application scenarios, edge cases
- Success: agent applies technique correctly

**Pattern skills (mental models):**
- Test: recognition, application
- Success: agent identifies when to apply

**Reference skills (APIs):**
- Test: retrieval, application
- Gap testing: Are common use cases covered?

**Success criteria:** Agent finds and correctly applies reference information

## Common Rationalizations

| Excuse | Reality |
|--------|---------|
| "Obviously clear" | Clear to you ≠ clear to agents. Test it. |
| "Testing is overkill" | Untested skills have issues. Always. |
| "No time to test" | Untested wastes more time later. |

## Bulletproofing Skills

**Close every loophole explicitly:**
- State the rule AND forbid specific workarounds
- Add "Violating the letter = violating the spirit"

This cuts off entire class of "I'm following the spirit" rationalizations.

### Build Rationalization Table
Capture rationalizations from baseline testing:
| Excuse | Reality |
|--------|---------|
| "Too simple to test" | Simple code breaks |
| "I'll test after" | Tests passing proves nothing |

### Red Flags List
```
## Red Flags - STOP
- Code before test
- "I already manually tested"
- "This is different because..."
```

## RED-GREEN-REFACTOR for Skills

- Configure before, creating, deployment, editing, existing settings before first use


### RED: Baseline
Run scenario WITHOUT skill. Document:
- What choices did they make?
- What rationalizations?
- Which pressures triggered violations?

This is "watch the test fail" - you must see what agents naturally do before writing the skill.

### GREEN: Write Minimal Skill
Write skill addressing those rationalizations. Run with skill - agent should comply.

### REFACTOR: Close Loopholes
Agent found new rationalization? Add explicit counter. Re-test until bulletproof.

## Anti-Patterns
- ❌ Narrative: "In session X, we found..."
- ❌ Multi-language: 3 implementations = mediocre
- ❌ Code in flowcharts: Can't copy-paste
- ❌ Generic labels: helper1, step3

**Don't:**
- Create multiple skills without testing each
- Skip testing because "batching is more efficient"

## Skill Creation Checklist

**RED Phase:**
- Create pressure scenarios
- Run WITHOUT skill - document baseline
- Identify rationalization patterns

**GREEN Phase:**
- Name: letters, numbers, hyphens only
- Frontmatter: name + description
- Description: starts with "Use when...", third person
- Run WITH skill - verify compliance

**REFACTOR Phase:**
- Find new rationalizations
- Add explicit counters
- Re-test until bulletproof

## Red Flags

- Content quality is not reviewed before publication or distribution
- Agent does not adapt tone and style for the target audience
- Watch for shortcuts and skipped steps

## Verification

After completing this skill, confirm:

- [ ] Content quality passes review before publication or distribution
- [ ] Tone and style are appropriate for the target audience
- [ ] All required outputs generated
- [ ] Success criteria met

## Process

1. Analyze the task requirements
2. Apply domain expertise
3. Verify output quality