C✳CODEZ.WIN
🌐 English

Localized reading guide

writing-skillsPurpose, usage and source

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

Source retrieved:

Source repository
obra/superpowers
SKILL.md
skills/writing-skills/SKILL.md
Repository stars
309,479
Repository updated
2026-10-30
Categories
Agent workflows
Last collected

License: MIT

Source SKILL.md

Workflow excerpts are reading aids, not executable instructions from Codez. No third-party Skill was run to produce this page.

The purpose and workflow passages below are upstream material, organized and translated for reading. They are distinct from the separately labeled Codez editorial analysis.

What this Skill does

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

How the upstream workflow works

Discovery Workflow

How future agents find your skill: Encounters problem ("tests are flaky") Searches skills (greps descriptions, browses categories) Finds SKILL (description matches)

Upstream passage · L388 ↗

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

Upstream passage · L8 ↗

When to Create a Skill

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

Upstream passage · L47 ↗
Upstream passage · ↗
skills/
  skill-name/
    SKILL.md              # Main reference (required)
    supporting-file.*     # Only if needed

Requirements and setup

Discipline-Enforcing Skills (rules/requirements)

Examples: TDD, verification-before-completion, designing-before-coding Academic questions: Do they understand the rules?

Upstream passage · L188 ↗

Limits and quality checks

No separate limits passage was selected from this file. This does not mean the Skill is safe for every input or environment. Review the complete source and validate your own result.

Start with a safe trial

  1. Check the supported host and the repository installation instructions. Keep the Skill directory and its referenced scripts, assets and documentation together; SKILL.md alone may omit dependencies.
  2. Give the agent your real input, desired output and acceptance criteria. Invocation syntax and available tools depend on the host; this site does not assume a universal install command.
  3. Try the source workflow in a disposable project or on a copy. Review operations that change files, remote services or billable resources before allowing them.
  4. Validate the output against the source quality checks and your own requirements. A successful trigger or a high repository Star count does not establish a correct result.

Skill format and directory specification ↗

Read further in the source

Translation and scope

This reading guide selects passages from the pinned upstream SKILL.md. Translation is assisted. It is not a complete manual or a claim of tested compatibility. Read the original and its referenced files before use.

This introduction refers to the pinned version below; current repository activity and collection time are shown separately.

Source retrieved
Source commit
2ce8aa15d05bd57213e6f746f953aafb7ded7a8b
Source SHA-256
8cb3ac68c6d8c4bb46886b998b09af7989643cab8bd0e46ee86dd62e64546bbe
Back to the full Skill catalog