| 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"} |
Skill Crafter
基于 Google ADK 官方推荐的 5 大设计模式，帮你构建高质量 Agent Skills。
核心理念：格式已解决，内容设计才是关键
"30+ 工具已统一格式，这件事基本解决了。真正的问题永远是：Skill 内部逻辑怎么设计？"
— Google Cloud Tech
不要这样做：
- ❌ 死磕 YAML 字段是否完整
- ❌ 纠结目录结构是否规范
- ❌ 复制粘贴格式模板
应该这样做：
- ✅ 先想清楚这个 Skill 解决什么问题
- ✅ 选对正确的设计模式
- ✅ 用模式指导 SKILL.md 的内容设计
决策树：哪个模式适合你？
你需要做什么？
│
├─ 给 Agent 封装某个工具/库的用法？ → Tool Wrapper
│
├─ 批量生成相似结构的内容？ → Generator
│
├─ 需要质量审查/打分/评审？ → Reviewer
│
├─ 目标明确但路径不清晰，要先问用户？ → Inversion
│
└─ 任务复杂，需要分步骤强制执行？ → Pipeline
模式可以组合：Pipeline 可以包含 Reviewer 步骤，Generator 开头可以用 Inversion 收集变量。
模式详解
1️⃣ Tool Wrapper｜工具包装器
核心问题：Agent 需要临时掌握某个特定库的用法，但没有在系统 Prompt 里硬编码。
解决方式：把库的用法说明封装成 Skill，Agent 只在用到时才加载。
什么时候用：
- 封装公司内部编码规范
- 封装某个框架/库的 best practices
- 需要让 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
---
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 风格做依赖注入
2️⃣ Generator｜生成器
核心问题：Agent 每次生成的内容结构不一致，输出不可预测。
解决方式：用模板 + 变量填充，保证每次输出结构相同。
什么时候用：
- 生成 PRD / 技术报告 / 文档
- 批量生成测试用例
- 标准化输出格式
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 ← 输出模板
示例：技术报告生成器
---
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 报告
3️⃣ Reviewer｜评审器
核心问题：评审逻辑和执行逻辑混在一起，难以复用不同的评审标准。
解决方式：把检查什么（规则）和怎么检查（流程）分开，规则存在外部文件里。
什么时候用：
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 代码评审器
---
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**：最有价值的改进建议
4️⃣ Inversion｜逆推模式
核心问题：Agent 收到模糊需求就急着开始做，做完才发现不匹配用户期望。
解决方式：Agent 先当面试官，逐阶段收集信息，全部完成前不开始构建。
什么时候用：
- 项目规划
- 新功能设计
- 系统架构讨论
- 任何"动手前需要先理解需求"的场景
SKILL.md 核心结构：
---
name: xxx-planner
description: 项目规划技能。使用场景：用户说"我要做 xxx"、"帮我规划"、"设计一个系统"时激活。
metadata:
pattern: inversion
interaction: multi-turn
---
你是结构化需求访谈者。
⚠️ 严格规则：在所有阶段完成前，**不要开始构建或设计**。
- Q1: 这个项目为用户解决什么问题？
- Q2: 谁是主要用户？技术背景如何？
- Q3: 预期规模？（日活/数据量/请求量）
- Q4: 部署环境是什么？
- Q5: 有技术栈偏好吗？
- Q6: 有哪些硬性要求？（延迟/可用性/合规/预算）
1. 加载 'assets/plan-template.md'
2. 用收集到的需求填充模板每个章节
3. 呈现完整计划给用户
4. 询问："这个计划准确捕捉你的需求了吗？有什么要改的？"
5. 根据反馈迭代，直到用户确认
5️⃣ Pipeline｜流水线
核心问题：复杂任务被塞进一个 Skill，Agent 跳过步骤或漏掉检查点。
解决方式：显式定义步骤顺序 + 硬性门控条件（需要用户确认才能进入下一步）。
什么时候用：
- 多阶段文档生成（解析 → 写 docstring → 组装 → 检查）
- 复杂系统构建（调研 → 设计 → 实现 → 测试）
- 任何不能跳步的流程
SKILL.md 核心结构：
---
name: xxx-pipeline
description: 多步骤流水线。使用场景：用户要求处理 xxx 复杂任务时激活。
metadata:
pattern: pipeline
steps: "N"
---
你是流水线执行器。严格按顺序执行每一步，**不要跳过步骤**，某步失败则停止。
[具体操作]
⚠️ 门控：[用户确认条件]
[具体操作]
⚠️ 门控：[用户确认条件]
[具体操作]
关键要素：
- 显式门控条件（必须用户确认才能进入下一步）
- 不同步骤加载不同的 reference 文件（保持 context 干净）
- 不允许跳过或并行
示例：API 文档生成流水线
---
name: doc-pipeline
description: 通过多步骤流水线生成 API 文档。使用场景：用户要求为模块生成文档、创建 API docs 时激活。
metadata:
pattern: pipeline
steps: "4"
---
你是文档生成流水线。严格按顺序执行，不要跳过步骤或跳过失败。
分析用户的 Python 代码，提取所有公共类、函数和常量。
以检查清单形式呈现清单。
询问："这是你想文档化的完整公共 API 吗？"
对每个缺少 docstring 的函数：
- 加载 'references/docstring-style.md' 获取所需格式
- 按风格指南生成 docstring
- 呈现每个生成的 docstring 供用户确认
⚠️ 在用户确认 Step 2 之前，**不要进入 Step 3**。
加载 'assets/api-doc-template.md' 获取输出结构。
将所有类、函数和 docstrings 编译成单一
现有 Skill 重构指南
如果现有 Skill 存在以下问题，用对应模式重构：
| 问题症状 | 推荐模式 | 重构方向 |
|---|
| Skill 太长，塞了太多指令 | 按 Pipeline 拆分步骤 | 拆成多步，每步独立 |
| 输出格式每次不一致 | 改成 Generator | 加模板 + 变量填充 |
| 评审逻辑和执行逻辑混在一起 | 改成 Reviewer | 把 checklist 拆到 references/ |
| Agent 不问清楚就开始做 | 改成 Inversion | 加阶段化提问流程 |
| 只是封装一个工具的用法 | 改成 Tool Wrapper | 精简 + references/ 做详细规范 |
创建新 Skill 的标准流程
Step 1：明确场景
- 用户会怎么触发这个 Skill？（触发词）
- 它的核心功能是什么？
- 预期输出是什么？
Step 2：选对模式
Step 3：初始化
mkdir -p skills/your-skill/{references,assets,scripts}
Step 4：编写 SKILL.md
- Frontmatter：
name + description（description 要写清楚什么时候触发）
- Body：模式对应的标准结构
- metadata：标注使用的 pattern
Step 5：补充 references/（按需）
- 不要在 SKILL.md 里堆细节
- 详细规则放在 references/，SKILL.md 只写"何时加载哪个文件"
Step 6：验证清单
□ 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 | 不确定该用哪个模式时 |
