# Writing Skills

Create, edit and test agent skills before deploying them.

- Repository: https://github.com/obra/superpowers (310584 stars)
- Category: AI and agents
- License: MIT
- Last updated: 2026-10-29
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add obra/superpowers --skill writing-skills -g -a claude-code -y`
Codex: `npx skills add obra/superpowers --skill writing-skills -g -a codex -y`
Cursor: `npx skills add obra/superpowers --skill writing-skills -g -a cursor -y`
Gemini CLI: `npx skills add obra/superpowers --skill writing-skills -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add obra/superpowers`

## Description

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

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Writing Skills

## Overview

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

**Personal skills live in your runtime's skills directory** (`~/.claude/skills/` on Claude Code), see [codex-tools.md](../using-superpowers/references/codex-tools.md) or [gemini-tools.md](../using-superpowers/references/gemini-tools.md) for the path on those runtimes. Codex, Copilot CLI, and Gemini CLI all also recognize `~/.agents/skills/` as a cross-runtime alias.

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 references/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 agents 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

The rest: https://github.com/obra/superpowers/blob/HEAD/skills/writing-skills/SKILL.md