How Skills Work

The Core Idea

AI coding agents (Claude Code, Cursor, Copilot, OpenCode, Gemini CLI, Codex, Windsurf) are instruction-followers. They do not have an opinion about how to develop software — they follow whatever guidance is in their context. SuperSpecs exploits this by injecting a structured, opinionated workflow into every agent's context before any development begins.

The result: every agent on every project follows the same four-phase lifecycle — Plan, Execute, Verify, Ship — without any custom integration code.

Skills

A skill is a Markdown file (SKILL.md) that contains step-by-step instructions for one phase of the workflow. Skills are the only real source code in the framework.

.skills/
└── execute-tdd/
    └── SKILL.md        ← plain Markdown, no code

Each SKILL.md starts with a YAML frontmatter block:

---
name: execute-tdd
description: Enforce RED → GREEN → REFACTOR with no exceptions
slash_command: tdd
phase: "2.3 — Execute › per task (TDD)"
---

• slash_command determines the command file name (e.g. tdd.md → /superspecs:tdd)
• description is used in command files and agent skill listings
• The body is the detailed instruction set the agent follows when invoked

Two-Layer Installation

setup.sh runs two separate installation steps for each agent:

1. Skills (auto-discovery)

Each AI tool has a designated directory it scans for skills. setup.sh creates a <name>/SKILL.md symlink structure in each of those directories:

~/.claude/skills/execute-tdd/SKILL.md   → .skills/execute-tdd/SKILL.md
~/.agents/skills/execute-tdd/SKILL.md   → .skills/execute-tdd/SKILL.md
~/.config/opencode/skills/execute-tdd/SKILL.md  → .skills/execute-tdd/SKILL.md
# ... same for every agent and every skill

When an agent starts, it reads its skills directory and registers each skill as available context. The description field tells the agent when to invoke a skill automatically.

2. Commands (slash invocation)

setup.sh also generates real command files (not symlinks) in each agent's commands directory. The file name determines the slash command — not the frontmatter:

~/.claude/commands/superspecs/ship.md        →  /superspecs:ship   (Claude Code)
~/.config/opencode/commands/superspecs-ship.md  →  /superspecs-ship   (OpenCode)

Generated command files contain only a description frontmatter field and the skill body. The SKILL.md-specific fields (slash_command, name, phase) are intentionally stripped.

# ~/.claude/commands/superspecs/ship.md (generated)
---
description: Create the PR, write the changelog...
---

# Skill: ship
You are shipping the feature...

Command naming by agent:

OpenCode does not support colon namespacing in command names.

Bootstrap Files

Beyond skills and commands, each agent also gets a bootstrap file that is loaded at the start of every session. These prime the agent with the lifecycle summary so it behaves correctly even before a slash command is issued.

Bootstrap files are short — they contain the lifecycle diagram, the slash command table, the four hard rules, and the key directory paths. They fit comfortably in the initial context window and cost negligible tokens.

The Four Hard Rules

These are enforced by the skills and bootstrap files. Agents are instructed to refuse to continue if any rule is violated.