Skills Are the New Superpower for AI Coding: A Complete Guide to Claude Code's Modular Knowledge Packages

What is a Skill?

A Skill is a modular knowledge package that extends an AI Agent's capabilities (a reusable capability module).

Think of it as a "specialized operations manual" — when the AI needs to complete a task in a specific domain (like analyzing business logs, converting audio formats, deploying to the cloud), the Skill is loaded to provide dedicated workflows, tool scripts, and domain knowledge. It encapsulates knowledge, processes, and tools together, allowing you to quickly complete tasks in a specific domain.

Skill = Expertise + Operational Flow + Tool Invocation

Core Value: Solidify the knowledge that "general AI doesn't have, but domain experts use daily," enabling the AI to possess domain expert capabilities.

Differences from MCP and Prompt

System Prompt is a one-time instruction, MCP is giving the AI new arms, Skill is giving the AI a code of conduct.

Dimension	System Prompt	MCP	Skill
Essence	One-time role setting	Tool/capability extension protocol	Reusable behavioral constraints
Problem Solved	Temporarily adjust AI style	AI cannot connect to external systems	AI doesn't work according to specifications
Requires Coding	No	Yes (Server/Client)	Not mandatory (pure Markdown is fine, scripts are optional)
Persistence	Current conversation only	Persistent (service always on)	Persistent (file storage)
Target Audience	Everyone	Developers	Everyone
Typical Example	"You are a translation assistant"	Connect to database, call API	Enforce TDD, standardize Git commits

https://github.com/agentskills/agentskills

II. Skill Explanation

skill-name/
├── SKILL.md          ← Must have, core file
└── (Optional resources)
    ├── scripts/      ← Executable scripts (Python/Bash, etc.)
    ├── references/   ← Reference documents (loaded on demand)
    └── assets/       ← Static resources (templates, images, fonts, etc.)

Structure of SKILL.md

Claude Code Skill uses the YAML Front Matter + Markdown Body format:

---
name: skill-unique-name      # Unique identifier for the skill
description: |               # Trigger scenario description (AI judges when to use based on this)
  Use when doing X.
  Use BEFORE doing Y.
  What this Skill does, when to trigger it.
---

# Skill Body (Markdown)  # Operational guide for the AI

## Core Principles
- Principle 1
- Principle 2

## Execution Flow
1. Step 1
2. Step 2
3. Step 3

## Prohibited Actions
- Do not do A
- Do not skip B

The Five Elements of a Skill

┌─────────────────────────────────────────────┐
│  1. Metadata                                │
│     name:        Unique identifier          │
│     description: Trigger scenario description│
│                                             │
│  2. Context (Applicable Context)            │
│     Scenarios and prerequisites for the skill│
│                                             │
│  3. Process (Execution Flow)                │
│     Step-by-step workflow, can include checklist│
│                                             │
│  4. Constraints (Constraint Rules)          │
│     Prohibited actions, must-follow principles│
│                                             │
│  5. Output Format (Output Specification)    │
│     How results should be presented, what format│
└─────────────────────────────────────────────┘

Skill Installation Methods and Directory Structure Creation

# In Claude Code, Skill files are stored in:
~/.claude/skills/        # Global skills (available to all projects)
.claude/skills/          # Project-level skills (available only to the current project)

# File naming:
~/.claude/skills/tdd/SKILL.md
~/.claude/skills/code-review/SKILL.md
~/.claude/skills/git-commit/SKILL.md

Complete Skill Directory Structure

A complete Skill is not just a .md file; it can also include auxiliary resources:

.claude/skills/my-skill/
├── SKILL.md            # Skill main file (required)
├── reference/             # Reference materials directory (optional)
│   ├── api-spec.md        # API specification document
│   ├── style-guide.md     # Code style guide
│   └── examples/          # Example files
│       └── good-example.ts
├── scripts/               # Auxiliary scripts directory (optional)
│   ├── validate.sh        # Validation script (callable by Skill)
│   └── setup.py           # Environment initialization script
└── assets/                # Static resources directory (optional)
    ├── checklist.md       # Checklist template
    └── templates/         # Output templates
        └── report.md

III. Three-Level Loading Mechanism (Understanding This is Crucial)

Skills adopt a "load on demand" design to avoid wasting context window:

Level	Content	When Loaded	Size
Level 1	`name` + `description`	Always in context	~100 words
Level 2	`SKILL.md` body	After Skill is triggered	< 5000 words
Level 3	`scripts/` `references/` `assets/`	When AI deems necessary	Unlimited

Actual Effect: The AI always knows which Skills are available, but only "opens" them when truly needed.

IV. Detailed Explanation of Three Types of Optional Resources

scripts/ Deterministic Scripts

Purpose: Solidify repeatedly written code into directly executable scripts. Scripts callable during Skill execution

Suitable Scenarios:

Rotate PDF: scripts/rotate_pdf.py
Decrypt audio: scripts/decrypt_ncm.py
Analyze logs: scripts/parse_log.py

Advantage: Can be executed without being read into context, saving tokens.

references/ Reference Documents

Purpose: Store knowledge that the AI needs to reference but doesn't need to occupy context constantly. Provide background knowledge and reference specifications for the AI

Suitable Scenarios:

Database table structure: references/schema.md
API documentation: references/api_docs.md
Company policies: references/policies.md

Design Principle: Split into independent files by domain. When the user asks about sales data, only load sales.md, not finance.md.

assets/ Static Resources

Purpose: Store files that will be used in the output, without needing to be read into context. Templates, static files

Suitable Scenarios:

Frontend templates: assets/frontend-template/
PPT templates: assets/slides.pptx
Brand Logo: assets/logo.png
Checklist template: checklist.md

How to Reference Resources in a Skill

---
name: code-review
description: Use when reviewing code changes before merging.
---

## Reference Specifications
Please read the coding standards in reference/style-guide.md before reviewing.

## Execution Flow
1. Run scripts/validate.sh for static checks
2. Review item by item according to assets/checklist.md
3. Output results using the format in assets/templates/report.md

V. Complete Process for Creating a Skill

Step 1: Define the Use Case

Before starting, think clearly about the specific use case:

What words will the user say to trigger this Skill?
What specific task is the AI expected to complete?
What are typical input/output examples?

Step 2: Plan Reusable Resources

For each use case, ask:

"To complete this task, what code/documentation do I need to rewrite/recheck every time?"

Organize the answers into a planning list for scripts/, references/, and assets/.

Step 3: Initialize the Skill

python scripts/init_skill.py <skill-name> --path <output directory>

This will automatically generate the standard directory structure and SKILL.md template.

Step 4: Write the Content

SKILL.md Writing Tips:

description is the trigger mechanism; write it clearly and comprehensively (what scenario, what the user will say)
Keep the body within 500 lines; put details in references/
Start with imperative verbs: "Run the script...", "Read the file..."

Resource File Writing Tips:

Scripts must be actually run and tested after writing
Add a table of contents if reference documents exceed 100 lines
Delete unnecessary example files

Step 5: Package and Publish

python scripts/package_skill.py <skill directory path>

(You can DM me for the script)

Before packaging, it will automatically validate:

YAML frontmatter format
Completeness of required fields
Directory structure compliance

After validation passes, a .skill file (essentially a zip package) is generated.

Step 6: Iterate and Optimize

Use the Skill in real tasks, observe the AI's performance, and continuously improve SKILL.md and resource files.

VI. Core Design Principles

Principle 1: Prioritize Simplicity

The context window is a shared resource. For every added piece of text, ask yourself:

"Is this information the AI doesn't know? What are the consequences of deleting it?"

Don't write: "Before you begin, you need to understand the importance of this task..." Do write: Directly give the operational steps.

Principle 2: Match Freedom to the Task

Task Characteristics	Freedom	Writing Style
Fixed steps, error-prone	Low	Specific scripts + strict parameters
Preferred solution, allows variation	Medium	Pseudocode + configurable parameters
Multiple solutions possible, depends on context	High	Text guidance + heuristic principles

Principle 3: Progressive Disclosure

Put only the core workflow in SKILL.md; point details to references/ files via references:

## Advanced Features

- **Form Filling**: See [FORMS.md](references/FORMS.md)
- **API Reference**: See [API.md](references/API.md)

## Log Format

See [references/log-format.md](references/log-format.md)

VII. A Complete Skill Example

Suppose we want to create a pdf-rotator Skill:

Directory Structure:

pdf-rotator/
├── SKILL.md
└── scripts/
    └── rotate_pdf.py

SKILL.md:

---
name: pdf-rotator
description: |
  Rotate pages in a PDF file. Use when the user needs to rotate PDF pages,
  correct scanned document orientation. Trigger words: rotate PDF, PDF page orientation
---

# PDF Rotation Tool

## Usage

Run `scripts/rotate_pdf.py`:

```bash
python scripts/rotate_pdf.py --input input.pdf --output out.pdf --angle 90
```

Parameter Description:
- `--angle`: Rotation angle, options 90, 180, 270
- `--pages`: Specify page numbers (e.g., `1,3,5`), leave blank to rotate all pages

VIII. Common Mistakes

Mistake	Correct Practice
Writing "when to use" in the SKILL.md body	Should be written in the `description` field (the body is loaded only after triggering, so writing it there is useless)
Creating README.md, CHANGELOG.md	Keep only files necessary for the task
Stuffing all details into SKILL.md	Put details in `references/`, SKILL.md only contains the core process
Skipping script testing	Scripts must be actually run and verified
Deeply nested references	All references files are directly referenced from SKILL.md in one layer

IX. Practical Examples

Example 1: TDD Skill (Enforce Test-Driven Development)

Problem Background: AI always writes implementation code directly, skipping tests, leading to poor code quality.

Skill file ~/.claude/skills/test-driven-development/SKILL.md:

---
name: test-driven-development
description: |
  Use this skill when the user asks to implement any feature, function, or module.
  Enforces Test-Driven Development (TDD) workflow: write tests FIRST, then implementation.
---

## Core Principles

**Red-Green-Refactor Cycle:**

1. **Red**: First write a failing test
2. **Green**: Write the minimum code to make the test pass
3. **Refactor**: Optimize the code while keeping the test passing

## Enforced Workflow

### Step 1: Write Tests (Must be completed first)

Before writing any implementation code, you must:
1. Create a test file (e.g., `test_xxx.py` or `xxx.test.ts`)
2. Write at least one test case
3. Show the test code to the user

### Step 2: Confirm Tests

Confirm with the user:
- "Tests have been written. Shall I proceed to write the implementation code?"

### Step 3: Write Implementation

Only after user confirmation can you write the implementation code.

## Prohibited Actions

- ❌ Do not write implementation code first and then add tests
- ❌ Do not skip tests and directly provide implementation
- ❌ Do not give both tests and implementation in the same response (unless explicitly requested by the user)
- ❌ Do not write tests without assertions

## Test Specifications

```python
# Python example: using pytest
def test_function_should_do_something():
    # Arrange
    input_data = ...
    
    # Act
    result = function_under_test(input_data)
    
    # Assert
    assert result == expected_value
```

```typescript
// TypeScript example: using Jest
describe('functionName', () => {
  it('should do something when given input', () => {
    // Arrange
    const input = ...;
    
    // Act
    const result = functionName(input);
    
    // Assert
    expect(result).toBe(expectedValue);
  });
});
```

## Response Template

When the user asks to implement a feature, use the following format to reply:

---

**📝 Step 1: Write Tests**

```language
// Test code
```

**Scenarios covered by tests:**
- [ ] Scenario 1: Normal input
- [ ] Scenario 2: Boundary case
- [ ] Scenario 3: Exception handling

---

**After confirmation, I will write the implementation code. Shall I continue?**

Effect: The AI is forced to work according to the Red → Green → Refactor cycle, significantly improving code quality.

Example 2: Standardized Git Commit Skill

Skill file ~/.claude/skills/git-commit/SKILL.md:

---
name: git-commit
description: |
  Use this skill when the user asks to commit code, write commit messages, or mentions git commit.
  Enforces Conventional Commits specification with mandatory scope.
---

## Commit Format

```
<type>(<scope>): <subject>

[optional body]

[optional footer]
```

## Mandatory Rules

### 1. Type - Required

| Type | Description |
|------|-------------|
| `feat` | New feature |
| `fix` | Bug fix |
| `docs` | Documentation changes |
| `style` | Code formatting (no functional impact) |
| `refactor` | Refactoring (not a new feature or fix) |
| `perf` | Performance improvement |
| `test` | Adding or modifying tests |
| `chore` | Build process or auxiliary tool changes |
| `ci` | CI configuration changes |
| `revert` | Revert a commit |

### 2. Scope - Required ⚠️

- **Must** include scope to indicate the affected module/component
- Use lowercase letters, connect multiple words with `-`
- Examples: `user`, `auth`, `payment`, `ui-button`

### 3. Subject - Required

- Concise description, no more than 50 characters
- Can be in Chinese or English
- Do not end with a period
- Use imperative mood (start with a verb)

## Correct Examples ✅

```
feat(user): add user registration function
fix(auth): fix login timeout issue
docs(readme): update installation instructions
refactor(api): refactor request interceptor
test(utils): add date formatting tests
chore(deps): upgrade lodash to 4.17.21
perf(list): optimize long list rendering performance
```

## Incorrect Examples ❌

```
feat: add feature              # ❌ Missing scope
fix(Auth): fix issue           # ❌ Scope should be lowercase
add user module                 # ❌ Missing type and scope
feat(user): add feature.      # ❌ Do not end with a period
```

## Commit Message Generation Process

When the user asks to generate a commit message:

1. **Analyze changes**: View git diff or user description
2. **Determine type**: Choose based on the nature of the change
3. **Determine scope**: Determine based on the affected module
4. **Write subject**: Concisely describe the change
5. **Output complete commit message**

## Prohibited Actions

- ❌ Do not generate commit messages without a scope
- ❌ Do not use types outside the specification
- ❌ Do not let the subject exceed 50 characters
- ❌ Do not use vague descriptions like "fix bug" or "update code"

## Execution Steps

When the user asks to commit code, follow these steps:

### Step 1: View Changes

```bash
git status
git diff --cached  # if already staged
git diff           # if not staged
```

### Step 2: Analyze Changes and Generate Commit Message

Based on the changes, generate a commit message according to the specification and show it to the user:

```
Suggested commit message:

feat(module-name): concise description of the change
```

### Step 3: Confirm and Execute

Ask the user if they confirm, then execute:

```bash
git add .  # or specify files
git commit -m "type(scope): subject"
```

### Step 4: (Optional) Push

Ask the user if they need to push to remote:

```bash
git push origin <branch>
```

Example 3: Code Review Skill

Skill file ~/.claude/skills/code-reviewer/SKILL.md:

---
name: code-reviewer
description: |
  Use this skill when the user asks for code review, review code, or check code quality.
  Performs comprehensive code review covering quality, security, performance, and readability.
---

## Review Dimensions

Conduct a comprehensive review of the code, covering the following four dimensions:

| Dimension | Focus |
|-----------|-------|
| 🔧 **Code Quality** | Naming conventions, code structure, design patterns, DRY principle, single responsibility |
| 🔒 **Security** | SQL injection, XSS, sensitive information leakage, permission checks, input validation |
| ⚡ **Performance** | Time complexity, space complexity, memory leaks, N+1 queries, cache usage |
| 📖 **Readability** | Comment completeness, code formatting, function length, logical clarity |

## Issue Severity Levels

| Level | Label | Description |
|-------|-------|-------------|
| 🔴 **Critical** | Must fix | Serious bugs, security vulnerabilities, risk of data loss |
| 🟠 **Major** | Recommended to fix | Performance issues, design flaws, maintainability issues |
| 🟡 **Minor** | Optional to fix | Code style, naming suggestions, minor optimizations |
| 🟢 **Info** | For reference only | Best practice suggestions, knowledge sharing |

## Execution Steps

### Step 1: Get the Code

Obtain the code to be reviewed through one of the following methods:
- User pastes code directly
- Read specified file
- View git diff

### Step 2: Review Dimension by Dimension

Check according to the four dimensions in order, recording any issues found.

### Step 3: Output Review Report

Use the following format for output:

---

## Code Review Report

### 📊 Overall Assessment

Briefly summarize code quality, give a score (1-10)

### 🔍 Issues Found

#### 🔴 Critical

**Issue Description**
- Location: `filename:line number`
- Issue: Specific description
- Risk: Potential impact

**Fix Suggestion**
```language
// Fixed code
```

#### 🟠 Major

(Same format as above)

#### 🟡 Minor

(Same format as above)

### ✅ What Was Done Well

List highlights and best practices in the code

### 📝 Improvement Suggestions

Give overall improvement directions

---

## Output Specifications

- All review comments should be output in **Chinese**
- When an issue is found, **must provide a code example after the fix**
- When pointing out the issue location, indicate the **filename and line number**
- List each issue separately, do not merge

## Prohibited Actions

- ❌ Do not just say "the code is well written" without giving specific analysis
- ❌ Do not just point out issues without providing fix code
- ❌ Do not omit security-related issues
- ❌ Do not use vague descriptions like "there's a problem here" without explaining the reason

Example 4: Patent Writing Skill (Domain Knowledge Injection)

Skill file ~/.claude/skills/patent-writing/SKILL.md:

---
name: patent-writing
description: |
  Use this skill when the user asks to write a patent, draft patent claims, or create patent documentation.
  Supports both invention patents and utility model patents following CNIPA specifications.
  Specialized for software/internet technology field.
---

## Scope of Application

- **Patent Types**: Invention patents, utility model patents
- **Standards**: China National Intellectual Property Administration (CNIPA)
- **Technical Field**: Software/Internet

## Patent Document Structure

A complete patent application file includes the following parts:

| No. | Part | Description |
|-----|------|-------------|
| 1 | **Invention Title** | Concise, reflecting the technical subject |
| 2 | **Technical Field** | Indicate the technical field to which the invention belongs |
| 3 | **Background Art** | Describe existing technology and its shortcomings |
| 4 | **Summary of the Invention** | Technical problem, technical solution, beneficial effects |
| 5 | **Brief Description of Drawings** | Explain the content of each drawing |
| 6 | **Detailed Description** | Describe at least one embodiment in detail |
| 7 | **Claims** | Define the scope of protection (independent claim + dependent claims) |
| 8 | **Abstract** | Overview of the technical solution within 300 words |

## Execution Steps

### Step 1: Collect Technical Information

Ask the user for the following information:
- What is the technical problem to be solved?
- What is the core technical solution?
- What are the advantages over existing technology?
- What are the specific implementation methods?

### Step 2: Write Each Part

Write in the following order:

#### 2.1 Invention Title
- No more than 25 characters
- Use the format "A method/system/device for ..."
- Do not use trademarks, model numbers, or non-technical terms

#### 2.2 Technical Field
```
The present invention relates to the technical field of [broad field], and in particular to a method/system/device for [specific technology].
```

#### 2.3 Background Art
- Describe existing technical solutions (can cite existing patents or literature)
- Objectively analyze the shortcomings of existing technology
- Do not disparage existing technology; use neutral expressions like "there is room for improvement"

#### 2.4 Summary of the Invention

**Technical Problem**
```
To solve the technical problems of [problem 1], [problem 2], etc., existing in the above-mentioned prior art, the present invention provides ...
```

**Technical Solution**
```
The present invention provides a [invention title], comprising the following steps/modules:
Step S1/Module M1: ...
Step S2/Module M2: ...
```

**Beneficial Effects**
- List 3-5 specific technical effects
- Use quantitative data to support (if applicable)

#### 2.5 Claims

**Independent Claim (Claim 1)**
- Preamble: Features of the existing technology
- Characterizing part: "characterized in that" + innovation point

**Dependent Claims (Claims 2-N)**
- Reference the preceding claims
- Further define technical features

```
1. A [invention title], characterized in that it comprises:
   [Technical feature A];
   [Technical feature B];
   [Technical feature C].

2. The [invention title] according to claim 1, characterized in that said [feature A] specifically comprises:
   [Refined feature A1];
   [Refined feature A2].
```

#### 2.6 Detailed Description
- Describe in detail with reference to the drawings
- Describe at least one complete embodiment
- Use expressions like "in one embodiment", "preferably"

### Step 3: Generate Abstract
- No more than 300 words
- Summarize the technical problem, solution, and effects
- Use "this application" instead of "the present invention"

### Step 4: Output Complete Document

Output the complete patent application document in standard format.

## Writing Specifications

### Language Requirements
- Use written language, avoid colloquial expressions
- Technical terms must be consistent throughout
- Claims should use single sentences (can be separated by semicolons)

### Special Requirements for Software Patents
- Method patents: Emphasize step order and data processing process
- System patents: Emphasize module division and interaction relationships
- Avoid pure algorithms/business methods; must reflect technical effects

### Drawing Requirements
- Method flowcharts: Use S1, S2, etc. to label steps
- System architecture diagrams: Use module/unit naming
- Ensure drawing labels are consistent with the specification

## Output Template

```markdown
# [Invention Title]

## Technical Field

The present invention relates to ...

## Background Art

Currently, ... has the following problems:
1. ...
2. ...

## Summary of the Invention

### Technical Problem
To solve the above problems, the present invention provides ...

### Technical Solution
The present invention provides a [name], comprising:
...

### Beneficial Effects
The present invention has the following beneficial effects:
1. ...
2. ...

## Brief Description of Drawings

Figure 1 is a flowchart of an embodiment of the present invention;
Figure 2 is an architecture diagram of an embodiment of the present invention.

## Detailed Description

The present invention will be further described below with reference to the drawings.
...

## Claims

1. A ..., characterized in that it comprises:
   ...

2. The ... according to claim 1, characterized in that:
   ...

## Abstract

This application discloses ...
```

## Prohibited Actions

- ❌ Do not use absolute terms like "best" or "optimal"
- ❌ Do not use vague words like "for example" or "preferably" in claims
- ❌ Do not have inconsistencies between claims and the specification description
- ❌ Do not omit functional descriptions of technical features
- ❌ Do not directly copy the user's original description without patent-style rewriting

X. skill-creator and IDE Practice

Using skill-creator to Write Skills

The practical examples in Section IX above were all written by me using skill-creator. What is skill-creator?

Skill-Creator is a skill generator officially launched by Anthropic: a "meta-skill" for creating skills.

You can understand it this way:

Ordinary Skill = Teach the AI to do one thing (e.g., "help me review code")

Skill-Creator = Teach the AI how to create other Skills

Simply put, you just need to describe your needs in natural language, and Skill-Creator will automatically generate a complete, usable Skill for you.

Trigger method:

Directly tell ClaudeCode:
1. "Help me write a Skill for XXX"
2. "Create a skill file for the YYY process"
3. Or directly enter /skill-creator"

For example: "I want to create a skill that, given a video link, can send me the text transcript. If it's in another language, it's best to provide both the original language version and the Chinese version."

What Skill-Creator does:

First asks you a few questions to confirm the details of the requirement
Automatically designs the entire structure of the skill
Generates the complete SKILL.md and configuration files
Completes the writing quickly

How to Update skill-creator

To update Skill-Creator to the latest version, just say one sentence to your Agent, and the Agent will automatically complete the entire process of searching, git clone, backup, replacement, and verification:

"https://github.com/anthropics/skills/tree/main/skills/skill-creator, this skills has been updated, help me update to the latest version"

Using in ClaudeCode

# Skill file storage paths
~/.claude/skills/           # Global (effective for all projects)
<project root>/.claude/skills/  # Project-level (effective only for the current project)

# Create a new Skill (directly create a new .md file)
touch ~/.claude/skills/api-review/SKILL.md

# Let Claude help you write the content
# Enter in the conversation: "Help me write an API review Skill and save it to ~/.claude/skills/api-review/SKILL.md"

Using in Cursor

Cursor has its own skill:

.cursor/skills/     → Cursor's skill files (for Cursor AI)
.claude/skills/     → Claude Code's skill files (for Claude Code CLI)

For compatibility, Cursor also loads skills from Claude and Codex directories: .claude/skills/, .codex/skills/, ~/.claude/skills/, and ~/.codex/skills/.

The fastest way to write a Skill in Cursor:

1. Open Cursor, create a new .claude/skills/xxx/SKILL.md

2. Enter in Cursor Chat:
   "Help me write a Claude Skill about [xxx],
    including YAML front matter, execution flow, and prohibited actions"

3. Cursor AI directly generates the content, Apply to the file

4. Switch to the Claude Code terminal, the Skill is immediately available

General Advice for Cross-IDE Use

Advice	Reason
Manage Skill files with Git	Team sharing, version tracking
Place global Skills in `~/.claude/skills/`	Reuse common skills across projects
Place project Skills in `.claude/skills/`	Project-specific standards, committed with the codebase
Use kebab-case for directory names	e.g., `api-review`, clear and easy to identify
Use skill-creator for the first draft	5x faster than writing manually, then fine-tune manually
Regularly test Skills with real scenarios	Skills need to evolve with changing requirements

XI. Superpowers: Enterprise-Grade Skill Suite Ready to Use

Concept and Philosophy

Superpowers is an open-source, structured workflow skill system designed for AI coding assistants. Think of it as a "software engineering training package for AI" — a development standards manual + enforced workflow for a development intern.

Superpowers is not a set of system prompts, but a pluggable skill system. Each skill is a SKILL.md file that defines strict rules for a specific scenario. The workflow is chained together by a series of mandatory skills:

Requirements Input
    │
    ▼
brainstorming
    │  └── Refine requirements through questioning, explore alternatives
    ▼
using-git-worktrees (Create isolated workspace)
    │  └── Use git worktrees to create independent branches
    ▼
writing-plans (Write implementation plan)
    │  └── Break down work into 2-5 minute atomic tasks
    ▼
test-driven-development
    │  └── Red → Green → Refactor cycle
    ▼
subagent-driven-development
    │  └── Dispatch subagents for task-by-task execution + two-stage review
    ▼
requesting-code-review
    ▼
verification-before-completion
    ▼
finishing-a-development-branch

Skill Discovery Mechanism

Superpowers' using-superpowers skill is the entry point for the entire system. It forces the AI to check for relevant skills before any response.

Trigger rules:

If a skill might be relevant (even with only 1% probability), it must be called
If a skill includes a checklist, todos must be created for each item
Priority when multiple skills are applicable: process skills (e.g., brainstorming) > implementation skills

Detailed Core Skills

Skill Name	Trigger Scenario	Core Function
`test-driven-development` (TDD)	Before implementing any feature or fixing a bug	Enforce Red→Green→Refactor cycle. No failing test, no production code
`systematic-debugging`	When encountering a bug or test failure	Diagnose before treating, evidence first. No root cause investigation, no fix
`brainstorming`	Before creating a feature/component/modification	Explore requirements and design, prevent over-engineering
`writing-plans`	After receiving requirements specifications	Generate detailed implementation plan before starting
`executing-plans`	When executing an existing implementation plan	Batch step-by-step execution with checkpoints
`requesting-code-review`	After completing feature implementation	Verify work meets requirements before submission
`receiving-code-review`	When receiving code review feedback	Rigorously evaluate feedback, do not blindly accept
`verification-before-completion`	Before declaring a task complete	Force running verification commands, evidence first. Must run verification commands and confirm actual output
`finishing-a-development-branch`	After implementation is complete and tests pass	Guide merge/PR/cleanup decisions
`using-git-worktrees`	Before starting isolated feature development	Create isolated git worktree
`subagent-driven-development`	When executing a plan with multiple independent tasks	Parallel subagent development. Claude works autonomously for hours without deviating from the plan
`code-reviewer`	After completing important project steps	Multi-dimensional code review

Installation Guide

Refer to the official git project introduction: https://github.com/obra/superpowers

Claude Code (Recommended Method)

# Step 1: Register the plugin marketplace
/plugin marketplace add obra/superpowers-marketplace

# Step 2: Install the Superpowers plugin
/plugin install superpowers@superpowers-marketplace

# Step 3: Verify installation
/help
# You should see the following commands:
# /superpowers:brainstorm   - Interactive design refinement
# /superpowers:write-plan   - Create implementation plan
# /superpowers:execute-plan - Batch execute plan

# Update plugin
/plugin update superpowers

Other Methods

Cursor:
Enter /add-plugin superpowers in the Agent chat

Codex / OpenCode:
Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md

Gemini CLI:
gemini extensions install https://github.com/obra/superpowers

Differences from Other Concepts

Concept	Essence	Characteristics
Prompt	Temporary instruction	One-time, ad-hoc, only effective in the current conversation
MCP	External connection	Give the AI an access card, securely connect to external systems
Skill	Capability package	Reusable knowledge + process encapsulation
Superpowers	Skill system	Enforced workflow + complete framework of 14 core skills

In a nutshell: Skills are "capability packages," Superpowers is the "complete development standard to arm the AI with these capability packages."

Practical Examples

Scenario 1: Before Developing a New Feature

User: Implement a user login module

→ brainstorming Skill automatically triggers:
  First explore requirements (OAuth? JWT? Session?)

→ writing-plans Skill takes over:
  Generate detailed implementation plan, list all steps

→ test-driven-development Skill guards:
  Write tests first for each step, then implement

Scenario 2: When Encountering a Bug

User: This API keeps returning 500

→ systematic-debugging Skill automatically triggers:
  Step 1: Reproduce the issue
  Step 2: Collect error stack traces and logs
  Step 3: Form 2-3 hypotheses
  Step 4: Verify each one
  → Prohibited from proposing a fix before reproduction

Scenario 3: Before Committing Code

User: OK, ready to commit

→ verification-before-completion Skill triggers:
  First run tests, show passing evidence
  Then perform code-reviewer review
  Only allow commit after confirming everything is correct

XII. Discovering Useful Skills

Major Skill Repositories

skills.sh (Community Curated): https://skills.sh/

Community-maintained curated collection of high-quality Skills
Categorized by domain (Engineering, Writing, Data, Security, etc.)
Has ratings and usage statistics, quality is guaranteed
Supports one-click installation

Anthropic Official Repository: https://github.com/anthropics/skills

Officially maintained by Anthropic, synchronized with the latest version of Claude Code
Contains the most authoritative format specifications and best practice examples
The best reference for learning how to write good Skills

XIII. Summary

Skills are essentially the crystallization of human intelligence — transforming experts' working methods, judgment criteria, and execution processes into structured constraints that AI can understand and follow, upgrading AI from an "obedient tool" to a "collaborator with professional competence."

Core one-liner: Skill = description (determines when to trigger) + SKILL.md (tells the AI how to do it) + optional resources (helps the AI do it better).

The essence of mastering Skills is:

Abstraction - Extract general patterns from specific tasks
Encapsulation - Process and structure knowledge
Reuse - Build once, use continuously

🎉 In the next issue, we will share detailed usage methods and effect descriptions of incredibly useful Skills (Development & Testing). Stay tuned! 🎉