AI Skills 完全指南

让 AI 编码助手从"通用工具"进化为"领域专家"

一、什么是 Skills？

1.1 概念定义

Skills（技能） 是 AI 编码助手的能力扩展机制。它通过一组结构化的指令文件，教会 AI 在特定场景下"该怎么做"。

你可以把 Skills 理解为 AI 的**"技能插件"**：

每个 Skill 是一个独立的文件夹，包含一份核心指令文件 SKILL.md
SKILL.md 用自然语言描述了"在什么场景下、按什么步骤、以什么标准"来完成一类特定任务
AI 在接收到用户请求后，会自动匹配或被手动指定使用某个 Skill，然后严格遵循其中的指令来执行任务

简单来说：

Skills = 写给 AI 看的标准操作手册

没有 Skills 时，AI 依赖自身的通用训练知识来响应请求——它可能做得不错，但缺乏你的团队规范、你的项目约定、你的质量标准。

有了 Skills 后，AI 就像一个经过岗前培训的新员工，知道"在我们这里，事情应该这样做"。

1.2 核心价值

为什么需要 Skills？因为在真实的软件工程中，光靠 AI 的通用能力是不够的。

痛点	没有 Skills	有了 Skills
一致性	每次生成的代码风格、结构都不一样	始终遵循统一的编码规范和架构模式
可复用	好的 Prompt 用完就丢，下次还得重写	指令持久化为文件，随时复用
可共享	经验停留在个人脑子里	团队成员共享同一套 Skills，统一协作标准
质量保障	AI 可能跳过关键步骤（如测试、安全检查）	通过 Skill 强制执行质量关卡
专业深度	AI 给出泛泛的通用方案	AI 按照领域专家的思路精细执行

更具体地说，Skills 解决了三个关键问题：

① 弥合"通用 AI"与"特定项目"之间的鸿沟

AI 大模型的训练数据是通用的，它并不了解你的项目采用了什么技术栈、遵循什么规范、有哪些踩坑经验。Skills 用结构化的指令将这些项目专属知识注入 AI 的工作流程中。

② 将隐性经验转化为显性流程

资深工程师在做代码审查、性能优化、安全审计时，脑中有一套"检查清单"。这些经验通常是隐性的、碎片化的。Skills 将这些经验编码为明确的步骤和标准，让 AI（以及团队中的每一个人）都能遵循。

③ 构建可持续迭代的 AI 协作体系

一个好的 Prompt 是一次性的；一个好的 Skill 是可以持续迭代的。你可以根据实际使用效果不断优化 Skill 的指令，让 AI 的表现越来越好——这本质上是在训练你的私有 AI 工作流。

1.3 类比理解

为了更直观地理解 Skills，我们可以用几个类比：

🏭 Skills 之于 AI Agent = SOP 之于团队成员

对比维度	SOP（标准作业程序）	Skills
对象	人类员工	AI 编码助手
载体	文档、手册、培训材料	`SKILL.md` 文件 + 辅助脚本
目的	确保人类按标准流程工作	确保 AI 按标准流程工作
效果	新员工快速上手，减少出错	AI 精准执行，减少返工
迭代	根据实践反馈持续优化	根据使用效果持续优化

🎮 Skills 之于 AI = 技能树之于游戏角色

一个"初始状态"的 AI 编码助手，就像一个刚创建的游戏角色——有基础属性，但没有专精。

通过安装不同的 Skills，你可以让它：

装上 security-audit → 变成安全专家，能系统性地扫描漏洞
装上 perf-optimizer → 变成性能调优师，能定位瓶颈并给出量化方案
装上 architect-spec → 变成架构师，能输出规范的架构设计文档
装上 test-driven-development → 变成TDD 实践者，先写测试再写实现

每个 Skill 都是一个"技能点"，点得越多、越精细，AI 的综合能力就越强。

📱 Skills 之于 AI = App 之于手机

手机出厂时自带基础功能（通话、短信），但真正让它强大的是你安装的各种 App。

同样，AI 编码助手出厂时自带通用编码能力，但真正让它适配你的项目、匹配你的工作流的，是你为它配置的各种 Skills。

总结：Skills 不是在"限制" AI，而是在"引导" AI。它把 AI 的通用能力，精确地校准到你的项目上下文中，让 AI 从一个"什么都会一点"的通才，变成一个"在你的项目里什么都做得很好"的专家。

二、Skills 的结构与组成

2.1 目录规范

Skills 存放在项目根目录下的 .agent/skills/ 目录中。每个 Skill 是一个独立的子文件夹，文件夹名即为 Skill 的标识符。

标准目录结构如下：

项目根目录/
├── .agent/
│   └── skills/
│       ├── my-first-skill/          # Skill 文件夹（名称即标识符）
│       │   ├── SKILL.md             # ✅ 核心指令文件（必需）
│       │   ├── scripts/             # 📜 辅助脚本（可选）
│       │   │   └── validate.sh
│       │   ├── examples/            # 📖 参考示例（可选）
│       │   │   └── sample-output.md
│       │   └── resources/           # 📦 静态资源（可选）
│       │       └── template.json
│       ├── another-skill/
│       │   └── SKILL.md
│       └── ...

命名约定：

规则	示例	说明
使用 `kebab-case`	`security-audit`	全小写，单词间用连字符
名称要有描述性	`test-driven-development`	一眼看出这个 Skill 做什么
避免过于笼统	❌ `coding` / ✅ `frontend-vibe`	太宽泛的名字会导致职责不清

2.2 SKILL.md —— 核心指令文件

SKILL.md 是每个 Skill 唯一必需的文件。它由两部分组成：

📋 YAML Frontmatter（元数据头）

文件顶部以 --- 包裹的 YAML 块，声明 Skill 的基本信息：

yaml

---
name: security-audit
description: 当用户要求"检查安全问题"、"这段代码安全吗"、"做一下安全审计"时触发。系统性地扫描代码中的安全风险并给出修复方案。
---

字段	必需	说明
`name`	✅	Skill 的唯一标识名，通常与文件夹名一致
`description`	✅	关键字段！ AI 通过它判断何时触发此 Skill。应包含：触发场景（用户会说什么）+ 核心功能（Skill 做什么）

⚡ 重要提示：description 不仅是给人看的，更是给 AI 看的。它是 AI 进行 Skill 匹配的依据。写得越精确，AI 的匹配就越准确。

📝 Markdown 指令体（正文）

Frontmatter 之后的部分就是指令正文，用标准 Markdown 编写。这是 Skill 的核心——告诉 AI 具体怎么做。

一个好的指令体通常包含以下要素：

markdown

---
name: example-skill
description: ...
---

# Skill 名称

## 触发条件
描述在什么场景下应该使用这个 Skill。

## 执行步骤
1. 第一步：做什么
2. 第二步：做什么
3. 第三步：做什么

## 输出规范
描述输出的格式、结构和质量标准。

## 注意事项
- 边界情况处理
- 常见错误避免
- 与其他 Skill 的配合

## 示例
展示输入和期望输出的对照。

2.3 可选扩展目录

除了 SKILL.md 之外，你可以添加辅助资源来增强 Skill 的能力：

📜 `scripts/` —— 辅助脚本

存放 AI 在执行 Skill 时可能调用的脚本文件。

scripts/
├── lint-check.sh        # 代码风格检查脚本
├── run-security-scan.py # 安全扫描脚本
└── generate-report.sh   # 报告生成脚本

典型用途：

自动化检查（lint、测试、安全扫描）
数据处理和格式转换
环境初始化和配置

📖 `examples/` —— 参考示例

提供具体的输入/输出样例，帮助 AI 理解期望的行为模式。

examples/
├── good-commit-message.md   # 好的提交信息示例
├── bad-commit-message.md    # 反面示例
└── refactoring-before-after.md  # 重构前后对比

典型用途：

展示期望的输出格式和风格
提供 few-shot learning 的样本
正反对比，明确边界

📦 `resources/` —— 静态资源

存放模板文件、配置文件、检查清单等静态资源。

resources/
├── pr-template.md        # PR 模板
├── checklist.json        # 检查项清单
└── architecture-rules.yaml  # 架构约束规则

典型用途：

文档模板和骨架
配置文件和规则定义
检查清单和评估标准

2.4 一个最小 Skill 示例

以下是一个完整但最小化的 Skill，用于规范 Git 提交信息：

.agent/skills/commit-message/
└── SKILL.md

SKILL.md 内容：

markdown

---
name: commit-message
description: 当用户要求"帮我写个 commit message"、"提交信息怎么写"时触发。按照 Conventional Commits 规范生成标准化的提交信息。
---

# Git Commit Message 规范化

## 触发条件
用户完成代码修改后，需要生成提交信息。

## 执行步骤

1. **分析变更内容**：查看当前的 `git diff` 或已暂存的文件变更
2. **确定变更类型**：根据变更内容判断类型（feat / fix / refactor / docs / chore 等）
3. **识别影响范围**：确定变更影响的模块或组件（scope）
4. **撰写提交信息**：按照以下格式生成

## 输出格式

采用 Conventional Commits 规范：

\```
<type>(<scope>): <简短描述>

<详细说明（可选）>

<关联信息（可选）>
\```

## 示例

\```
feat(auth): 添加微信扫码登录功能

- 集成微信开放平台 OAuth2.0 授权流程
- 新增 WeChatLoginButton 组件
- 添加 token 刷新机制

Closes #42
\```

## 注意事项
- 简短描述不超过 50 个字符
- 使用中文撰写描述（根据团队约定）
- 如有关联 Issue，在 footer 中注明

总结：一个 Skill 的最小形态就是一个文件夹 + 一个 SKILL.md。随着需求复杂化，你可以逐步添加 scripts/、examples/、resources/ 来增强它的能力。保持"从简单开始，按需扩展"的原则。

三、Skills 如何工作？

3.1 触发机制

AI 是如何知道该使用哪个 Skill 的？这要从两种触发方式说起：

🤖 自动匹配（推荐）

当你向 AI 发出请求时，AI 会扫描所有已安装 Skills 的 description 字段，寻找与你的请求最匹配的 Skill。

用户请求                          AI 匹配过程
─────────                         ──────────
"帮我检查一下这段代码           → 扫描所有 Skill 的 description
 有没有安全问题"                → 匹配到 security-audit:
                                   "当用户要求'检查安全问题'、
                                    '这段代码安全吗'时触发"
                                → 加载 security-audit 的 SKILL.md
                                → 按照指令执行安全审计

这就是为什么 description 字段如此重要——它是 AI 进行语义匹配的关键依据。

匹配优先级逻辑：

优先级	场景	说明
🥇 最高	用户明确指定了 Skill	如："使用 security-audit 技能检查代码"
🥈 高	用户请求与某个 Skill 的 description 高度匹配	关键词完全命中
🥉 中	用户请求与某个 Skill 的 description 语义相关	意图相近但措辞不同
⚪ 低	没有匹配到任何 Skill	AI 使用通用能力处理

✋ 手动指定

你也可以直接告诉 AI 使用某个特定的 Skill：

"请使用 architect-spec 技能，帮我设计这个功能的架构"

手动指定适用于以下场景：

AI 没有自动匹配到正确的 Skill
你想强制使用某个特定的工作流
同一个请求可能匹配多个 Skill，你需要明确选择

3.2 执行流程

当一个 Skill 被触发后，AI 会按照以下流程执行：

┌─────────────┐
│  ① 识别     │  AI 接收用户请求，匹配到合适的 Skill
└──────┬──────┘
       ▼
┌─────────────┐
│  ② 加载     │  读取 SKILL.md 的完整内容（指令 + 资源）
└──────┬──────┘
       ▼
┌─────────────┐
│  ③ 理解     │  解析指令中的步骤、规范、约束和示例
└──────┬──────┘
       ▼
┌─────────────┐
│  ④ 执行     │  严格按照指令步骤工作，结合项目实际情况
└──────┬──────┘
       ▼
┌─────────────┐
│  ⑤ 输出     │  按照 Skill 定义的输出规范交付结果
└─────────────┘

关键细节说明：

① 识别阶段

AI 不仅看 description，还会综合考虑用户请求中的关键词、上下文和意图。例如，用户说"这个接口响应太慢了"，AI 能理解这是性能问题，从而匹配到 perf-optimizer。

② 加载阶段

AI 会读取 SKILL.md 的完整内容。如果指令中引用了 scripts/、examples/ 或 resources/ 中的文件，AI 也会按需读取这些辅助资源。

③ 理解阶段

AI 会将 Skill 指令内化为自己的"工作计划"。这不是简单的文本复制——AI 会根据当前的项目上下文，对通用指令进行具体化的适配。

④ 执行阶段

这是最核心的阶段。AI 会：

按照指令中定义的步骤顺序逐步执行
遵循指令中的约束条件（如命名规范、文件结构要求）
参考指令中的示例来确保输出质量
在需要时调用 scripts/ 中的脚本

⑤ 输出阶段

AI 按照 Skill 定义的输出规范交付结果。这可能是：

一份结构化的分析报告
一组符合规范的代码文件
一个标准化的提交信息
一份详细的架构设计文档

3.3 与普通 Prompt 的区别

你可能会想："直接写一个详细的 Prompt 不也能做到吗？为什么还需要 Skills？"

这是一个好问题。让我们来对比一下：

对比维度	普通 Prompt	Skills
生命周期	一次性使用，用完即弃	持久化存储，反复使用
存储方式	存在聊天记录里，难以检索	以文件形式存在项目中，随代码版本管理
可维护性	修改需要重新编写整个 Prompt	直接编辑 `SKILL.md`，增量更新
可共享性	复制粘贴，容易丢失上下文	Git 仓库共享，团队统一使用
触发方式	每次都需手动输入	AI 自动识别并触发
复杂度上限	受限于对话窗口的长度	可拆分为多个文件，支持脚本和资源
质量一致性	同一个人每次写的 Prompt 都不一样	同一个 Skill 每次执行的标准一致

用一个生活化的类比来总结：

普通 Prompt = 口头交代任务
  "小王，你去把那个报告做一下，格式参考上次的，别忘了加封面。"
  → 每次交代的细节可能不同，容易遗漏

Skills = 书面的作业指导书
  一份完整的文档，写明了报告的格式规范、模板位置、审核标准。
  → 任何人拿到都能按标准执行，结果一致

什么时候用 Prompt，什么时候用 Skill？

场景	推荐方式	原因
一次性的探索性问题	Prompt	不值得为此创建 Skill
反复执行的标准化任务	Skill	一次编写，长期受益
团队共享的工作流程	Skill	确保团队标准一致
需要多步骤协作的复杂任务	Skill	流程不会遗漏
快速的代码片段生成	Prompt	简单直接，无需流程化

总结：Skills 的工作机制可以概括为"匹配 → 加载 → 执行"。它与普通 Prompt 的核心区别在于持久化和标准化——Skills 把一次性的好想法，变成了可复用、可迭代、可共享的团队资产。

四、内置 Skills 分类速览

一个成熟的 Skills 体系通常覆盖软件开发的完整生命周期。以下按功能领域分为五大类，帮助你快速了解每个 Skill 的定位和用途。

4.1 🧭 规划类 Skills

在动手写代码之前，先想清楚要做什么、怎么做。

Skill	触发场景	核心能力
`brainstorming`	"我想做一个 XX 功能"	探索用户意图、梳理需求、讨论设计方案，在动手之前充分思考
`writing-plans`	"帮我制定实现计划"	将需求拆解为多步骤的实施计划，定义里程碑和检查点
`architect-spec`	"帮我设计系统架构"	输出标准化的架构产物：数据模型、API 设计、组件关系图

使用时机：项目启动阶段、新功能规划阶段、重大技术决策前。

典型工作流：

brainstorming → architect-spec → writing-plans → 开始编码
   探索需求        设计架构         制定计划

4.2 💻 开发类 Skills

按照最佳实践和项目规范编写代码。

Skill	触发场景	核心能力
`frontend-vibe`	"帮我写个前端页面"	编写前端 UI 组件、页面布局、对接后端接口，注重视觉效果
`backend-core`	"帮我写后端接口"	编写 API 路由、数据库模型、业务逻辑、AI 大模型集成
`test-driven-development`	"帮我实现这个功能"	先写测试用例，再写实现代码，确保代码质量从源头把控

使用时机：功能实现阶段、需求开发阶段。

TDD 的价值：test-driven-development 不只是一个编码 Skill，它改变了开发的思维方式：

传统方式：需求 → 编码 → 测试（发现 bug）→ 修复 → 再测试
TDD 方式：需求 → 写测试 → 编码（让测试通过）→ 重构 → 完成 ✅

4.3 🔍 质量类 Skills

发现问题、诊断问题、解决问题。

Skill	触发场景	核心能力
`systematic-debugging`	"这里有个 bug"	系统性地定位 bug，不猜测、不盲改，用证据说话
`security-audit`	"检查安全问题"	扫描代码中的安全漏洞（SQL 注入、XSS、权限绕过等），给出修复方案
`perf-optimizer`	"这个接口太慢了"	定位性能瓶颈，给出量化的优化方案和预期收益
`refactor-guru`	"帮我重构这段代码"	安全地改善代码结构，不改变外部行为，减少技术债务

使用时机：代码审查阶段、线上问题排查、技术债务清理。

systematic-debugging 的核心原则：

❌ 错误做法：看到报错 → 猜测原因 → 改代码 → 祈祷能跑
✅ 正确做法：看到报错 → 收集证据 → 定位根因 → 验证修复 → 回归测试

4.4 ⚙️ 工作流类 Skills

规范化日常开发流程中的关键环节。

Skill	触发场景	核心能力
`git-workflow`	"帮我写个 commit message"	生成规范的提交信息、解决合并冲突、生成 changelog
`verification-before-completion`	即将宣布任务完成时	强制执行验证步骤，先跑通测试再说完成
`requesting-code-review`	"帮我提交代码审查"	生成结构化的 CR 请求，突出关键变更和风险点
`receiving-code-review`	收到审查反馈时	理性分析反馈，验证建议的合理性，避免盲目同意
`finishing-a-development-branch`	开发分支完成时	引导完成收尾工作：合并、清理、文档更新

使用时机：贯穿整个开发周期的关键节点。

verification-before-completion 的重要性：

这个 Skill 体现了一个核心理念——"证据先于断言"：

❌ "我改好了，应该没问题了。"
✅ "我改好了，测试全部通过（附截图），手动验证了 3 个边界场景。"

4.5 📝 文档类 Skills

好代码需要好文档。

Skill	触发场景	核心能力
`doc-generator`	"帮我写注释 / API 文档 / README"	自动为代码和项目生成高质量的技术文档
`prompt-engineer`	"帮我设计一个 Prompt"	结构化地设计、测试和迭代 LLM Prompt 模板

使用时机：功能完成后的文档补全、API 发布前的文档编写。

4.6 全景图

将所有 Skills 放到软件开发生命周期中，可以看到它们的分布：

 项目生命周期
 ═══════════════════════════════════════════════════════

 📐 规划阶段        💻 开发阶段        🔍 质量阶段        🚀 交付阶段
 ──────────        ──────────        ──────────        ──────────
 brainstorming     frontend-vibe     systematic-       git-workflow
 architect-spec    backend-core        debugging       verification-
 writing-plans     test-driven-      security-audit      before-
                     development     perf-optimizer       completion
                                     refactor-guru     requesting-
                                                         code-review
                                                       doc-generator

 ◀─────────────────────────────────────────────────────────────────▶
                    prompt-engineer（贯穿全程）

总结：内置 Skills 覆盖了从需求规划到代码交付的完整链路。你不需要一次性使用所有 Skills——根据当前工作阶段，选择合适的 Skill 即可。随着使用经验的积累，你会自然地形成自己的 Skill 组合习惯。

五、如何使用 Skills？

掌握了 Skills 的概念和结构后，接下来看看在实际工作中如何使用它们。

5.1 自动触发 —— 最自然的方式

大多数情况下，你不需要做任何特殊操作。只需像平时一样用自然语言描述你的需求，AI 会自动匹配合适的 Skill。

示例对话：

👤 用户：这段代码好像有内存泄漏，帮我查一下。

🤖 AI 内部：
   → 关键词匹配："内存泄漏"、"查一下"
   → 匹配到 Skill：systematic-debugging + perf-optimizer
   → 加载 SKILL.md，按照系统性调试流程执行

🤖 AI 回复：
   我将按照系统性调试流程来排查这个内存泄漏问题。
   第一步：收集证据...
   第二步：定位可疑代码...
   ...

让自动触发更准确的技巧：

技巧	示例	效果
使用 Skill 关注的关键词	"帮我做一下安全审计"	精确命中 `security-audit`
描述具体的问题类型	"接口响应时间从 200ms 涨到了 2s"	命中 `perf-optimizer`
说明期望的工作方式	"用 TDD 的方式实现这个功能"	命中 `test-driven-development`

5.2 手动指定 —— 精确控制

当自动匹配不够准确，或者你想强制使用某个 Skill 时，可以直接在请求中指明：

方式一：直接说出 Skill 名称

👤 "请使用 architect-spec 技能，帮我设计用户权限系统的架构。"

方式二：描述你想要的工作模式

👤 "我想先头脑风暴一下这个功能的所有可能方案，不要急着写代码。"
   → AI 识别到这是 brainstorming 的工作模式

方式三：引用 Skill 的行为特征

👤 "帮我改这个 bug，但请先收集证据、定位根因，不要直接改代码。"
   → AI 识别到这是 systematic-debugging 的工作方式

5.3 组合使用 —— 串联工作流

Skills 的真正威力在于组合使用。一个完整的开发任务往往需要多个 Skills 的接力协作。

场景：从零开发一个新功能

阶段 1️⃣  brainstorming
├── 用户描述需求："我想给系统加一个数据导出功能"
├── AI 引导探索：导出什么数据？什么格式？谁来用？
└── 产出：需求文档 + 方案选型

         ▼

阶段 2️⃣  architect-spec
├── 根据需求设计技术方案
├── 定义数据模型、API 接口、组件结构
└── 产出：架构设计文档

         ▼

阶段 3️⃣  writing-plans
├── 将架构方案拆解为具体的实施步骤
├── 定义每个步骤的输入、输出和验收标准
└── 产出：分步实施计划

         ▼

阶段 4️⃣  test-driven-development
├── 先编写测试用例
├── 再实现功能代码
└── 确保所有测试通过

         ▼

阶段 5️⃣  verification-before-completion
├── 运行完整测试套件
├── 手动验证关键场景
└── 确认无遗漏

         ▼

阶段 6️⃣  git-workflow + doc-generator
├── 生成规范的 commit message
├── 补充 API 文档和 README
└── 提交代码审查

5.4 实战示例

📌 示例 1：修复一个线上 Bug

👤 用户："线上用户反馈登录后被立即踢出，帮我排查一下。"

🤖 AI 自动触发：systematic-debugging

执行过程：
1. 收集证据
   - 查看相关日志和错误信息
   - 确认问题的复现条件
   - 检查最近的代码变更

2. 形成假设
   - 假设 A：Token 过期时间配置错误
   - 假设 B：角色验证逻辑有误
   - 假设 C：Session 存储出现竞态条件

3. 逐一验证
   - 排除假设 A：Token 有效期配置正常
   - 验证假设 B：发现角色验证跳过了某个条件 ✅

4. 修复 + 回归测试
   - 修复角色验证逻辑
   - 编写针对性的测试用例
   - 运行完整测试套件确认无回归

📌 示例 2：重构老旧模块

👤 用户："services 目录下有 5 个文件都在重复创建 LLM 客户端，帮我重构。"

🤖 AI 自动触发：refactor-guru

执行过程：
1. 分析现状
   - 扫描所有文件，找出重复的代码模式
   - 绘制依赖关系图

2. 设计方案
   - 提取公共代码为 llm_client.py 工厂模块
   - 提取 JSON 解析逻辑为 llm_utils.py 工具模块

3. 安全重构
   - 逐文件替换，每次替换后运行测试
   - 确保外部行为完全不变

4. 验证
   - 所有现有测试通过
   - 没有引入新的依赖问题

📌 示例 3：为新接口编写文档

👤 用户："刚写完了用户管理的 API，帮我生成接口文档。"

🤖 AI 自动触发：doc-generator

执行过程：
1. 扫描代码
   - 读取路由定义和数据模型
   - 提取请求参数、响应格式、错误码

2. 生成文档
   - 按照 RESTful API 文档规范
   - 包含请求/响应示例
   - 添加认证说明和错误处理说明

3. 输出
   - 结构清晰的 Markdown 文档
   - 可直接集成到项目 README 或 API 文档站

📌 示例 4：组合技 —— 安全审计 + 性能优化

👤 用户："这个支付模块即将上线，帮我全面检查一下。"

🤖 AI 组合触发：security-audit + perf-optimizer

Phase 1 - 安全审计：
   ✅ SQL 注入检查
   ✅ XSS 防护验证
   ⚠️ 发现：金额校验缺少服务端验证
   ⚠️ 发现：日志中打印了敏感信息

Phase 2 - 性能优化：
   ✅ 数据库查询分析
   ⚠️ 发现：N+1 查询问题
   ⚠️ 发现：缺少必要的缓存层

最终产出：
   📄 安全审计报告（含修复方案）
   📄 性能优化报告（含量化指标）

总结：使用 Skills 的最佳策略是"日常靠自动触发，关键节点手动指定，复杂任务组合串联"。不需要记忆所有 Skill 的名字——你只需要像平时一样描述需求，AI 会帮你找到合适的技能。

六、如何编写自定义 Skill？

当内置 Skills 无法满足你的特定需求时，你可以编写自己的 Skill。这比你想象的要简单得多。

6.1 确定 Skill 的职责边界

在动手编写之前，先回答三个问题：

问题	目的	示例
这个 Skill 解决什么问题？	明确职责	"确保所有 API 接口都有统一的错误处理格式"
什么时候应该触发它？	定义触发条件	"当用户要求编写新的 API 接口时"
它不应该做什么？	划清边界	"不负责数据库模型设计，那是 architect-spec 的事"

🎯 职责边界的黄金法则：

✅ 好的边界：一个 Skill 做一类事，做到极致
   → api-error-handler：专门处理 API 错误格式规范

❌ 坏的边界：一个 Skill 什么都管
   → code-helper：写代码、改 bug、做测试、写文档...

6.2 编写 SKILL.md

Step 1：编写 Frontmatter

yaml

---
name: api-error-handler
description: 当用户要求"编写新接口"、"添加 API 路由"、"处理接口错误"时触发。确保所有 API 接口遵循统一的错误处理规范和响应格式。
---

编写 description 的技巧：

要素	说明	示例
列举触发短语	用户可能说的话	"编写新接口"、"添加 API 路由"
描述核心功能	Skill 做什么	"确保遵循统一的错误处理规范"
用引号包裹关键词	提高匹配精度	"处理接口错误"

Step 2：编写指令正文

一个好的指令正文应该包含以下模块（按需选用）：

markdown

# [Skill 名称]

## 背景与目标
为什么需要这个 Skill？解决什么问题？

## 触发条件
明确列出在什么场景下使用。

## 前置检查
执行前需要确认的事项（如依赖是否安装、配置是否存在）。

## 执行步骤
编号列出具体的操作步骤，越详细越好。

## 输出规范
定义输出的格式、结构和质量标准。

## 示例
提供输入和期望输出的对照，这是最有效的指令方式。

## 边界与约束
明确 Skill 不应该做什么，防止越界。

## 常见问题
列出可能遇到的问题和解决方案。

编写指令的核心原则：

具体优于抽象 — "使用 HTTP 422 状态码" 比 "使用合适的状态码" 好
示例优于描述 — 给一个代码示例比写三段描述更有效
约束优于自由 — 明确的限制条件能防止 AI 发挥过度
步骤优于目标 — "先检查 X，再执行 Y" 比 "确保质量" 更可执行

6.3 添加辅助资源

根据 Skill 的复杂度，按需添加辅助资源：

api-error-handler/
├── SKILL.md                    # 核心指令
├── examples/                   # 参考示例（推荐）
│   ├── good-error-response.py  # 正确的错误处理示例
│   └── bad-error-response.py   # 反面示例
├── resources/                  # 模板资源（可选）
│   └── error-codes.json        # 错误码定义表
└── scripts/                    # 辅助脚本（可选）
    └── check-error-handling.sh # 检查脚本

6.4 测试与迭代

编写完成后，通过以下步骤验证 Skill 的效果：

① 触发测试 — 验证 AI 能否正确匹配到你的 Skill

测试用语：
  → "帮我写一个用户注册接口"     （应触发）
  → "这段代码格式不对帮我改一下"  （不应触发）
  → "接口报错了帮我处理一下"     （应触发）

② 执行测试 — 验证 AI 是否按照指令执行

检查点：
  □ 是否按照定义的步骤顺序执行？
  □ 输出格式是否符合规范？
  □ 是否遵守了约束条件？
  □ 边界情况是否处理得当？

③ 迭代优化 — 根据实际效果调整指令

常见调整：
  → AI 跳过了某个步骤  → 在指令中加粗强调 + 加上 "必须" 关键词
  → AI 输出格式不对    → 补充更具体的示例
  → AI 做了不该做的事  → 在"边界与约束"中明确排除
  → 触发不够精准      → 调整 description 中的关键词

6.5 一个完整的自定义 Skill 示例

以下是一个用于规范化 API 错误处理的完整 Skill：

目录结构：

.agent/skills/api-error-handler/
├── SKILL.md
└── examples/
    └── error-response-example.md

SKILL.md：

markdown

---
name: api-error-handler
description: 当用户要求"编写新接口"、"添加 API"、"处理接口错误"、"统一错误格式"时触发。确保所有 API 接口遵循统一的错误处理规范和响应格式。
---

# API 错误处理规范化

## 背景
项目中不同接口的错误响应格式不统一，导致前端处理困难。
本 Skill 确保所有新增接口都遵循统一的错误处理模式。

## 触发条件
- 用户要求编写新的 API 接口
- 用户要求处理或优化接口的错误响应
- 用户要求统一错误格式

## 执行步骤

### 1. 检查现有模式
查看项目中是否已有错误处理的基类或工具函数。

### 2. 使用标准错误响应格式
所有错误响应**必须**遵循以下 JSON 结构：

\```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "用户可读的错误描述",
    "details": {}
  }
}
\```

### 3. 使用正确的 HTTP 状态码

| 状态码 | 使用场景 |
|--------|---------|
| 400    | 请求参数格式错误 |
| 401    | 未认证 |
| 403    | 无权限 |
| 404    | 资源不存在 |
| 422    | 业务逻辑校验失败 |
| 500    | 服务器内部错误 |

### 4. 实现全局异常捕获
确保有统一的异常处理中间件，防止异常泄露。

## 边界与约束
- 本 Skill 只关注错误处理格式，不涉及业务逻辑设计
- 不修改已有接口的正常响应格式
- 日志记录由其他模块负责

## 示例
参考 examples/error-response-example.md

examples/error-response-example.md：

markdown

# 错误响应示例

## ✅ 正确示例

\```python
from fastapi import HTTPException

class AppError(HTTPException):
    def __init__(self, code: str, message: str, status_code: int = 400, details: dict = None):
        self.error_body = {
            "success": False,
            "error": {
                "code": code,
                "message": message,
                "details": details or {}
            }
        }
        super().__init__(status_code=status_code, detail=self.error_body)

# 使用方式
raise AppError(
    code="USER_NOT_FOUND",
    message="指定的用户不存在",
    status_code=404
)
\```

## ❌ 错误示例

\```python
# 不要这样做：直接返回字符串
raise HTTPException(status_code=400, detail="参数错误")

# 不要这样做：暴露内部错误信息
raise HTTPException(status_code=500, detail=str(e))
\```

总结：编写自定义 Skill 的核心流程是"定边界 → 写指令 → 加示例 → 测迭代"。从一个最小化的 SKILL.md 开始，根据实际使用效果逐步完善。不要追求一次写完美——好的 Skill 是迭代出来的。

七、最佳实践与注意事项

7.1 Skill 设计原则

原则一：单一职责

每个 Skill 只做一件事，但把这件事做到极致。

✅ 好的设计                        ❌ 坏的设计
─────────                          ─────────
security-audit    → 只做安全审计    all-in-one → 安全审计 + 性能优化
perf-optimizer    → 只做性能优化                 + 代码重构 + 写文档
refactor-guru     → 只做代码重构
doc-generator     → 只做文档生成

判断标准：如果你的 Skill 的 description 中需要用很多"和"来连接不同的功能，那它可能需要拆分。

原则二：明确触发条件

description 要写得精准，既不能太宽（误触发），也不能太窄（触发不到）。

质量等级	description 示例	问题
❌ 太宽	"当用户需要帮助时触发"	几乎任何请求都会触发
❌ 太窄	"当用户说'帮我检查 SQL 注入漏洞'时触发"	只有精确匹配才能触发
✅ 合适	"当用户要求'检查安全问题'、'做安全审计'、'扫描漏洞'时触发。系统性地扫描代码中的安全风险"	覆盖多种表达，同时边界清晰

原则三：可测试

好的 Skill 应该具备可验证性——你能明确判断 AI 是否正确执行了它。

✅ 可测试的指令：
   "所有错误响应必须包含 code、message、details 三个字段"
   → 检查输出是否包含这三个字段即可

❌ 不可测试的指令：
   "确保代码质量很高"
   → "高"的标准是什么？无法客观判断

原则四：渐进式复杂度

从最简单的版本开始，根据使用反馈逐步添加复杂度。

V1：只有 SKILL.md（基本指令）
     ↓  使用一段时间后
V2：添加 examples/（发现 AI 输出格式不稳定）
     ↓  继续优化
V3：添加 scripts/（需要自动化检查）
     ↓  团队推广后
V4：添加 resources/（需要共享模板和配置）

7.2 常见误区

误区一：指令过于宽泛

❌ "写出高质量的代码"
   → AI 不知道你的"高质量"标准是什么

✅ "代码必须满足以下条件：
    1. 所有函数必须有 docstring
    2. 所有参数必须有类型注解
    3. 单个函数不超过 30 行
    4. 使用项目统一的命名规范（snake_case）"

误区二：缺少示例

指令写得再清楚，都不如一个好的示例直观。

❌ 只有描述：
   "使用 Conventional Commits 格式编写提交信息"

✅ 描述 + 示例：
   "使用 Conventional Commits 格式编写提交信息，如：
    feat(auth): 添加微信扫码登录功能
    fix(api): 修复用户列表分页计算错误"

误区三：忽视边界定义

不告诉 AI "不该做什么"，AI 可能会过度发挥。

❌ 没有边界：
   Skill 只定义了"做什么"，AI 额外做了一堆你没要求的事

✅ 有明确边界：
   "## 边界与约束
    - 本 Skill 不修改现有的数据库模型
    - 不涉及前端组件的样式调整
    - 不自动安装新的依赖包"

误区四：一次追求完美

❌ 花一整天写了一个 500 行的 SKILL.md，结果实际使用时发现方向偏了

✅ 先写一个 50 行的核心版本：
   → 实际使用 3-5 次
   → 记录问题和改进点
   → 逐步迭代完善

7.3 维护建议

📌 版本控制

将 .agent/skills/ 目录纳入 Git 管理，享受所有版本控制的好处：

bash

# Skills 文件应和代码一起提交
git add .agent/skills/
git commit -m "feat(skills): 新增 api-error-handler 技能"

# 可以追溯每次调整的原因
git log --oneline .agent/skills/api-error-handler/SKILL.md

📌 团队共享

Skills 随代码仓库自动共享给所有团队成员：

团队成员 A 编写了 security-audit Skill
     ↓ git push
团队成员 B 拉取代码后自动获得
     ↓ 使用中发现可以优化
团队成员 B 提交改进 PR
     ↓ 团队讨论 + 合并
所有人都受益于更好的 Skill

📌 定期回顾

建议每 1-2 个月回顾一次 Skills 库：

检查项	操作
有没有从未被触发的 Skill？	考虑调整 description 或删除
有没有经常需要手动覆盖的 Skill？	指令可能需要优化
有没有新的重复模式还没有被 Skill 化？	考虑创建新 Skill
有没有两个 Skill 职责重叠？	考虑合并或重新划分边界

📌 命名一致性

保持团队内的 Skill 命名风格统一：

✅ 统一风格
   security-audit
   perf-optimizer
   doc-generator

❌ 混乱风格
   security-audit
   optimizePerformance
   Doc_Gen

总结：好的 Skill 具备四个特征——职责单一、触发精准、可以验证、持续迭代。避免一次追求完美，从简单开始，让实践驱动优化。将 Skills 纳入版本控制和团队协作流程，让它成为团队共同维护的知识资产。

八、总结与展望

回顾：一张图看懂 Skills

                        ┌─────────────────────┐
                        │   什么是 Skills？     │
                        │   AI 的技能插件       │
                        └──────────┬──────────┘
                                   │
                    ┌──────────────┼──────────────┐
                    ▼              ▼              ▼
             ┌────────────┐ ┌──────────┐ ┌────────────┐
             │  结构组成   │ │ 工作机制  │ │  使用方式   │
             │            │ │          │ │            │
             │ SKILL.md   │ │ 自动匹配  │ │ 自动触发   │
             │ scripts/   │ │ 加载指令  │ │ 手动指定   │
             │ examples/  │ │ 执行步骤  │ │ 组合串联   │
             │ resources/ │ │ 交付输出  │ │            │
             └────────────┘ └──────────┘ └────────────┘
                                   │
                    ┌──────────────┼──────────────┐
                    ▼              ▼              ▼
             ┌────────────┐ ┌──────────┐ ┌────────────┐
             │  内置 Skills│ │ 自定义   │ │  最佳实践   │
             │            │ │          │ │            │
             │ 规划类      │ │ 定边界   │ │ 单一职责   │
             │ 开发类      │ │ 写指令   │ │ 精准触发   │
             │ 质量类      │ │ 加示例   │ │ 可验证     │
             │ 工作流类    │ │ 测迭代   │ │ 持续迭代   │
             │ 文档类      │ │          │ │            │
             └────────────┘ └──────────┘ └────────────┘

核心要点速记

#	要点	一句话总结
1	Skills 是什么	写给 AI 看的标准操作手册
2	最小组成	一个文件夹 + 一个 `SKILL.md`
3	触发方式	日常自动触发，关键时刻手动指定
4	编写原则	具体优于抽象，示例优于描述
5	迭代策略	从简单开始，让实践驱动优化
6	团队协作	纳入 Git，像管理代码一样管理 Skills

展望：Skills 的未来

Skills 机制代表了一种全新的人机协作范式——通过结构化的知识传递，让 AI 成为团队中真正的生产力成员。

随着 AI 编码助手的能力不断增强，Skills 的价值也将持续放大：

🔄 更智能的匹配 — AI 将能更精准地理解用户意图，自动组合多个 Skills
🤝 跨团队共享 — 优质的 Skills 可以像开源库一样在社区中分享和复用
📊 数据驱动优化 — 基于使用数据自动识别需要优化的 Skills
🔗 Skill 间协作 — Skills 之间可以声明依赖关系，自动编排执行顺序

立即开始

不要等到"万事俱备"才开始使用 Skills。现在就可以：

选一个你最频繁执行的重复性任务（比如写 commit message、做代码审查）
为它创建一个最小化的 Skill（只需一个 SKILL.md）
实际使用 3-5 次，记录需要改进的地方
迭代优化，让它越来越好

记住：最好的 Skill 不是一次写出来的，而是一次次用出来的。

📝 本文档持续更新中。如有建议或反馈，欢迎在项目中提出 Issue。

AI Skills 完全指南 ​

一、什么是 Skills？ ​

1.1 概念定义 ​

1.2 核心价值 ​

1.3 类比理解 ​

🏭 Skills 之于 AI Agent = SOP 之于团队成员 ​

🎮 Skills 之于 AI = 技能树之于游戏角色 ​

📱 Skills 之于 AI = App 之于手机 ​

二、Skills 的结构与组成 ​

2.1 目录规范 ​

2.2 SKILL.md —— 核心指令文件 ​

📋 YAML Frontmatter（元数据头） ​

📝 Markdown 指令体（正文） ​

2.3 可选扩展目录 ​

📜 scripts/ —— 辅助脚本 ​

📖 examples/ —— 参考示例 ​

📦 resources/ —— 静态资源 ​

2.4 一个最小 Skill 示例 ​

三、Skills 如何工作？ ​

3.1 触发机制 ​

🤖 自动匹配（推荐） ​

✋ 手动指定 ​

3.2 执行流程 ​

3.3 与普通 Prompt 的区别 ​

四、内置 Skills 分类速览 ​

4.1 🧭 规划类 Skills ​

4.2 💻 开发类 Skills ​

4.3 🔍 质量类 Skills ​

4.4 ⚙️ 工作流类 Skills ​

4.5 📝 文档类 Skills ​

4.6 全景图 ​

五、如何使用 Skills？ ​

5.1 自动触发 —— 最自然的方式 ​

5.2 手动指定 —— 精确控制 ​

5.3 组合使用 —— 串联工作流 ​

场景：从零开发一个新功能 ​

5.4 实战示例 ​

📌 示例 1：修复一个线上 Bug ​

📌 示例 2：重构老旧模块 ​

📌 示例 3：为新接口编写文档 ​

📌 示例 4：组合技 —— 安全审计 + 性能优化 ​

六、如何编写自定义 Skill？ ​

6.1 确定 Skill 的职责边界 ​

6.2 编写 SKILL.md ​

Step 1：编写 Frontmatter ​

Step 2：编写指令正文 ​

6.3 添加辅助资源 ​

6.4 测试与迭代 ​

6.5 一个完整的自定义 Skill 示例 ​

七、最佳实践与注意事项 ​

7.1 Skill 设计原则 ​

原则一：单一职责 ​

原则二：明确触发条件 ​

原则三：可测试 ​

原则四：渐进式复杂度 ​

7.2 常见误区 ​

误区一：指令过于宽泛 ​

误区二：缺少示例 ​

误区三：忽视边界定义 ​

误区四：一次追求完美 ​

7.3 维护建议 ​

📌 版本控制 ​

📌 团队共享 ​

📌 定期回顾 ​

📌 命名一致性 ​

八、总结与展望 ​

回顾：一张图看懂 Skills ​

核心要点速记 ​

展望：Skills 的未来 ​

立即开始 ​

AI Skills 完全指南

一、什么是 Skills？

1.1 概念定义

1.2 核心价值

1.3 类比理解

🏭 Skills 之于 AI Agent = SOP 之于团队成员

🎮 Skills 之于 AI = 技能树之于游戏角色

📱 Skills 之于 AI = App 之于手机

二、Skills 的结构与组成

2.1 目录规范

2.2 SKILL.md —— 核心指令文件

📋 YAML Frontmatter（元数据头）

📝 Markdown 指令体（正文）

2.3 可选扩展目录

📜 `scripts/` —— 辅助脚本

📖 `examples/` —— 参考示例

📦 `resources/` —— 静态资源

2.4 一个最小 Skill 示例

三、Skills 如何工作？

3.1 触发机制

🤖 自动匹配（推荐）

✋ 手动指定

3.2 执行流程

3.3 与普通 Prompt 的区别

四、内置 Skills 分类速览

4.1 🧭 规划类 Skills

4.2 💻 开发类 Skills

4.3 🔍 质量类 Skills

4.4 ⚙️ 工作流类 Skills

4.5 📝 文档类 Skills

4.6 全景图

五、如何使用 Skills？

5.1 自动触发 —— 最自然的方式

5.2 手动指定 —— 精确控制

5.3 组合使用 —— 串联工作流

场景：从零开发一个新功能

5.4 实战示例

📌 示例 1：修复一个线上 Bug

📌 示例 2：重构老旧模块

📌 示例 3：为新接口编写文档

📌 示例 4：组合技 —— 安全审计 + 性能优化

六、如何编写自定义 Skill？

6.1 确定 Skill 的职责边界

6.2 编写 SKILL.md

Step 1：编写 Frontmatter

Step 2：编写指令正文

6.3 添加辅助资源

6.4 测试与迭代

6.5 一个完整的自定义 Skill 示例

七、最佳实践与注意事项

7.1 Skill 设计原则

原则一：单一职责

原则二：明确触发条件

原则三：可测试

原则四：渐进式复杂度

7.2 常见误区

误区一：指令过于宽泛

误区二：缺少示例

误区三：忽视边界定义

误区四：一次追求完美

7.3 维护建议

📌 版本控制

📌 团队共享

📌 定期回顾

📌 命名一致性

八、总结与展望

回顾：一张图看懂 Skills

核心要点速记

展望：Skills 的未来

立即开始