// 基于 Google ADK 5大设计模式的 Agent Skill 构建器。 用于从零创建高质量 Skills，或重构/评审现有 Skills。 触发场景： - "创建一个 skill" - "帮我写个 SKILL.md" - "这个 skill 怎么改进" - "如何设计一个 agent skill" - "review/audit/tidy an existing skill" - "哪个模式适合我的场景" - "skill 太复杂了，怎么拆分"
| name | skill-crafter |
| description | 基于 Google ADK 5大设计模式的 Agent Skill 构建器。 用于从零创建高质量 Skills，或重构/评审现有 Skills。 触发场景： - "创建一个 skill" - "帮我写个 SKILL.md" - "这个 skill 怎么改进" - "如何设计一个 agent skill" - "review/audit/tidy an existing skill" - "哪个模式适合我的场景" - "skill 太复杂了，怎么拆分" |
| metadata | {"patterns":["tool-wrapper","generator","reviewer","inversion","pipeline"],"version":"2.0"} |
基于 Google ADK 官方推荐的 5 大设计模式，帮你构建高质量 Agent Skills。
"30+ 工具已统一格式，这件事基本解决了。真正的问题永远是：Skill 内部逻辑怎么设计？" — Google Cloud Tech
不要这样做：
应该这样做：
你需要做什么？
│
├─ 给 Agent 封装某个工具/库的用法？ → Tool Wrapper
│
├─ 批量生成相似结构的内容？ → Generator
│
├─ 需要质量审查/打分/评审？ → Reviewer
│
├─ 目标明确但路径不清晰，要先问用户？ → Inversion
│
└─ 任务复杂，需要分步骤强制执行？ → Pipeline
模式可以组合：Pipeline 可以包含 Reviewer 步骤，Generator 开头可以用 Inversion 收集变量。
核心问题：Agent 需要临时掌握某个特定库的用法，但没有在系统 Prompt 里硬编码。
解决方式：把库的用法说明封装成 Skill，Agent 只在用到时才加载。
什么时候用：
SKILL.md 核心结构：
---
name: xxx-expert
description: xxx技术细节。使用场景：编写/审查/调试 xxx 代码时激活。
metadata:
pattern: tool-wrapper
---
你是 xxx 领域的专家。
## 加载约定
从 'references/conventions.md' 加载完整规范。
## 工作流程
1. 加载 references/conventions.md
2. 按规范执行任务
3. 每个违规都要指出具体规则和修复建议
目录结构：
xxx-expert/
├── SKILL.md
└── references/
└── conventions.md ← 详细规范，按需加载
示例：FastAPI 专家 Skill
# skills/api-expert/SKILL.md
---
name: api-expert
description: FastAPI 开发最佳实践。使用场景：构建、审查、调试 FastAPI 应用时激活。
metadata:
pattern: tool-wrapper
domain: fastapi
---
你是 FastAPI 开发专家。
## 核心约定
从 'references/conventions.md' 加载 FastAPI 最佳实践列表。
## 审查代码时
1. 加载规范参考
2. 检查每条规则的违反情况
3. 引用具体规则 + 给出修复建议
## 编写代码时
1. 加载规范参考
2. 严格遵循所有约定
3. 所有函数签名加类型注解
4. 使用 Annotated 风格做依赖注入
核心问题：Agent 每次生成的内容结构不一致，输出不可预测。
解决方式：用模板 + 变量填充，保证每次输出结构相同。
什么时候用：
SKILL.md 核心结构：
---
name: xxx-generator
description: 生成结构化文档。使用场景：用户要求写/创建/起草报告时激活。
metadata:
pattern: generator
---
按步骤执行，不要跳过任何步骤。
Step 1: 加载 'references/style-guide.md'（语气和格式规则）
Step 2: 加载 'assets/template.md'（输出模板）
Step 3: 询问用户缺失的变量
Step 4: 按规则填充模板
Step 5: 返回完成的文档
目录结构：
xxx-generator/
├── SKILL.md
├── references/
│ └── style-guide.md ← 风格指南
└── assets/
└── template.md ← 输出模板
示例：技术报告生成器
# skills/report-generator/SKILL.md
---
name: report-generator
description: 生成结构化技术报告。使用场景：用户要求写报告、摘要、分析文档时激活。
metadata:
pattern: generator
---
你是技术报告生成器。严格按步骤执行：
Step 1: 加载 'references/style-guide.md' 获取语气和格式规则
Step 2: 加载 'assets/report-template.md' 获取输出结构
Step 3: 询问用户缺失信息：
- 主题是什么
- 关键发现或数据点
- 目标读者（技术/高管/通用）
Step 4: 按风格规则填充模板，每个章节都必须存在
Step 5: 返回完整 Markdown 报告
核心问题：评审逻辑和执行逻辑混在一起，难以复用不同的评审标准。
解决方式：把检查什么（规则）和怎么检查（流程）分开，规则存在外部文件里。
什么时候用：
SKILL.md 核心结构：
---
name: xxx-reviewer
description: 评审 xxx 代码/内容。使用场景：用户提交代码求 review 时激活。
metadata:
pattern: reviewer
severity-levels: error,warning,info
---
你是 xxx 评审专家。
Step 1: 加载 'references/checklist.md'（评审标准）
Step 2: 理解代码意图
Step 3: 应用每条规则，输出：
- 违规位置（行号或大致位置）
- 严重程度：error / warning / info
- 解释"为什么是问题"
- 具体修复建议（含修复代码）
Step 4: 结构化输出：
- Summary（总体评价）
- Findings（按严重程度分组）
- Score（1-10分）
- Top 3 Recommendations
目录结构：
xxx-reviewer/
├── SKILL.md
└── references/
└── checklist.md ← 可替换的评审标准
关键思想：换一份 checklist = 换一个专业领域，同一套基础设施完全复用。
示例：Python 代码评审器
# skills/code-reviewer/SKILL.md
---
name: code-reviewer
description: 评审 Python 代码质量、风格和常见 bug。使用场景：用户提交代码求反馈或审计时激活。
metadata:
pattern: reviewer
severity-levels: error,warning,info
---
你是 Python 代码评审专家。严格执行以下协议：
Step 1: 加载 'references/review-checklist.md' 获取完整评审标准
Step 2: 仔细阅读代码，理解其目的后再批判
Step 3: 对每条违规：
- 记录行号或大致位置
- 分类严重程度：error（必须修）/ warning（应该修）/ info（考虑修）
- 解释"为什么"是问题，不只是"什么"是问题
- 给出具体修复建议和修复后的代码
Step 4: 结构化输出：
- **Summary**：代码做什么，整体质量评估
- **Findings**：按严重程度分组（error → warning → info）
- **Score**：1-10分并简述理由
- **Top 3 Recommendations**：最有价值的改进建议
核心问题：Agent 收到模糊需求就急着开始做，做完才发现不匹配用户期望。
解决方式：Agent 先当面试官，逐阶段收集信息，全部完成前不开始构建。
什么时候用：
SKILL.md 核心结构：
---
name: xxx-planner
description: 项目规划技能。使用场景：用户说"我要做 xxx"、"帮我规划"、"设计一个系统"时激活。
metadata:
pattern: inversion
interaction: multi-turn
---
你是结构化需求访谈者。
⚠️ 严格规则：在所有阶段完成前，**不要开始构建或设计**。
## Phase 1 — 问题发现（一次问一个问题，等待回答）
- Q1: 这个项目为用户解决什么问题？
- Q2: 谁是主要用户？技术背景如何？
- Q3: 预期规模？（日活/数据量/请求量）
## Phase 2 — 技术约束（Phase 1 全部回答后才开始）
- Q4: 部署环境是什么？
- Q5: 有技术栈偏好吗？
- Q6: 有哪些硬性要求？（延迟/可用性/合规/预算）
## Phase 3 — 综合（所有问题回答后才执行）
1. 加载 'assets/plan-template.md'
2. 用收集到的需求填充模板每个章节
3. 呈现完整计划给用户
4. 询问："这个计划准确捕捉你的需求了吗？有什么要改的？"
5. 根据反馈迭代，直到用户确认
核心问题：复杂任务被塞进一个 Skill，Agent 跳过步骤或漏掉检查点。
解决方式：显式定义步骤顺序 + 硬性门控条件（需要用户确认才能进入下一步）。
什么时候用：
SKILL.md 核心结构：
---
name: xxx-pipeline
description: 多步骤流水线。使用场景：用户要求处理 xxx 复杂任务时激活。
metadata:
pattern: pipeline
steps: "N"
---
你是流水线执行器。严格按顺序执行每一步，**不要跳过步骤**，某步失败则停止。
## Step 1 — [名称]
[具体操作]
⚠️ 门控：[用户确认条件]
## Step 2 — [名称]
[具体操作]
⚠️ 门控：[用户确认条件]
## Step N — [名称]
[具体操作]
关键要素：
示例：API 文档生成流水线
# skills/doc-pipeline/SKILL.md
---
name: doc-pipeline
description: 通过多步骤流水线生成 API 文档。使用场景：用户要求为模块生成文档、创建 API docs 时激活。
metadata:
pattern: pipeline
steps: "4"
---
你是文档生成流水线。严格按顺序执行，不要跳过步骤或跳过失败。
## Step 1 — 解析 & 清点
分析用户的 Python 代码，提取所有公共类、函数和常量。
以检查清单形式呈现清单。
询问："这是你想文档化的完整公共 API 吗？"
## Step 2 — 生成 Docstrings
对每个缺少 docstring 的函数：
- 加载 'references/docstring-style.md' 获取所需格式
- 按风格指南生成 docstring
- 呈现每个生成的 docstring 供用户确认
⚠️ 在用户确认 Step 2 之前，**不要进入 Step 3**。
## Step 3 — 组装文档
加载 'assets/api-doc-template.md' 获取输出结构。
将所有类、函数和 docstrings 编译成单一 API 参考文档。
## Step 4 — 质量检查
对照 'references/quality-checklist.md' 审查：
- 每个公共符号都有文档
- 每个参数有类型和描述
- 每个函数至少有一个使用示例
报告结果。呈现最终文档前修复问题。
如果现有 Skill 存在以下问题，用对应模式重构：
| 问题症状 | 推荐模式 | 重构方向 |
|---|---|---|
| Skill 太长，塞了太多指令 | 按 Pipeline 拆分步骤 | 拆成多步，每步独立 |
| 输出格式每次不一致 | 改成 Generator | 加模板 + 变量填充 |
| 评审逻辑和执行逻辑混在一起 | 改成 Reviewer | 把 checklist 拆到 references/ |
| Agent 不问清楚就开始做 | 改成 Inversion | 加阶段化提问流程 |
| 只是封装一个工具的用法 | 改成 Tool Wrapper | 精简 + references/ 做详细规范 |
# 创建 Skill 目录结构
mkdir -p skills/your-skill/{references,assets,scripts}
name + description（description 要写清楚什么时候触发）□ description 清楚描述了触发场景
□ 使用了正确的模式结构
□ references/ 内容只在需要时加载（SKILL.md 不重复）
□ 严重程度用 error/warning/info 分级（如果是 Reviewer）
□ Pipeline 有显式门控条件
□ Inversion 在所有阶段完成前不允许构建
□ 目录结构符合规范（SKILL.md 在根目录）
| 文件 | 何时加载 |
|---|---|
references/workflows.md | 需要多步工作流参考时 |
references/output-patterns.md | 需要输出模板和格式参考时 |
references/checklist-examples.md | 设计 Reviewer 评审标准时 |
references/pattern-selection.md | 不确定该用哪个模式时 |