# Writing Skills

> Use when creating new skills, editing existing skills, or verifying skills work before deployment

- Skill: `yeaight7/writing-skills` (Agent Skill)
- Install (CLI): `npx skillmds@latest add yeaight7/writing-skills`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yeaight7/writing-skills/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: yeaight7 (https://skillmd.com/u/yeaight7)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/yeaight7/writing-skills

---


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

## What is a Skill?

A **skill** is a reference guide for proven techniques, patterns, or tools. Skills help future agent 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

## SKILL.md Structure

**Frontmatter (YAML):**

- Two required fields: `name` and `description`
- `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**
  - Keep under 500 characters if possible

**Body format:** Use pure Markdown headings for structure. Prefer `## Purpose`, `## When to Use`, `## Workflow`, and `## Verification`. Do not use XML-like tags such as `<Purpose>`, `<Workflow>`, or `<Use_When>` as normal top-level sectioning. Use XML-like delimiters only for nested examples, quoted input, external documents, or machine-readable prompt payloads.

````markdown
---
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
Before/after comparison or step-by-step

## Quick Reference
Table or bullets for scanning common operations

## Common Mistakes
What goes wrong + fixes
````

## Claude Search Optimization (CSO)

**Critical:** The description field must help agents decide whether to load the skill. It should ONLY describe triggering conditions — never summarize the workflow.

```yaml
# BAD: Summarizes workflow - agent may follow this instead of reading the full skill
description: Use when executing plans - dispatches subagent per task with review between tasks

# GOOD: Just triggering conditions
description: Use when executing implementation plans with independent tasks
```

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

## File Organization

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

**Keep inline:** Principles, concepts, code patterns under 50 lines, everything else.

**Separate files for:** API docs/reference over 100 lines, reusable scripts/utilities.

## The Iron Law

```
NO SKILL WITHOUT A FAILING TEST FIRST
```

This applies to NEW skills AND EDITS to existing skills.

## RED-GREEN-REFACTOR for Skills

| TDD Concept | Skill Creation |
| --- | --- |
| Test case | Pressure scenario with subagent |
| RED | Agent violates rule without skill (baseline) |
| GREEN | Agent complies with skill present |
| REFACTOR | Close loopholes while maintaining compliance |

### RED: Write Failing Test (Baseline)

Run pressure scenario WITHOUT the skill. Document exact behavior:

- What choices did they make?
- What rationalizations did they use (verbatim)?

### GREEN: Write Minimal Skill

Write skill addressing those specific rationalizations. Don't add extra content for hypothetical cases. Verify agent now complies.

### REFACTOR: Close Loopholes

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

## Skill Creation Checklist

**RED Phase:**

- [ ] Run baseline scenario WITHOUT skill — document violations verbatim

**GREEN Phase:**

- [ ] `name` uses only letters, numbers, hyphens
- [ ] YAML frontmatter with `name` and `description`
- [ ] Pure Markdown body with headings, not XML-like top-level section tags
- [ ] Description starts with "Use when..." — no workflow summary
- [ ] Keywords throughout for discovery
- [ ] Clear overview with core principle
- [ ] Run scenarios WITH skill — verify compliance

**REFACTOR Phase:**

- [ ] Identify new rationalizations from testing
- [ ] Add explicit counters for discipline skills
- [ ] Build rationalization table

## Common Mistakes

| Anti-Pattern | Why Bad |
|---|---|
| Narrative storytelling | Too specific, not reusable |
| Multi-language examples | Mediocre quality, maintenance burden |
| Generic labels (step1, helper2) | No semantic meaning |
| Description summarizing workflow | Agent follows description, skips full skill |

## When to Create a Skill

**Create when:**

- Technique wasn't intuitively obvious
- You'd reference this again across projects
- Pattern applies broadly (not project-specific)

**Don't create for:**

- One-off solutions
- Standard practices documented elsewhere
- Project-specific conventions (put in CLAUDE.md instead)