xiaolai/writing-skills

Writing Skills

Scope: covers SKILL.md authoring. For agent writing, see [[writing-agents]]. For plugin architecture, see [[writing-plugins]].

1. The Description is Everything

The description field determines when Claude loads this skill. It is not a summary -- it is a trigger mechanism.

Bad (score 55):

description: "Helpful skill for React development"

Good (score 95):

description: "Use when building React components, debugging re-renders, optimizing performance with useMemo/useCallback, or fixing hook dependency arrays"

Description Checklist

| Criterion | Test | |-----------|------| | 3+ trigger phrases | Count distinct action phrases separated by commas | | Action-oriented | Starts with "Use when..." or "How to..." | | Includes tool/framework name | The technology name appears explicitly | | Matches real queries | Would a user's actual question contain any of your trigger words? |

Trigger Phrase Construction

Map real user queries to trigger phrases:

| User says | Trigger phrase to include | |-----------|--------------------------| | "My component re-renders too much" | "debugging re-renders" | | "How do I memoize this?" | "optimizing performance with useMemo/useCallback" | | "My useEffect runs in a loop" | "fixing hook dependency arrays" | | "I need a new component for..." | "building React components" |

Rule: if you can't list 3 real user queries that match your description, rewrite it.

2. Body Structure

Section Order

1. Scope note (if related skills exist) -- tells Claude when to use THIS skill vs another
2. Most commonly needed patterns -- what users ask about 80% of the time
3. Decision matrices -- when to use A vs B (tables)
4. Worked examples -- before/after with scores
5. Common mistakes -- anti-patterns to avoid
6. References -- links to deep dives

Heading Rules

• H1 (#): skill title only (one per file)
• H2 (##): major sections (numbered: ## 1. Section Name)
• H3 (###): subsections within a major section
• Never skip heading levels (no H2 followed directly by H4)

Code Examples

Every code example must show the problem, then the solution:

### Bad (breaks on concurrent requests)
` ` `python
global_state = {}  # shared mutable state
` ` `

### Good (request-scoped)
` ` `python
def handler(request):
    state = {}  # local to this request
` ` `

Rules for code examples:

• Runnable, not pseudocode
• Contextual -- show enough surrounding code to understand placement
• Annotated -- comment the critical line, not every line

3. Progressive Disclosure

Keep SKILL.md under 500 lines. Use the file system for depth:

skills/my-domain/my-skill/
  SKILL.md          # core patterns (< 500 lines)
  references/       # deep dives, edge cases, full API docs
    advanced.md
    api-reference.md
  examples/         # working code samples
    basic-setup.ts
    advanced-config.ts
  scripts/          # utility scripts
    validate.sh

When to Extract to references/

| Content type | Keep in SKILL.md? | Extract to references/? | |-------------|-------------------|------------------------| | Top 5 patterns everyone needs | Yes | No | | Full API reference (50+ entries) | No | Yes | | Edge cases (< 5% of users) | No | Yes | | Configuration matrix (20+ options) | No | Yes | | Quick decision table (< 10 rows) | Yes | No |

4. Worked Example: Improving a Skill

Before (score 55/100)

---
name: docker-helper
description: "Information about Docker"
version: 0.1.0
---

# Docker Helper

Docker is a containerization platform. Here are some useful commands.

## Commands
- `docker build` - builds an image
- `docker run` - runs a container
- `docker ps` - lists containers

## Dockerfile
A Dockerfile contains instructions for building an image.

## Docker Compose
Docker Compose is for multi-container applications.

Problems:

• Description is a label, not a trigger mechanism (0 trigger phrases)
• Body teaches theory Claude already knows from training
• No code examples showing problem/solution
• No decision matrices
• No scope note

After (score 92/100)

---
name: docker-helper
description: "Use when writing Dockerfiles, debugging container networking, optimizing image size with multi-stage builds, or configuring Docker Compose services. Covers build cache, volume mounts, health checks, and compose profiles."
version: 0.1.0
---

# Docker Helper

> Scope: covers Docker CLI, Dockerfiles, and Compose. For Kubernetes deployment, see [[k8s-deploy]].

## 1. Image Size Optimization

### Before (1.2 GB)
` ` `dockerfile
FROM node:20
COPY . .
RUN npm install
RUN npm run build
CMD ["node", "dist/index.js"]
` ` `

### After (148 MB -- 88% smaller)
` ` `dockerfile
FROM node:20-slim AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build

FROM node:20-slim
WORKDIR /app
COPY --from=build /app/dist ./dist
COPY --from=build /app/node_modules ./node_modules
CMD ["node", "dist/index.js"]
` ` `

Key changes: multi-stage build, slim base, copy only production artifacts.

## 2. Base Image Selection

| Use case | Base image | Size |
|----------|-----------|------|
| Node.js production | node:20-slim | 180 MB |
| Node.js minimal | node:20-alpine | 130 MB |
| Python production | python:3.12-slim | 150 MB |
| Static files only | nginx:alpine | 40 MB |
| From scratch (Go/Rust) | scratch | < 20 MB |

Changes made:

1. Description: 0 trigger phrases -> 8 trigger phrases (+37 points)
2. Scope note added (+5 points)
3. Replaced theory with problem/solution examples (+25 points)
4. Added decision matrix (+10 points)
5. Removed content Claude knows from training (-15 lines, +5 points for conciseness)

5. Common Mistakes

| Mistake | Why it hurts | Fix | |---------|-------------|-----| | Description is a feature list | Claude can't match user queries to the skill | Rewrite as trigger phrases starting with "Use when..." | | Body teaches theory | Wastes tokens on content Claude already knows | Show patterns and decisions, not definitions | | Over 500 lines | Bloats context window, penalized by linters | Extract to references/, keep core patterns only | | No scope note | Claude doesn't know when to use THIS skill vs a related one | Add scope note referencing related skills | | Pseudocode examples | Not actionable, can't be copy-pasted | Use runnable code with enough context | | Every section has equal weight | Buries the most useful content | Lead with the 80% patterns, push edge cases to references/ |

6. Quality Checklist

Before shipping a skill, verify:

• [ ] Description has 3+ specific trigger phrases
• [ ] Description starts with "Use when..." or "How to..."
• [ ] Scope note present (if related skills exist)
• [ ] H2 sections numbered, H3 subsections under them
• [ ] Code examples show problem then solution
• [ ] Decision tables for A-vs-B choices
• [ ] Total lines < 500
• [ ] No content Claude already knows from training
• [ ] At least one worked example with before/after