引言：一次没有模型权重的开源

2026 年 9 月 4 日，Anthropic 在 GitHub 上线了 anthropics/skills 公共仓库，当日冲上 Trending 榜单。这个仓库里没有权重文件，也没有推理框架，核心资产是一批按目录组织起来的文件夹。每个文件夹里躺着一个 SKILL.md 文件，仓库 README 开篇就声明这是 Anthropic 对 Agent Skills 的实现。规范本体在 agentskills.io，实现与标准之间刻意划出了一条清晰的边界线，实现侧与标准侧互不越界。

就是这样一个 Markdown 文件，正在成为 Claude Code、OpenAI Codex、Cursor、GitHub Copilot 与微软 Agent Framework 共同遵守的技能格式。同一份技能文件可以在不同厂商的 Agent 之间迁移，不需要为每家重写一遍适配层，这在一年前还难以想象。格式层面的统一意味着技能资产第一次变成了可携带的工程产物，不再是锁死在某个产品里的私有配置。这是技能资产走向标准化的起点。

本文拆解这份官方参考实现，重点看三件事。第一是 SKILL.md 的字段约束，第二是渐进式披露背后的上下文账本，第三是与 MCP 的职责分工。最后给出一个可运行的技能包实例，看标准如何落成可复制的工程产物。账号此前讨论过 Agent Skills 与 MCP 的分层关系，这次我们聚焦实现层，看工程师从这份开源里能直接抄走什么。

一、一个 Markdown 文件凭什么成为跨厂商标准

按 agentskills.io 规范，一个技能是至少包含 SKILL.md 文件的目录，目录名就是技能名。文件以 YAML frontmatter 开头，后接自由格式的 Markdown 正文，整体建议控制在 500 行以内。详细资料拆到引用文件里按需加载，最简形式的技能目录只有一个文件。其余一切皆可选，这个极低的入场门槛是技能能被大规模采纳的第一原因。

frontmatter 只有两个必填字段，即 name 与 description。name 是技能的唯一标识符，description 描述技能做什么、什么时候用，它直接决定了 Agent 会不会在某个任务里激活这个技能。这两个字段是整个触发系统的输入信号，规范刻意不加第三个必填字段。license、compatibility、metadata 全部可选，连实验性的 allowed-tools 也只做预批准，不参与必填校验，也不会阻塞技能加载。

name 的约束相当严格，1 到 64 个字符，仅限小写字母数字与连字符。正则要求是 ^[a-z0-9]+(-[a-z0-9]+)*$，禁止前导、尾随或连续连字符，还必须与父目录名完全一致。任何一条不满足，技能就不会被识别。这套正则把命名空间锁死在 ASCII 范围，规避了跨平台文件系统的编码差异。这是格式能稳定迁移的底层保障，也是新手最常见的失败点。

description 的长度上限是 1024 个字符，规范建议以动词开头，例如提取合同中的金额与截止日期。这段文字出现在工具选择器与规划器推理里，写得好坏直接决定技能被调用的频率。实践经验是两句话结构，第一句说清实现什么，第二句说清何时使用。触发信号密度比文采重要得多，空泛描述会让技能永远等不到激活。

触发机制是这套格式的灵魂，Agent 启动时只读取 name 与 description 两份元数据。正文在技能被激活后才加载，一百个技能在会话里共存也只消耗约一万个 token 的元数据。上下文窗口不会被撑爆，这是技能系统与系统提示词体系最本质的架构差异。把加载成本从常驻降到按需，是渐进式披露的直接体现。

五家主流厂商的采纳让这套格式成了事实标准，Claude Code 从本地目录加载技能。Codex 与 Cursor 读取工作区里的 SKILL.md，Copilot 遵守相同的 frontmatter 约定，微软 Agent Framework 也实现了同一规范。标准比任何单一平台都大，这是它最值钱的地方。对开发者而言，写一次技能、到处运行的目标，第一次有了真实落地的格式底座，迁移也有了统一参照。

二、仓库里放了什么：skills、spec、template 三层结构

anthropics/skills 仓库的顶层目录划分得很清楚，./skills 放技能示例，./spec 放 Agent Skills 规范本身，./template 放模板技能。三个目录分别回答能做什么、标准是什么、从哪里起步，结构本身就是一份使用说明。README 里还给了目录浏览指引，把四类示例的导航路径直接写出来。这降低了陌生开发者的进入成本，也展示了官方期望的仓库组织方式。

示例技能按用途分了四大类，即创意与设计、开发与技术、企业与沟通、文档类。它们横跨完全不同的任务形态，从生成品牌规范文档，到测试 Web 应用、生成 MCP Server，再到处理个人自动化任务。每个示例都在示范一种组织模式，读者按图索骥就能找到最接近的参考。四类划分本身就是官方对使用场景的完整归类。

每个技能完全自包含，不依赖仓库里的其他文件，这是技能可移植的前提。把目录整个复制到另一个项目的 .claude/skills 下，功能不变，这是文件级标准相对接口级标准最朴素的优势。依赖外置意味着复制时得连依赖一起搬，自包含则让复制即用成为可能。这条原则也写进了官方对脚本的自包含要求。

spec 目录是规范本体，与 agentskills.io 网站内容对应，定义了目录结构、frontmatter 字段、脚本与引用文件的组织方式。规范用词刻意保持最小，可选目录只有 scripts、references、assets 三个，且全部非必需。scripts 放可执行代码，references 放按需阅读的技术文档，assets 放模板、图像与数据文件。职责划分一读即明，没有给模糊地带留空间，新手也不会用错。

template 目录则提供了一个可以直接复制的起点，frontmatter 只含 name 与 description 两个字段。正文给了几条使用示例和指南占位，从模板起步而不是从空白文件起步，能避开最常踩的名称合规坑。官方还维护了创建技能的支持文档，把字段约束与上传流程固化成可检索的知识。这避免了开发者反复踩同样的命名错误。

值得注意的细节是文件引用规则，SKILL.md 里引用其他文件时使用相对路径，且保持在一层深度以内。规范明确建议避免深层嵌套的引用链，每深一层，路径解析成本和出错概率都会上升。规范原文用的是保持引用一层深这个表述，在以建议为主的文档里属于少见的硬性要求。这直接关系到按需加载的性能。

三、渐进式披露：三层加载的上下文账

渐进式披露是这套规范里最值得抄的工程思想，它把技能的加载成本拆成三个层级。第一层是元数据，约 100 个 token，包括 name 与 description，在会话启动时为所有技能加载，用于触发判断。第二层是指令，即 SKILL.md 的正文，建议控制在 5000 个 token 以内，在技能被激活时整份加载。第三层是资源，只在执行过程中按需读取。

这个设计直接回应了上下文窗口的成本问题，如果每个技能都完整加载，五十个技能就能吃满 10 万 token 的上下文。Agent 的推理质量会断崖式下跌，多技能共存几乎不可能。拆成三层后，绝大多数技能在绝大多数会话里只付出 100 token 的元数据开销。资源文件读多少取决于任务实际需要多少，成本与使用严格挂钩。

对应到创作实践，规范给出的指引是把 SKILL.md 保持在 500 行以内，详细的技术参考拆到 references 目录。模板与示例数据放进 assets，可执行逻辑写进 scripts，正文只保留触发和引导所需的最小指令集。判断标准是删掉这段内容技能还能不能跑，能跑就不该留在主文件里。这个标准可操作性强，写的时候随时可以自检。

菜单模式是渐进式披露的高级用法，SKILL.md 只写概述和目录索引，把三条完整工作流拆成三个子文件。Agent 根据当前任务只读取相关子文件，上下文消耗与任务复杂度严格成正比。这套模式适合指令总量超过 5000 token 的复杂技能，避免激活一次就吃满预算。主文件加子文件的组合，让单技能也可以按需展开。

这套分层逻辑与账号常写的 harness 设计一脉相承，控制面保持轻量，执行面按需膨胀。技能文件不是越大越好，而是越结构化越好，每一层都要回答现在真的需要我吗。对 Agent 应用来说，上下文是唯一不可再生的资源。渐进式披露本质上就是给上下文预算做精细的成本核算，值得每个 Agent 团队直接抄走。

四、SKILL.md 与 MCP 的分工：操作手册与工具协议

社区常把技能与 MCP 混为一谈，但两者回答的问题完全不同。SKILL.md 回答这个服务怎么用，MCP 清单回答这个服务器暴露了哪些工具，OpenAPI 回答接口的参数 schema 是什么。三者分层而非对立，技能定义行为流程，工具协议定义能力接口。前者管何时做、怎么做，后者管能调什么、怎么调，职责边界相当清晰。

可以这样理解，SKILL.md 是操作手册层，OpenAPI 是模式层，MCP 是工具调用层。一个 Agent 面对陌生服务时，先读 /skill.md 学会调用方式，再查 OpenAPI 拿到参数定义。最后通过 MCP 或直接 HTTP 执行动作，各层各司其职。技能文件把端点的认证模型、请求形态与调用时序一次性写清，省去模型在对话里反复试探的成本，也降低了出错概率。

实践中两者经常组合使用，SKILL.md 告诉模型该调哪个端点、何时调，OpenAPI 提供正式的参数 schema。技能把何时用、怎么用固化成指令，MCP 把能调什么暴露成接口，前者决定行为，后者决定能力边界。一个完整的 Agent 应用通常同时接入两者。MCP Server 提供工具，技能目录提供业务知识与操作流程，缺一不可，组合使用才是完整形态。

与遗留的 ai-plugin.json 相比，SKILL.md 的优势是零协议握手，Agent 请求文档根路径下的 /skill.md。解析 frontmatter，校验名称，把正文当指令读，全程不需要注册中心或鉴权流程。发现成本低到几乎可以忽略，这解释了它为什么能在一年内获得五家厂商支持。同样定位的旧格式逐渐退场，就是因为多了那层不必要的握手。

对工程师的启示是，给 Agent 用的接口文档应该先解决怎么用，再解决有什么。很多团队的 MCP Server 做得很好，却缺少一层操作手册，模型能调用工具但不知道业务上什么时候该用。技能恰好补上这层缺失，把高频操作流程固化成文件。文件可以进版本库做评审，比反复优化系统提示词更可维护，长期成本更低。

五、从模板到生产：技能的工程化工作流

Anthropic 官方把创建技能总结为六个步骤，顺序很反直觉，先设计文件架构，再写资源文件，最后才写 SKILL.md 正文。因为正文是胶水层，必须引用真实存在的脚本，先写指令再补资源，很容易写出指向空文件的悬空引用。官方文档把这一步列为标准工作流的起点，这个顺序值得直接抄走。新作者照做能少走大量弯路。

第二步的架构决策遵循自由度原则，确定性任务用脚本，创造性任务用提示词。比如固定格式的文件转换，逻辑写进 Python 脚本，模型只负责调用，品牌文案这类开放任务则把规范与范例写进指令。自由度判断标准很直接，同一输入是否应产生同一输出，是就写脚本，不是就写指令。这个二分法不会用错。

YAML frontmatter 不要手写，用脚手架脚本生成，官方推荐维护一个生成脚本。把 name、description、license 等字段的参数化配置变成标准输出，从源头保证格式合规，避免下划线、大写字母这类最常见的命名错误。脚手架脚本同时能校验目录名与 name 字段的一致性。这等于把规范约束提前到编写阶段而非运行阶段，纠错成本大幅下降。

上传路径分两种，Claude Code 开发者把技能目录放进全局目录或项目目录，Agent 自动发现加载。Claude 应用用户把技能目录打包成 ZIP 上传，团队版还需管理员先在组织设置里启用技能能力。两种路径的发现机制完全不同，前者基于文件系统扫描，后者基于应用内上传与权限配置。集成前必须确认目标环境的加载方式。

API 场景则是两步走，先通过 /v1/skills 接口上传技能文件，再在 Messages 请求里按 skill_id 与 version 引用。只上传不引用，普通请求不会自动启用技能，这个先后顺序是集成时最常踩的坑。API 场景还要同时启用 Skills、Files API 与代码执行相关的能力开关。任何一个缺失都会静默失败，排查时先检查这组开关，再往下追网络层，逐项核对。

上传命令需要携带 skills 相关的 beta header，例如 anthropic-beta: skills-2025-10-02，代码执行还要额外声明。header 缺失时技能接口直接返回空结果，排查时优先检查这一项。这些细节在官方文档里都有明确记载，但分散在多个页面。集成工程师最好提前整理成一张核对清单，逐项过一遍再联调，避免在联调阶段浪费时间，把已知坑提前排掉。

六、可运行的技能包：SKILL.md 与 scripts 组合实例

理论讲完，直接看一个可落地的技能包，下面是一个 csv-audit 技能。目录里只有 SKILL.md 和一个 Python 脚本，脚本读取 CSV 文件，输出行列数与空值统计，是典型的确定性任务写脚本范式。整个技能只依赖 Python 标准库，不引入任何第三方包。在任何有 Python 3 的环境里都能直接运行，这是技能可移植性的最小验证，也是入门的最短路径。

csv-audit/
├── SKILL.md
└── scripts/
    └── audit.py

SKILL.md 的 frontmatter 只声明 name 与 description，正文用最少的指令说明触发条件、脚本用法与输出格式。description 以动词开头，直接告诉 Agent 什么时候该激活。正文里只有用法一行命令与输出格式的三条说明，其余细节全部由脚本自己负责。主文件保持轻薄是渐进式披露的落地示范，技能本身就是一个活教材，示范了标准要求的全部要素。

---
name: csv-audit
description: 审计 CSV 文件的结构质量，输出行列数与空值统计，在清洗数据前调用
---

# CSV Audit

读取 CSV 文件并输出审计报告，用于数据清洗前的质量检查。

## 用法

python scripts/audit.py --file 路径.csv

## 输出格式

- 总行数与总列数
- 每列非空值比例
- 疑似重复行的数量

import argparse, csv, sys

def main():
    ap = argparse.ArgumentParser(description="Audit a CSV file")
    ap.add_argument("--file", required=True)
    args = ap.parse_args()
    rows = list(csv.reader(open(args.file, encoding="utf-8-sig")))
    if not rows:
        print("EMPTY_FILE"); sys.exit(1)
    header, body = rows[0], rows[1:]
    width = len(header)
    nonempty = [0] * width
    for r in body:
        for i, cell in enumerate(r[:width]):
            if cell.strip():
                nonempty[i] += 1
    print(f"ROWS={len(body)} COLS={width}")
    for i, h in enumerate(header):
        print(f"{h}={nonempty[i] / len(body):.1%}")
    seen, dup = set(), 0
    for r in body:
        k = tuple(c.strip() for c in r)
        if k in seen:
            dup += 1
        seen.add(k)
    print(f"DUPLICATES={dup}")

if __name__ == "__main__":
    main()

这个脚本值得注意的有三点，用 utf-8-sig 兼容带 BOM 的 Excel 导出文件，空值按 strip 后的字符串判断，重复行以整行归一化内容为键。任何一步漏掉，结果都会和预期偏差，这类边缘处理正是脚本与提示词的差异所在。空文件时直接打印 EMPTY_FILE 并返回退出码 1，把异常状态显式暴露给调用方。脚本不吞错误，Agent 才能做出正确决策。

脚本的自包含性是工程关键，它不依赖第三方库，标准库即可运行，错误时给出明确退出码。技能里的脚本面向未知运行环境，依赖越少，可移植性越强，这正是技能包与一次性脚本的本质区别。官方对 scripts 的要求同样是自包含或清楚记录依赖，并给出有用的错误信息。这些要求读起来像常识，写起来最容易偷懒。

把这段技能放进项目的 .claude/skills 目录，Claude Code 就会在收到数据清洗任务时自动激活它。同样的目录复制到 Codex 的工作区，行为保持一致，跨平台复用的价值在这一步真正兑现。这也是读者能立即上手的路径，复制示例、替换脚本、跑通一次真实任务。技能开发的全流程就完成了闭环，后续优化可在稳定基线上逐步进行。

这个例子的意义不止于演示语法，它展示了技能设计的完整决策链。目录结构、字段填写、脚本边界、错误处理，每一步都有明确依据而不是拍脑袋。把这套决策过程沉淀成团队规范，新技能的质量下限就能被整体抬高。技能开发的竞争力，最终来自这种可复制的工程习惯。

七、跨厂商采纳背后的三个信号

第一个信号是标准正在赢过平台，同一份 SKILL.md 能被五家产品读取。技能资产不再绑定单一厂商，开发者为 Claude 写的技能可以直接迁移到 Codex 与 Cursor 环境。迁移成本从重写适配层降为复制目录，这是生态级的分水岭。历史上每次出现这种情况，都是基础设施走向成熟的前兆，Agent 技能正处在同样的拐点上。

第二个信号是能力封装从接口下沉到文件，过去 Agent 的能力靠系统提示词、微调或专用接口承载。如今一个带 frontmatter 的 Markdown 文件就能定义可复用的任务能力，封装单元从代码与权重变成了文档加脚本的组合。迭代与分发都轻了一个数量级，技能可以像代码一样评审、版本化与回滚。这是治理层面的巨大进步。

第三个信号是厂商开始用开源争夺开发者心智，Anthropic 开源技能仓库与之前开源 MCP 规范是同一策略。先定标准，再给参考实现，让生态在自家格式上生长，规范文件本身没有护城河。率先被广泛采纳的格式才是护城河，后来者不如在既有标准上做深做透。借生态的势能放大自身，远比对抗标准更划算。

对观望者的启示是，现在开始把团队里的重复 Agent 任务沉淀成技能，等于在标准成型期低价买入兼容性资产。等格式彻底固化后再补课，历史包袱会重得多，因为存量技能文件的迁移成本远比新建要高。技能资产会随时间复利增长，每沉淀一个就少一次重复搭建。这是投入产出比最高的时机窗口。

风险同样存在，allowed-tools 字段仍标记为实验性，各实现对该字段的支持并不一致。Microsoft Agent Framework 的语义与 Anthropic 官方实现也有细微差别，跨厂商迁移前必须用目标环境实测一遍技能行为。不能只看格式兼容就以为万事大吉，技能生态的标准化还远未完成。提前锁定单一实现细节反而会降低可移植性，保持克制是必要的。

八、给开发者的三条落地建议

第一条是从官方 template 起步，不要从零写 frontmatter，模板已经避开命名合规坑。只需替换 name 与 description 并填充正文，就能得到一个可被五家产品识别的技能。先让技能跑起来，再谈优化触发率，避免被字段细节拖住。命名规则、描述长度这些约束一次踩过之后，第二第三个技能的速度会快很多，边际成本迅速下降。

第二条是把确定性逻辑写进 scripts，让 SKILL.md 保持轻薄。文件转换、数据校验这类稳定任务交给脚本，模型只负责调用与组合。开放创作类任务才把规范写进指令，判断标准很简单，同一输入是否应得到同一输出。脚本负责可重算的逻辑，指令负责需要判断的策略，两者分开后调试成本会显著下降。

第三条是先做最小技能验证全链路，再扩充资源目录，把第一个技能放进 .claude/skills 后。用真实任务验证触发、指令加载、脚本执行三个环节，确认无误后再添加 references 与 assets。避免一次引入过多变量无法定位问题，最小闭环跑通后，复制模板扩充到同类场景。效率远高于每写一个技能就从头验证一次，节奏感很重要。

最后回到成本视角，技能的本质是用结构换上下文，三层加载让 Agent 在 10 万 token 窗口内同时持有几十个技能仍有余裕。对 Agent 开发者，这是当前性价比最高的能力组织方式，值得在下一迭代优先落地。Anthropic 把参考实现开源，把最好的实践摆到了开发者面前。剩下的问题只有一个，你什么时候开始写第一个技能。