掌握了 AI Skills 的基础概念和核心结构后，如何将它们应用于日常开发才是关键。本文将深入探讨 Skills 的使用方式、自定义编写方法以及团队协作的最佳实践，帮助你与 AI 助手建立高效的工作流。
五、如何使用 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 的真正威力在于组合使用。一个复杂的开发任务，往往需要多个技能像流水线一样接力完成。
场景：从零开发一个新功能
阶段 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 实战示例
下面通过几个具体的场景，看看 Skills 如何解决实际问题。
📌 示例 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 无法满足你的特定需求时，完全可以自己动手编写。这个过程比你想象的要简单，更像是在为一位新同事编写一份清晰的工作手册。
6.1 确定 Skill 的职责边界
动手之前，先想清楚三个核心问题：
| 问题 |
目的 |
示例 |
| 这个 Skill 解决什么问题？ |
明确职责 |
“确保所有 API 接口都有统一的错误处理格式” |
| 什么时候应该触发它？ |
定义触发条件 |
“当用户要求编写新的 API 接口时” |
| 它不应该做什么？ |
划清边界 |
“不负责数据库模型设计，那是 architect-spec 的事” |
🎯 职责边界的黄金法则：
✅ 好的边界：一个 Skill 做一类事，做到极致
→ api-error-handler：专门处理 API 错误格式规范
❌ 坏的边界：一个 Skill 什么都管
→ code-helper：写代码、改 bug、做测试、写文档...
6.2 编写 SKILL.md
这是 Skill 的核心文件。一份好的 SKILL.md 应该像一份优秀的技术文档，结构清晰，指令明确。
Step 1：编写 Frontmatter
这是 Skill 的“身份证”，用于 AI 进行匹配。
---
name: api-error-handler
description: 当用户要求“编写新接口”、“添加 API 路由”、“处理接口错误”时触发。确保所有 API 接口遵循统一的错误处理规范和响应格式。
---
编写 description 的技巧：
| 要素 |
说明 |
示例 |
| 列举触发短语 |
用户可能说的话 |
“编写新接口”、“添加 API 路由” |
| 描述核心功能 |
Skill 做什么 |
“确保遵循统一的错误处理规范” |
| 用引号包裹关键词 |
提高匹配精度 |
“处理接口错误” |
Step 2：编写指令正文
一个好的指令正文通常包含以下模块，你可以根据 Skill 的复杂度按需选用：
# [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 能否正确匹配
测试用语：
→ “帮我写一个用户注册接口” （应触发）
→ “这段代码格式不对帮我改一下” （不应触发）
→ “接口报错了帮我处理一下” （应触发）
② 执行测试 — 验证 AI 是否按照指令执行
检查点：
□ 是否按照定义的步骤顺序执行？
□ 输出格式是否符合规范？
□ 是否遵守了约束条件？
□ 边界情况是否处理得当？
③ 迭代优化 — 根据实际效果调整指令
常见调整：
→ AI 跳过了某个步骤 → 在指令中加粗强调 + 加上“必须”关键词
→ AI 输出格式不对 → 补充更具体的示例
→ AI 做了不该做的事 → 在“边界与约束”中明确排除
→ 触发不够精准 → 调整 description 中的关键词
6.5 一个完整的自定义 Skill 示例
下面是一个用于规范化 API 错误处理的完整 Skill 实例，你可以以此为模板进行创作。
目录结构：
.agent/skills/api-error-handler/
├── SKILL.md
└── examples/
└── error-response-example.md
SKILL.md 内容：
---
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 内容：**
错误响应示例
✅ 正确示例
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
)
❌ 错误示例
# 不要这样做：直接返回字符串
raise HTTPException(status_code=400, detail="参数错误")
# 不要这样做：暴露内部错误信息
raise HTTPException(status_code=500, detail=str(e))
> **总结**：编写自定义 Skill 的核心流程是“定边界 → 写指令 → 加示例 → 测迭代”。从一个最小化的 `SKILL.md` 开始，根据实际使用效果逐步完善。不要追求一次写完美——好的 Skill 是迭代出来的。
## 七、最佳实践与注意事项
掌握了创建和使用的方法后，让我们来看看如何设计出真正高效、好用的 Skills。
### 7.1 Skill 设计原则
遵循以下原则，能让你的 Skills 库更健壮、更易维护。
**原则一：单一职责**
每个 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 常见误区
避开这些陷阱，能让你的 Skills 编写过程事半功倍。
**误区一：指令过于宽泛**
❌ “写出高质量的代码”
→ AI 不知道你的“高质量”标准是什么
✅ “代码必须满足以下条件：
- 所有函数必须有 docstring
- 所有参数必须有类型注解
- 单个函数不超过 30 行
- 使用项目统一的命名规范（snake_case）”
误区二：缺少示例
指令写得再清楚，都不如一个好的示例直观。
❌ 只有描述：
“使用 Conventional Commits 格式编写提交信息”
✅ 描述 + 示例：
“使用 Conventional Commits 格式编写提交信息，如：
feat(auth): 添加微信扫码登录功能
fix(api): 修复用户列表分页计算错误”
误区三：忽视边界定义
不告诉 AI “不该做什么”，AI 可能会过度发挥。
❌ 没有边界：
Skill 只定义了“做什么”，AI 额外做了一堆你没要求的事
✅ 有明确边界：
“## 边界与约束
- 本 Skill 不修改现有的数据库模型
- 不涉及前端组件的样式调整
- 不自动安装新的依赖包”
误区四：一次追求完美
❌ 花一整天写了一个 500 行的 SKILL.md，结果实际使用时发现方向偏了
✅ 先写一个 50 行的核心版本：
→ 实际使用 3-5 次
→ 记录问题和改进点
→ 逐步迭代完善
7.3 维护建议
将 Skills 视为团队的重要资产进行管理，才能让它的价值持续放大。
📌 版本控制
将 .agent/skills/ 目录纳入 Git 管理，享受所有版本控制的好处：
# Skills 文件应和代码一起提交
git add .agent/skills/
git commit -m "feat(skills): 新增 api-error-handler 技能"
# 可以追溯每次调整的原因
git log --oneline .agent/skills/api-error-handler/SKILL.md
📌 团队共享
Skills 随代码仓库自动共享给所有团队成员，这是一种极佳的知识沉淀和传递方式。团队成员可以在 技术文档 板块分享和讨论各自创建的优秀 Skill 模板。
团队成员 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。
- 🤝 跨团队共享 — 优质的 Skills 可以在像云栈社区这样的开发者社区中像开源库一样被分享和复用。
- 📊 数据驱动优化 — 系统能基于使用数据自动识别出哪些 Skills 最有效、哪些需要优化。
- 🔗 Skill 间协作 — Skills 之间可以声明依赖关系，实现自动化的执行编排。
立即开始
不要等待“完美时机”，现在就可以行动：
- 选一个你最频繁执行的重复性任务（比如写 commit message、做代码审查）
- 为它创建一个最小化的 Skill（只需一个
SKILL.md）
- 实际使用 3-5 次，记录下哪些地方 AI 做得好，哪些地方需要更明确的指令
- 迭代优化，让你的 Skill 变得越来越“聪明”
记住：最好的 Skill 不是一次写出来的，而是一次次用出来的。
发表于 前天 05:39
|
查看: 20|
回复: 0
