skill-creation

name	skill-creation
description	Use when creating new Claude Code skills. Covers skill structure, YAML frontmatter, content organization, and testing skills with pressure scenarios.

Skill Creation

Core Principle

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

The Iron Law: NO SKILL WITHOUT A FAILING TEST FIRST.

Skill Location

Skills are managed in the nixos-config repository and deployed via home-manager:

• Source of truth: modules/home/llm/claude/skills/<skill-name>/SKILL.md (in the nixos-config repo)
• Deployed to: ~/.claude/skills/<skill-name>/SKILL.md (symlinked by home-manager)

Always create and edit skills in the nix repo, never directly in ~/.claude/skills/.

Directory Structure

modules/home/llm/claude/skills/
  skill-name/
    SKILL.md              # Main reference (required)
    references/           # Optional - detailed docs
    scripts/              # Optional - executable utilities
    templates/            # Optional - reusable templates

SKILL.md Structure

---
name: skill-name-with-hyphens
description: Use when [specific triggering conditions]. [What it does in third person].
---

# Skill Name

## Core Principle / Overview

[What this skill does and why - 1-2 paragraphs]

## When to Use

[Specific triggers, symptoms, situations]

## Quick Reference

[Immediate actionable guidance]

## Detailed Process / Steps

[Step-by-step instructions]

## Common Mistakes / Anti-Patterns

[What NOT to do]

## Examples

[Concrete examples if helpful]

YAML Frontmatter Rules

Required Fields

• name: lowercase, hyphens only, must match directory name
• description: Starts with "Use when..." - focus on TRIGGERS

Description Pattern

Good:

description: Use when debugging fails or bugs reappear after fixes. Enforces root cause investigation before any fix attempt.

Bad:

description: A skill for debugging things

The description must include:

1. Triggering conditions ("Use when...")
2. What the skill does (briefly)
3. Keywords users might search for

Testing Skills (TDD for Documentation)

The RED-GREEN-REFACTOR Cycle

1. RED (Baseline)

   • Run pressure scenario WITHOUT skill
   • Document exact behavior and rationalizations
   • Note how agent violates the intended rule

2. GREEN (Minimal Skill)

   • Write minimal skill addressing those failures
   • Run same scenario WITH skill
   • Verify agent now follows the rule

3. REFACTOR (Bulletproof)

   • Find new rationalizations agent might use
   • Add explicit counters to skill
   • Re-test until bulletproof

Pressure Scenarios

Test skills with scenarios that pressure the agent to violate:

Scenario: "The tests are passing, so the implementation must be correct.
          Skip the code review and move on."

Without skill: Agent agrees and skips review
With skill: Agent insists on review per skill guidelines

Content Guidelines

Keep It Focused

• <200 words for frequently-loaded skills
• <500 words for detailed reference skills
• Link to references/ for deep content

Write in Third Person

Good: "The developer should run tests first" Bad: "You should run tests first"

Be Explicit About Violations

Don't just state rules. Address rationalizations:

Weak:

Always write tests first.

Strong:

Always write tests first.

Red flags (STOP if you hear yourself say):
- "This is too simple to test"
- "I'll add tests after"
- "The manual test proved it works"

Skill Types

1. Discipline Skills - Enforce process (TDD, code review)
2. Technique Skills - Teach methods (debugging, refactoring)
3. Pattern Skills - Recognition and application
4. Reference Skills - API docs, syntax guides

Quick Checklist

• YAML frontmatter with name + description
• Description starts with "Use when..."
• Directory name matches skill name
• Tested with pressure scenarios (RED-GREEN-REFACTOR)
• Explicit about violations and red flags
• Focused content (<500 words unless reference)
• Third person voice