skill-crafter

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

# 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 风格做依赖注入

---

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      ← 输出模板

示例：技术报告生成器

# 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 报告

---

3️⃣ Reviewer｜评审器

核心问题：评审逻辑和执行逻辑混在一起，难以复用不同的评审标准。

解决方式：把检查什么（规则）和怎么检查（流程）分开，规则存在外部文件里。

什么时候用：

• 代码审查
• 内容质量评审
• 安全审计
• PR 自动审查

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**：最有价值的改进建议

---

4️⃣ Inversion｜逆推模式

核心问题：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. 根据反馈迭代，直到用户确认

---

5️⃣ Pipeline｜流水线

核心问题：复杂任务被塞进一个 Skill，Agent 跳过步骤或漏掉检查点。

解决方式：显式定义步骤顺序 + 硬性门控条件（需要用户确认才能进入下一步）。

什么时候用：

• 多阶段文档生成（解析 → 写 docstring → 组装 → 检查）
• 复杂系统构建（调研 → 设计 → 实现 → 测试）
• 任何不能跳步的流程

SKILL.md 核心结构：

---
name: xxx-pipeline
description: 多步骤流水线。使用场景：用户要求处理 xxx 复杂任务时激活。
metadata:
  pattern: pipeline
  steps: "N"
---

你是流水线执行器。严格按顺序执行每一步，**不要跳过步骤**，某步失败则停止。

## Step 1 — [名称]
[具体操作]
⚠️ 门控：[用户确认条件]

## Step 2 — [名称]
[具体操作]
⚠️ 门控：[用户确认条件]

## Step N — [名称]
[具体操作]

关键要素：

• 显式门控条件（必须用户确认才能进入下一步）
• 不同步骤加载不同的 reference 文件（保持 context 干净）
• 不允许跳过或并行

示例：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 存在以下问题，用对应模式重构：

问题症状	推荐模式	重构方向
Skill 太长，塞了太多指令	按 Pipeline 拆分步骤	拆成多步，每步独立
输出格式每次不一致	改成 Generator	加模板 + 变量填充
评审逻辑和执行逻辑混在一起	改成 Reviewer	把 checklist 拆到 references/
Agent 不问清楚就开始做	改成 Inversion	加阶段化提问流程
只是封装一个工具的用法	改成 Tool Wrapper	精简 + references/ 做详细规范

---

创建新 Skill 的标准流程

Step 1：明确场景

• 用户会怎么触发这个 Skill？（触发词）
• 它的核心功能是什么？
• 预期输出是什么？

Step 2：选对模式

• 参考上方决策树
• 考虑是否可以组合模式

Step 3：初始化

# 创建 Skill 目录结构
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	不确定该用哪个模式时