What Are Skills

Relevant source files

• .cursor-plugin/plugin.json
• README.md
• skills/brainstorming/SKILL.md
• skills/using-superpowers/SKILL.md
• skills/writing-skills/SKILL.md
• skills/writing-skills/render-graphs.js

This page defines skills as a technical construct within the Superpowers system, explaining their structure, discovery mechanisms, and how they differ from conventional documentation. For information about how agents are required to use skills, see The Rule: Mandatory First Response Protocol. For practical guidance on discovering and invoking skills, see Finding and Invoking Skills.

Definition

A skill is a structured markdown document that defines a reusable capability for AI coding assistants. Skills are stored as SKILL.md files with YAML frontmatter metadata and follow a standardized format designed for machine discovery and human readability.

Skills are not passive reference documentation. They are active process definitions that agents must check for and invoke before performing related tasks. The system enforces this through the using-superpowers meta-skill loaded at session start.

Key distinguishing characteristics:

Characteristic	Skills	Regular Documentation
Discovery	Searchable via tool calls	Manual browsing required
Invocation	Platform-native tool integration	Read tool or direct file access
Optimization	Claude Search Optimization (CSO)	Standard technical writing
Validation	Pressure-tested with TDD methodology	Typically untested
Enforcement	Mandatory checking protocol	Optional reference
Structure	Strict YAML frontmatter + sections	Freeform markdown

Sources: README.md1-160 RELEASE-NOTES.md163-169 skills/writing-skills/testing-skills-with-subagents.md1-385

File Structure

SKILL.md Format

Every skill must contain a SKILL.md file as its primary definition. Skills are stored in directories like skills/test-driven-development/SKILL.md or skills/brainstorming/SKILL.md. The file consists of two parts:

YAML Frontmatter:

Required frontmatter fields:

• name: Lowercase kebab-case matching directory name (e.g., test-driven-development, using-git-worktrees)
• description: CSO-optimized trigger description, 200-500 characters, third-person voice

The frontmatter is parsed by lib/skills-core.js which extracts the YAML header and makes it available to platform tools. Maximum total frontmatter size is 1024 characters as enforced by platform APIs.

Standard sections:

1. Overview - Brief explanation of skill purpose
2. When to Use - Specific trigger conditions and symptoms
3. Quick Reference - Scannable tables or checklists
4. Process/Workflow - Step-by-step instructions (often in DOT diagrams)
5. Integration - References to related skills using explicit markers

Sources: skills/writing-skills/SKILL.md93-137 RELEASE-NOTES.md379-436

Directory Structure

Diagram: Actual Skill Directory Structure and Bundling

Supporting files are bundled within the skill directory and referenced from SKILL.md. Real examples from the codebase:

• Techniques - systematic-debugging/root-cause-tracing.md, systematic-debugging/defense-in-depth.md, systematic-debugging/condition-based-waiting.md
• Tools - systematic-debugging/find-polluter.sh, writing-skills/render-graphs.js
• Examples - systematic-debugging/condition-based-waiting-example.ts
• References - test-driven-development/testing-anti-patterns.md, writing-skills/anthropic-best-practices.md

The bundling pattern consolidates related sub-skills into parent directories, reducing the total number of top-level skills that must be searched during discovery.

Sources: RELEASE-NOTES.md218-232 skills/writing-skills/SKILL.md72-90

Claude Search Optimization (CSO)

Skills use Claude Search Optimization to ensure agents discover them through semantic search without requiring explicit naming. The description field is the primary CSO surface.

CSO Principles

❌ Bad Description (Workflow Summary):

Problem: Claude reads the description instead of the full skill content, missing critical details.

✅ Good Description (Trigger-Only):

CSO Requirements:

1. Trigger-focused - State when to use, not how to use
2. Keyword coverage - Include terms users might search for
3. No workflow details - These belong in SKILL.md body
4. 200-500 characters - Long enough for coverage, short enough to scan

Why this matters: Agents perform semantic search over descriptions to find relevant skills. Workflow summaries in descriptions cause agents to follow the abbreviated description instead of loading the full skill content.

Sources: RELEASE-NOTES.md162-169 skills/writing-skills/testing-skills-with-subagents.md220-226

Skill Types and Categories

Skills are organized into functional categories based on their role in the development workflow:

Diagram: Skill Type Hierarchy and Common Workflows

Meta Skills

Control how the skill system itself operates. Loaded automatically at session start.

• using-superpowers - Enforces mandatory skill checking protocol
• writing-skills - Defines skill creation and testing methodology

Process Skills

Define high-level workflows that orchestrate other skills. Take priority when multiple skills apply.

• brainstorming - Design refinement before implementation
• systematic-debugging - Structured root cause investigation
• writing-plans - Task breakdown and specification

Implementation Skills

Define specific technical practices for code execution.

• test-driven-development - RED-GREEN-REFACTOR enforcement
• using-git-worktrees - Branch isolation and setup
• subagent-driven-development - Fresh context per task with two-stage review

Priority rule: Process skills trigger before implementation skills. For example, "Build feature X" triggers brainstorming first, then writing-plans, then test-driven-development.

Sources: README.md99-123 RELEASE-NOTES.md164-170

Discovery and Invocation

Discovery Mechanism

Diagram: Skill Discovery Code Flow Through skills-core.js

Skills are discovered through three-tier priority system implemented in lib/skills-core.js:

1. Project skills - .opencode/skills/ or .claude/skills/ in current working directory
2. Personal skills - Platform-specific directories (~/.claude/skills/, ~/.config/opencode/skills/, ~/.agents/skills/)
3. Superpowers skills - skills/ directory in plugin root (symlinked from ~/.config/superpowers/skills/ on some platforms)

Key functions in skills-core.js:

• findAllSkills(searchPaths) - Recursively scans directories for SKILL.md files
• parseSkillFile(skillPath) - Extracts YAML frontmatter using regex
• resolveSkillByName(skillName, searchPaths) - Returns first match following priority order
• formatSkillsForClaude(skills) - Formats skill list for display

Sources: RELEASE-NOTES.md289-325 README.md27-78

Platform-Specific Invocation

Diagram: Platform Tool Integration With Actual File Paths

Platform	Tool Name	Implementation File	Search Paths	Bootstrap Hook
Claude Code	Skill	Native (built-in)	skills/ (plugin root)	hooks/session-start.sh
OpenCode	skill	Native (built-in)	~/.config/opencode/skills/superpowers/	.opencode/plugins/superpowers.js
Codex	superpowers-codex use-skill	.codex/superpowers-codex (Node.js CLI)	~/.agents/skills/superpowers/	Native skill discovery

All platforms use lib/skills-core.js module for consistent skill file parsing via parseSkillFile() and resolveSkillByName() functions.

Sources: hooks/session-start.sh1-52 RELEASE-NOTES.md33-37 RELEASE-NOTES.md118-136

Skill Cross-References

Skills reference each other using explicit requirement markers:

Namespace format: All skill references use superpowers: prefix to distinguish repository skills from personal skills.

Marker	Meaning	Agent Behavior
REQUIRED BACKGROUND	Prerequisites to understand	Must read before using skill
REQUIRED SUB-SKILL	Must invoke during workflow	Must invoke at appropriate step
Complementary skills	Optional but helpful	May invoke if relevant

Sources: RELEASE-NOTES.md357-363 RELEASE-NOTES.md404-412

Validation and Testing

Test-Driven Development for Skills

Skills undergo the same RED-GREEN-REFACTOR cycle as code:

TDD Phase	Skill Testing	Artifact
RED	Run scenario without skill	Documented agent failures
GREEN	Write skill addressing failures	SKILL.md with counters
REFACTOR	Close rationalization loopholes	Updated red flags and tables

Pressure scenarios combine multiple stressors to test skill enforcement:

• Time pressure (deadlines, emergencies)
• Sunk cost (hours of work at risk)
• Authority (manager override)
• Exhaustion (end of day)

Example test scenario:

Running this without the test-driven-development skill captures baseline failures and rationalizations. Running with the skill verifies enforcement.

Sources: skills/writing-skills/testing-skills-with-subagents.md1-385 skills/writing-skills/examples/CLAUDE_MD_TESTING.md1-190

Rationalization Tables

Skills include explicit tables mapping agent excuses to rebuttals:

These tables are built iteratively through REFACTOR cycles, addressing each new rationalization discovered during pressure testing.

Sources: skills/writing-skills/testing-skills-with-subagents.md164-210

Enforcement Mechanisms

The Rule and Bootstrap Injection

The skills/using-superpowers/SKILL.md meta-skill enforces mandatory skill checking:

"If even 1% chance a skill applies, you MUST invoke it"

This rule is loaded into the system prompt at session start via platform-specific bootstrap mechanisms:

Diagram: Bootstrap Injection Implementation Code Flow

Key implementation details:

• Claude Code: hooks/session-start.sh runs synchronously (async: false in hooks/hooks.json), reads skills/using-superpowers/SKILL.md, escapes for JSON using bash parameter substitution, outputs hookSpecificOutput.additionalContext
• OpenCode: .opencode/plugins/superpowers.js uses experimental.chat.system.transform hook, calls getBootstrapContent() function which imports lib/skills-core.js, modifies system prompt directly
• Cursor: Uses same hooks/session-start.sh as Claude Code with additional_context output format

Agents cannot rationalize around the injected content due to:

1. Red flag detection - Common excuses are pre-emptively countered in using-superpowers
2. Absolute language - "You do not have a choice. You cannot rationalize your way out."
3. Mandatory first response protocol - 5-step checklist before any response

Sources: hooks/session-start.sh1-52 RELEASE-NOTES.md25-28 RELEASE-NOTES.md289-299

Anti-Rationalization Guards

Skills include Red Flags sections listing common evasion patterns:

Each red flag triggers the agent to re-evaluate and invoke the skill anyway.

Sources: RELEASE-NOTES.md312-327

Skill Lifecycle

Diagram: Complete Skill Lifecycle From Creation to Production

Key implementation stages:

1. Creation - Follow skills/writing-skills/SKILL.md TDD methodology using skills/writing-skills/testing-skills-with-subagents.md pressure scenarios
2. Deployment - Standard git workflow to main branch
3. Distribution - Plugin update triggers via /plugin update superpowers command; next session runs hooks/session-start.sh which injects skills/using-superpowers/SKILL.md
4. Usage - Agents discover via Skill tool semantic search over frontmatter descriptions; invoke via platform-specific tools
5. Monitoring - Real-world failures captured as rationalization patterns, feed back into RED phase testing

Sources: skills/writing-skills/SKILL.md1-656 skills/writing-skills/testing-skills-with-subagents.md1-385 hooks/session-start.sh1-52

Why Skills Work

Skills achieve enforcement through structural properties absent in conventional documentation:

Machine-Readable Metadata

• YAML frontmatter enables semantic search
• description field optimized for LLM retrieval
• Standardized format allows automated validation

Pressure-Tested Content

• TDD methodology validates enforcement under stress
• Rationalization tables preemptively counter excuses
• Red flags detect evasion patterns

Mandatory Protocol

• using-superpowers loaded at session start
• "The Rule" makes checking non-optional
• Anti-rationalization guards prevent bypass

Supporting Ecosystem

• Platform-native tool integration
• Three-tier priority system for overriding
• Continuous validation loop via monitoring

The combination creates a system where agents consistently use proven processes instead of ad-hoc improvisation.

Sources: README.md1-160 skills/writing-skills/testing-skills-with-subagents.md1-385