Skip to content

5种SKILL.md设计模式:从Tool Wrapper到Pipeline的实战指南

2026年4月23日

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种设计模式:

  1. Tool Wrapper:让agent瞬间成为任何库的专家
  2. Generator:按模板产出结构化文档
  3. Reviewer:按严重程度给代码打分
  4. Inversion:agent先采访你,再动手
  5. 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》

不要孤军奋战啦!

加入微信群一起学习交流 AI

与大神一起使用 OpenClaw、Hermes、Claude Code、Seedance 2.0、GPT-Image-2 等

微信公众号

扫码关注微信公众号
私信 "加群",将自动获取微信群二维码

探索 AI 世界,掌握智能未来