Skill学习指南

一、Skill是什么

把它想象成一本"专项操作手册"------当 AI 需要完成某个特定领域的任务时（比如分析业务日志、转换音频格式、部署到云端），Skill 就会被加载进来，提供专属的工作流程、工具脚本和领域知识。它将知识、流程和工具封装在一起，让你能够快速完成特定领域的任务。

Skill = 专业知识 + 操作流程 + 工具调用

核心价值： 把那些"通用 AI 不具备，但领域专家天天用"的知识固化下来，让 AI 具备领域专家的能力。

和 MCP 及 Prompt 的区别

System Prompt 是一次性指令，MCP 是给 AI 装新手臂，Skill 是给 AI 装行为准则。

维度	System Prompt	MCP	Skill
本质	一次性角色设定	工具/能力扩展协议	可复用行为约束
解决什么问题	临时调整 AI 风格	AI 连不到外部系统	AI 不按规范工作
需要写代码	否	是（Server/Client）	非必须（纯 Markdown就可以，scripts为可选）
持久性	仅当前对话	持久（服务常驻）	持久（文件存储）
面向人群	所有人	开发者	所有人
典型例子	"你是一个翻译助手"	连接数据库、调用 API	强制 TDD、规范 Git 提交

Skill说明

plain 复制代码

 skill-name/
├── SKILL.md          ← 必须有，核心文件
└── （可选资源）
    ├── scripts/      ← 可执行脚本（Python/Bash 等）
    ├── references/   ← 参考文档（按需加载）
    └── assets/       ← 静态资源（模板、图片、字体等）

SKILL.md 的结构

Claude Code Skill 使用 YAML Front Matter + Markdown 正文 的格式：

plain 复制代码

 ---
name: skill-unique-name      # 技能的唯一标识符
description: |               # 触发场景描述（AI 据此判断何时使用）
  Use when doing X.
  Use BEFORE doing Y.
  这个 Skill 做什么，什么时候触发它。
---

# 技能正文（Markdown）  # 给 AI 的操作指南

## 核心原则
- 原则一
- 原则二

## 执行流程
1. 第一步
2. 第二步
3. 第三步

## 禁止行为
- 禁止做 A
- 禁止跳过 B

Skill 的五要素

plain 复制代码

┌─────────────────────────────────────────────┐
│  1. Metadata（元数据）                        │
│     name:        唯一标识符                   │
│     description: 触发场景描述                 │
│                                             │
│  2. Context（适用上下文）                     │
│     该技能适用的场景和前提条件                  │
│                                             │
│  3. Process（执行流程）                       │
│     步骤化工作流，可包含 checklist             │
│                                             │
│  4. Constraints（约束规则）                   │
│     禁止行为、必须遵守的原则                    │
│                                             │
│  5. Output Format（输出规范）                 │
│     结果应如何呈现、什么格式                    │
└─────────────────────────────────────────────┘

Skill 安装方式与目录结构制作

plain 复制代码

bash
 体验AI代码助手
 代码解读
复制代码
# Claude Code 中，Skill 文件存放在：
~/.claude/skills/        # 全局技能（所有项目可用）
.claude/skills/          # 项目级技能（仅当前项目可用）

# 文件命名：
~/.claude/skills/tdd/SKILL.md
~/.claude/skills/code-review/SKILL.md
~/.claude/skills/git-commit/SKILL.md

Skill 完整目录结构

一个完整的 Skill 不只是一个 .md 文件，还可以包含辅助资源：

plain 复制代码

bash
 体验AI代码助手
 代码解读
复制代码
.claude/skills/my-skill/
├── SKILL.md            # Skill 主文件（必须）
├── reference/             # 参考资料目录（可选）
│   ├── api-spec.md        # API 规范文档
│   ├── style-guide.md     # 代码风格指南
│   └── examples/          # 示例文件
│       └── good-example.ts
├── scripts/               # 辅助脚本目录（可选）
│   ├── validate.sh        # 验证脚本（Skill 可调用）
│   └── setup.py           # 环境初始化脚本
└── assets/                # 静态资源目录（可选）
    ├── checklist.md       # 检查清单模板
    └── templates/         # 输出模板
        └── report.md

三、加载机制

Skill 采用"按需加载"的设计，避免浪费上下文窗口：

级别	内容	何时加载	大小
第一级	name + description	始终在上下文中	~100 词
第二级	SKILL.md 正文	Skill 被触发后	< 5000 词
第三级	scripts/ references/ assets/	AI 判断需要时	无限制

实际效果： AI 随时知道有哪些 Skill，但只有真正需要时才"打开"它。

四、可选资源详解

scripts/ 确定性脚本

用途：把反复编写的代码固化成可直接执行的脚本。Skill 执行过程中可调用的脚本

适合场景：

旋转 PDF：scripts/rotate_pdf.py
解密音频：scripts/decrypt_ncm.py
分析日志：scripts/parse_log.py

优势：不需要读入上下文就能执行，节省 token。

references/ 参考文档

用途：存储 AI 需要参考但不必一直占用上下文的知识。给 AI 提供背景知识和参考规范

适合场景：

数据库表结构：references/schema.md
API 文档：references/api_docs.md
公司政策：references/policies.md

设计原则：按领域拆分成独立文件，用户问销售数据时只加载 sales.md，不加载 finance.md。

assets/ 静态资源

用途：存储输出中会用到的文件，不需要读入上下文。模板、静态文件

适合场景：

前端模板：assets/frontend-template/
PPT 模板：assets/slides.pptx
品牌 Logo：assets/logo.png
checklist 模板：checklist.md

在 Skill 中引用资源的方式

plain 复制代码

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

## 参考规范
请在审查前阅读 reference/style-guide.md 中的编码规范。

## 执行流程
1. 运行 scripts/validate.sh 做静态检查
2. 按照 assets/checklist.md 逐项审查
3. 使用 assets/templates/report.md 格式输出结果

五、完整的Skill创建流程

第 1 步：明确使用场景

在动手之前，先想清楚具体用例：

用户会说什么话来触发这个 Skill？
期望 AI 完成什么具体任务？
有哪些典型的输入/输出例子？

第 2 步：规划可复用资源

对每个用例问：

"完成这个任务，每次都需要重写什么代码/重查什么文档？"

把答案整理成 scripts/、references/、assets/ 的规划清单。

第 3 步：初始化 Skill

plain 复制代码

python scripts/init_skill.py <skill-name> --path <输出目录>

这会自动生成标准目录结构和 SKILL.md 模板。

第 4 步：编写内容

SKILL.md 编写要点：

description 是触发机制，要写得清晰全面（什么场景用、用户会说什么）
正文控制在 500 行以内，细节放到 references/
用祈使句/动词开头："运行脚本..."、"读取文件..."

资源文件编写要点：

脚本写完必须实际运行测试
参考文档超过 100 行要加目录
不需要的示例文件要删掉

第 5 步：打包发布

plain 复制代码

python scripts/package_skill.py <skill目录路径>

打包前会自动校验：

YAML frontmatter 格式
必填字段完整性
目录结构规范
校验通过后生成 .skill 文件（本质是 zip 包）。

第 6 步：迭代优化

在真实任务中使用，观察 AI 的表现，不断改进 SKILL.md 和资源文件。

六、核心设计原则

原则 1：精简优先

上下文窗口是公共资源。每加一段文字都问自己：

"这是 AI 不知道的信息吗？删掉会有什么后果？"

不要写： "在开始之前，你需要理解这个任务的重要性..."

要写：直接给出操作步骤。

原则 2：自由度要匹配任务

任务特性	自由度	写法
步骤固定、易出错	低	具体脚本 + 严格参数
有首选方案、允许变化	中	伪代码 + 可配置参数
多种方案均可、依赖上下文	高	文字指导 + 启发式原则

任务特性自由度写法步骤固定、易出错低具体脚本 + 严格参数有首选方案、允许变化中伪代码 + 可配置参数多种方案均可、依赖上下文高文字指导 + 启发式原则

原则 3：渐进式披露

SKILL.md 只放核心工作流，细节通过引用指向 references/ 文件：

plain 复制代码

## 高级功能

- **表单填写**：详见 [FORMS.md](references/FORMS.md)
- **API 参考**：详见 [API.md](references/API.md)

## 日志格式

详见 [references/log-format.md](references/log-format.md)

七、完整的 Skill 示例

假设要创建一个 pdf-rotator Skill：

目录结构：

plain 复制代码

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

SKILL.md：

plain 复制代码

---
name: pdf-rotator
description: |
  旋转 PDF 文件中的页面。当用户需要旋转 PDF 页面、
  修正扫描件方向时使用。触发词：旋转 PDF、PDF 页面方向
---

# PDF 旋转工具

## 使用方法

运行 `scripts/rotate_pdf.py`：

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

参数说明：
- `--angle`：旋转角度，可选 90、180、270
- `--pages`：指定页码（如 `1,3,5`），不填则旋转所有页

八、实战示例

案例 1：TDD技能（强制测试驱动开发）

问题背景：AI 总是直接写实现代码，跳过测试，导致代码质量难以保证。

Skill 文件 ~/.claude/skills/test-driven-development/SKILL.md：

plain 复制代码

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

## 核心原则

**红-绿-重构（Red-Green-Refactor）循环：**

1. **红（Red）**：先写一个失败的测试
2. **绿（Green）**：写最少的代码让测试通过
3. **重构（Refactor）**：优化代码，保持测试通过

## 强制工作流程

### 第一步：编写测试（必须先完成）

在写任何实现代码之前，必须：
1. 创建测试文件（如 `test_xxx.py` 或 `xxx.test.ts`）
2. 编写至少一个测试用例
3. 向用户展示测试代码

### 第二步：确认测试

向用户确认：
- "测试已编写完成，是否继续编写实现代码？"

### 第三步：编写实现

只有在用户确认后，才能编写实现代码。

## 禁止行为

- ❌ 禁止先写实现代码再补测试
- ❌ 禁止跳过测试直接给实现
- ❌ 禁止在同一个回复中同时给出测试和实现（除非用户明确要求）
- ❌ 禁止写没有断言的测试

## 测试规范

```python
# Python 示例：使用 pytest
def test_function_should_do_something():
    # Arrange（准备）
    input_data = ...
    
    # Act（执行）
    result = function_under_test(input_data)
    
    # Assert（断言）
    assert result == expected_value

typescript 复制代码

// TypeScript 示例：使用 Jest
describe('functionName', () => {
  it('should do something when given input', () => {
    // Arrange
    const input = ...;
    
    // Act
    const result = functionName(input);
    
    // Assert
    expect(result).toBe(expectedValue);
  });
});

回复模板

当用户要求实现功能时，使用以下格式回复：

📝 第一步：编写测试

language 复制代码

// 测试代码

测试覆盖的场景：

场景1：正常输入
场景2：边界情况
场景3：异常处理

确认后我将编写实现代码。是否继续？

复制代码

效果：AI 被强制按 Red → Green → Refactor 循环工作，代码质量显著提升。
### 案例 2：规范化 Git 提交技能

Skill 文件 ~/.claude/skills/git-commit/SKILL.md：

```plain
---
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 格式

():

optional body

optional footer

复制代码

## 必须遵守的规则

### 1. Type（类型）- 必填

| Type | 说明 |
|------|------|
| `feat` | 新功能 |
| `fix` | Bug 修复 |
| `docs` | 文档变更 |
| `style` | 代码格式（不影响功能） |
| `refactor` | 重构（不是新功能也不是修复） |
| `perf` | 性能优化 |
| `test` | 添加或修改测试 |
| `chore` | 构建过程或辅助工具变动 |
| `ci` | CI 配置变更 |
| `revert` | 回滚提交 |

### 2. Scope（作用域）- 必填 ⚠️

- **必须**包含 scope，用于说明影响的模块/组件
- 使用小写字母，多个单词用 `-` 连接
- 示例：`user`, `auth`, `payment`, `ui-button`

### 3. Subject（描述）- 必填

- 简洁描述，不超过 50 个字符
- 中英文皆可
- 不要以句号结尾
- 使用祈使语气（动词开头）

## 正确示例 ✅

feat(user): 添加用户注册功能

fix(auth): 修复登录超时问题

docs(readme): 更新安装说明

refactor(api): 重构请求拦截器

test(utils): 增加日期格式化测试

chore(deps): 升级 lodash 到 4.17.21

perf(list): 优化长列表渲染性能

复制代码

## 错误示例 ❌

feat: 添加功能 # ❌ 缺少 scope

fix(Auth): 修复问题 # ❌ scope 应该小写

新增用户模块 # ❌ 缺少 type 和 scope

feat(user): 添加功能。 # ❌ 不要句号结尾

复制代码

## 生成 Commit Message 流程

当用户要求生成 commit message 时：

1. **分析变更内容**：查看 git diff 或用户描述
2. **确定 type**：根据变更性质选择
3. **确定 scope**：根据影响的模块确定
4. **撰写 subject**：简洁描述变更内容
5. **输出完整 commit message**

## 禁止行为

- ❌ 禁止生成不带 scope 的 commit message
- ❌ 禁止使用规范外的 type
- ❌ 禁止 subject 超过 50 字符
- ❌ 禁止使用模糊描述如"修复bug"、"更新代码"

## 执行步骤

当用户要求提交代码时，按以下步骤执行：

### 步骤 1：查看变更

```bash
git status
git diff --cached  # 如果已 staged
git diff           # 如果未 staged

步骤 2：分析变更并生成 commit message

根据变更内容，按规范生成 commit message，向用户展示：

复制代码

建议的 commit message：

feat(module-name): 简洁描述变更内容

步骤 3：确认并执行

询问用户是否确认，确认后执行：

bash 复制代码

git add .  # 或指定文件
git commit -m "type(scope): subject"

步骤 4：（可选）推送

询问用户是否需要推送到远程：

bash 复制代码

git push origin <branch>

复制代码

### 案例 3：代码审查技能

Skill 文件 ~/.claude/skills/code-reviewer/SKILL.md：

```plain
---
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.
---

## 检查维度

对代码进行全面审查，覆盖以下四个维度：

| 维度 | 关注点 |
|------|--------|
| 🔧 **代码质量** | 命名规范、代码结构、设计模式、DRY原则、单一职责 |
| 🔒 **安全性** | SQL注入、XSS、敏感信息泄露、权限校验、输入验证 |
| ⚡ **性能** | 时间复杂度、空间复杂度、内存泄漏、N+1查询、缓存使用 |
| 📖 **可读性** | 注释完整性、代码格式、函数长度、逻辑清晰度 |

## 问题严重级别

| 级别 | 标识 | 说明 |
|------|------|------|
| 🔴 **Critical** | 必须修复 | 严重bug、安全漏洞、数据丢失风险 |
| 🟠 **Major** | 建议修复 | 性能问题、设计缺陷、可维护性问题 |
| 🟡 **Minor** | 可选修复 | 代码风格、命名建议、微小优化 |
| 🟢 **Info** | 仅供参考 | 最佳实践建议、知识分享 |

## 执行步骤

### 步骤 1：获取代码

通过以下方式之一获取待审查代码：
- 用户直接粘贴代码
- 读取指定文件
- 查看 git diff

### 步骤 2：逐维度审查

按照四个维度依次检查，记录发现的问题。

### 步骤 3：输出审查报告

使用以下格式输出：

---

## Code Review 报告

### 📊 总体评价

简要总结代码质量，给出评分（1-10分）

### 🔍 发现的问题

#### 🔴 Critical

**问题描述**
- 位置：`文件名:行号`
- 问题：具体描述
- 风险：可能造成的影响

**修复建议**
```language
// 修复后的代码

🟠 Major

（同上格式）

🟡 Minor

（同上格式）

✅ 做得好的地方

列出代码中的亮点和最佳实践

📝 改进建议

给出整体改进方向

输出规范

所有 review 意见使用中文输出
发现问题时必须提供修复后的代码示例
指出问题位置时标注文件名和行号
每个问题单独列出，不要合并

禁止行为

❌ 禁止只说"代码写得不错"而不给出具体分析
❌ 禁止只指出问题而不提供修复代码
❌ 禁止遗漏安全相关问题

❌ 禁止使用模糊描述如"这里有问题"而不解释原因

案例 4：专利撰写技能（领域知识注入）

Skill 文件 ~/.claude/skills/patent-writing/SKILL.md：

plain 复制代码

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

## 适用范围

- **专利类型**：发明专利、实用新型专利
- **规范标准**：中国国家知识产权局（CNIPA）
- **技术领域**：软件/互联网

## 专利文档结构

一份完整的专利申请文件包含以下部分：

| 序号 | 部分 | 说明 |
|------|------|------|
| 1 | **发明名称** | 简明扼要，体现技术主题 |
| 2 | **技术领域** | 说明发明所属技术领域 |
| 3 | **背景技术** | 描述现有技术及其缺陷 |
| 4 | **发明内容** | 技术问题、技术方案、有益效果 |
| 5 | **附图说明** | 说明每幅附图的内容 |
| 6 | **具体实施方式** | 详细描述至少一个实施例 |
| 7 | **权利要求书** | 定义保护范围（独立权利要求+从属权利要求） |
| 8 | **摘要** | 300字以内的技术方案概述 |

## 执行步骤

### 步骤 1：收集技术信息

向用户了解以下信息：
- 要解决的技术问题是什么？
- 核心技术方案是什么？
- 与现有技术相比有什么优势？
- 有哪些具体实施方式？

### 步骤 2：撰写各部分内容

按以下顺序撰写：

#### 2.1 发明名称
- 不超过25个字
- 采用"一种...的方法/系统/装置"格式
- 不使用商标、型号或非技术词汇

#### 2.2 技术领域

本发明涉及[大领域]技术领域，尤其涉及一种[具体技术]的方法/系统/装置。

复制代码

#### 2.3 背景技术
- 描述现有技术方案（可引用已有专利或文献）
- 客观分析现有技术的缺陷
- 不要贬低现有技术，使用"存在改进空间"等中性表述

#### 2.4 发明内容

**技术问题**

为了解决上述现有技术中存在的[问题1]、[问题2]等技术问题，本发明提供了一种...

复制代码

**技术方案**

本发明提供一种[发明名称]，包括以下步骤/模块：

步骤S1/模块M1：...

步骤S2/模块M2：...

复制代码

**有益效果**
- 列出3-5个具体的技术效果
- 使用量化数据支撑（如适用）

#### 2.5 权利要求书

**独立权利要求（权1）**
- 前序部分：现有技术特征
- 特征部分："其特征在于" + 创新点

**从属权利要求（权2-N）**
- 引用前述权利要求
- 进一步限定技术特征

一种[发明名称]，其特征在于，包括：
$技术特征A\]； \[技术特征B\]； \[技术特征C\]。$ $细化特征A1\]； \[细化特征A2\]。 #### 2.6 具体实施方式 - 结合附图详细描述 - 至少描述一个完整实施例 - 使用"在一个实施例中"、"优选地"等表述 ### 步骤 3：生成摘要 - 不超过300字 - 概述技术问题、方案和效果 - 不使用"本发明"，使用"本申请" ### 步骤 4：输出完整文档按标准格式输出完整专利申请文件。 ## 撰写规范 ### 语言要求 - 使用书面语，避免口语化表达 - 技术术语前后一致 - 权利要求使用单句（可用分号分隔） ### 软件专利特殊要求 - 方法专利：强调步骤顺序和数据处理过程 - 系统专利：强调模块划分和交互关系 - 避免纯算法/商业方法，需体现技术效果 ### 附图要求 - 方法流程图：使用S1、S2等标注步骤 - 系统架构图：使用模块/单元命名 - 确保附图标记与说明书一致 ## 输出模板 ```markdown # [发明名称] ## 技术领域本发明涉及... ## 背景技术目前，...存在以下问题： 1. ... 2. ... ## 发明内容 ### 技术问题为了解决上述问题，本发明提供... ### 技术方案本发明提供一种[名称]，包括： ... ### 有益效果本发明具有以下有益效果： 1. ... 2. ... ## 附图说明图1为本发明实施例提供的...流程图；图2为本发明实施例提供的...架构图。 ## 具体实施方式下面结合附图对本发明作进一步说明。 ... ## 权利要求书 1. 一种...，其特征在于，包括： ... 2. 根据权利要求1所述的...，其特征在于： ... ## 摘要本申请公开了一种...$

❌ 禁止使用"最好"、"最优"等绝对化用语
❌ 禁止在权利要求中使用"例如"、"优选"等模糊词
❌ 禁止权利要求与说明书描述不一致
❌ 禁止遗漏技术特征的功能性描述
❌ 禁止直接复制用户原始描述而不进行专利化改写

九、skill-creator 与 IDE 实战

使用 skill-creator 写 Skill

上面第九部分实战案例，其实都是我用 skill-creator 编写的。什么是 skill-creator？

Skill-Creator 是 Anthropic 官方推出的技能生成器：一个用来创建技能的"母技能"（Meta-Skill）。

你可以这样理解：
plain 复制代码
```
普通 Skill = 教 AI 做某一件事（如"帮我审查代码"）
Skill-Creator = 教 AI 如何创建其他 Skill
```

简单来说，你只需要用自然语言描述你的需求，Skill-Creator 就会自动帮你生成一个完整的、可用的 Skill。

触发方式：

plain 复制代码

直接告诉 ClaudeCode：
1、"帮我写一个 XXX 的 Skill"
2、"创建一个用于 YYY 流程的技能文件"
3、或者直接输入/skill-creator"

例如："我想创建一个 skill，给一个视频链接，它能把文字版的讲稿发给我。如果是别的语言，最好把原语言版和中文版都给我。"

Skill-Creator 做了什么：

先问你几个问题，确认需求细节
自动设计整个 skill 的结构
生成完整的 SKILL.md 和配置文件
很快编写完成

skill-creator 更新方式

更新 Skill-Creator 到最新版，只需要对你的 Agent 说一句话，Agent 会自动完成搜索、git clone、备份、替换、验证全过程

ClaudeCode 里使用

plain 复制代码

# Skill 文件存放路径
~/.claude/skills/           # 全局（所有项目生效）
<项目根目录>/.claude/skills/  # 项目级（仅当前项目生效）

# 创建一个新 Skill（直接新建 .md 文件）
touch ~/.claude/skills/api-review/SKILL.md

# 让 Claude 帮你写内容
# 在对话中输入："帮我写一个 API 审查的 Skill，保存到 ~/.claude/skills/api-review/SKILL.md"

Cursor 里使用

Cursor 有自己的 skill：

plain 复制代码

.cursor/skills/     → Cursor 的技能文件（作用于 Cursor AI）
.claude/skills/     → Claude Code 的技能文件（作用于 Claude Code CLI）

为了兼容性，Cursor 还会从 Claude 和 Codex 目录加载技能：.claude/skills/、.codex/skills/、~/.claude/skills/ 和 ~/.codex/skills/。

在 Cursor 里写 Skill 的最快方式：

plain 复制代码

1. 打开 Cursor，新建 .claude/skills/xxx/SKILL.md

2. 在 Cursor Chat 里输入：
   "帮我写一个关于 [xxx] 的 Claude Skill，
    包含 YAML front matter、执行流程和禁止行为"

3. Cursor AI 直接生成内容，Apply 到文件

4. 切换到 Claude Code 终端，Skill 立即可用

关于跨 IDE 的通用建议

建议	原因
Skill 文件用 Git 管理	团队共享、版本追踪
全局 Skill 放 ****~/.claude/skills/	跨项目复用通用技能
项目 Skill 放 ****.claude/skills/	项目专属规范，随代码库一起提交
目录名用 kebab-case	如 api-review，清晰易识别
先用 skill-creator 生成初稿	比手写快 5 倍，再手动精调
定期用真实场景测试 Skill	Skill 会随需求变化，需迭代更新

十、Superpowers：开箱即用的企业级 Skill 套件

概念及理念

Superpowers 是一套开源的、为 AI 编程助手设计的结构化工作流技能系统。把它理解为一个"给 AI 的软件工程培训包"，这是一本给开发实习生的开发规范手册 + 强制工作流程。

Superpowers 不是一套系统提示词，而是一个插件化的技能系统。每个技能都是一个 SKILL.md 文件，定义了特定场景下的严格规则。工作流程由一系列强制技能串联而成：

plain 复制代码

需求输入
    │
    ▼
brainstorming（头脑风暴）
    │  └── 通过提问精炼需求，探索替代方案
    ▼
using-git-worktrees（创建隔离工作区）
    │  └── 用 git worktrees 创建独立分支
    ▼
writing-plans（编写实施计划）
    │  └── 将工作分解为 2-5 分钟的原子任务
    ▼
test-driven-development（测试驱动开发）
    │  └── 红→绿→重构循环
    ▼
subagent-driven-development（子代理驱动开发）
    │  └── 派发子代理逐任务执行 + 双阶段审查
    ▼
requesting-code-review（请求代码审查）
    ▼
verification-before-completion（完成前验证）
    ▼
finishing-a-development-branch（完成开发分支）

技能发现机制

Superpowers 的 using-superpowers 技能是整个系统的入口。它强制 AI 在任何响应之前先检查是否有相关技能适用。

触发规则：

如果某个技能可能相关（哪怕只有 1% 的可能性），必须调用
如果技能包含 checklist，必须逐项创建 todo
多技能时的优先级：过程技能（如 brainstorming）> 实现技能

核心技能详解

Skill 名称	触发场景	核心作用
test-driven-development（TDD）	实现任何功能或修 Bug 前	强制 Red→Green→Refactor 循环没有失败的测试，就不写生产代码
systematic-debugging（系统化调试）	遇到 Bug 或测试失败时	先诊断后治疗，证据优先没有根因调查，就不做修复
brainstorming（头脑风暴）	创建功能/组件/修改行为前	探索需求和设计，防止过度工程
writing-plans（编写实施计划）	拿到需求规格后	生成详细实现计划再动手
executing-plans	执行已有实现计划时	带检查点的批量分步执行
requesting-code-review（请求代码审查）	完成功能实现后	提交前验证工作符合要求
receiving-code-review	收到代码审查反馈时	严谨评估反馈，不盲目接受
verification-before-completion（完成前验证）	声明任务完成前	强制运行验证命令，证据先行必须运行验证命令并确认实际输出
finishing-a-development-branch（完成开发分支）	实现完成、测试通过后	引导 merge/PR/cleanup 决策
using-git-worktrees（创建隔离工作区）	开始需要隔离的功能开发前	创建隔离 git worktree
subagent-driven-development（子代理驱动开发）	执行有多个独立任务的计划时	并行 subagent 开发Claude自主工作数小时而不偏离计划
code-reviewer	重要项目步骤完成后	多维度代码审查

安装指引

可以参考 git 项目官方介绍：https://github.com/obra/superpowers

Claude Code（推荐方式）

plain 复制代码

# 步骤 1：注册插件市场
/plugin marketplace add obra/superpowers-marketplace

# 步骤 2：安装 Superpowers 插件
/plugin install superpowers@superpowers-marketplace

# 步骤 3：验证安装
/help
# 应该看到以下命令：
# /superpowers:brainstorm   - 交互式设计精炼
# /superpowers:write-plan   - 创建实施计划
# /superpowers:execute-plan - 批量执行计划

# 更新插件
/plugin update superpowers

其他方式

plain 复制代码

Cursor：
在 Agent 聊天中输入 /add-plugin superpowers

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

与其他概念的区别

概念	本质	特点
Prompt	临时指令	一次性的、临场的、只在当前对话生效
MCP	外部连接	给 AI 开门禁卡，安全连接外部系统
Skill	能力包	可复用的知识+流程封装
Superpowers	技能系统	强制工作流 + 14 个核心技能的完整框架

一句话总结：Skills 是"能力包"，Superpowers 是"用这些能力包武装 AI 的完整开发规范"。

实战示例

场景 1：开发新功能前

plain 复制代码

用户：实现一个用户登录模块

→ brainstorming Skill 自动触发：
  先探索需求（OAuth？JWT？Session？）

→ writing-plans Skill 接力：
  生成详细实现计划，列出所有步骤

→ test-driven-development Skill 守护：
  每一步先写测试，再写实现

场景 2：遇到 Bug 时

plain 复制代码

用户：这个接口一直返回 500

→ systematic-debugging Skill 自动触发：
  Step 1: 复现问题
  Step 2: 收集错误堆栈和日志
  Step 3: 形成 2-3 个假设
  Step 4: 逐一验证
  → 禁止在未复现前提出修复方案

场景 3：提交代码前

plain 复制代码

用户：好了，可以提交了

→ verification-before-completion Skill 触发：
  先运行测试，展示通过证据
  再做 code-reviewer 审查
  确认无误后才允许提交

十一、好用的Skill推荐

主要 Skill 仓库

skills.sh（社区精选）： https://skills.sh/

社区维护的高质量 Skill 精选集
按领域分类（工程、写作、数据、安全等）
有评分和使用量统计，质量有保障
支持一键安装

Anthropic 官方仓库： https://github.com/anthropics/skills

Anthropic 官方维护，与 Claude Code 最新版本保持同步
包含最权威的格式规范和最佳实践示例
是学习如何写好 Skill 的最佳参考

一、Skill是什么

和 MCP 及 Prompt 的区别

Skill说明

SKILL.md 的结构

Skill 的五要素

Skill 安装方式与目录结构制作

Skill 完整目录结构

三、加载机制

四、可选资源详解

scripts/ 确定性脚本

references/ 参考文档

assets/ 静态资源

在 Skill 中引用资源的方式

五、完整的Skill创建流程

第 1 步：明确使用场景

第 2 步：规划可复用资源

第 3 步：初始化 Skill

第 4 步：编写内容

第 5 步：打包发布

第 6 步：迭代优化

六、核心设计原则

原则 1：精简优先

原则 2：自由度要匹配任务

原则 3：渐进式披露

七、完整的 Skill 示例

八、实战示例

案例 1：TDD技能（强制测试驱动开发）

回复模板

步骤 2：分析变更并生成 commit message

步骤 3：确认并执行

步骤 4：（可选）推送

🟠 Major

🟡 Minor

✅ 做得好的地方

📝 改进建议

输出规范

禁止行为

案例 4：专利撰写技能（领域知识注入）

九、skill-creator 与 IDE 实战

使用 skill-creator 写 Skill

skill-creator 更新方式

ClaudeCode 里使用

Cursor 里使用

关于跨 IDE 的通用建议

十、Superpowers：开箱即用的企业级 Skill 套件

概念及理念

技能发现机制

核心技能详解

安装指引

Claude Code（推荐方式）

其他方式

与其他概念的区别

实战示例

场景 1：开发新功能前

场景 2：遇到 Bug 时

场景 3：提交代码前

十一、好用的Skill推荐

主要 Skill 仓库