writing-skills

name	writing-skills
description	Use when creating new skills, editing existing skills, or verifying skills work before deployment

Writing Skills

Overview

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

You write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), write the skill (documentation), watch tests pass (agents comply), and refactor (close loopholes).

Core principle: If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing.

REQUIRED BACKGROUND: You MUST understand ltk:test-driven-development before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill adapts TDD to documentation.

What is a Skill?

A skill is a reference guide for proven techniques, patterns, or tools. Skills help future Claude instances find and apply effective approaches.

Skills are: Reusable techniques, patterns, tools, reference guides

Skills are NOT: Narratives about how you solved a problem once

TDD Mapping for Skills

TDD Concept	Skill Creation
Test case	Pressure scenario with subagent
Production code	Skill document (SKILL.md)
Test fails (RED)	Agent violates rule without skill (baseline)
Test passes (GREEN)	Agent complies with skill present
Refactor	Close loopholes while maintaining compliance

Skill Types

Technique

Concrete method with steps to follow (condition-based-waiting, root-cause-tracing)

Pattern

Way of thinking about problems (flatten-with-flags, test-invariants)

Reference

API docs, syntax guides, tool documentation

Directory Structure

skills/
  category/
    skill-name/
      SKILL.md              # Main reference (required)
      supporting-file.*     # Only if needed

Separate files for:

1. Heavy reference (100+ lines) - API docs, comprehensive syntax
2. Reusable tools - Scripts, utilities, templates

Keep inline:

• Principles and concepts
• Code patterns (< 50 lines)
• Everything else

SKILL.md Structure

Frontmatter (YAML):

• Only two fields supported: name and description
• Max 1024 characters total
• name: Use letters, numbers, and hyphens only
• description: Third-person, describes ONLY when to use (NOT what it does)
  • Start with "Use when..." to focus on triggering conditions
  • Include specific symptoms, situations, and contexts
  • NEVER summarize the skill's process or workflow

---
name: Skill-Name-With-Hyphens
description: Use when [specific triggering conditions and symptoms]
---

# Skill Name

## Overview
What is this? Core principle in 1-2 sentences.

## When to Use
Bullet list with SYMPTOMS and use cases
When NOT to use

## Core Pattern (for techniques/patterns)
Before/after code comparison

## Quick Reference
Table or bullets for scanning common operations

## Implementation
Inline code for simple patterns
Link to file for heavy reference or reusable tools

## Common Mistakes
What goes wrong + fixes

Claude Search Optimization (CSO)

Critical for discovery: Future Claude needs to FIND your skill

Rich Description Field

CRITICAL: Description = When to Use, NOT What the Skill Does

The description should ONLY describe triggering conditions. Do NOT summarize the skill's process or workflow.

Why this matters: When a description summarizes workflow, Claude may follow the description instead of reading the full skill content.

# BAD: Summarizes workflow - Claude may follow this instead of reading skill
description: Use when executing plans - dispatches subagent per task with code review between tasks

# GOOD: Just triggering conditions, no workflow summary
description: Use when executing implementation plans with independent tasks in the current session

Keyword Coverage

Use words Claude would search for:

• Error messages: "Hook timed out", "race condition"
• Symptoms: "flaky", "hanging", "zombie"
• Synonyms: "timeout/hang/freeze"
• Tools: Actual commands, library names

Descriptive Naming

Use active voice, verb-first:

• creating-skills not skill-creation
• condition-based-waiting not async-test-helpers

The Iron Law (Same as TDD)

NO SKILL WITHOUT A FAILING TEST FIRST

This applies to NEW skills AND EDITS to existing skills.

Write skill before testing? Delete it. Start over.

RED-GREEN-REFACTOR for Skills

RED: Write Failing Test (Baseline)

Run pressure scenario with subagent WITHOUT the skill. Document exact behavior:

• What choices did they make?
• What rationalizations did they use (verbatim)?
• Which pressures triggered violations?

GREEN: Write Minimal Skill

Write skill that addresses those specific rationalizations. Don't add extra content for hypothetical cases.

Run same scenarios WITH skill. Agent should now comply.

REFACTOR: Close Loopholes

Agent found new rationalization? Add explicit counter. Re-test until bulletproof.

Skill Creation Checklist

RED Phase - Write Failing Test:

• Create pressure scenarios
• Run scenarios WITHOUT skill - document baseline behavior verbatim
• Identify patterns in rationalizations/failures

GREEN Phase - Write Minimal Skill:

• Name uses only letters, numbers, hyphens
• YAML frontmatter with only name and description (max 1024 chars)
• Description starts with "Use when..." and includes specific triggers/symptoms
• Description written in third person
• Keywords throughout for search
• Clear overview with core principle
• Address specific baseline failures identified in RED
• Run scenarios WITH skill - verify agents now comply

REFACTOR Phase - Close Loopholes:

• Identify NEW rationalizations from testing
• Add explicit counters
• Build rationalization table from all test iterations
• Re-test until bulletproof

Deployment:

• Commit skill to git