当我们谈论智能体（Agent）的能力复用时，一个根本性问题始终横亘在开发者面前：如何标准化地定义一个「技能」或「能力」，使其可被发现、可被组合、可被可靠地调用？无论是 Claude Code 中的技能加载，还是 MCP（Model Context Protocol）中的工具注册，底层都面临同一个挑战 —— 用什么样的元数据描述，才能让模型和工具链理解这个能力何时适用、输入输出几何、以及如何验证执行结果。
本文以 Addy Osmani 的 Agent Skills 项目为核心案例，对标 MCP 的工具描述规范，系统梳理可复用智能体能力的标准化定义模式，并给出可直接落地的元数据框架设计。
从工作流到元数据：两种能力定义范式的碰撞
Agent Skills 的工作流导向方法
Agent Skills 项目（GitHub 26K+ Star）提出了一个核心洞察：技能（Skill）不是参考文档，而是一个工作流。它是一段包含前端阵脚（frontmatter）的 Markdown 文件，当智能体进入特定情境时，这段工作流会被注入到上下文中。一个技能的基本结构包含触发条件、步骤序列、检查点（checkpoint）和退出标准。关键设计原则可以归纳为五点，其中第一条「过程优于论述」直接点明了工作流与参考文档的本质区别 —— 后者是静态的知识沉淀，前者是一套可执行的动作序列。
在此基础上，项目构建了覆盖六个生命周期阶段的技能体系。Define（定义阶段）负责明确需求，Plan（规划阶段）分解任务，Build（构建阶段）以纵向切片方式实现功能，Verify（验证阶段）运行测试，Review（阶段）进行代码审查，Ship（发布阶段）完成交付。技能之间通过一个元技能（using-agent-skills）作为路由，根据当前上下文动态决定激活哪些技能。这种渐进式披露（Progressive Disclosure）的策略，使得一个包含二十个技能的技能库可以被压缩到 5K token 的上下文中而不导致上下文污染。
MCP 的结构化工具描述范式
MCP（Model Context Protocol）则采用了另一种路径 —— 基于 JSON Schema 的结构化描述。在 MCP 的规范中，工具（Tool）的元数据由以下核心字段组成：name（唯一标识符）、title（可读标题）、description（功能描述）、inputSchema（输入参数的 JSON Schema 定义）、outputSchema（输出结果的 JSON Schema 定义）、annotations（注解，包含 readOnlyHint、destructiveHint、idempotentHint、openWorldHint 等语义标记），以及可选的 execution 字段用于声明任务支持级别。MCP 的工具描述本质上是声明式的，强调类型的精确性和可验证性，这与 Agent Skills 的过程式描述形成了鲜明对比。
一个典型的 MCP 工具定义大约包含五十到一百行 JSON 结构，其中 inputSchema 部分通常占据最大篇幅，因为它是模型理解「这个工具能接受什么」的关键依据。
统一元数据框架的设计要点
将 Agent Skills 的工作流能力与 MCP 的结构化描述相结合，可以构建一个兼顾过程语义与类型语义的统一元数据框架。该框架需要解决三个核心问题：能力何时被触发、能力如何被执行、能力的结果如何被验证。
技能标识与生命周期映射
每个技能应当具备以下基础元数据字段。name 采用小写连字符格式（如 test-driven-development），与 MCP 的命名规范保持一致。title 提供人类可读的技能名称（如「测试驱动开发」）。description 用一到两句话描述技能的核心功能。lifecyclePhase 标识技能所属的生命周期阶段，可选值为 define、plan、build、verify、review、ship，对应 Agent Skills 的六阶段模型。tags 是可选的标签数组，用于增强技能的可发现性，例如 [testing、tdd、verification]。version 采用语义化版本号格式（如 1.0.0），便于版本管理和迭代。
这种设计使得技能既可以被生命周期阶段路由（Agent Skills 的方式），也可以被标签和描述关键词检索（MCP 工具注册的方式），从而支持两种不同的调用路径。
输入输出模式定义
输入模式的定义应当采用 JSON Schema 的一个子集，确保兼容 MCP 的 inputSchema 规范。required 数组声明必填参数。properties 定义每个参数的名称、类型、格式和约束。示例（examples）字段对于复杂参数尤为重要，因为它帮助模型理解参数的典型取值。
输出模式同样采用 JSON Schema 定义，但增加了一个关键的语义字段：evidenceTypes。它声明了技能执行完成后应产出的证据类型，可选值包括 test-results（测试通过结果）、build-output（构建产物）、runtime-trace（运行时追踪）、review-approval（审查批准）等。这直接对应了 Agent Skills 的核心理念 —— 验证是不可协商的退出条件。一个技能必须在产出指定类型的证据之后才能被视为完成。
反合理化与约束声明
Agent Skills 最独特的设计是反合理化表格（Anti-rationalization Tables）。这个设计预置了智能体可能用来跳过工作流的借口，并附带明确的反驳。例如，「这个任务太简单，不需要写规格说明」这一借口的对应反驳是「即使五行代码也需要验收标准」；「我稍后再写测试」的对应反驳是「稍后是负荷词，没有稍后」。
在元数据框架中，这一设计可以通过 constraints 字段表达。constraints 是一个数组，每个元素包含借口（rationalization）、反驳（rebuttal）和约束级别（severity，可选值为 must-ignore、warn、block）三个子字段。当智能体尝试激活某个借口时，框架可以根据 severity 决定是否阻止技能执行。这种设计对于长时间运行的智能体尤为重要 —— 在短会话中跳过一次测试可能只产生一个 bug，但在三十小时的会话末尾跳过测试则会导致一场调试考古学。
渐进式披露与作用域控制
框架必须支持渐进式披露机制。Agent Skills 的实践表明，不应该在会话开始时将所有技能加载到上下文中 —— 每个加载的 token 都会在某处降低模型性能。解决方案是采用两级结构：元技能（meta-skill）作为路由，根据当前任务类型和生命周期阶段决定加载哪些具体技能。元技能本身只需要几百字节的路由逻辑，而具体技能在工作流执行时才被加载。
此外，作用域控制（Scope Discipline）是决定智能体输出是否可合并的关键因素。元数据框架应当在技能级别声明 scopeConstraints，即该技能允许修改的范围边界。例如，test-driven-development 技能的 scopeConstraints 应声明为「仅修改被测试文件和对应的测试文件」，而 code-simplification 技能应包含 Chesterton 栅栏约束 ——「在理解代码为何存在之前不得删除代码」。这些约束在技能被激活时作为系统提示的一部分注入到上下文中，确保智能体不会在修复一个 bug 时顺手重写三个无关文件。
框架落地的工程参数
将上述元数据框架应用到实际项目中时，以下工程参数可作为配置基准。
技能加载策略方面，建议初始上下文仅包含元技能（通常在 500 到 800 token），具体技能在任务进入对应生命周期阶段时按需加载，单次加载的技能内容不超过 2000 token，总上下文中的技能内容不超过 8000 token。元技能路由应优先匹配 lifecyclePhase 字段，其次匹配 tags 中的标签，最后匹配 description 中的关键词。
验证证据要求方面，每个技能必须在退出时产出至少一种 evidenceTypes 中声明的证据类型。如果技能执行完成但未产出对应证据，框架应视为执行失败并返回错误。evidenceTypes 中的每种证据类型应对应一个具体的验证器函数，例如 test-results 对应「所有测试用例通过且覆盖率不低于阈值」，review-approval 对应「至少一名人类审查者签署批准」。
约束 enforcement 方面，constraints 数组中 severity 为 block 的约束必须被强制执行，任何触发该约束的智能体行为都会被阻止并返回解释性错误消息。severity 为 warn 的约束在触发时记录警告日志但允许继续执行。severity 为 must-ignore 的约束作为文档存在，提醒智能体这些借口已被识别但当前不强制阻止。
版本管理与兼容性方面，元数据框架应遵循向后兼容原则进行迭代。引入新字段时应使用可选字段，旧版本技能文件不应因缺少新字段而失效。建议每三个月对技能库进行一次审计，识别过时的约束声明和不再适用的反合理化借口。
框架的适用边界
该元数据框架最适合的场景包括：需要跨多个智能体平台（如 Claude Code、Cursor、 Gemini CLI）复用一个技能库的组织；需要对智能体行为进行严格过程控制的工程团队；需要为智能体构建可发现、可组合能力目录的平台提供商。
但在以下场景中应当审慎使用或简化框架：简单的单轮对话智能体，不需要复杂的生命周期管理；快速原型阶段，过早的元数据标准化会拖累迭代速度；能力边界清晰的工具型智能体，MCP 的轻量级描述已足够。
值得强调的是，元数据框架的价值不在于一次性构建完备，而在于为团队提供了一种共同语言来描述和争论「什么是好的智能体行为」。正如 Agent Skills 项目本身揭示的道理 —— 高级工程师的大部分工作不会出现在代码 diff 中，智能体能力的标准化定义也是如此。它的价值在于让那些原本隐性的工程判断变得可传递、可审计、可组合。
参考资料
- Agent Skills 项目及设计原则（Addy Osmani）：https://addyosmani.com/blog/agent-skills/
- Model Context Protocol 规范中的 Schema 定义：https://modelcontextprotocol.io/specification/draft/schema