Agent Skill 设计模式

代理技能设计模式随着AI Agent的应用快速普及，越来越多的开发者开始将大型语言模型（LLM）流程整合进日常的自动化工作与CI/CD平台中。然而，在审视这些Agent的技能时，我们往往会陷入一个盲点：过度关注外部的「格式规范」。

我们花费大量时间确保SKILL.mdYAML 标头正确无误、目录结构符合标准。但事实上，随着东南代理工具（如 Claude Code、Gemini CLI 等）逐渐将技能封装格式统一起来，简单的「格式问题」已经不再是最大的挑战。

现在，真正的考验在于「内容的逻辑设计」。

把庞杂、脆弱的指令全部塞进单一的系统提示词（System Prompt）中，不仅难以维护，更会导致Agent的行为难以预测。一个用于调用外部API的技能，与一个包含四个步骤的文件生成平台，虽然资料夹里看起来都是一个SKILL.md文件，但它们内部的操作逻辑却是截然不同的。

解决这个痛点，谷歌云技术深入研究了当前生态系中的最佳实践，总结了5种设计模式。为了明确明确的分工边界与后续加载的机制，我们能够行为有效的控制令牌消耗，并打造出结构更严谨、更可控且具备高度增强性的企业级AI Agent。

---

1. Tool Wrapper（工具包装模式）

• 让 Agent 成为特定函式库或框架的专家。然后把所有的 API 规范或团队编码风格硬塞进系统提示词里，不如将它们储备成一项技能。Agent 只有在真正需要处理该技术时，才会动态加载外部的参考文件（例如references/conventions.md）。非常适合用来确保 Agent 写出来的程序符合团队内部的最佳实践。
• 将企业内部的资料库查询工具或特定框架的编写芯片封装起来。代理在对话中才知道这项技能的存在，只有在判断确实需要编写或审查相关程序代码时，才会完整加载规范。

SKILL.md原始码示例（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. Generator（生成器模式）

• 为了解决Agent生成文件结构不同的问题。该模式扮演「专案经理」的角色，它不把版面配置在指令里写死，而是配合Agent去读取assets/里的范本（模板）和references/里的风格指南，接着询问缺少的变数，最后精准地执行「填空」作业。
• 提供一个标准的 API 文件范本。当给予一段时间方案编码时，代理会严格按照该范本的格式，自动对应的配方并形成 Markdown 说明文件或发行说明。

SKILL.md原始码示例（技术报告生成器）：

# 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.审阅者（审阅者模式）

• 将「要检查什么」与「如何检查」彻底分开。透过读取外部的模组化评分表（如references/review-checklist.md），代理会系统性地扫描物资，把发现的问题严重程度进行分类。如果今天认为「风格审查」改成「资安审查」，只需替换那份清单文件即可，基础架构不用动。
• 在代码审查流程中，配置包含记忆体泄漏检查、命名规范与漏洞防御的清单。代理会逐项扫描原始码，并进行灰度分层的建议与质量报告。

SKILL.md原始码示例（Python程序码审查）：

# 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（烧烤角色模式）

• 打破特工总是「急着猜测并给出答案」的习惯。此模式赋予特工「采访官/采访者」的身分，跨越设定不可妥协的闸门指令（例如「在所有阶段完成前，绝对不要开始建置」），强制特工循序渐进地思考。直到收集完需求和限制条件后，才会开始变量最终规划。
• 当您需要编写一份新的系统架构规划时，代理会先主动反问目标建设环境、技术限制与非功能性需求，待所有前置条件确认完毕后才进行生成。

SKILL.md原始码范例（专案规划采访者）：

# 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。步骤一提取程序代码结构；步骤二生成Docstrings并暂停等待人类开发者确认；确认无误后，步骤三才构建成最终的API文件。

SKILL.md原始码示例（API文件生成表格）：

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

💡结语：设计模式的组合应用

这 5 种模式并非互斥，而是可以相互组合的。例如，你可以用 Generator 搭配最初的反转提问，或者在 Pipeline 的最后加上一步 Reviewer 模式来进行自我质量检查。善用这些模式，可以帮助你跳脱传统提示词的限制，马上出更稳定、专业的 Agent 应用。