Agent Skill设计模式和技巧

码以致用

65人浏览 · 2026-03-24 13:47:24

码以致用 · 2026-03-24 13:47:24 发布

最近Google和Anthropic各发布了一篇指导Agent开发者设计Skill的文章，我把这些模式和技巧翻译总结如下：

Anthropic的9条Skill技巧

避免写显而易见的东西

Claude Code 对您的代码库非常了解，Claude 也精通编程，包括许多固有偏好。如果您发布的主要是关于知识的技能，请重点介绍能够促使 Claude 突破常规思维的信息。

例如，前端设计技能是一个很好的案例——它由 Anthropic 的一位工程师在与客户协作改进 Claude 的设计品味时构建而成，避开了经典模式（如 Inter 字体和紫色渐变）。

构建Gotcha部分

在任何技能中，最具价值的部分是“Gotcha”部分，也就是Agent可能踩的坑。这些部分应基于 Claude 在使用您的技能时遇到的常见失败点构建。理想情况下，您应随时间更新技能，以捕捉这些Gotcha。

使用文件系统与渐进式披露

正如我们之前所说，一个技能是一个文件夹，而不仅仅是一个 Markdown 文件。您应将整个文件系统视为上下文工程与渐进式披露的形式。告知 Claude 您的技能中有哪些文件，它会在适当的时候读取这些文件。

最简单的渐进式披露方式是引用其他 Markdown 文件供 Claude 使用。例如，您可以将详细的函数签名和使用示例拆分到 references/api.md 文件中。

另一个例子：如果最终输出是 Markdown 文件，您可能在 assets/ 目录中包含一个模板文件供复制使用。

您可以建立包含参考资料、脚本、示例等的文件夹，以帮助 Claude 更高效地工作。

避免对 Agent 的死板控制

Claude 通常会遵循您的指令，但由于技能具有高可复用性，您需特别注意避免指令过于具体。为 Claude 提供其所需的必要信息，同时赋予其适应具体情境的灵活性。例如：

思考设置流程

某些技能可能需要用户设置上下文信息。例如，如果您制作一个向 Slack 发布每日Standup Meeting的技能，您可能希望 Claude 询问用户发布到哪个 Slack 频道。

一个可行的做法是将此类设置信息存储在与技能目录同级的 config.json 文件中（如上述示例）。若配置未设置，Agent可向用户请求相关信息。

若需让Agent呈现结构化、多选式问题，可指示 Claude 使用 AskUserQuestion 工具。

描述字段是给模型看的

当 Claude Code 启动会话时，它会构建一个包含所有可用技能及其描述的清单。这个清单是 Agent 扫描以决定“是否有针对此请求的技能”的依据。这意味着描述字段不是摘要，而是描述何时触发此拉取请求。把它想象成激活这个技能的If语句。

记忆与数据存储

某些技能可以通过在其中存储数据来包含一种形式的记忆。您可以将数据存储在任何形式中，从简单的追加写文本日志文件或 JSON 文件，到复杂的 SQLite 数据库。

例如，一个Standup Meeting发布技能可能会维护一个 standups.log 文件，记录每次发布的内容，这意味着下次运行时，Claude 可以读取自己的历史记录并告知自昨天以来发生了哪些变化。

存储在技能目录中的数据在升级技能时可能会被删除，因此您应将其存储在稳定文件夹中。从今天起，Claude Code为每个插件提供 ${CLAUDE_PLUGIN_DATA} 作为用于存储数据的稳定文件夹。

存储脚本与生成代码

您给予 Agent 的最强大的工具之一是代码。提供脚本和库可以让 Agent 将回合花费在功能组合上，决定接下来做什么，而不是重构样板代码。

例如，在您的数据科学技能中，您可能拥有一组从事件源获取数据的函数库。为了让 Claude 进行复杂分析，您可以给它一组助手函数，如下所示：

随后，Agent 可以即时生成脚本来组合这些功能，以完成诸如“周二发生了什么？”之类的提示更高级的分析。

按需Hook

技能可以包含仅在技能被调用时激活的钩子，在整个会话期间可用。将此用于那些您不希望一直运行但有时极其有用的具有特定约束的钩子。

例如：

/careful —— 通过 Bash 的 PreToolUse 匹配器阻止 rm -rf、DROP TABLE、force-push、kubectl delete。仅当您知道正在接触生产环境（prod）时才需要这个——如果一直开启会让您发疯
/freeze —— 阻止任何不在特定目录中的编辑/写入操作。调试时很有用。

Google的5个Skill设计模式

工具封装器：让你的Agent瞬间成为任何库的专家
生成器：从可重用的模板生成结构化的文档
审查器：根据严重程度对代码进行检查，并打分
反转：Agent在行动前会先与你进行访谈（Interview）
管道：强制执行严格的多步骤工作流程，并设置检查点

模式 1：工具封装器

工具封装器为你的 Agent 提供特定库的即时上下文。与其将 API 约定硬编码到你的系统提示中，不如将它们打包成一个技能。你的 Agent 仅在实际与该技术交互时才会加载此上下文。

这是最简单的实现模式。SKILL.md 文件会监听用户提示中的特定库关键词，从 references/ 目录动态加载内部文档，并将这些规则视为绝对真理。这正是你将团队内部编码指南或特定框架最佳实践直接集成到开发人员工作流程中的方式。

下面是一个示例，展示了如何使用工具封装器来教Agent编写 FastAPI 代码。注意指令明确地告诉代理仅在开始审查或编写代码时加载 conventions.md 文件：

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

工具封装器应用知识，生成器强制一致的输出。如果你发现Agent每次运行生成不同的文档结构，生成器通过协调一个填空过程来解决这个问题。

它利用两个可选目录：assets/ 包含你的输出模板，references/ 包含你的风格指南。指令充当项目经理。它们指示Agent加载模板，读取风格指南，向用户询问缺失的变量，并填充文档。这对于生成可预测的 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：审查器

审查器模式将需要检查的内容与如何检查的内容分离。与其编写一个详细的系统提示，其中详细说明每个代码异味的检查方法，不如将模块化的评分标准存储在 references/review-checklist.md 文件中。

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

以下代码审查器技能演示展示了这种分离。指令保持静态，但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：反转

Agent本质上倾向于立即猜测和生成。反转模式颠覆了这种动态。与其让用户驱动提示，让代理执行，不如让代理充当面试官。

反转依赖于明确、不可协商的限制性指令（例如“在所有阶段完成后，不要开始构建”），以强制代理首先收集上下文。它按顺序提出结构化问题，并在获取你的回答后，才在移动到下一个阶段。在Agent获得你需求和部署约束的完整图景之前，它拒绝合成最终输出。

要看到它如何运作，请查看这个项目计划器技能。这里关键的要素是严格的分阶段和明确的门禁提示，该提示阻止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：管道

对于复杂的任务，你不能容忍跳过的步骤或忽略指令。管道模式强制执行严格的、顺序的工作流程，并设置明确的检查点。

指令本身充当工作流程定义。通过实施明确的菱形门禁条件（例如，在从文档字符串生成到最终组装之前需要用户批准），管道确保Agent无法绕过复杂的任务并呈现未验证的最终结果。

此模式利用所有可选目录，仅在需要特定步骤时才从不同的参考文件和模板中提取它们，从而保持上下文窗口的清洁。

在这个文档管道示例中，请注意明确的门禁条件。Agent被明确禁止在先前步骤中生成文档字符串之前移动到组装阶段：

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

原文：

https://x.com/trq212/status/2033949937936085378x.com/trq212/status/2033949937936085378

https://x.com/GoogleCloudTech/status/2033953579824758855x.com/GoogleCloudTech/status/2033953579824758855