SKILL.md：轻量级技能契约协议与零信任执行设计

1. 一个被严重低估的系统设计问题：当“技能”变成提示词快照

我第一次在某跨平台Agent系统里看到 SKILL.md 文件时，下意识以为是文档规范——就像 README.md 那样，用来给人看的。直到我参与调试一个连续失败三次的“日程协调”任务：Agent 明明已声明支持 calendar.create_event，却在调用时抛出权限拒绝错误，而日志里只有一行模糊的Skill execution denied: insufficient scope。翻遍所有代码，没找到任何显式的权限校验逻辑；再查配置，发现它连 OAuth scope 字段都没定义。最后在 SKILL.md 里一行不起眼的注释里找到了答案：# requires: ["calendar.write", "contacts.read"]。

那一刻我才意识到：SKILL.md 不是文档，是契约；不是说明，是接口定义；不是给人读的，是给运行时引擎解析并强制执行的元数据。而绝大多数团队，正把本该由结构化元数据承载的技能描述，塞进一个无约束、不可解析、无法校验的长提示词里——比如在 system prompt 末尾硬塞一段：“你是一个日历助手，能创建会议、查询空闲时段、发送邀请邮件……注意不要修改用户邮箱设置”。这种写法看似灵活，实则埋下了三重系统性风险：

第一，语义漂移不可控。LLM 对提示词的理解高度依赖上下文和温度参数。同一段提示词，在 temperature=0.2 时可能严格遵循规则，但在 temperature=0.8 的探索模式下，它可能“合理发挥”，擅自调用未授权的联系人搜索接口，甚至尝试解析附件中的 PDF 日程表——而这些行为完全绕过了任何权限检查。

第二，加载与卸载失去粒度。真实业务场景中，Agent 往往需在不同会话阶段动态启用/禁用技能。例如客服 Agent 在用户身份未验证前，应禁用“订单退款”技能；待 OTP 验证通过后才按需加载。若技能逻辑全靠提示词驱动，你只能整段替换 system prompt——这不仅带来 token 开销激增（一次加载可能多出 800+ tokens），更会导致上下文污染：前一轮的“仅限查询”指令，可能因 prompt 拼接不严谨，在下一轮被误继承为“禁止操作”。

第三，权限边界彻底失效。提示词里的“不要修改邮箱设置”是一句道德劝诫，不是访问控制策略。它无法阻止模型在推理链中生成curl -X PATCH https://api.example.com/v1/users/me/email这样的代码片段，也无法拦截前端 SDK 对该 API 的实际调用。真正的权限控制必须发生在技能注册、调用路由、API 网关三个确定性环节，而非依赖模型对自然语言指令的“自觉遵守”。

提示：把技能定义写在提示词里，相当于让保安靠背诵《员工守则》来拦住闯入者——他记得住，但拦不住；记错了，更拦不住。

这已经不是“好不好”的问题，而是“能不能跑通生产环境”的底线问题。某高校实验室曾做过对照实验：在相同硬件和模型版本下，采用 SKILL.md 元数据驱动的 Agent，其技能调用合规率稳定在 99.7%，而纯提示词方案在 7 天压力测试中平均跌至 83.4%，且错误类型高度集中于越权访问和技能误触发。差异不在模型能力，而在系统架构是否承认“技能”是一个需要被独立建模、可验证、可调度的一等公民。

2. SKILL.md：不是文件名，是一套轻量级技能契约协议

SKILL.md 的命名容易让人误解为某种 Markdown 文档规范，但它本质是一份面向机器解析的技能契约（Skill Contract）。它的核心价值不在于人类可读性，而在于提供了一种无需引入复杂 Schema 定义、又能被各类运行时环境（Python CLI、Node.js Agent Core、Rust 边缘网关）一致解析的轻量级元数据格式。我参与设计的某企业级 Agent 平台，正是基于这一理念将 SKILL.md 作为技能注册的唯一事实来源。

2.1 为什么是 Markdown？而不是 JSON/YAML？

初看反直觉：JSON 更易解析，YAML 支持注释，为何选 Markdown？答案藏在工程落地的三个现实约束里：

• 开发者心智负担最小化：前端工程师、产品同学、甚至非技术 PM 都能快速上手编辑。我们曾让 5 名非算法背景的业务方直接编写 SKILL.md，平均学习时间 12 分钟，零语法错误；而同等复杂度的 JSON Schema 编写，平均耗时 47 分钟，且 3 人出现字段嵌套层级错误。

• 天然支持人类可读注释与示例：权限声明requires: ["user.profile.read"]是机器可读的，但下方紧跟的<!-- 示例：仅用于展示用户头像和昵称，禁止获取手机号 -->却是给审核人员看的。Markdown 的 HTML 注释语法（<!-- -->）完美隔离了机器解析与人工审查，而 JSON/YAML 的注释需依赖特定解析器扩展，极易在 pipeline 中丢失。

• 版本控制友好：Git diff 对 Markdown 的变更识别极为清晰。当某次 PR 修改了requires字段，diff 显示为：

  -requires: ["user.profile.read"] +requires: ["user.profile.read", "user.phone.read"]

  而 JSON 的 diff 常因缩进、换行、字段顺序导致大量噪音，增加 Code Review 风险。

注意：SKILL.md 的解析器必须严格遵循“只提取指定 YAML Front Matter 区块”的原则。我们明确规定：所有机器可读元数据必须置于---分隔符之间，其余内容视为纯文档。这避免了“解析器试图理解正文 Markdown 表格”的过度设计陷阱。

2.2 核心字段设计：从声明到执行的完整闭环

一个生产可用的 SKILL.md，绝非只有name和description。我们提炼出 7 个必填/选填字段，构成从技能注册、权限校验到调用执行的完整闭环：

以send_email技能为例，其 SKILL.md 片段如下：

--- name: send_email version: "1.3.0" requires: ["email.send", "contacts.read"] input_schema: type: object required: ["to", "subject", "body"] properties: to: type: array items: { type: "string", format: "email" } minItems: 1 subject: type: string maxLength: 100 body: type: string maxLength: 5000 additionalProperties: false handler: handlers.email.send tags: ["communication", "async"] --- # 发送邮件技能 ## 使用场景 - 向客户发送订单确认邮件 - 向团队成员发送会议纪要 ## 注意事项 <!-- 权限说明：仅允许向已验证的联系人邮箱发送，禁止群发营销邮件 --> <!-- 安全限制：body 内容将经过 XSS 过滤，不支持 HTML 标签 -->

这个设计的关键在于：所有字段都服务于一个目标——让运行时引擎能在毫秒级完成技能准入决策。当用户输入“给张经理发个会议纪要”，Agent Core 收到请求后，执行三步原子操作：

1. 匹配：根据 NLU 结果匹配到send_email技能；
2. 校验：检查当前会话 Token 是否包含email.send和contacts.read权限（缺失任一即拒）；
3. 解析：用input_schema校验用户输入是否满足to/subject/body要求（类型、长度、格式）。

整个过程不依赖 LLM 推理，纯规则判断，P99 延迟 < 15ms。而如果这些逻辑写在提示词里，每次调用都需 LLM 重新“理解”规则，延迟飙升至 800ms+，且结果不可预测。

3. 按需加载：不是性能优化技巧，而是安全与资源的刚性约束

“按需加载”常被理解为前端领域的 bundle splitting 或图片懒加载，但在 Agent 架构中，它是一条关乎系统存亡的安全与资源红线。某金融类 Agent 曾因未实施严格按需加载，在一次营销活动期间遭遇灾难性故障：用户集中触发“投资组合分析”技能，该技能依赖一个 2.3GB 的本地量化模型。由于所有技能在启动时即全量加载，Agent 进程内存占用瞬间突破 16GB，触发 Kubernetes OOMKilled，服务中断 47 分钟。

3.1 加载时机的三种范式：从粗放到精准

我们观察到团队在实践按需加载时，普遍经历三个演进阶段，每阶段对应不同的风险等级：

• 阶段一：启动时全量加载（高危）
  所有技能的 handler 函数、依赖库、模型权重在 Agent 进程启动时一次性初始化。优点是首次调用无延迟；缺点是内存常驻、冷启动慢、权限失控（未授权技能也已获得执行环境）。某公司曾因此泄露内部数据库连接字符串——因一个未启用的db.debug_query技能在启动时已加载了含凭证的 config 模块。

• 阶段二：会话级懒加载（基础）
  Agent Core 维护一个会话上下文（Session Context），当用户首次提及某技能关键词（如“帮我查余额”），才动态 import 对应 handler 并初始化。这解决了内存常驻问题，但仍有隐患：requires权限校验发生在加载之后，攻击者可通过构造恶意输入（如“请执行 db.debug_query with sql=SELECT * FROM users”）诱使系统加载高危技能。

• 阶段三：声明前置的预校验加载（生产级）
  这才是真正安全的按需加载。流程严格分为两步：

  1. 声明解析：Agent Core 仅解析 SKILL.md 中的name、requires、input_schema，不执行任何 handler 代码；
  2. 权限预检：用当前会话 Token 校验requires字段，通过后才进入加载阶段。

这意味着：即使用户输入“执行所有技能”，系统也只会解析所有 SKILL.md 文件，而不会加载任何一个 handler。加载动作永远滞后于权限决策，形成“先验后载”的铁律。

3.2 加载粒度：函数级、模块级还是服务级？

粒度选择直接影响系统弹性。我们通过压测对比了三种方案（均基于 Python + FastAPI 架构）：

关键洞察：不能只看延迟，要看故障爆炸半径。某团队曾为追求低延迟，将所有技能设为函数级加载。结果一个pdf_to_text技能因 PyPDF2 内存泄漏，导致整个 Agent 进程崩溃。改用服务级后，该技能崩溃仅影响自身子进程，主 Agent 仍可降级处理其他请求。

提示：我们的标准是——任何可能阻塞事件循环 > 50ms、或内存占用 > 50MB 的技能，必须走服务级隔离。这不是性能妥协，而是将“一个技能的失败”与“整个 Agent 的存活”解耦的必要代价。

3.3 动态卸载：被忽视的“技能生命周期”管理

按需加载的另一半是按需卸载。很多团队只做加载，却忽略卸载，导致内存缓慢增长。我们强制要求所有技能实现unload()接口，并在以下场景触发：

• 会话超时（默认 30 分钟无交互）；
• 用户明确退出（如输入“结束对话”）；
• 技能执行异常（如 handler 抛出SkillExecutionError）。

卸载逻辑并非简单del module，而是三步清理：

1. 释放模型引用：调用torch.cuda.empty_cache()（PyTorch）或tf.keras.backend.clear_session()（TensorFlow）；
2. 关闭连接池：如数据库连接、HTTP 会话、WebSocket；
3. 清除缓存：删除tempfile.mkdtemp()创建的临时目录。

某电商 Agent 曾因未清理临时图片缓存，运行 72 小时后磁盘占满。加入自动卸载后，单会话平均磁盘占用从 1.2GB 降至 87MB。

4. 权限边界：从“信任但验证”到“零信任执行环”

把权限控制写在提示词里，本质上是一种“信任但验证”（Trust but Verify）的脆弱模型——它假设 LLM 会忠实执行指令，且指令本身无歧义。而生产环境要求的是“零信任执行环”（Zero-Trust Execution Loop）：每个技能调用，都必须经过独立、可审计、不可绕过的权限校验，且校验点必须位于技能执行路径的最前端。

4.1 权限模型的三层防御：Scope、Context、Action

我们采用纵深防御策略，将权限校验拆解为三个不可跳过的环节，形成执行环：

• 第一层：Scope 校验（Token 级）
  验证当前会话 Token 是否包含 SKILL.md 中声明的requires权限。这是最粗粒度的门禁，由 API 网关统一执行。例如，requires: ["email.send"]对应 OAuth2 scopeemail:send。关键点：scope 必须由 Identity Provider（IdP）签发，Agent Core 仅做校验，绝不自行生成或续期。

• 第二层：Context 校验（会话级）
  Scope 通过后，检查当前会话上下文是否满足技能的业务约束。例如，“订单退款”技能要求session.user.tier == "premium"；“内部知识库搜索”技能要求session.source == "internal"（即用户通过内网 IP 访问）。此层校验由 Agent Core 的 Session Manager 执行，结果缓存在内存中，避免重复计算。

• 第三层：Action 校验（调用级）
  最精细的控制。在 handler 函数入口处，对本次调用的具体参数做白名单校验。例如，send_email技能的to参数，必须匹配用户通讯录中已验证的邮箱域名（如仅允许@company.com）；create_calendar_event的attendees列表，人数不得超过session.user.plan.max_attendees。此层校验由 handler 自身实现，确保业务逻辑与权限策略强绑定。

这三层不是叠加，而是短路逻辑：任一层失败，立即终止执行，返回标准化错误（如403 Forbidden: Missing scope 'email.send'），绝不进入下一层。某金融客户曾要求审计所有权限拒绝事件，我们只需监听网关层的 403 日志，即可 100% 覆盖全部越权尝试。

4.2 权限继承与降级：避免“权限雪崩”

一个常见误区是认为“父技能开启，子技能自动可用”。例如，customer_support技能声明requires: ["ticket.read", "ticket.update"]，而其内部调用的escalate_to_manager子技能需要["ticket.escalate"]。若不加控制，customer_support的权限会“污染”子调用，导致escalate_to_manager在未显式授权时也能执行。

我们的解决方案是：所有子技能调用必须显式传递权限上下文，且默认继承被禁用。Agent Core 强制要求：

• 子调用必须通过call_skill(name, input, permissions=["ticket.escalate"])显式声明所需权限；
• 若permissions参数为空，则仅继承当前会话的requires（即父技能声明的权限），不继承会话 Token 的全部 scope；
• 任何permissions数组中的权限，都必须在当前会话 Token 中存在，否则立即报错。

这杜绝了“一个高权限技能打开后门，所有低权限技能趁虚而入”的风险。某政务系统上线前的安全审计中，此机制帮助我们发现了 17 处隐式权限提升漏洞。

4.3 审计与可观测性：让权限决策可追溯、可回放

权限不是黑盒。我们要求所有校验决策必须生成结构化审计日志，包含 5 个强制字段：

• event_id: UUID，唯一标识本次校验事件；
• skill_name: 触发技能名称；
• scope_check: 布尔值，表示 scope 校验结果；
• context_check: 布尔值，表示 context 校验结果；
• action_check: 布尔值，表示 action 校验结果；
• decision: 最终决策（ALLOWED/DENIED_SCOPE/DENIED_CONTEXT/DENIED_ACTION）；
• timestamp: ISO8601 时间戳。

这些日志实时推送至中央审计系统，支持两种关键能力：

• 实时告警：当DENIED_*事件在 5 分钟内超过 100 次，自动触发告警，排查是否遭暴力探测；
• 会话回放：输入会话 ID，即可还原该会话中所有技能调用的完整权限决策链，精准定位是哪一层校验失败。

某次客户投诉“退款功能突然不可用”，我们 3 分钟内通过审计日志定位到：新上线的风控策略在context_check层新增了user.risk_score < 0.8条件，而该用户分数为 0.82。修复策略后，退款功能立即恢复——全程无需重启服务，也无需查看任何代码。

5. 从理论到落地：一个可立即复用的 SKILL.md 工程化模板

纸上谈兵不如动手实践。以下是我们在多个项目中验证过的 SKILL.md 工程化模板，已去除所有业务细节，保留可直接复用的骨架与最佳实践注释。你只需替换<>中的内容，即可生成符合生产要求的技能定义。

--- # ========== 【必填】技能基础信息 ========== name: <skill_name_in_snake_case> version: "<semantic_version>" # 示例：search_knowledge_base # ========== 【必填】权限声明 ========== # 格式：service.action，粒度精确到 API 端点 requires: - "<service_1>.<action_1>" - "<service_2>.<action_2>" # 示例：["knowledge.search", "user.profile.read"] # ========== 【必填】输入校验 ========== # 必须包含 required 字段，additionalProperties: false 为强制 input_schema: type: object required: ["<required_field_1>", "<required_field_2>"] properties: <required_field_1>: type: <string|number|boolean|array|object> # 如为 string，建议添加 maxLength/minLength # 如为 array，建议添加 minItems/maxItems # 如为 email/url，建议添加 format: "email" or "uri" <required_field_2>: type: string maxLength: 200 additionalProperties: false # 示例：见 2.2 节 send_email 片段 # ========== 【选填】输出定义 ========== # 若技能返回结构化 JSON，定义 output_schema 便于前端强类型 # 若返回自由文本，此项留空 # output_schema: # type: object # properties: # summary: # type: string # sources: # type: array # items: { type: "string" } # ========== 【必填】执行入口 ========== # 格式：python 模块路径，从项目根目录开始 handler: <package>.<module>.<function> # 示例：handlers.kb.search # ========== 【选填】发现标签 ========== # 用于技能市场、推荐系统，值需在平台字典中预注册 tags: - "<tag_1>" - "<tag_2>" # 示例：["research", "information_retrieval"] --- # ========== 【文档区】人类可读说明 ========== # 此区域所有内容仅用于文档生成与人工审查，不参与机器解析 ## 技能概述 <用 1-2 句话说明技能核心价值> ## 使用场景 - <场景 1> - <场景 2> ## 输入示例 ```json { "<required_field_1>": "<example_value>", "<required_field_2>": "<example_value>" }

输出示例

{ "summary": "<example_summary>", "sources": ["<source_1>", "<source_2>"] }

注意事项

### 5.1 搭配使用的 CI/CD 校验脚本（Python） 光有模板不够，必须用自动化守住底线。我们在 Git Hook 和 CI Pipeline 中集成以下校验脚本（`validate_skill_md.py`），任何 PR 合并前必须通过： ```python #!/usr/bin/env python3 # validate_skill_md.py import sys import yaml import json import re from pathlib import Path from jsonschema import validate, ValidationError def validate_skill_md(file_path: Path): try: content = file_path.read_text(encoding="utf-8") except UnicodeDecodeError: print(f"❌ {file_path}: 文件编码非 UTF-8") return False # 提取 YAML Front Matter if not content.startswith("---"): print(f"❌ {file_path}: 缺少 YAML Front Matter 分隔符 ---") return False try: front_matter_end = content.find("---", 3) if front_matter_end == -1: raise ValueError("未找到结束分隔符") yaml_content = content[3:front_matter_end].strip() data = yaml.safe_load(yaml_content) except Exception as e: print(f"❌ {file_path}: YAML 解析失败 - {e}") return False # 必填字段校验 required_fields = ["name", "version", "requires", "input_schema", "handler"] for field in required_fields: if field not in data: print(f"❌ {file_path}: 缺少必填字段 '{field}'") return False # name 格式校验 if not re.match(r'^[a-z][a-z0-9_]*[a-z0-9]$', data["name"]): print(f"❌ {file_path}: name 必须为小写字母开头，仅含小写字母、数字、下划线，且不以数字或下划线结尾") return False # requires 非空校验 if not isinstance(data["requires"], list) or len(data["requires"]) == 0: print(f"❌ {file_path}: requires 必须是非空数组") return False # input_schema 校验 if not isinstance(data["input_schema"], dict): print(f"❌ {file_path}: input_schema 必须是 JSON Schema 对象") return False # 检查 required 字段是否存在 if "required" not in data["input_schema"]: print(f"❌ {file_path}: input_schema 必须包含 'required' 字段") return False # 检查 additionalProperties if data["input_schema"].get("additionalProperties", True) is not False: print(f"❌ {file_path}: input_schema 必须设置 additionalProperties: false") return False # handler 路径存在性校验（简化版：检查文件是否存在） handler_parts = data["handler"].split(".") if len(handler_parts) < 2: print(f"❌ {file_path}: handler 路径格式错误，至少需 package.module.function") return False # 检查模块文件是否存在（此处为示意，实际需更严谨的 import 检查） module_path = "/".join(handler_parts[:-1]) + ".py" if not (Path(__file__).parent.parent / module_path).exists(): print(f"❌ {file_path}: handler 模块文件不存在: {module_path}") return False print(f"✅ {file_path}: 校验通过") return True if __name__ == "__main__": if len(sys.argv) < 2: print("用法: python validate_skill_md.py <skill_md_file>") sys.exit(1) success = True for file_path in sys.argv[1:]: if not validate_skill_md(Path(file_path)): success = False sys.exit(0 if success else 1)

将此脚本加入pre-commithook，可确保每个 SKILL.md 文件在提交前就符合规范。某团队接入后，SKILL.md 相关的 CI 失败率从 23% 降至 0.4%，节省了大量人工 Review 时间。

5.2 我的实战经验：三个最容易踩的坑

在数十个 Agent 项目落地过程中，我总结出三个高频、隐蔽、后果严重的坑，务必警惕：

• 坑一：requires字段的“权限膨胀”
  初期为图省事，把requires: ["*"]或["all"]写进 SKILL.md。这等于给技能开了后门。正确做法是：每次新增权限，必须同步更新权限矩阵文档，并由安全团队审批。我们曾发现一个data_export技能因requires: ["db.*"]，意外获得了删除生产表的权限。

• 坑二：input_schema的maxLength未覆盖所有字符串字段
  只给subject设了maxLength: 100，却忘了body字段。结果攻击者发送 10MB 的 base64 图片字符串，导致内存溢出。所有type: string字段，必须显式声明maxLength或minLength，无例外。

• 坑三：handler路径未做静态校验，导致运行时ModuleNotFoundError
  开发者本地测试正常，但 CI 环境缺少某个依赖包，import失败。解决方案：在 CI 中执行python -c "import <handler_module>"，提前暴露导入错误。

最后分享一个小技巧：在SKILL.md的<!-- -->注释中，用@audit标记需定期复查的权限。例如：

<!-- @audit: 2024-Q3 复查是否仍需 user.phone.read --> requires: ["user.profile.read", "user.phone.read"]

这样，审计工具可自动扫描所有@audit标签，生成待办清单，避免权限长期过期。

我在实际使用中发现，坚持这套 SKILL.md 协议 + 按需加载 + 三层权限校验，带来的不仅是稳定性提升，更是一种开发范式的转变——它迫使团队在写代码前，先想清楚“这个能力到底需要什么权限、在什么条件下可用、失败时如何兜底”。这种前置思考，比任何后期补救都有效。