Appearance
5种SKILL.md设计模式:从Tool Wrapper到Pipeline的实战指南
规范只告诉你Skill怎么打包,但里面的逻辑怎么组织?完全没说。一个封装FastAPI规范的skill,跟一个四步文档流水线,运行逻辑差了十万八千里,但SKILL.md文件看起来一模一样。看完整个生态圈,发现大家都在用这5种设计模式。
写SKILL.md的时候,很多人会卡在格式上:YAML怎么写、目录怎么建、规范怎么跟。但其实30多个agent工具(Claude Code、Gemini CLI、Cursor……)都已经统一了布局,格式这事基本不用操心了。
真正头疼的,是内容怎么设计。
规范只告诉你skill怎么打包,但里面的逻辑怎么组织?完全没说。一个封装FastAPI规范的skill,跟一个四步文档流水线,运行逻辑差了十万八千里,但SKILL.md文件看起来一模一样。
看完整个生态圈,从Anthropic的仓库到Vercel和Google的内部指南,发现大家都在用这5种设计模式:
- Tool Wrapper:让agent瞬间成为任何库的专家
- Generator:按模板产出结构化文档
- Reviewer:按严重程度给代码打分
- Inversion:agent先采访你,再动手
- Pipeline:带检查点的多步工作流
模式1:Tool Wrapper
Tool Wrapper的作用很简单:让你的agent随时能拿到特定库的上下文。
不用把API规范硬塞进系统提示词,打包成skill就行。agent只有真正用到这个技术时,才会加载这些上下文。
这是最容易实现的模式。SKILL.md监听用户提示词里的关键词,动态加载references/目录里的文档,把这些规则当"绝对真理"用。比如用户提到FastAPI,skill才会加载相关规范,平时不占上下文。团队内部的编码规范、框架的最佳实践,都可以这样直接注入到开发者工作流里。
举个例子,这个Tool Wrapper教agent怎么写FastAPI:
yaml
# skills/api-expert/SKILL.md
---
name: api-expert
description: FastAPI development best practices and conventions. Use when building, reviewing, or debugging FastAPI applications, REST APIs, or Pydantic models.
metadata:
pattern: tool-wrapper
domain: fastapi
---markdown
You are an expert in FastAPI development. Apply these conventions to the user's code or question.
## Core Conventions
Load 'references/conventions.md' for the complete list of FastAPI best practices.
## When Reviewing Code
1. Load the conventions reference
2. Check the user's code against each convention
3. For each violation, cite the specific rule and suggest the fix
## When Writing Code
1. Load the conventions reference
2. Follow every convention exactly
3. Add type annotations to all function signatures
4. Use Annotated style for dependency injection注意看,指令明确说了:只在审查或编写代码时才加载conventions.md。不相关的时候,别占着上下文。
模式2:Generator
Tool Wrapper是"注入知识",Generator是"管住输出"。
被agent每次生成的东西都不一样困扰过?Generator能帮你——说白了就是一个填空流程。
它用两个目录:assets/放输出模板,references/放风格指南。指令就像项目经理:加载模板→读风格指南→问用户要缺失的信息→填进去。API文档、commit message、项目架构……都可以这么搞。
这个技术报告生成器的例子,skill文件里没有实际的布局或语法规则,只是协调资源、强制按步骤执行:
yaml
# skills/report-generator/SKILL.md
---
name: report-generator
description: Generates structured technical reports in Markdown. Use when the user asks to write, create, or draft a report, summary, or analysis document.
metadata:
pattern: generator
output-format: markdown
---markdown
You are a technical report generator. Follow these steps exactly:
Step 1: Load 'references/style-guide.md' for tone and formatting rules.
Step 2: Load 'assets/report-template.md' for the required output structure.
Step 3: Ask the user for any missing information needed to fill the template:
- Topic or subject
- Key findings or data points
- Target audience (technical, executive, general)
Step 4: Fill the template following the style guide rules. Every section in the template must be present in the output.
Step 5: Return the completed report as a single Markdown document.模式3:Reviewer
Reviewer的核心思想:把"检查什么"和"怎么检查"分开。
不用写一长串系统提示词描述每个代码坏味道,把评分标准存到references/review-checklist.md里就行了。
用户提交代码,agent加载清单,逐项评分,按严重程度分组输出。把Python风格清单换成OWASP安全清单,同一套skill基础设施就能干完全不同的事。自动化PR审查、人工审查前抓漏洞,都好用。
看这个代码审查器的例子——指令是静态的,但审查标准动态加载,输出按严重程度分类:
yaml
# skills/code-reviewer/SKILL.md
---
name: code-reviewer
description: Reviews Python code for quality, style, and common bugs. Use when the user submits code for review, asks for feedback on their code, or wants a code audit.
metadata:
pattern: reviewer
severity-levels: error, warning, info
---markdown
You are a Python code reviewer. Follow this review protocol exactly:
Step 1: Load 'references/review-checklist.md' for the complete review criteria.
Step 2: Read the user's code carefully. Understand its purpose before critiquing.
Step 3: Apply each rule from the checklist to the code. For every violation found:
- Note the line number (or approximate location)
- Classify severity: error (must fix), warning (should fix), info (consider)
- Explain WHY it's a problem, not just WHAT is wrong
- Suggest a specific fix with corrected code
Step 4: Produce a structured review with these sections:
- **Summary**: What the code does, overall quality assessment
- **Findings**: Grouped by severity (errors first, then warnings, then info)
- **Score**: Rate 1-10 with brief justification
- **Top 3 Recommendations**: The most impactful improvements模式4:Inversion
Agent有个毛病:总想猜你的意图,然后立刻输出结果。
Inversion翻转了这个逻辑——不是你驱动提示词、agent执行,而是agent来采访你。
怎么做到?靠明确的门控指令,比如"所有阶段完成之前,不要开始构建"。agent按顺序提问,等你的回答,再进入下一阶段。没搞清楚你的需求和部署约束之前,绝不输出最终结果。
看这个项目规划器——严格的分阶段+明确的门控提示词,agent在收集完所有答案之前,不能生成计划:
yaml
# skills/project-planner/SKILL.md
---
name: project-planner
description: Plans a new software project by gathering requirements through structured questions before producing a plan. Use when the user says "I want to build", "help me plan", "design a system", or "start a new project".
metadata:
pattern: inversion
interaction: multi-turn
---markdown
You are conducting a structured requirements interview. DO NOT start building or designing until all phases are complete.
## Phase 1 — Problem Discovery (ask one question at a time, wait for each answer)
Ask these questions in order. Do not skip any.
- Q1: "What problem does this project solve for its users?"
- Q2: "Who are the primary users? What is their technical level?"
- Q3: "What is the expected scale? (users per day, data volume, request rate)"
## Phase 2 — Technical Constraints (only after Phase 1 is fully answered)
- Q4: "What deployment environment will you use?"
- Q5: "Do you have any technology stack requirements or preferences?"
- Q6: "What are the non-negotiable requirements? (latency, uptime, compliance, budget)"
## Phase 3 — Synthesis (only after all questions are answered)
1. Load 'assets/plan-template.md' for the output format
2. Fill in every section of the template using the gathered requirements
3. Present the completed plan to the user
4. Ask: "Does this plan accurately capture your requirements? What would you change?"
5. Iterate on feedback until the user confirms模式5:Pipeline
复杂任务最怕的就是跳步骤、忽略指令。
Pipeline用硬检查点解决这个问题。
指令本身就是工作流定义。实现明确的门控条件(比如"docstring生成后要用户批准才能进入组装阶段"),agent就没法绕过复杂任务直接给你一个未验证的结果。
这个模式把所有可选目录都用上:不同步骤加载不同的参考文件和模板,上下文窗口保持干净。
看这个文档流水线——门控条件很明确:用户确认docstring之前,不能进入组装阶段:
yaml
# skills/doc-pipeline/SKILL.md
---
name: doc-pipeline
description: Generates API documentation from Python source code through a multi-step pipeline. Use when the user asks to document a module, generate API docs, or create documentation from code.
metadata:
pattern: pipeline
steps: "4"
---markdown
You are running a documentation generation pipeline. Execute each step in order. Do NOT skip steps or proceed if a step fails.
## Step 1 — Parse & Inventory
Analyze the user's Python code to extract all public classes, functions, and constants. Present the inventory as a checklist. Ask: "Is this the complete public API you want documented?"
## Step 2 — Generate Docstrings
For each function lacking a docstring:
- Load 'references/docstring-style.md' for the required format
- Generate a docstring following the style guide exactly
- Present each generated docstring for user approval
Do NOT proceed to Step 3 until the user confirms.
## Step 3 — Assemble Documentation
Load 'assets/api-doc-template.md' for the output structure. Compile all classes, functions, and docstrings into a single API reference document.
## Step 4 — Quality Check
Review against 'references/quality-checklist.md':
- Every public symbol documented
- Every parameter has a type and description
- At least one usage example per function
Report results. Fix issues before presenting the final document.怎么选?
每种模式解决的问题不一样:
| 你的需求 | 用这个 |
|---|---|
| 给agent注入特定库/框架的知识 | Tool Wrapper |
| 按固定模板生成文档/代码 | Generator |
| 按标准审查代码/内容 | Reviewer |
| 先收集需求再产出 | Inversion |
| 多步骤、带检查点的复杂流程 | Pipeline |
模式可以组合
这些模式不是互斥的。
Pipeline可以在最后加个Reviewer步骤,双重检查自己的工作。Generator可以一开始用Inversion收集变量,再填充模板。
ADK的SkillToolset加上渐进式披露,agent只在运行时为它真正需要的模式花费上下文token。
写在最后
与其把一堆复杂指令塞进一个系统提示词,不如拆开、选对模式,构建真正可靠的agent。
虽然这几个设计模式比较有用,但实际写起来也不可能反复地回来看,然后再去运用。有人把几种设计模式和之前Anthropic的skills最佳实践融合在一起,对skill-optimizer进行了升级。
GitHub地址:https://github.com/chujianyun/skills/tree/main/skills/skill-optimizer
它能审查你的skill更适合哪种设计模式,根据最佳实践提供优化建议。你确认之后,它会自动帮你完成优化。
本篇内容整理自 Google Cloud Tech 《5 Agent Skill design patterns every ADK developer should know》
