---
name: skill-designer
description: 教你怎么设计高质量 SKILL.md 内容的 skill。当用户要创建新 skill 时自动触发。
---

# Agent Skill Designer

一个教你怎么设计高质量SKILL.md内容的skill。当用户要创建新skill时自动触发。

## 核心概念

SKILL.md的格式已经标准化了，但**内容设计**才是难点。同样的skill，用不同模式组织，效果天差地别。

**5种设计模式**：

| 模式 | 核心作用 | 何时用 |
|------|---------|--------|
| Tool Wrapper | 让AI临时变成某个库的专家 | 传递框架/库的规范和使用惯例 |
| Generator | 按固定模板生成结构化文档 | 生成固定格式的输出物 |
| Reviewer | 按检查清单评分/审查 | 评审、审计、打分 |
| Inversion | AI先问你，再决定怎么做 | 需求不明确、需要引导 |
| Pipeline | 强制按步骤执行，有检查点 | 复杂任务、不能跳过步骤 |


## 第一步：判断用哪种模式

回答3个问题，快速定位：

**Q1: 这个skill是要产生一个固定的文档/代码结构吗？**
- 是 → Generator
- 否 ↓

**Q2: 这个skill需要先收集用户信息才能工作吗？**
- 是 → Inversion
- 否 ↓

**Q3: 这个skill需要分步骤执行、不能跳过吗？**
- 是 → Pipeline
- 否 ↓

**Q4: 这个skill是让AI"学习"某个库的用法吗？**
- 是 → Tool Wrapper
- 否 ↓

**兜底**: Reviewer（默认模式）


## 第二步：按模式写SKILL.md

### Pattern 1: Tool Wrapper

**适用场景**：让AI在遇到特定技术栈时，自动加载最佳实践

**核心结构**：
```markdown
## 核心规范
读取 'references/conventions.md' 获取完整规范

## 写作时
1. 加载规范文件
2. 严格遵守每一条规则
3. 为所有函数签名添加类型注解

## 审查时
1. 加载规范文件
2. 对照检查每一条
3. 对每个违规，引用具体规则并给出修复建议
```

**关键点**：
- 规范文件独立存放（`references/`）
- 只在真正需要时才加载（渐进式披露）
- 规则要具体、可执行


### Pattern 2: Generator

**适用场景**：生成结构一致的文件（报告、文档、代码模板）

**核心结构**：
```markdown
## 工作流程

Step 1: 加载样式指南
读取 'references/style-guide.md'

Step 2: 加载输出模板
读取 'assets/output-template.md'

Step 3: 询问缺失信息
向用户收集模板中缺失的变量：
- 主题是什么？
- 关键数据点？
- 目标读者？

Step 4: 填充模板
严格按照样式指南的规则填充每个section

Step 5: 输出
返回完整的Markdown文档
```

**关键点**：
- 模板和样式指南独立（`assets/` + `references/`）
- 必须向用户收集缺失变量
- 输出格式固定，不可自定义


### Pattern 3: Reviewer

**适用场景**：代码审查、质量审计、安全检查

**核心结构**：
```markdown
## 审查协议

Step 1: 加载检查清单
读取 'references/review-checklist.md'

Step 2: 理解代码
先读懂代码的目的，再开始批评

Step 3: 逐项检查
对每个违规项：
- 记录位置（行号或大概位置）
- 分类 severity：error / warning / info
- 解释为什么是问题
- 给出具体修复代码

Step 4: 输出结构化报告
- Summary：代码做什么、总体评价
- Findings：按 severity 分组
- Score：1-10分，简短理由
- Top 3 Recommendations：最有价值的改进
```

**关键点**：
- 检查清单独立（可替换）
- 按 severity 分组输出
- 每个问题要解释"为什么"而不只是"是什么"


### Pattern 4: Inversion

**适用场景**：需求不明确、需要AI引导用户思考

**核心结构**：
```markdown
## 采访式交互

你是主持人。**不要**在收集完所有信息前开始构建。

### Phase 1 — 问题发现（一次问一个，等回答）

Q1: 这个项目为用户解决什么问题？
Q2: 主要用户是谁？技术水平如何？
Q3: 预期规模？（日活、数据量、请求量）

### Phase 2 — 技术约束（仅在Phase 1完成后再问）

Q4: 部署环境是什么？
Q5: 技术栈有什么偏好或限制？
Q6: 有什么硬性要求？（延迟、可用性、合规、预算）

### Phase 3 — 整合（仅在所有问题回答后才执行）

1. 加载输出格式模板
2. 用收集的信息填充每个section
3. 呈现完整方案
4. 询问："这个方案准确吗？有什么要改的？"
5. 根据反馈迭代，直到用户确认
```

**关键点**：
- **必须显式声明"Do NOT start building until..."**
- 严格按phase顺序，一次只问一个问题
- 所有问题回答完才能进入合成阶段


### Pattern 5: Pipeline

**适用场景**：复杂任务，必须按顺序执行、中间有检查点

**核心结构**：
```markdown
## 执行流程（不可跳过步骤）

### Step 1 — 解析 & 盘点
分析代码，提取所有公开的类、函数、常量
列出清单，询问："这是你想文档化的完整API吗？"

### Step 2 — 生成文档字符串（Gate: 必须用户确认后才能进入Step 3）
对每个缺少文档的函数：
- 加载 'references/docstring-style.md'
- 按规范生成文档字符串
- 展示给用户审批

### Step 3 — 组装文档
加载 'assets/api-doc-template.md'
将所有类、函数、文档字符串编译成完整API参考文档

### Step 4 — 质量检查
对照 'references/quality-checklist.md' 检查：
- 每个公开符号都有文档
- 每个参数都有类型和描述
- 每个函数至少一个使用示例
修复问题后再呈现最终文档
```

**关键点**：
- 显式的Gate条件（如"必须用户确认后才能进入Step 3"）
- 每步失败则整个pipeline停止
- 可以在Pipeline里嵌套Reviewer（自检）


## 第三步：组合模式

这些模式不是互斥的，可以组合：

| 组合方式 | 适用场景 |
|---------|---------|
| Pipeline + Reviewer | Pipeline末尾加自检步骤 |
| Generator + Inversion | 先收集变量，再填充模板 |
| Tool Wrapper + Reviewer | 学习规范后进行审查 |


## 快速参考

```
我想要...              → 用什么模式
─────────────────────────────────────
让AI学习某框架规范    → Tool Wrapper
生成固定格式的文档    → Generator
代码审查/质量审计     → Reviewer
先问需求再行动        → Inversion
强制按步骤执行        → Pipeline
```


## 常见错误

**错误1**: 把所有规则直接塞进SKILL.md
```markdown
# ❌ 错误 - 规则太多，AI记不住
## 规则1: xxx
## 规则2: xxx
## 规则3: xxx
...（50条规则）
```

```markdown
# ✅ 正确 - 外部引用，按需加载
## 规则
读取 'references/coding-conventions.md' 获取完整规则列表
```

**错误2**: 模式选择错误
- 需要生成结构化文档，却用了Reviewer
- 需要引导需求，却直接开始写代码

**错误3**: 缺少Gate条件
- Pipeline没有检查点，AI跳步
- Inversion没有"Do NOT start"声明，AI直接开始构建


## 参考资源

详细示例和ADK代码参考：
- `references/tool-wrapper-example.md` - FastAPI专家skill示例
- `references/generator-example.md` - 技术报告生成器示例
- `references/reviewer-example.md` - 代码审查员示例
- `references/inversion-example.md` - 项目规划师示例
- `references/pipeline-example.md` - 文档流水线示例
- `references/decision-tree.md` - 模式选择决策树