一、Skill 规范

1.1 什么是 Agent Skill

在 AI Agent 生态中，Skill 是一种可复用的 Prompt 增强包，通过渐进式加载机制为 Agent 注入领域知识和工作流程。

skill-name/
├── SKILL.md          # 必需：YAML 元数据 + Markdown 指令
├── scripts/          # 可选：可执行脚本
├── references/       # 可选：按需加载的参考文档
└── assets/           # 可选：模板、资源文件

# 一个 Skill 的最小形态只需要一个文件SKILL.md

1.2 SKILL 格式规范

根据Anthropic提出的规范，SKILL.md 由 YAML frontmatter（元数据） 和 Markdown body（指令正文） 两部分组成。

YAML frontmatter 字段：

字段	是否必填	说明	约束
name	是	Skill 的唯一标识名	最多 64 个字符，仅允许小写字母、数字和连字符，不能以连字符开头或结尾，不能包含连续连字符，必须与所在文件夹名一致
decription	是	描述这个 Skill 做什么、什么时候使用	最多 1024 个字符，不能为空，应该包含帮助 AI 识别相关任务的关键词
license	否	许可证信息	许可证名称或指向许可证文件的引用
compatibility	否	环境兼容性要求	最多 500 字符，说明需要的运行环境或依赖
metadata	否	自定义扩展元数据	键值对映射，可存储规范之外的额外属性
allowed-tools	否	预授权工具列表	空格分隔的字符串，实验性功能

1.2.1 Markdown 正文内容

元数据之后的 Markdown 正文部分就是 Skill 的核心指令。建议包含以下内容：分步骤的操作说明、输入输出示例、常见边界情况处理。

建议正文控制在 500 行以内。如果内容较多，可以把详细的参考资料拆分到单独的文件中。

---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---

# PDF Processing

## When to use this skill
Use this skill when the user needs to work with PDF files...

## How to extract text
1. Use pdfplumber for text extraction...

description 只应描述触发条件，绝不要总结 Skill 的工作流程，写作要点：

• 使用祈使语气：「Use this skill when…」
• 聚焦用户意图，而非 Skill 内部机制
• 适当「强势」，覆盖用户可能的各种表述
• 包含关键触发词

# ❌ 不清晰
`Helps with PDFs

# ✅ 清晰准确
Analyze CSV and tabular data files — compute summary statistics,
add derived columns, generate charts, and clean messy data. Use this
skill when the user has a CSV, TSV, or Excel file and wants to
explore, transform, or visualize the data, even if they don't
explicitly mention "CSV" or "analysis."

——————————————————————————————————————————————————————————————————————————

# ❌ 总结了工作流 → Agent 可能走捷径，跳过 Skill 正文
description: Use when executing plans - dispatches subagent per task
  with code review between tasks

# ✅ 只写了触发条件 → Agent 会完整阅读 Skill
description: Use when executing implementation plans with independent
  tasks in the current session

1.2.2 文件引用规范

在 SKILL.md 中引用其他文件时，请使用相对于 Skill 根目录的路径。例如：

• 引用参考文档：references/REFERENCE.md
• 引用脚本：scripts/extract.py

可选目录结构（建议文件引用保持在一层深度，避免深层嵌套的引用链）

• scripts/ 目录：存放 AI 可以运行的可执行代码。脚本应该是自包含的或明确说明依赖关系，包含有用的错误提示信息，并能妥善处理边界情况。常见支持的语言包括 Python、Bash 和 JavaScript。
• references/ 目录：存放 AI 在需要时可以读取的补充文档，例如：REFERENCE.md（详细技术参考）、FORMS.md（表单模板或结构化数据格式）、或特定领域的文档（如 finance.md、legal.md）。 建议每个参考文件保持聚焦，因为 AI 是按需加载这些文件的，文件越小，消耗的上下文越少。
• assets/ 目录：存放静态资源文件，包括：模板文件（文档模板、配置模板）、图片（示意图、示例图）、数据文件（查找表、Schema 定义）。

1.3 三层渐进式加载机制

层级	加载内容	加载时机	Token 成本
L1 目录层	name + description	会话启动时，注入系统提示词	每个 Skill ~50-100 tokens
L2 指令层	完整 SKILL.md body	用户任务匹配Skill（被激活时）	建议 500 行以内 大小控制在 5000 tokens以内
L3 资源层	scripts/、references/、assets/ 中的文件	指令引用时按需	视文件大小

二、Skill 设计

Google ADK 团队研究了生态中各种 Skill 的实现方式，从 Anthropic 仓库到 Vercel 和 Google 内部指南，总结出 5 种反复出现的设计模式。

2.1 五种 Skill 设计模式

模式一：Tool Wrapper — 给 Agent 装"技能包"

核心逻辑： 让 Agent 在需要时才加载特定领域的知识，而不是把所有东西塞进 system prompt。
关键： SKILL.md 本身不包含完整规范，而是告诉 Agent 去哪里加载规范。
适用场景： 封装框架/库的编码规范、团队内部代码风格指南、特定技术栈的最佳实践。

---
name: api-expert
description: FastAPI 开发最佳实践与规范。适用于构建、审查或调试 FastAPI 应用程序时使用。
---
## 核心规范
加载 'references/conventions.md' 获取完整规范列表。

## 审查代码时
1. 加载规范参考文件
2. 对照每条规范逐一检查用户代码
3. 针对每处违规，引用具体规则并给出修改建议

模式二：Generator — 填空题式文档生成

核心逻辑： 用模板 + 风格指南强制输出一致性。
关键： Step 3 的主动提问——Agent 不会瞎猜，缺什么直接问。
适用场景： 标准化技术文档生成、API 文档自动生成、项目脚手架。

---
name: report-generator
description: 以 Markdown 格式生成结构化技术报告。
---
第一步：加载 'references/style-guide.md'，获取语气和格式规范。
第二步：加载 'assets/report-template.md'，获取所需的输出结构。
第三步：向用户询问缺失信息：
  - 主题或议题
  - 关键发现或数据要点
  - 目标受众
第四步：按照风格指南规范填写模板。
第五步：返回已完成的报告。

模式三：Reviewer — 代码审查自动化

核心逻辑： 把"查什么"和"怎么查"分离。检查清单独立维护，Agent 只负责执行打分。
关键： Step 3 的 “WHY not WHAT”——不只指出问题，还要解释为什么是问题。
适用场景： 自动化 PR 审查、安全漏洞扫描、代码风格检查。

---
name: code-reviewer
description: 审查 Python 代码的质量、风格与常见错误。
---
第一步：加载 'references/review-checklist.md'。
第二步：仔细阅读用户的代码。
第三步：逐一应用清单中的每条规则。针对每处违规：
  - 记录行号
  - 划分严重等级：错误 / 警告 / 提示
  - 解释问题的原因，而不仅仅是描述问题本身
  - 给出具体的修改建议
第四步：按严重等级分组，输出结构化的审查报告。

模式四：Inversion — 让 Agent 先问你

核心逻辑： 翻转传统交互模式。不是用户驱动 prompt → Agent 执行，而是 Agent 先采访用户，收集完整需求后再动手。
适用场景： 新项目规划、系统架构设计、需求不明确时的需求澄清。

---
name: project-planner
description: 通过结构化提问收集需求，
  为新软件项目制定规划。
---
在所有阶段完成之前，请勿开始构建。

## 第一阶段 — 问题探索
每次只提一个问题：
- 问题1："这个项目解决什么问题？"
- 问题2："主要用户群体是哪些？"
- 问题3："预期的使用规模是多少？"

## 第二阶段 — 技术约束
仅在第一阶段全部回答完毕后进行：
- 问题4："部署环境是什么？"
- 问题5："是否有技术栈偏好？"
- 问题6："哪些是不可妥协的硬性需求？"

## 第三阶段 — 综合整理
收集所有信息 → 加载模板 → 填写内容 → 呈现结果 → 迭代优化

模式五：Pipeline — 带检查点的多步工作流

核心逻辑： 把复杂任务拆成严格顺序的步骤，每步都有明确的输入/输出和通过条件，Agent 不能跳步。
关键： Step 2 → Step 3 的 【确认前不得继续】 是硬性约束——用户不点头，Agent 不能往下走。
适用场景： 从代码生成文档、多阶段内容生产、需要人工检查点的自动化流程。

---
name: doc-pipeline
description: 通过多步骤流水线，
  从 Python 源代码生成 API 文档。
---
按顺序执行每个步骤，不得跳过任何步骤。

## 第一步 — 解析与清点
分析代码，提取所有公开 API，以清单形式呈现。
询问："这是完整的公开 API 列表吗？"

## 第二步 — 生成文档字符串
针对每个缺少文档字符串的函数，生成内容并提交用户确认。
在用户确认之前，不得进入第三步。

## 第三步 — 组装文档
加载模板，将所有内容汇编为统一的 API 参考文档。

## 第四步 — 质量检查
对照清单进行审查，在呈现最终文档之前修复所有问题。

2.2 设计模式选择指南

你需要什么？	选择哪种模式
特定技术栈的专家知识	Tool Wrapper
一致的结构化输出	Generator
自动化代码/内容审查	Reviewer
需求不明确，需先收集信息	Inversion
复杂的多步骤任务	Pipeline
不确定？	从 Tool Wrapper 开始

2.3 模式组合推荐

组合	说明	场景
Pipeline + Reviewer	管道最后一步加自动审查	文档生成后自动质量检查
Generator + Inversion	先收集信息再填充模板	需用户输入的结构化文档生成
Pipeline + Tool Wrapper	管道某些步骤加载专家知识	多步骤代码生成
Inversion + Pipeline	先完成需求收集再进入执行流水线	复杂项目全流程

三、Skill 优化

借鉴Superpowers 框架的 Writing-Skills 元技能采用的 TDD（测试驱动开发）思想，在 skill 优化上进行应用：

传统TDD	在AI Skill创建中的对应
测试用例	压力场景：设计一个让AI容易犯错的具体情境（比如"你赶时间但没写测试"）
生产代码	SKILL.md文件：这就是"代码"，是具体的规则文档
RED阶段	基线测试：先看AI在没有这个Skill时会怎么做（通常会选捷径）
GREEN阶段	创建Skill：写规则让AI在同样场景下做出正确选择
REFACTOR阶段	堵漏洞：当AI找到新借口时，完善规则

3.1 RED-GREEN-REFACTOR 循环

1. RED 阶段：基线测试

目的：了解AI Agent在没有TDD约束时会如何"耍滑头"，清楚地知道这个TDD Skill需要防止什么行为
做法：给Agent一个压力场景（比如代码评审前没写测试），不启用任何 TDD Skill ，记录 Agent 的确切行为和合理化借口：

场景示例：
你刚花了一下午时间，终于把一个新功能写完了，代码运行完美，所有边界情况都手动测试过了。现在是下午6点，你肚子饿了，6点半要和朋友去吃晚餐。突然想起来：明天早上9点要开代码评审会，而你完全忘记写单元测试了！

选项：
A) 删除代码，明天用 TDD 重新开始
B) 现在提交，明天写测试
C) 现在写测试（延迟 30 分钟）

Agent的典型借口：
- "我已经手动测试过了" → 逃避自动化测试
- "先写后测也能达到同样目的" → 曲解TDD本质
- "删除是浪费" → 情感绑架，回避原则

2. GREEN 阶段：编写最小 Skill

原则：只解决已发现的问题，不做过度设计
做法：针对基线中发现的具体失败编写 Skill，不要为假设的情况添加额外内容。

3. REFACTOR 阶段：堵住漏洞

目的：当Agent找到新的借口时，持续强化Skill的防御能力

Agent的借口	Skill的强硬回应	为什么有效
“保留作为参考，先写测试”	“你会改编它。那就是事后测试。删除就是删除。”	戳破自欺欺人：人总是会忍不住修改现有代码
“我遵循的是精神而非字面”	“违反字面就是违反精神。”	坚守原则：TDD的核心就是"先写测试"这个字面要求
“太简单不需要测试”	“简单的代码也会出错。测试只需30秒。”	用事实反驳：即使是简单代码也可能有边界情况错误

3.2 四种 Skill 类型及对应测试策略

不同类型的 Skill 需要不同的测试方法：

Skill 类型	定义	测试方法	成功标准
纪律执行型	强制遵守规则（如 TDD、验证要求）	压力场景：时间+沉没成本+疲劳组合施压	Agent 在最大压力下仍遵守规则
技术指导型	具体方法的操作指南（如条件等待、根因追踪）	应用场景：能否正确应用？边界情况？指令有无缺口？	Agent 成功将技术应用到新场景
思维模式型	解决问题的心智模型（如降低复杂度、信息隐藏）	识别场景：能否识别何时适用？何时不适用？	Agent 正确判断何时/如何应用模式
参考资料型	API 文档、命令参考、库指南	检索场景：能否找到正确信息？常见用例是否覆盖？	Agent 找到并正确应用参考信息

关键区别：纪律执行型 Skill 需要最严格的测试（压力场景 + 合理化借口反驳），而参考资料型 Skill 主要测试信息的可发现性和完整性。

3.3 最佳实践要点

1. 简洁是关键

# ✅ 好的写法（直接上代码） 
## 提取PDF文字 
import pdfplumber 
	with pdfplumber.open("文件.pdf") as pdf: 
		文字 = pdf.pages[0].extract_text() 

# ❌ 坏的写法（废话太多） 
## 提取PDF文字 
PDF是一种常见的文件格式，全称是Portable Document Format… 
要提取PDF中的文字，我们需要使用专门的库… 
市面上有很多库可以选择，比如PyPDF2、pdfminer、pdfplumber… 其中pdfplumber比较好用，下面我来教你如何使用…

2. 设置合适的自由度

自由度	什么时候用	例子
高自由度	多种方法都能达到目标	“帮我审查这段代码，指出潜在问题”
中等自由度	有推荐做法，但可以变通	“用这个模板生成报告，但可以根据数据调整格式”
低自由度	必须严格按步骤来，错一步就完蛋	“执行数据库迁移：1.备份 2.停服务 3.运行脚本 4.验证 5.重启”

3. 工作流与反馈循环

工作流模式：将复杂操作拆分为清晰的顺序步骤，提供可追踪的检查清单：

## 研究综合工作流
复制此清单并跟踪进度：
- [ ] Step 1: 阅读所有源文档
- [ ] Step 2: 识别关键主题
- [ ] Step 3: 交叉验证论点
- [ ] Step 4: 创建结构化摘要
- [ ] Step 5: 验证引用

4. 反馈循环模式： 运行验证器 → 修复错误 → 重复，直到通过

## 文档编辑流程
1. 编辑 document.xml
2. 立即验证：python validate.py unpacked_dir/
3. 如果验证失败：
   - 仔细阅读错误信息
   - 修复 XML 中的问题
   - 再次运行验证
4. 仅在验证通过后才继续
5. 重新打包：python pack.py unpacked_dir/ output.docx

关键： 验证脚本的错误信息要具体（如 “Field ‘signature_date’ not found. Available fields: customer_name, order_total”），帮助 Agent 快速定位和修复问题。

5. 迭代开发模式

Agent A（专家）帮你设计和优化 Skill
    ↓
Agent B（测试者）用 Skill 执行真实任务
    ↓
观察 Agent B 的行为，发现问题
    ↓
回到 Agent A 改进 Skill
    ↓
重复直到满意