说到 𝚂𝙺𝙸𝙻𝙻.𝚖𝚍，开发者往往会把注意力过度集中在“格式”上——比如 YAML 怎么写、目录怎么组织、是否严格遵循规范。但如今，已经有超过 30 种 Agent 工具（例如 Claude Code、Gemini CLI 和 Cursor）都在采用同一套布局标准，因此“格式”这个问题，实际上已经几乎不再构成挑战了。
现在真正的挑战，是内容设计。规范文档告诉你应该如何打包一个 skill，却完全没有告诉你：skill 内部的逻辑应该如何组织。例如，一个封装 FastAPI 约定的 skill，和一个四步式文档生成流水线，在外部看起来它们的 𝚂𝙺𝙸𝙻𝙻.𝚖𝚍 文件几乎一模一样，但它们的实际运作方式却截然不同。
通过研究整个生态中各类 skill 的构建方式——从 Anthropic 的仓库，到 Vercel，再到 Google 的内部指南——我们发现，有五种反复出现的设计模式，能够帮助开发者构建更可靠的 agent。
本文会结合可运行的 ADK 代码，逐一讲解这五种模式：
- Tool Wrapper：让你的 agent 立即成为任何库的专家
- Generator：基于可复用模板生成结构化文档
- Reviewer：按严重级别依据检查清单给代码打分
- Inversion：agent 在行动前先“采访”你
- Pipeline：通过检查点强制执行严格的多步工作流
模式 1：Tool Wrapper
Tool Wrapper（工具封装器） 会为你的 agent 提供针对某个特定库的按需上下文。你不必把 API 约定硬编码进 system prompt，而是把它们打包进一个 skill 中。只有当 agent 真的在处理这项技术时，它才会加载这些上下文。
这是最容易实现的一种模式。𝚂𝙺𝙸𝙻𝙻.𝚖𝚍 文件会监听用户提示中是否出现特定库的关键字，然后从 𝚛𝚎𝚏𝚎𝚛𝚎𝚗𝚌𝚎𝚜/ 目录中动态加载你的内部文档，并把其中的规则当作绝对准则来应用。你完全可以用这种机制，把团队内部的编码规范，或者某个特定框架的最佳实践，直接嵌入到开发者的工作流中。
下面是一个 Tool Wrapper 的示例，它教 agent 如何编写 FastAPI 代码。请注意，这里的指令明确要求：只有当 agent 开始审查代码或编写代码时，才去加载 𝚌𝚘𝚗𝚟𝚎𝚗𝚝𝚒𝚘𝚗𝚜.𝚖𝚍 文件：
# 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
---
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
模式 2：Generator
如果说 Tool Wrapper 的作用是“注入知识”，那么 Generator（生成器） 的作用就是“强制输出一致性”。如果你总是遇到 agent 每次运行都生成不同文档结构的问题，那么 Generator 模式就是为了解决这个问题：它通过一个“填空式流程”来组织输出。
它会用到两个可选目录：𝚊𝚜𝚜𝚎𝚝𝚜/ 用来存放输出模板，𝚛𝚎𝚏𝚎𝚛𝚎𝚗𝚌𝚎𝚜/ 用来存放风格指南。而指令本身则充当项目经理的角色：它会要求 agent 加载模板、阅读风格指南、向用户询问缺失变量，然后再填充文档。这个模式非常适合用来生成结构稳定的 API 文档、统一提交信息格式，或脚手架化项目架构。
在下面这个“技术报告生成器”的例子里，skill 文件本身并不包含真正的版式结构，也不包含具体语法规则。它只是负责协调这些资源的读取，并强制 agent 按步骤执行：
# 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
---
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（审查器） 模式把“检查什么”与“如何检查”分离开来。你不需要在 system prompt 里长篇大论地列出所有代码异味，而是可以把一套模块化的审查标准，存放在 𝚛𝚎𝚏𝚎𝚛𝚎𝚗𝚌𝚎𝚜/𝚛𝚎𝚟𝚒𝚎𝚠-𝚌𝚑𝚎𝚌𝚔𝚕𝚒𝚜𝚝.𝚖𝚍 文件中。
当用户提交代码后，agent 会加载这份检查清单，并系统化地对代码进行打分，再按照问题严重级别归类输出结果。如果你把一套 Python 风格检查清单替换成 OWASP 安全检查清单，那么在完全相同的 skill 基础设施下，你就能得到一种完全不同、专门面向安全的审计能力。
这是一种非常高效的方式，可以自动化 PR review，或者在人类开始审查之前提前发现漏洞。
下面这个代码审查 skill 就很好地体现了这种分离。指令本身保持不变，但 agent 会动态加载外部清单中的审查标准，并强制生成按严重级别组织的结构化输出：
# 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
---
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（反转） 模式，正是要把这种动态反过来。它不再是“用户发出 prompt，agent 立刻执行”，而是让 agent 扮演一个采访者的角色。
Inversion 依赖的是明确且不可协商的门控指令，例如“在所有阶段完成之前，绝对不要开始构建”。这种门控会强制 agent 先收集上下文。它会按照结构化顺序逐个提问，并在进入下一阶段之前等待你的回答。在获取完整需求与部署约束之前，agent 会拒绝合成最终输出。
来看下面这个“项目规划 skill”的例子。这里最关键的地方，就是严格的阶段划分，以及那条明确的门控提示：在收集到所有用户回答之前，agent 不得开始生成最终方案。
# 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
---
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 生成结果，之后才能进入最终组装阶段），Pipeline 能确保 agent 不能绕过复杂任务的中间步骤，直接抛出一个未经验证的最终结果。
这种模式会用到所有可选目录，并且只会在某个具体步骤真正需要时，才加载相应的参考文件和模板，从而保持上下文窗口尽量干净。
在下面这个“文档生成流水线”的例子中，请特别注意那些明确的门控条件。这里明确禁止 agent 在用户确认上一步生成的 docstring 之前，进入后续的组装阶段：
# 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"
---
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 skill 模式
每一种模式，回答的其实都是不同的问题。你可以用下面这棵决策树，来判断你的场景最适合哪一种模式：
最后一点：这些模式是可以组合的
这些模式并不是彼此互斥的，它们是可以组合使用的。
一个 Pipeline skill，可以在最后加入一个 Reviewer 步骤，对自己的结果再做一次复查。一个 Generator，也可以在最开始依赖 Inversion，先向用户收集必要变量，再去填充模板。借助 ADK 的 𝚂𝚔𝚒𝚕𝚕𝚃𝚘𝚘𝚕𝚜𝚎𝚝 和渐进式披露（progressive disclosure）机制，你的 agent 只会在运行时消耗上下文 token，去加载它当前真正需要的模式。
不要再试图把复杂而脆弱的指令，硬塞进一个单一的 system prompt 里了。把你的工作流拆开，应用合适的结构模式，去构建更可靠的 agent。
现在就开始
Agent Skills 规范是开源的，并且已经在 ADK 中获得原生支持。你已经知道如何打包格式；现在，你也知道该如何设计内容了。去用 Google Agent Development Kit 构建更聪明的 agent 吧。
如果你愿意，我还可以继续把这篇内容进一步整理成更适合发布在中文技术社区的版本，比如改成更像微信公众号、掘金或极客时间专栏的中文表达。
