# Skill Crafter

> 基于 Google ADK 5大设计模式的 Agent Skill 构建器。 用于从零创建高质量 Skills，或重构/评审现有 Skills。 触发场景： - "创建一个 skill" - "帮我写个 SKILL.md" - "这个 skill 怎么改进" - "如何设计一个 agent skill" - "review/audit/tidy an existing skill" - "哪个模式适合我的场景" - "skill 太复杂了，怎么拆分"

- Skill: `zhanlincui/skill-crafter` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add zhanlincui/skill-crafter`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zhanlincui/skill-crafter/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: ZhanlinCui (https://skillmd.com/u/zhanlincui)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zhanlincui/skill-crafter

---


# 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 核心结构**：
```yaml
---
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
```yaml
# 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 核心结构**：
```yaml
---
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      ← 输出模板
```

**示例**：技术报告生成器
```yaml
# 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 核心结构**：
```yaml
---
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 代码评审器
```yaml
# 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 核心结构**：
```yaml
---
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 核心结构**：
```yaml
---
name: xxx-pipeline
description: 多步骤流水线。使用场景：用户要求处理 xxx 复杂任务时激活。
metadata:
  pattern: pipeline
  steps: "N"
---

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

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

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

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

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

**示例**：API 文档生成流水线
```yaml
# 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：初始化
```bash
# 创建 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` | 不确定该用哪个模式时 |