/shipyard-writing-skills

name: shipyard-writing-skills
description: Applies test-driven development to creating and editing skills. Use when creating, editing, or improving a skill, editing any SKILL.md file, writing skill descriptions, or debugging why a skill does not activate. Also use when the user says "create a skill", "write a skill", "new skill", "improve this skill", or "skill isn't triggering", or when reviewing skill quality.

<!-- TOKEN BUDGET: 380 lines / ~1140 tokens -->

Writing Skills

<activation>

When This Skill Activates

• Creating a new skill (SKILL.md file)
• Editing or improving an existing skill
• Verifying a skill works before deployment
• Reviewing skill quality or effectiveness

Natural Language Triggers

• "create a skill", "write a skill", "new skill", "improve this skill"

</activation>

Overview

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

**Personal skills live in agent-specific directories (`~/.claude/skills` for Claude Code, `~/.codex/skills` for Codex)**

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 shipyard:shipyard-tdd 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

<instructions>

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 | | **Write test first** | Run baseline scenario BEFORE writing skill | | **Watch it fail** | Document exact rationalizations agent uses | | **Minimal code** | Write skill addressing those specific violations | | **Watch it pass** | Verify agent now complies | | **Refactor cycle** | Find new rationalizations -> plug -> re-verify |

The entire skill creation process follows RED-GREEN-REFACTOR.

When to Create a Skill

**Create when:**

• Technique wasn't intuitively obvious to you
• You'd reference this again across projects
• Pattern applies broadly (not project-specific)
• Others would benefit

**Don't create for:**

• One-off solutions
• Standard practices well-documented elsewhere
• Project-specific conventions (put in CLAUDE.md)
• Mechanical constraints (if it's enforceable with regex/validation, automate it -- save documentation for judgment calls)

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 (office docs)

Directory Structure

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

**Flat namespace** - all skills in one searchable namespace

**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):**

• `name`: max 64 chars, lowercase letters, numbers, and hyphens only; no "anthropic" or "claude"
• `description`: max 1024 chars, no XML tags, third person
• One short clause on what the skill does, then "Use when..." with the triggering conditions
• Put the key use case first; Claude Code shortens descriptions in the skill listing when the budget runs out
• Include specific symptoms, situations, and contexts
• **NEVER summarize the skill's process or workflow steps** (see CSO section for why)
• Keep under 500 characters if possible
• Claude Code supports more optional fields (`argument-hint`, `allowed-tools`, `disable-model-invocation`, and others). See `anthropic-best-practices.md`. Shipyard skills use only `name`, `description`, and `argument-hint`.

---
name: skill-name-with-hyphens
description: Does [one-clause outcome]. Use when [specific triggering conditions and symptoms].
---

# Skill Name

## Overview
What is this? Core principle in 1-2 sentences. Put critical rules here, at the top: after context compaction, only the start of an invoked skill is kept.

## 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

Claude Search Optimization (CSO) — Quick Reference

| Element | Rule | Example | |---------|------|---------| | Description | One-clause outcome + triggering conditions, no workflow steps | `"Fixes flaky async tests. Use when tests hang waiting for async ops"` | | Keywords | Error messages, symptoms, tool names | `"ENOTEMPTY", "flaky", "bats-core"` | | Name | Verb-first, hyphenated | `condition-based-waiting` not `async-helpers` | | Token budget | `<150 words` getting-started, `<500 words` others | Compress, cross-reference | | Cross-refs | Skill name + requirement marker, no `@` links | `**REQUIRED SUB-SKILL:** Use shipyard:foo` |

**Why no `@` links:** `@` syntax force-loads files immediately, consuming con