AI Agent Skills 工程化实践：从参考框架到自定义工作流的完整构建指南
目录
AI Agent Skills 的工程化背景
1、为什么需要自定义 Skill 体系
2、Skill 设计的核心原则
构建自定义 Skill 工作流
1、环境准备与基础架构
2、Skill 文件的组织规范
3、核心 Skill 的设计与实现
实战案例
案例一：设计一个代码审查 Skill ------ /code-review-enhanced
案例二：构建需求澄清流水线 ------ /clarify-and-spec
案例三：自动化技术调研 ------ /deep-research
进阶：Skill 的组合与编排
总结与展望
AI Agent Skills 的工程化背景
随着 Claude Code、Cursor、Windsurf 等 AI 编程助手的普及，开发者逐渐意识到：单纯依赖模型的通用能力，难以应对复杂工程场景中的系统性问题。mattpocock/skills 的出现，为这一领域提供了极具参考价值的范式------它证明了通过结构化的 Prompt 工程与可组合的工作流，可以显著提升 AI Agent 在真实软件开发中的可靠性和可控性。
然而，每个团队的技术栈、业务领域和协作方式各不相同。直接套用现成的 Skill 集合往往只能解决 80% 的共性问题，剩余的 20% 需要结合团队自身的上下文来定制。因此，掌握从参考框架到自定义工作流的构建方法，成为提升 AI 工程化能力的关键一步。
1、为什么需要自定义 Skill 体系
| 痛点 | 说明 |
|---|---|
| 领域术语不一致 | 通用 Skill 无法理解团队内部的业务概念和命名规范，导致代码生成与现有体系脱节。 |
| 流程与团队规范冲突 | 每个团队的代码审查标准、提交规范、架构约束不同，需要 Skill 能够适配本地规则。 |
| 工具链差异 | 团队可能使用 GitLab 而非 GitHub，使用 Jira 而非 Linear，使用内网 Wiki 而非 Obsidian。 |
| 安全与合规要求 | 企业环境对数据出境、代码审查、权限控制有严格要求，需要 Skill 在本地闭环运行。 |
自定义 Skill 体系的核心价值在于：将团队的工程智慧、领域知识和协作规范，编码为 AI 可执行的结构化指令，从而在保持自主控制的前提下，规模化释放 AI 的生产力。
2、Skill 设计的核心原则
借鉴 mattpocock/skills 的设计哲学，并结合自定义场景的需求，优秀的 Skill 应遵循以下原则：
| 原则 | 详细说明 |
|---|---|
| 单一职责 | 每个 Skill 只解决一个明确的问题，避免"万能 Skill"导致的输出失控。 |
| 可组合性 | Skill 之间通过标准化的输入/输出格式衔接，像乐高积木一样自由组合。 |
| 上下文感知 | Skill 必须能够读取项目中的领域文档（如 CONTEXT.md、GLOSSARY.md），确保输出与项目上下文一致。 |
| 人机协作 | 关键决策点必须留给人类确认，Skill 负责提供选项、分析利弊，而非自动执行。 |
| 可观测性 | Skill 的执行过程应产生可追溯的日志和中间产物，便于调试和复盘。 |
| 渐进式增强 | 从最简单的版本开始，根据实际使用反馈持续迭代，避免过度设计。 |
构建自定义 Skill 工作流
1、环境准备与基础架构
在开始编写 Skill 之前，建议先搭建一个标准化的工作空间。以下是一个推荐的目录结构：
.agents/
├── skills/ # Skill 定义文件
│ ├── engineering/
│ │ ├── code-review.md
│ │ ├── clarify-requirements.md
│ │ └── implement-feature.md
│ ├── productivity/
│ │ ├── daily-standup.md
│ │ └── meeting-notes.md
│ └── misc/
│ └── git-guardrails.md
├── context/ # 领域上下文文档
│ ├── CONTEXT.md # 项目全景描述
│ ├── GLOSSARY.md # 术语表
│ └── ADR/ # 架构决策记录
├── workflows/ # 组合工作流定义
│ └── feature-lifecycle.md
└── templates/ # 输出模板
├── spec-template.md
└── ticket-template.md关键文件说明：
CONTEXT.md：项目的"活文档"，包含业务背景、技术栈、架构概览、关键约束。所有 Skill 在执行前应优先读取此文件。GLOSSARY.md：统一领域术语表，确保 AI 生成的代码和文档使用团队认可的名词。workflows/：定义多个 Skill 的组合顺序和触发条件，形成端到端的工程流水线。
2、Skill 文件的组织规范
一个标准的 Skill 文件（以 Markdown 格式为例）应包含以下结构：
markdown
# /skill-name
## 目标
一句话描述该 Skill 的核心目的。
## 触发条件
- 用户在什么场景下应该调用此 Skill
- 前置依赖（如需要先执行哪个 Skill）
## 输入
- 期望用户提供的信息
- 自动读取的上下文文件
## 执行步骤
1. 第一步：做什么，为什么
2. 第二步：做什么，产出什么
3. ...
## 输出
- 产物的格式和保存位置
- 后续可衔接的 Skill
## 注意事项
- 边界情况处理
- 需要人类确认的关键决策点示例：/clarify-requirements 的 Skill 定义片段：
markdown
# /clarify-requirements
## 目标
通过结构化访谈，将用户的模糊需求转化为明确、可验收的规格说明。
## 触发条件
- 用户提出一个新功能需求，但细节尚不清晰
- 用户说"我想做一个 XXX"，但缺乏具体范围
## 输入
- 用户的初始需求描述
- 自动读取：`CONTEXT.md`、`GLOSSARY.md`、相关 ADR
## 执行步骤
1. **领域对齐**：先检查 `GLOSSARY.md`，确认需求中涉及的术语是否已有定义。如有歧义，向用户确认。
2. **范围界定**：询问用户该功能的边界------包含什么，明确排除什么。
3. **验收标准**：引导用户定义至少 3 个可测试的验收条件。
4. **冲突检查**：对照 `CONTEXT.md` 和现有 ADR，识别潜在的技术冲突或架构风险。
5. **输出规格**：将访谈结果整理为 `specs/FEATURE-NAME.md`，格式遵循 `templates/spec-template.md`。
## 输出
- `specs/FEATURE-NAME.md`：包含背景、范围、验收标准、技术约束
- 更新的 `GLOSSARY.md`（如有新增术语）
## 注意事项
- 如果需求涉及外部系统依赖，必须确认接口契约是否已存在
- 如果需求可能改变现有架构，标记为"需架构评审"3、核心 Skill 的设计与实现
基于上述规范，以下三个 Skill 覆盖了软件工程中最常见的高价值场景：
| Skill | 功能定位 | 解决的问题 |
|---|---|---|
/clarify-requirements |
需求澄清与规格化 | 需求理解偏差、术语不一致 |
/code-review-enhanced |
上下文感知的代码审查 | 代码质量、架构合规、安全漏洞 |
/deep-research |
结构化技术调研 | 技术选型盲目、调研结论不可复现 |
实战案例
案例一：设计一个代码审查 Skill ------ /code-review-enhanced
背景：传统的 AI 代码审查往往只关注语法和风格，忽略了项目特定的架构约束和业务逻辑正确性。
Skill 设计：
markdown
# /code-review-enhanced
## 目标
基于项目上下文和团队规范，对代码变更进行深度审查。
## 输入
- Git diff 或 PR 链接
- 自动读取：`CONTEXT.md`、相关 ADR、`.eslintrc` 等配置文件
## 执行步骤
1. **变更概览**：总结本次变更涉及的文件和核心逻辑。
2. **架构合规检查**：
- 是否遵循分层架构（如 Controller → Service → Repository）？
- 是否引入了新的依赖？是否符合技术栈约束？
- 是否破坏了现有模块的封装性？
3. **领域逻辑检查**：
- 对照 `GLOSSARY.md`，检查命名是否准确反映业务概念。
- 识别潜在的边界条件遗漏（如空值、并发、时区）。
4. **安全与性能扫描**：
- 检查 SQL 注入、XSS、敏感信息泄露风险。
- 识别明显的性能反模式（如 N+1 查询、内存泄漏）。
5. **可测试性评估**：
- 变更是否可测试？是否需要补充单元测试？
6. **输出审查报告**：按严重级别分类（阻塞 / 警告 / 建议），并提供修复建议。
## 输出
- 结构化审查报告（Markdown 格式）
- 如需修改，生成 `review-comments.md` 并标注行号使用示例：
用户：/code-review-enhanced
Agent：请提供本次审查的代码变更（粘贴 diff 或提供 PR 链接）。
用户：[粘贴 diff]
Agent：[执行审查步骤，输出结构化报告]案例二：构建需求澄清流水线 ------ /clarify-and-spec
背景：产品经理提出需求后，开发团队常常需要多轮会议才能对齐理解。通过 Skill 流水线，可以将这一过程结构化、异步化。
工作流定义 （workflows/feature-lifecycle.md）：
markdown
# 功能开发流水线
## 阶段一：需求澄清
Skill：`/clarify-requirements`
输入：产品经理的原始需求
输出：`specs/FEATURE-XXX.md`
## 阶段二：架构预检
Skill：`/architecture-preview`
输入：`specs/FEATURE-XXX.md`
输出：架构影响评估报告，确认是否需要更新 ADR
## 阶段三：任务拆分
Skill：`/to-tickets`
输入：通过预检的 Spec
输出：GitHub Issues / Jira Tickets，带依赖关系
## 阶段四：实现与审查
Skill：`/implement` + `/code-review-enhanced`
输入：Tickets
输出：PR + 审查报告价值：整个流程从需求提出到代码提交，都有明确的 Skill 负责，减少了信息在人与人之间的传递损耗。
案例三：自动化技术调研 ------ /deep-research
背景：技术选型时，团队需要调研多个方案，但调研过程往往缺乏结构化，结论难以复现和评审。
Skill 设计：
markdown
# /deep-research
## 目标
针对特定技术问题，进行结构化调研并输出可评审的调研报告。
## 输入
- 调研问题（如"应该选择 Next.js 还是 Nuxt.js 作为前端框架？"）
- 约束条件（如团队已熟悉 React、项目需要 SSR、预算限制）
## 执行步骤
1. **问题拆解**：将大问题拆分为评估维度（学习曲线、生态成熟度、性能、维护成本等）。
2. **信息收集**：基于高可信度来源（官方文档、GitHub 仓库、权威基准测试）收集事实。
3. **对比分析**：在每个维度上对候选方案进行客观对比，标注信息来源。
4. **风险评估**：识别每个方案的风险点和缓解措施。
5. **推荐与决策记录**：给出推荐方案，并说明决策依据。将结论写入 `research/YYYY-MM-DD-topic.md`。
## 输出
- `research/YYYY-MM-DD-topic.md`：包含问题、维度、对比表、推荐、风险
- 自动追加到 `ADR/`（如调研结果导致了架构决策）进阶：Skill 的组合与编排
当单个 Skill 无法满足复杂场景时，可以通过以下方式进行组合：
1. 顺序编排（Pipeline）
如案例二所示，多个 Skill 按固定顺序执行，前一阶段的输出作为后一阶段的输入。这种模式适用于标准化的工程流程。
2. 条件分支（Conditional Routing）
设计一个"路由器" Skill（类似 mattpocock/skills 中的 /ask-matt），根据用户输入的上下文，动态推荐下一个应执行的 Skill：
markdown
# /route
## 逻辑
- 如果用户提到"bug"或"报错" → 推荐 `/diagnosing-bugs`
- 如果用户提到"新功能"或"需求" → 推荐 `/clarify-requirements`
- 如果用户提到"重构"或"架构" → 推荐 `/improve-codebase-architecture`
- 如果用户输入模糊 → 推荐 `/grill-me` 进行澄清3. 循环迭代（Loop）
对于需要多轮打磨的场景（如写作、设计），Skill 可以设计为循环执行，直到满足退出条件：
markdown
# /iterate-design
## 循环条件
每轮输出后询问用户："是否满意？还是需要调整以下方面：A / B / C"
- 用户选择继续 → 进入下一轮迭代
- 用户选择满意 → 输出最终产物并结束总结与展望
mattpocock/skills 为我们展示了 AI Agent 在真实工程中的巨大潜力，但其真正的价值不在于 Skill 本身，而在于它所倡导的工程化思维：将软件开发中的隐性知识显性化，将重复性决策结构化，将人机协作流程标准化。
自定义 Skill 体系的构建并非一蹴而就。建议团队从以下路径渐进推进：
- 先记录，后编码 ：先维护好
CONTEXT.md和GLOSSARY.md，这是所有 Skill 的上下文基础。 - 从高频场景切入：选择团队每天重复 3 次以上的工作（如代码审查、需求澄清）作为第一个 Skill。
- 小步快跑，持续迭代：第一个版本的 Skill 可能只有 3 个步骤，根据实际使用反馈逐步丰富。
- 建立反馈闭环：定期复盘 Skill 的输出质量，将改进点反哺到 Skill 定义中。
未来，随着 AI Agent 能力的增强，Skill 体系将不仅限于文本指令，还可能集成自动化测试、性能分析、安全扫描等工具链，形成真正的**"AI 原生"工程平台**。而在这个趋势中，掌握 Skill 设计与编排能力的团队，将获得显著的工程效率优势。