在编写 . 文件时开发人员往往会过于关注格式——确保 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 users 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 users 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 users 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 its 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 users 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种最常用的代理技能设计模式 - 汇智网