Writing Skills

Writing Skills

Overview

Create effective, well-tested Claude Code skills that trigger reliably, load efficiently, and produce consistent results. This skill enforces a TDD approach to skill creation — define test prompts first, write the minimal skill, then harden against misfire and rationalization.

This is a RIGID skill. Every step must be followed exactly. No shortcuts.

Phase 1: Define Test Prompts (RED)

[HARD-GATE] Before writing any skill content, define the prompts that should trigger it.

Write 3-5 test prompts:

Document expected behavior for each:

Test prompt: "Create a new React component with tests"
Expected: Should trigger component-creation skill
Should NOT trigger: testing-strategy, code-review, writing-skills

STOP — Do NOT proceed to Phase 2 until all test prompts are documented.

Phase 2: Write Minimal SKILL.md (GREEN)

Create the minimum skill definition that passes all test prompts from Phase 1.

Required Structure

Every SKILL.md MUST contain ALL of these elements:

Frontmatter Rules

---
name: skill-name          # lowercase with hyphens, unique identifier
description: "Use when [trigger conditions]"  # Max 1024 chars
---

[HARD-GATE] The description field MUST start with "Use when".

CSO (Claude Search Optimization) Rules

The description field determines when a skill is selected. Optimize it like a search query.

Good:

description: "Use when creating database migrations, designing table schemas, adding indexes, or optimizing SQL queries"

Bad:

description: "A comprehensive guide to database design covering normalization, indexing, query optimization, and migration strategies"

Trigger Condition Patterns

STOP — Verify the description would match test prompts from Phase 1 before proceeding.

Phase 3: Harden the Skill (REFACTOR)

Review and close loopholes:

Token Efficiency Targets

Token Reduction Strategies

• Use tables instead of prose for structured information
• Use terse imperative sentences, not explanatory paragraphs
• Move reference material to separate files (loaded only when needed)
• Eliminate redundancy — say it once
• Use code examples only when the pattern is non-obvious

STOP — Re-run test prompts mentally. Does the skill trigger correctly for all 5? Does it NOT trigger for near-misses?

Phase 4: Validate and Save

1. Verify all 10 required elements from Phase 2 are present 2. Verify token budget is within target 3. Verify STOP markers exist between phases 4. Save the SKILL.md file 5. Test by invoking the skill with each test prompt

Validation Checklist

Skill Types and Testing

Testing by Skill Type

Anti-Patterns / Common Mistakes

Anti-Rationalization Guards

• [HARD-GATE] Do NOT write a skill without defining test prompts first (Phase 1)
• [HARD-GATE] Do NOT omit the description field or use a non-"Use when" format
• Do NOT skip the hardening phase — every skill needs rationalization review
• Do NOT skip the validation checklist — all 11 items must pass
• Do NOT create skills over 500 lines — split into skill + reference file
• Do NOT use prose where a table would be clearer

Integration Points

Concrete Example: Complete Minimal Skill

---
name: docker-setup
description: "Use when creating Dockerfiles, docker-compose configurations, or containerizing an application for development or production"
---

# Docker Setup

## Overview

Guide the creation of Docker configurations for development and production environments. Produces Dockerfiles, docker-compose files, and .dockerignore with best practices.

## Phase 1: Discovery
[Ask about: runtime, ports, volumes, env vars, multi-stage needs]
STOP — confirm requirements.

## Phase 2: Generate Configuration
[Create Dockerfile, docker-compose.yml, .dockerignore]
STOP — present for review.

## Phase 3: Verify
[Build image, run container, verify health check]

## Anti-Patterns
| Mistake | Fix |
|---------|-----|
| Running as root | Use non-root USER |
| No .dockerignore | Always create one |

## Skill Type
**Flexible**

Skill Type

Rigid — The TDD approach (test prompts first), required structure elements, and validation checklist must be followed exactly. No elements may be skipped.

Anthropic Best Practices for Skill Authoring

Reference document for writing Claude Code skills that follow Anthropic's official guidance.

Progressive Disclosure (3-Tier Context Loading)

Load context incrementally to minimize token usage:

Tier 1: Always Loaded

• The description field in frontmatter
• Used for skill selection/matching
• Must be under 1024 characters
• Contains trigger conditions only

Tier 2: Loaded When Skill is Selected

• The SKILL.md body content
• Contains instructions, steps, patterns
• Must be under 500 lines
• Should be self-contained

Tier 3: Loaded On Demand

• Referenced files (checklists, templates, examples)
• Loaded only when explicitly needed during execution
• One level deep -- referenced files should not reference other files

Description as Trigger Condition

The description field is a search index, not documentation.

Do:

description: "Use when reviewing pull requests, checking code quality, or performing pre-merge validation"

Do not:

description: "This skill helps developers perform thorough code reviews using best practices from Google's engineering guidelines"

Rules:

• Start with "Use when..."
• List 2-5 specific trigger scenarios
• Use verbs that match user intent (creating, debugging, deploying, reviewing)
• Maximum 1024 characters
• No marketing language or superlatives

Body Under 500 Lines

The SKILL.md body is loaded into context whenever the skill is invoked. Every line costs tokens.

Strategies to stay under 500 lines:

• Use tables instead of verbose lists
• Move reference material to separate files
• Use terse imperative sentences
• Include code examples only when the pattern is non-obvious
• Eliminate repeated information

File References One Level Deep

Skills can reference other files for detailed content:

See [OWASP Checklist](./owasp-checklist.md) for detailed vulnerability patterns.

Rules:

• Referenced files are loaded only when needed
• References must be one level deep (a referenced file must not reference another file)
• Use relative paths from the skill directory
• Referenced files should be self-contained

Forward Slashes Only

All file paths in skills must use forward slashes, regardless of platform:

# Correct
templates/skills/my-skill/SKILL.md

# Incorrect
templates\skills\my-skill\SKILL.md

Self-Contained Skills

Skills should minimize external dependencies:

• Do not assume specific tools are installed unless checking first
• Do not reference URLs that may change or become unavailable
• Include essential information directly in the skill body
• Use referenced files (in the same directory) for supplementary content
• Do not depend on other skills being present -- reference them as optional enhancements

Allowed-Tools Field for Security

When a skill should only use specific tools, restrict access:

---
name: read-only-review
description: "Use when performing read-only code analysis"
allowed-tools:
  - Read
  - Grep
  - Glob
---

This prevents the skill from accidentally modifying files, running commands, or accessing resources it should not touch.

Use cases:

• Read-only analysis skills (no Bash, no Edit, no Write)
• Skills that should not access the network (no WebFetch)
• Skills restricted to specific MCP tools

Testing Skills Before Deployment

Manual Testing

1. Write 3-5 test prompts that should trigger the skill 2. Write 2-3 prompts that should NOT trigger it 3. Invoke each prompt and verify correct skill selection 4. Check that the skill produces expected output for each test prompt 5. Verify token usage is within budget

Checklist

• [ ] Description starts with "Use when..."
• [ ] Description is under 1024 characters
• [ ] Body is under 500 lines
• [ ] All file paths use forward slashes
• [ ] Referenced files exist and are one level deep
• [ ] No external URL dependencies that could break
• [ ] Frontmatter has name and description
• [ ] Skill is self-contained (works without other skills installed)
• [ ] Test prompts trigger correctly
• [ ] Near-miss prompts do not trigger incorrectly
• [ ] Token usage is within target for skill type