Writing Skills

Writing Skills

Scope: covers SKILL.md authoring. SKILL.md is the cross-tool open standard (agentskills.io) — the same file works in Claude Code (.claude/skills/), Codex CLI (.agents/skills/), and Antigravity (.agent/skills/). Only name and description are required by the spec; per-tool extras (Claude's model:/allowed-tools:, Codex's agents/openai.yaml sidecar) live in [[nlpm:conventions-claude]] / [[nlpm:conventions-codex]] / [[nlpm:conventions-antigravity]]. 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

Trigger Phrase Construction

Map real user queries to trigger phrases:

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/

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

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