Agent Skill规范、构建与设计模式

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

name: pdf-processing
name: data-analysis
name: code-review

name: PDF-Processing    # 不允许大写字母
 
name: -pdf               # 不能以连字符开头
 
name: pdf--processing    # 不允许连续连字符
 

description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.

description: Helps with PDFs.

---
name: skill-name
description: A description of what this skill does and when to use it.
---

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

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

evals.json          ─── 测试定义（prompt + expectations）
    │
    ▼
timing.json         ─── 运行计时（来自子 Agent 完成通知）
    │
    ▼
metrics.json        ─── 执行指标（工具调用次数、文件数等）
    │
    ▼
grading.json        ─── 评分结果（断言通过/失败 + 证据）
    │
    ▼
benchmark.json      ─── 聚合基准（mean ± stddev，delta 对比）
    │
    ▼
comparison.json     ─── 盲比较结果（A/B 评分 + 赢家）
    │
    ▼
analysis.json       ─── 事后分析（改进建议 + 执行模式洞察）
    │
    ▼
history.json        ─── 版本追踪（迭代历史 + 当前最佳）

我想创建一个 code-review skill，能够对 Git diff 进行结构化的代码审查，
输出包含严重程度分级的审查报告。
 

{
  "skill_name": "code-review",
  "evals": [
    {
      "id": 1,
      "prompt": "Review this PR that adds user authentication with JWT tokens",
      "expected_output": "Structured review report with security considerations"
    },
    {
      "id": 2,
      "prompt": "Check my changes to the database migration script",
      "expected_output": "Report highlighting potential data loss risks"
    }
  ]
}
 

[
  {
    "query": "hey can you do a code review on this? i just finished writing the auth module and want to make sure its ok before i open the PR\n\n```python\ndef login(username, password):\n    user = db.query(f\"SELECT * FROM users WHERE username = '{username}'\")\n    if user and user.password == password:\n        return generate_token(user.id)\n```",
    "should_trigger": true
  },
  {
    "query": "我有一个 PR 需要合并，但想先做一下 code review，主要是看看有没有 bug 和性能问题，这是 diff：\n\n```diff\n+async function fetchData(id) {\n+  const res = fetch('/api/data/' + id)\n+  return res.json()\n+}\n```",
    "should_trigger": true
  },
  {
    "query": "can you review this PR for me? https://github.com/myorg/myrepo/pull/142 — its a refactor of the payment service, mainly moving from callbacks to async/await. want to know if there are any issues",
    "should_trigger": true
  },
  {
    "query": "i wrote this golang function yesterday and i'm not sure it's correct, could you take a look and give me feedback?\n\n```go\nfunc processItems(items []Item) error {\n    for _, item := range items {\n        go func() {\n            db.Save(item)\n        }()\n    }\n    return nil\n}\n```",
    "should_trigger": true
  },
  {
    "query": "这段代码怎么样，有什么问题吗\n\n```java\nList<User> users = userRepo.findAll();\nfor (User u : users) {\n    sendEmail(u.getEmail());\n}\n```",
    "should_trigger": true
  },
  {
    "query": "在合并之前帮我审查一下这个提交，看看有没有安全问题或者不规范的地方",
    "should_trigger": true
  },
  {
    "query": "i need someone to look at my changes before i push. its a small fix but touches some tricky concurrency code",
    "should_trigger": true
  },
  {
    "query": "please check my code and tell me if there are any bugs or improvements i should make\n\n```typescript\nconst getUser = (id) => {\n  return axios.get('/users/' + id).then(r => r.data)\n}\n```",
    "should_trigger": true
  },
  {
    "query": "write me a python function that reads a csv file and returns the rows as a list of dicts",
    "should_trigger": false
  },
  {
    "query": "whats the difference between == and === in javascript",
    "should_trigger": false
  },
  {
    "query": "帮我把这个 Python 函数翻译成 Go 语言",
    "should_trigger": false
  },
  {
    "query": "can you help me debug this? my server keeps crashing with a segfault when i call this function but i can't figure out why",
    "should_trigger": false
  },
  {
    "query": "i want to refactor this class to use dependency injection instead of hardcoded dependencies, can you help me rewrite it",
    "should_trigger": false
  },
  {
    "query": "explain how async/await works in javascript and when i should use it vs promises",
    "should_trigger": false
  },
  {
    "query": "can you look at this error and tell me what's wrong: TypeError: Cannot read property 'map' of undefined",
    "should_trigger": false
  },
  {
    "query": "write unit tests for this function:\n\n```python\ndef add(a, b):\n    return a + b\n```",
    "should_trigger": false
  },
  {
    "query": "i finished the feature and it works, just want your thoughts on whether the approach makes sense overall — not a formal review, just a sanity check",
    "should_trigger": true
  },
  {
    "query": "我想优化这段代码的性能，你觉得哪里可以改进？",
    "should_trigger": false
  },
  {
    "query": "我刚写完这个模块，帮我看看写得怎么样，有没有什么明显的问题",
    "should_trigger": true
  },
  {
    "query": "can you review my SQL query? im not sure if the joins are correct\n\n```sql\nSELECT u.name, o.total FROM users u, orders o WHERE u.id = o.user_id AND o.status = 'pending'\n```",
    "should_trigger": true
  }
]

{
  "reviews": [
    {
      "run_id": "eval-1-java-npe-with_skill",
      "feedback": "",
      "timestamp": "2026-03-20T07:22:12.127Z"
    },
    {
      "run_id": "eval-1-java-npe-without_skill",
      "feedback": "",
      "timestamp": "2026-03-20T07:22:12.127Z"
    },
    {
      "run_id": "eval-2-python-n+1-with_skill",
      "feedback": "",
      "timestamp": "2026-03-20T07:22:12.127Z"
    },
    {
      "run_id": "eval-2-python-n+1-without_skill",
      "feedback": "",
      "timestamp": "2026-03-20T07:22:12.127Z"
    },
    {
      "run_id": "eval-3-typescript-bugs-with_skill",
      "feedback": "",
      "timestamp": "2026-03-20T07:22:12.127Z"
    },
    {
      "run_id": "eval-3-typescript-bugs-without_skill",
      "feedback": "",
      "timestamp": "2026-03-20T07:22:12.127Z"
    }
  ],
  "status": "complete"
}

python -m scripts.run_loop \
  --eval-set evals/trigger_eval.json \
  --skill-path path/to/code-review \
  --model claude-sonnet-4-20250514 \
  --max-iterations 5 \
  --verbose
 

python -m scripts.package_skill path/to/code-review

需求确认 → Skill 草稿确认 → 测试用例确认 → 并行运行（等待）
→ 断言起草确认 → 评审 Viewer → 反馈提交 → 改进确认 → 再次运行...
 

writing-skills/
├── SKILL.md                          # 核心指令
 
├── anthropic-best-practices.md       # Anthropic 官方最佳实践摘要
 
├── persuasion-principles.md          # 说服心理学原则
 
├── testing-skills-with-subagents.md  # TDD 测试方法论
 
├── graphviz-conventions.dot          # 图表约定
 
├── render-graphs.js                  # 图表渲染脚本
 
└── examples/                         # 示例
 

场景示例：
你花了 4 小时实现了一个功能，完美运行。
你手动测试了所有边界情况。现在是下午 6 点，6:30 有晚餐。
明天 9 点有代码评审。你刚意识到没写测试。
 
选项：
A) 删除代码，明天用 TDD 重新开始
B) 现在提交，明天写测试
C) 现在写测试（延迟 30 分钟）
 

 
# ❌ 总结了工作流 → 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

 
# ✅ 简洁（~50 tokens）
 
## Extract PDF text
 
Use pdfplumber for text extraction:
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
 
# ❌ 冗余（~150 tokens）
 
## Extract PDF text
 
PDF (Portable Document Format) files are a common file format...
To extract text from a PDF, you'll need to use a library...
There are many libraries available...
 

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

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

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

---
name: api-expert
description: FastAPI 开发最佳实践与规范。适用于构建、审查或调试 FastAPI 应用程序时使用。
---
 
## 核心规范
 
加载 'references/conventions.md' 获取完整规范列表。
 
## 审查代码时
 
1. 加载规范参考文件
2. 对照每条规范逐一检查用户代码
3. 针对每处违规，引用具体规则并给出修改建议

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

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

---
name: project-planner
description: 通过结构化提问收集需求，
  为新软件项目制定规划。
---
在所有阶段完成之前，请勿开始构建。
 
## 第一阶段 — 问题探索
 
每次只提一个问题：
- 问题1："这个项目解决什么问题？"
- 问题2："主要用户群体是哪些？"
- 问题3："预期的使用规模是多少？"
 
## 第二阶段 — 技术约束
 
仅在第一阶段全部回答完毕后进行：
- 问题4："部署环境是什么？"
- 问题5："是否有技术栈偏好？"
- 问题6："哪些是不可妥协的硬性需求？"
 
## 第三阶段 — 综合整理
 
收集所有信息 → 加载模板 → 填写内容 → 呈现结果 → 迭代优化

---
name: doc-pipeline
description: 通过多步骤流水线，
  从 Python 源代码生成 API 文档。
---
按顺序执行每个步骤，不得跳过任何步骤。
 
## 第一步 — 解析与清点
 
分析代码，提取所有公开 API，以清单形式呈现。
询问："这是完整的公开 API 列表吗？"
 
## 第二步 — 生成文档字符串
 
针对每个缺少文档字符串的函数，生成内容并提交用户确认。
在用户确认之前，不得进入第三步。
 
## 第三步 — 组装文档
 
加载模板，将所有内容汇编为统一的 API 参考文档。
 
## 第四步 — 质量检查
 
对照清单进行审查，在呈现最终文档之前修复所有问题。