skill-crafter

Skill Crafter

Based on the 5 major design patternsofficially recommended by Google ADK, helping you build high-quality Agent Skills.

Core idea: format is already solved, content design is the key

"30+ tools have unified formats; this problem is basically solved. The real question is always: how should the internal logic of a Skill be designed?" — Google Cloud Tech

Don't do this：

❌ Obsess over whether YAML fields are complete
❌ Get bogged down in whether the directory structure is standardized
❌ Copy and paste format templates

Do this instead：

✅ First figure out what problem this Skill solves
✅ Choose the rightdesign pattern
✅ Use the pattern to guide the content design of SKILL.md

Decision tree: which pattern suits you?

你需要做什么？
│
├─ 给 Agent 封装某个工具/库的用法？     → Tool Wrapper
│
├─ 批量生成相似结构的内容？             → Generator
│
├─ 需要质量审查/打分/评审？            → Reviewer
│
├─ 目标明确但路径不清晰，要先问用户？   → Inversion
│
└─ 任务复杂，需要分步骤强制执行？       → Pipeline

Patterns can be combined: A Pipeline can include a Reviewer step, and a Generator can use Inversion at the beginning to collect variables.

Pattern details

1️⃣ Tool Wrapper | Tool Wrapper

Core problem: The Agent needs to temporarily master the usage of a specific library, but it is not hard-coded in the system prompt.

Solution: Encapsulate the library's usage instructions into a Skill, and the Agent only loads it when needed。

When to use：

Encapsulate the company's internal coding standards
Encapsulate the best practices of a framework/library
Need the Agent to precisely follow a tool's conventions

SKILL.md core structure：

---
name: xxx-expert
description: xxx技术细节。使用场景：编写/审查/调试 xxx 代码时激活。
metadata:
  pattern: tool-wrapper
---

你是 xxx 领域的专家。

## 加载约定
从 'references/conventions.md' 加载完整规范。

## 工作流程
1. 加载 references/conventions.md
2. 按规范执行任务
3. 每个违规都要指出具体规则和修复建议

Directory structure：

xxx-expert/
├── SKILL.md
└── references/
    └── conventions.md   ← 详细规范，按需加载

Example: FastAPI expert 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 | Generator

Core problem: The content generated by the Agent each time has an inconsistent structure, and the output is unpredictable.

Solution: Use templates + variable filling to ensure the output structure is the same every time.

When to use：

Generate PRDs / technical reports / documents
Batch-generate test cases
Standardize output formats

SKILL.md core structure：

---
name: xxx-generator
description: 生成结构化文档。使用场景：用户要求写/创建/起草报告时激活。
metadata:
  pattern: generator
---

按步骤执行，不要跳过任何步骤。

Step 1: 加载 'references/style-guide.md'（语气和格式规则）
Step 2: 加载 'assets/template.md'（输出模板）
Step 3: 询问用户缺失的变量
Step 4: 按规则填充模板
Step 5: 返回完成的文档

Directory structure：

xxx-generator/
├── SKILL.md
├── references/
│   └── style-guide.md   ← 风格指南
└── assets/
    └── template.md      ← 输出模板

Example: Technical report generator

# 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 | Reviewer

Core problem: Review logic and execution logic are mixed together, making it difficult to reuse different review standards.

Solution: Separatewhat to check(rules) fromhow to check(process), and store the rules in external files.

When to use：

Code review
Content quality review
Security audit
Automated PR review

SKILL.md core structure：

---
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

Directory structure：

xxx-reviewer/
├── SKILL.md
└── references/
    └── checklist.md   ← 可替换的评审标准

Key idea: Swap in a different checklist = switch to a different professional domain, while the same infrastructure is fully reused.

Example: Python code reviewer

# 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 | Reverse-inquiry mode

Core problem: The Agent rushes to start as soon as it receives a vague requirement, and only after finishing does it realize the result doesn't match the user's expectations.

Solution: The Agent acts as an interviewer first,collecting information stage by stage, and does not start building until all of it is complete.

When to use：

Project planning
New feature design
System architecture discussions
Any scenario where "requirements must be understood before starting work"

Core structure of 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 | Assembly line

Core problem: A complex task gets crammed into a single Skill, and the Agent skips steps or misses checkpoints.

Solution: Explicitly define the order of steps + hard gating conditions (user confirmation is required to proceed to the next step).

When to use：

Multi-stage document generation (parse → write docstring → assemble → check)
Complex system construction (research → design → implement → test)
Any process where steps cannot be skipped

Core structure of SKILL.md：

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

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

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

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

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

Key elements：

Explicit gating conditions (user confirmation is required to proceed to the next step)
Different steps load different reference files (to keep the context clean)
Skipping or parallelizing is not allowed

Example: API documentation generation pipeline

# 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' 审查：
- 每个公共符号都有文档
- 每个参数有类型和描述
- 每个函数至少有一个使用示例
报告结果。呈现最终文档前修复问题。

Guide to refactoring existing Skills

If an existing Skill has the following problems, refactor it using the corresponding pattern:

Problem symptom	Recommended pattern	Refactoring direction
The Skill is too long and stuffed with too many instructions	Split the steps according to Pipeline	Split into multiple steps, each independent
The output format is inconsistent every time	Change it to Generator	Add templates + variable filling
Review logic and execution logic are mixed together	Change it to Reviewer	Split the checklist into references/
The Agent starts working without asking clearly	Change it to Inversion	Add a staged questioning process
It merely encapsulates the usage of a tool	Change it to Tool Wrapper	Streamline it + use references/ for detailed specifications

Standard process for creating a new Skill

Step 1: Clarify the scenario

How will users trigger this Skill? (trigger words)
What is its core function?
What is the expected output?

Step 2: Choose the right pattern

Refer to the decision tree above
Consider whether patterns can be combined

Step 3: Initialize

# 创建 Skill 目录结构
mkdir -p skills/your-skill/{references,assets,scripts}

Step 4: Write SKILL.md

Frontmatter：name + description(The description must clearly statewhen it is triggered）
Body: the standard structure corresponding to the pattern
metadata: note the pattern used

Step 5: Add references/ (as needed)

Do not pile up details in SKILL.md
Put detailed rules in references/, and in SKILL.md only write "when to load which file"

Step 6: Verification checklist

□ description 清楚描述了触发场景
□ 使用了正确的模式结构
□ references/ 内容只在需要时加载（SKILL.md 不重复）
□ 严重程度用 error/warning/info 分级（如果是 Reviewer）
□ Pipeline 有显式门控条件
□ Inversion 在所有阶段完成前不允许构建
□ 目录结构符合规范（SKILL.md 在根目录）

Reference file index

File	When to load
`references/workflows.md`	When a multi-step workflow reference is needed
`references/output-patterns.md`	When output templates and formatting references are needed
`references/checklist-examples.md`	When designing Reviewer review criteria
`references/pattern-selection.md`	When unsure which pattern to use

About this skill

Core idea: format is already solved, content design is the key

Decision tree: which pattern suits you?

Pattern details

1️⃣ Tool Wrapper | Tool Wrapper

2️⃣ Generator | Generator

3️⃣ Reviewer | Reviewer

4️⃣ Inversion | Reverse-inquiry mode

5️⃣ Pipeline | Assembly line

Guide to refactoring existing Skills

Standard process for creating a new Skill

Step 1: Clarify the scenario

Step 2: Choose the right pattern

Step 3: Initialize

Step 4: Write SKILL.md

Step 5: Add references/ (as needed)

Step 6: Verification checklist

Reference file index