lgbarn/shipyard/shipyard-writing-skills

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

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

Why no `@` links: @ syntax force-loads files immediately, consuming context tokens you may not need yet.

Critical CSO rule — Description = Outcome + When to Use, NOT the Workflow: When a description summarizes the skill's workflow, Claude follows the description instead of reading the full skill. A description saying "code review between tasks" caused Claude to do ONE review even though the skill showed TWO stages. State the outcome in one short clause, then the triggering conditions. Never list the workflow steps.

Flowchart Usage

Use flowcharts ONLY for:

• Non-obvious decision points
• Process loops where you might stop too early
• "When to use A vs B" decisions

Never use flowcharts for reference material, code examples, linear instructions, or labels without semantic meaning.

Code Examples

One excellent example beats many mediocre ones

Choose most relevant language (testing → TypeScript/JS, system debug → Shell/Python, data → Python).

Good example: complete, runnable, well-commented WHY, from real scenario, ready to adapt.

Don't: implement in 5+ languages, create fill-in-the-blank templates, write contrived examples.

File Organization

</instructions>

<examples>

CSO Description Examples

<example type="good" title="Outcome and triggering conditions, no workflow summary">

description: Executes implementation plans with agents. Use when executing implementation plans with independent tasks in the current session

Outcome plus triggering conditions -- Claude reads the full skill to learn the workflow. </example>

<example type="bad" title="Workflow summary in description">

description: Use when executing plans - dispatches subagent per task with code review between tasks

Summarizes workflow -- Claude follows description instead of reading skill body, misses two-stage review. </example>

Skill Content Examples

<example type="good" title="Well-structured skill with XML tags and clear activation">

---
name: condition-based-waiting
description: Use when tests need to wait for async operations, processes, or state changes instead of using arbitrary sleep/timeouts
---
 
<activation>
## When This Skill Activates
-Tests using sleep(), setTimeout(), or fixed delays
-Flaky tests that pass/fail based on timing
-Waiting for processes, servers, or async state
</activation>
 
<instructions>
## Core Pattern
Poll for condition instead of sleeping...
</instructions>
 
<rules>
## Never
-Use fixed sleep() in tests
-Assume operation completes in N seconds
</rules>

Clear activation, XML structure, rules separated. </example>

<example type="bad" title="Missing structure, narrative style">

# Waiting in Tests
 
Last week I was working on a project where tests were flaky. I found that
using sleep(5) was unreliable. After some experimentation, I discovered
that polling for conditions works better...

Narrative style, no activation triggers, no XML structure, not reusable. </example>

</examples>

<rules>

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. Edit skill without testing? Same violation.

No exceptions:

• Not for "simple additions"
• Not for "just adding a section"
• Not for "documentation updates"
• Don't keep untested changes as "reference"
• Don't "adapt" while running tests
• Delete means delete

Spirit vs. Letter: Technically having a test scenario counts as "testing" only if you watched it fail first. Running a test after writing the skill is not RED-GREEN — it's just GREEN. Always establish a failing baseline first.

REQUIRED BACKGROUND: The shipyard:shipyard-tdd skill explains why this matters.

Testing All Skill Types

Common Rationalizations for Skipping Testing

Bulletproofing Skills Against Rationalization

Discipline skills must resist rationalization:

1. Close every loophole explicitly -- forbid specific workarounds with "No exceptions" lists
2. Address "Spirit vs Letter" -- add early: violating the letter violates the spirit
3. Build rationalization tables from baseline testing -- every excuse gets a counter
4. Create red flags lists for agent self-check (e.g., "Code before test", "This is different because...")
5. Update CSO descriptions with violation symptoms as triggers

Anti-Patterns

</rules>

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?

This is "watch the test fail" - you must see what agents naturally do before writing the skill.

GREEN: Write Minimal Skill