作者：Google Cloud Tech | 日期：2026年4月1日

当涉及到 𝚂𝙺𝙸𝙻𝙻.𝚖𝚍 时，开发者往往会专注于格式——确保 YAML 正确、组织目录并遵循规范。但随着超过 30 个代理工具（如 Claude Code、Gemini CLI 和 Cursor）都采用相同的布局，格式问题实际上已经过时了。

当前挑战在于内容设计。规范解释了如何打包技能，但完全未提供关于如何构建其内部逻辑的指导。例如，一个封装了 FastAPI 约定的技能与一个四步文档流程的技能完全不同，尽管它们的 𝚂𝙺𝙸𝙻𝙻.𝚖𝚍 文件在外观上看起来完全相同。

通过研究生态系统中技能的构建方式——从 Anthropic 的仓库到 Vercel 和 Google 的内部指南——可以发现五种常见的重复设计模式，这些模式可以帮助开发者构建代理。

本文将使用可工作的 ADK 代码逐一介绍每一个模式：

• • 工具封装器（Tool Wrapper）： 让你的代理成为任何库的即时专家
• • 生成器（Generator）： 从可重用的模板中生成结构化文档
• • 审阅者（Reviewer）： 根据严重程度对代码进行清单评分
• • 反转（Inversion）： 代理在行动前先对你进行访谈
• • 管道（Pipeline）： 执行严格的、多步骤的工作流程，并设置检查点

模式 1：工具封装器

工具封装器为你的智能体提供特定库的按需上下文。你无需将 API 规范硬编码到系统提示中，而是将它们打包成一个技能。你的智能体只有在实际使用该技术时才会加载这个上下文。

这是最简单的实现模式。𝚂𝙺𝙸𝙻𝙻.𝚖𝚍 文件监听用户提示中的特定库关键词，动态加载你内部文档中的 𝚛𝚎𝚏𝚎𝚛𝚎𝚗𝚌𝚎𝚜/ 目录内容，并将这些规则作为绝对真理应用。这就是你用来将团队的内部编码规范或特定框架最佳实践直接分发到开发者工作流程中的机制。

以下是一个工具封装器的示例，它教会代理如何编写 FastAPI 代码。请注意，指令明确告诉代理只在开始审查或编写代码时才加载 𝚌𝚘𝚗𝚟𝚎𝚗𝚝𝚒𝚘𝚗𝚜.𝚖𝚍 文件：

   
   # 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：生成器

工具封装器应用知识，而生成器则强制执行一致的输出。如果你在代理每次运行时生成不同的文档结构而苦恼，生成器通过编排填空过程来解决这个问题。

它利用两个可选目录：𝚊𝚜𝚜𝚎𝚝𝚜/ 存放输出模板，𝚛𝚎𝚏𝚎𝚛𝚎𝚗𝚌𝚎𝚜/ 存放风格指南。指令充当项目经理。它们告诉代理加载模板、阅读风格指南、向用户询问缺失变量并填充文档。这适用于生成可预测的 API 文档、标准化提交消息或搭建项目架构。

在这个技术报告生成器示例中，技能文件不包含实际的布局或语法规则。它只是协调这些资产的检索，并强制代理逐步执行：

   
   # 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：审阅者

审阅者模式将检查什么与如何检查分离开来。你无需编写详述每种代码异味的冗长系统提示，而是将模块化的评分标准存储在 𝚛𝚎𝚏𝚎𝚛𝚎𝚗𝚌𝚎𝚜/𝚛𝚎𝚟𝚒𝚎𝚠-𝚌𝚑𝚎𝚌𝚔𝚕𝚒𝚜𝚝.𝚖𝚍 文件中。

当用户提交代码时，代理加载此清单并系统地评分提交内容，按严重程度对发现进行分组。如果你将 Python 风格清单替换为 OWASP 安全清单，你将使用完全相同的技能基础设施获得完全不同的专业化审计。这是自动化 PR 审查或在人工查看代码之前捕获漏洞的高效方式。

以下代码审阅者技能演示了这种分离。指令保持静态，但代理动态地从外部清单加载特定的审查标准，并强制执行基于严重程度的结构化输出：

   
   # 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：反转

代理天生倾向于猜测并立即生成。反转模式颠覆了这种动态。不是用户驱动提示、代理执行，而是代理充当访谈者。

反转依赖于明确的、不可协商的门控指令（如"在所有阶段完成之前不要开始构建"），以强制代理首先收集上下文。它按顺序提出结构化问题，并在进入下一阶段之前等待你的回答。代理拒绝合成最终输出，直到它对你的需求和部署约束有了完整的了解。

要看实际效果，请看这个项目规划器技能。这里的关键要素是严格的分阶段和明确的门控提示，它阻止代理在收集所有用户答案之前合成最终计划：

   
   # 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：管道

对于复杂任务，你不能承受跳过步骤或忽略指令的代价。管道模式强制执行严格的、顺序的工作流程，并设有硬性检查点。

指令本身即作为工作流定义。通过实现明确的菱形门条件（例如在从文档字符串生成进入最终组装之前需要用户批准），管道确保代理不能绕过复杂任务并呈现未验证的最终结果。

此模式利用所有可选目录，仅在需要的特定步骤中引入不同的参考文件和模板，保持上下文窗口的清洁。

在这个文档管道示例中，请注意明确的门条件。代理被明确禁止在用户确认上一步生成的文档字符串之前进入组装阶段：

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

选择正确的代理技能模式

每种模式回答不同的问题。使用此决策树为你的用例找到合适的模式。

最后，模式可以组合

这些模式并非互斥的。它们可以组合。

一个管道技能可以在末尾包含审阅者步骤来双重检查其工作。一个生成器可以在开始时依赖反转来收集必要的变量，然后再填充模板。得益于 ADK 的 𝚂𝚔𝚒𝚕𝚕𝚃𝚘𝚘𝚕𝚜𝚎𝚝 和渐进式披露，你的代理只在运行时需要的确切模式上花费上下文令牌。

不要再试图将复杂而脆弱的指令塞进一个系统提示中。拆分你的工作流程，应用正确的结构模式，构建可靠的代理。

立即开始

Agent Skills 规范是开源的，并在 ADK 中原生支持。你已经知道如何打包格式。现在你知道如何设计内容了。使用 Google Agent Development Kit 构建更智能的代理。

https://x.com/GoogleCloudTech/status/2033953579824758855?s=20