Writing Skills

Overview

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

Personal skills live in agent-specific directories (~/.claude/skills for Claude Code, ~/.agents/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 superjawn:test-driven-development before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill adapts TDD to documentation.

Official guidance: For Anthropic's official skill authoring best practices, see anthropic-best-practices.md. This document provides additional patterns and guidelines that complement the TDD-focused approach in this skill.

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

Research phase

Before writing tests for a new skill, gather outside context. This is default-on: skip only with explicit, justified statement.

The aim is to ground the skill design in real prior art and current best practice, not just your own recall of patterns.

1. Pick research kinds

From the menu — patterns + best practices, prior art, authoritative guidance, user-context.

For writing-skills, the defaults are: web (skill authoring patterns + recent discourse) and codebase (prior art — does this overlap with an existing skill in this repo or a sibling plugin?). Add others when warranted — authoritative when the skill encodes a specific external standard (W3C, RFC, vendor docs), or user-context when prior decisions in memory shape the right shape for the skill.

2. Dispatch

Subagent by default:

Explore for codebase / prior-art questions ("does this repo or any installed plugin already have a skill for X?", "what naming convention do existing skills use here?")
general-purpose for web / authoring patterns ("what shape do effective Claude Code skills take?", "common pitfalls for skills in this domain?")
Run multiple in parallel when the kinds are independent

Inline only for light-touch research (single grep across ~/.claude/skills/, memory check).

3. Record findings

Findings land at .superpowers/skill-design-<skill-slug>.md where <skill-slug> is the kebab-case name of the skill you are designing. Write 3–5 tight bullets — load-bearing links/refs, prior-art notes, anything considered-but-ruled-out so future-you knows it was checked. The directory .superpowers/ is git-ignored by upstream convention.

4. Skip protocol

If skipping, write one line to .superpowers/skill-design-<skill-slug>.md: Skipped research because <reason>. <Verifiable pointer if applicable>.

Valid reasons:

Trivial scope (typo, comment edit, single-line config)
Fresh prior research — same topic in current session OR within last 7 days with verifiable spec/plan pointer. If the pointer doesn't resolve, the skip is invalid. (Beyond 7 days, repeat the research even if you remember the prior findings — the landscape drifts.)
User explicit — must quote the phrase that authorized the skip.
Repeat of identical task — must include a pointer to the prior successful run.

Invalid reasons: "I think I know", "seems straightforward", "moving fast", "user wants this done quickly", "already familiar with this codebase". If those are tempting, do the research.

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:

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

Keep inline:

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

SKILL.md Structure

Frontmatter (YAML):

Two required fields: name and description (see agentskills.io/specification for all supported fields)
Max 1024 characters total
name: Use letters, numbers, and hyphens only (no parentheses, special chars)
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 (see CSO section for why)
Keep under 500 characters if possible

---
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
[Small inline flowchart IF decision non-obvious]

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

## Real-World Impact (optional)
Concrete results

Claude Search Optimization (CSO)

**Critical for discove

writing-skills

Como adicionar

Cole no README do seu repo

Skills relacionadas

xlsx

how-it-works

weekly-digests

mem-search

Receba novas skills de Dados e Análise toda segunda