Writing Skills

This is TDD for documentation. You write pressure scenarios with subagents to see where they violate a rule (red), write the skill to address those specific violations (green), then iterate to close loopholes (refactor). The core insight is that if you didn't watch an agent fail without the skill, you don't know if it teaches the right thing. Most of the document focuses on making skills discoverable through rich descriptions that list triggering conditions, not workflow summaries, because testing showed Claude will follow a workflow description instead of reading the actual skill content. Requires understanding TDD fundamentals first.

skills.sh installs: 389
GitHub stars: 33.2K
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add davila7/claude-code-templates --skill writing-skills --agent claude-code

Installs into .claude/skills of the current project.

Files

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, ~/.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 superpowers: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.