写 Agent 这件事，说起来门槛不高，但真正写出一个靠谱的，比想象中难得多。
大多数人的第一版 Agent 都是一个套路：把需求写进 system prompt，给几个工具，然后指望它能自己搞定。结果往往是它要么过于保守什么都不干，要么过于激进一顿操作全错。你反复调 prompt、换模型、加约束，效果还是不理想。问题不在于你不够努力，而在于你从一开始就没按正确的结构来搭。
Anthropic 在 Smithery 上发布了一份 agent-development Skill，本质上是一份 Claude Code Plugin 的 Agent 开发规范。它不是那种”AI Agent 的未来”式的概念文章，而是一份精确到以下三个层面的实操手册：
-
字段名：每个 frontmatter 字段的命名规则和字符约束 -
触发条件：description 怎么写才能让 Agent 被正确唤醒 -
验证规则：写完后怎么确认 Agent 行为符合预期
每个字段为什么存在、边界在哪、怎么测试，都写得明明白白。
说白了，这份指南的核心就讲了一件事：Agent 不是靠长 prompt 堆出来的，是靠结构化的 frontmatter 和精确的触发条件撑起来的。如果你正在写 Claude Code Plugin，或者想把自己的 Agent 做得更可靠，这篇文章会把里面最有价值的东西拆给你看。
环境准备
这份 Skill 本身不需要安装。它是 Claude Code Plugin 开发体系的一部分，作为开发时的参考规范存在。
如果你已经在写 Claude Code Plugin，它的目录下应该有一个 agents/ 文件夹。每个 Agent 就是一个 .md 文件，放在这个文件夹里就会被自动发现。Skill 里提供了完整的验证脚本，但核心内容是那一套 frontmatter 的设计逻辑，读懂了比跑脚本重要。
跟大多数 Skill 不一样的是，这份指南不是”install and run”型的工具。它更像一份设计规范，每当你需要新建一个 Agent 或者怀疑现有 Agent 触发不稳定时，回来翻一下对应的章节就有答案。
整个 Skill 的文件组织很清晰。SKILL.md 是核心规范（文件结构、frontmatter 字段、system prompt 设计），references/ 下补充了系统提示词设计模式和触发示例，examples/ 提供了可复用的创建模板，scripts/ 放了验证和测试脚本。
操作流程：从零创建一个可靠的 Agent
Agent 的创建流程看起来简单，但细节决定成败。这份指南给出了两条路径：AI 辅助生成和手动创建。
AI 辅助路径适合快速起步。你给一段自然语言描述，让 Claude 按照固定的 JSON 模板生成 Agent 配置，然后转成标准的 Agent 文件格式。模板会完成四件事：
-
提取核心意图，确定 Agent 要解决什么问题 -
设计专家人设，让 Agent 在对应领域有专业判断 -
写系统提示词，包括行为边界、方法论和输出格式 -
生成触发条件描述，覆盖主动触发和被动触发两类场景
这套流程的好处是”规格先行”，先拿到结构化的规格再落地成文件，比直接从空白开始写靠谱。
手动创建路径适合你对 Agent 的行为有精确预期的场景。六个步骤：
-
起一个符合规范的标识符（小写字母、数字、连字符，3-50 字符） -
写触发条件描述（最关键的字段，下文展开讲） -
选模型（90% 的情况用 inherit就行） -
挑颜色（不同类型用不同颜色，UI 里一眼区分） -
定义工具集（最小权限原则，能给只读就不要给 Write） -
写系统提示词（用第二人称，给明确步骤和输出格式）
两条路径的核心差异在于方向。AI 辅助是从”意图”推导”结构”，手动创建是从”结构”倒推”意图”。如果你对 Agent 的行为边界特别在意，手动创建更快，因为不需要跟 AI 反复对齐预期。探索性场景用 AI 辅助更省时间。
写完文件后，验证是必不可少的。Skill 提供了 scripts/validate-agent.sh 做结构检查，还有一个 test-agent-trigger.sh 测触发是否生效。这套流程初看有点过度工程化，但 Agent 一旦部署出去，触发失败比写错逻辑更致命。用户输入了匹配的指令，Agent 没被激活，整个功能等于不存在。
关键设计：为什么触发条件描述是整份指南的灵魂
整份 SKILL.md 里最让我意外的设计决策，是 description 字段被明确标注为”最关键的字段”。
大多数 Agent 框架把 name 或者 system prompt 当核心，这份指南却说 description 才是命门。原因很现实：description 是 Agent 注册时加载到上下文中的，Claude 的调度模块根据它判断用户这句话要不要派给这个 Agent。如果你的 description 写得含糊，Agent 逻辑再好也不会被触发。
Skill 给出的 description 格式非常具体：
Use this agent when [conditions]. Typical triggers include
[scenario 1], [scenario 2], and [scenario 3].
See "When to invoke" in the agent body for worked scenarios.
这里面有三个信息层。第一句是触发条件，判断边界。第二句是典型场景速览，给调度器快速匹配。第三句是指针，把详细场景放在 body 里，避免 frontmatter 过载。这套分层设计把”调度器需要的信息”和”Agent 需要的详细指令”彻底解耦了。
还有一个容易被忽略的关键点：Skill 明确要求 description 同时覆盖两类触发。主动触发（Agent 自己判断该介入的情况）和被动触发（用户明确要求的情况）。举个例子，一个 code-reviewer Agent 的 description，既要写”when the user asks for code review”，也要写”when a significant amount of code has been written and needs review”。漏了任何一类，Agent 就会出现行为盲区。
另一个让我印象深刻的细节是 tools 字段的最小权限设计。Skill 给出了常见的工具组合：
| 场景 | 工具组合 | 原则 |
|---|---|---|
| 只读分析 | Read, Grep, Glob | 只看不改 |
| 代码生成 | Read, Write, Grep | 读写分离 |
| 自动化测试 | Read, Bash, Grep | 可执行但不可写源码 |
| 全权 Agent | 省略 tools 字段或用 * |
慎用 |
这背后是对 Agent 行为半径的精确控制。给一个 review Agent 开 Write 权限，它就可能不仅提建议还会改代码，而你根本没预期它这么做。
使用场景：两种创建路径怎么选
一个问题很实际：什么时候用 AI 辅助，什么时候手动？
如果你的场景跟 Skill 内置的模板高度匹配，比如写一个标准的 code reviewer 或者 test generator，AI 辅助足够了。模板已经覆盖了触发条件、流程步骤、输出格式这些需要反复试的环节，你只需要调整领域细节。
但当你的 Agent 有明显的非标逻辑时，手动创建效率更高。一个需要分阶段执行、有状态管理、输出格式不是纯文本的 Agent，模板生成的结果往往需要大量修改。与其跟 AI 反复对齐”不是这样”“再改一下”，不如直接从结构设计开始。
还有一类场景值得单独提：重构已有 Agent。很多人把一个简单 Agent 越改越复杂，最后触发逻辑和 system prompt 搅在一起，谁也看不懂。这份指南的价值不只是创建，它提供了一套统一的 Agent 文件格式规范。如果你的 agents/ 目录下有五个 Agent 各自用了不同写法，翻一遍这份规范再重构，体验会好很多。
整套指南看下来，最厉害的不是它列出了多少规则，而是每个规则都有明确的”为什么”和”不这么做会怎样”。Agent 开发最大的坑不是技术复杂，而是行为不可预期。这份规范本质上是在用结构化约束来消灭不确定性。
洞察与反思
Agent 开发领域有个很大的认知偏差：大家都在卷”模型能力”，没人在意”结构设计”。
各种 Agent 框架的评测都在比这些东西：
-
推理分高不高 -
工具调用准不准 -
多步任务的完成率高不高
但没人问前提对不对：Agent 能被正确触发吗？收到的上下文合适吗？拿到的工具权限恰当吗？如果这些前提没做好，再强的模型也救不回来。指南里反复强调的三件事才是决定 Agent 稳定性的基础设施：
-
description 精确度：触发条件覆盖是否完整 -
最小权限原则：tools 字段是否只给了必要权限 -
触发条件覆盖：主动触发和被动触发是否都考虑到
说实话，这份 Skill 让我重新想了一个问题：Agent 的可靠性瓶颈到底在模型还是在规则？Anthropic 的态度很明显，他们把规则一侧做到极致精确，让模型只在给定的边界内发挥。这跟当前主流 Agent 框架”把模型能力最大化”的思路正好相反。
我个人觉得这个方向是对的，但有一个前提：规则设计者必须能预见到足够多的边界情况。如果一个 Agent 面对的场景足够开放，结构化约束可能会限制它的灵活性。指南里没谈这个 trade-off，算是一个小遗憾。
还有一个观察：这份 Skill 本质上是在用 YAML frontmatter 实现一个轻量的 Agent 调度系统。description 是匹配函数，tools 是权限控制，model 是资源分配，color 是 UI 标识。这些概念在传统的多 Agent 系统里都是独立的调度模块，这里压缩进了几个字段里。简洁是简洁了，但复杂度上限也被锁死了。如果你的场景需要层级 Agent 或者动态任务分配，这套规范可能不够用。
不管你用不用 Claude Code Plugin，这份指南的价值在于它把 Agent 开发中最容易被忽视的结构性问题讲透了。它不卖概念，不画大饼，就是告诉你每个字段怎么填、填错了会出现什么后果。这种”实操手册”式的文档，比一百篇 Agent 趋势分析都值钱。
资源地址
| 资源 | 地址 |
|---|---|
| Smithery 页面 | https://smithery.ai/skills/anthropics/agent-development |
总结
写了这么多，最有感触的反而不是技术本身。
Agent 开发被太多人搞成了玄学。prompt 越长越复杂，模型越用越大，调试越来越凭直觉。但这份指南用不到 2000 字的规范告诉你：稳定运行的 Agent 靠的不是灵光一现的 prompt，是精确到字段级别的结构约束。
如果你正在写 Agent，下次遇到”为什么它有时触发有时不触发”这种问题时，先别看 prompt 写得好不好。检查你的 description 覆盖了几类触发场景，tools 有没有多余的权限，系统提示词是不是用第二人称给了明确步骤。这三个地方修对了，80% 的稳定性问题就解决了。