5种最常用的代理技能设计模式

微信 ezpoda免费咨询：AI编程 | AI模型微调| AI私有化部署
AI工具导航 | Tripo 3D | Meshy AI | ElevenLabs | KlingAI | ArtSpace | Phot.AI | InVideo

在编写 𝚂𝙺𝙸𝙻𝙻.𝚖𝚍 文件时，开发人员往往会过于关注格式——确保 YAML 代码正确、目录结构清晰，并遵循规范。但如今已有超过 30 种代理工具（例如 Claude Code、Gemini CLI 和 Cursor）采用相同的布局，格式问题实际上已经过时。

现在的挑战在于内容设计。规范解释了如何打包一个技能，但对于如何构建技能内部的逻辑却只字未提。例如，一个封装了 FastAPI 约定的技能与一个四步文档流程的技能，即使它们的 𝚂𝙺𝙸𝙻𝙻.𝚖𝚍 文件看起来完全相同，但它们的运行方式却截然不同。

通过研究整个生态系统中技能的构建方式——从 Anthropic 的代码库到 Vercel 和 Google 的内部指南——我们发现了五种反复出现的设计模式，可以帮助开发者构建智能体。

本文将通过可运行的 ADK 代码逐一介绍这些模式：

• 工具封装器：让你的智能体瞬间成为任何库的专家
• 生成器：从可重用的模板生成结构化文档
• 审查器：根据严重程度，对照检查清单对代码进行评分
• 反转：智能体在执行操作前会先询问你
• 管道：通过检查点强制执行严格的多步骤工作流程

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

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

它利用两个可选目录：arguments/ 存放您的输出模板，requests/ 存放您的风格指南。这些说明文档充当项目经理的角色。它们指示代理加载模板、读取样式指南、询问用户缺失的变量并填充文档。这对于生成可预测的 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 的 𝚂𝚔𝚒𝚕𝚕𝚃𝚘𝚘𝚕𝚜𝚎𝚝 和渐进式披露，您的代理仅在运行时将其上下文令牌用于所需的确切模式。

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

立即开始

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

原文链接：5 Agent Skill design patterns every ADK developer should know

汇智网翻译整理，转载请标明出处