01 AgentSkills 核心规范与标准结构详解关键词AgentSkills、SKILL.md、渐进式披露、可移植性、Agent 开放标准、技能目录结构、Frontmatter、Progressive Disclosure、Portability一、时代背景Agent 的执行力困境大模型的推理能力在过去两年经历了质的飞跃——链式思维、工具调用、多步规划这些能力的组合让 Agent 看起来似乎已经无所不能。但一线工程师的体感往往截然不同你搭了一个 Agent它能把问题分析得头头是道却在动手执行时一塌糊涂。问题出在哪里根本原因在于推理能力与执行知识的分离。模型知道要解析 PDF却不知道用什么工具、按什么格式、处理边界情况时该走哪条分支模型懂得要发布一个 npm 包却不清楚团队内部的发布流程、必须跑哪些检查项、changelog 要写到哪里。这些**程序性知识Procedural Knowledge**散落在文档、wiki、老员工的记忆里很难通过提示词临时塞给模型。2025 年Anthropic 在推出 MCP 协议之后面向这个痛点提出了另一套开放标准——Agent Skills。二、什么是 Agent SkillsAgent Skills 官方的定义很克制“A simple, open format for giving agents new capabilities and expertise.”一个 Skill就是一个文件夹。里面有指令、有脚本、有参考资料按照规定的结构组织好Agent 就能在需要的时候加载它按照其中的步骤完成任务。这个定义看似简单背后却蕴含着两个关键的设计哲学。2.1 可移植性Portability传统的 Agent 能力扩展方式往往和平台强耦合给 Claude Code 写的系统提示在 Cursor 里未必能用Dify 的工作流搬到 LangChain 里要重写一遍。Agent Skills 用文件夹的方式解决了这个问题。一套规范化的目录结构让技能变成平台无关的知识包。你为某个流程写的技能理论上可以在支持该标准的任何 Agent 平台上直接使用无需改写。这和 USB-C 的逻辑一样——不是让每个设备都重新设计接口而是定义一个大家都认的标准让能力可以像积木一样自由组合、自由迁移。2.2 渐进式披露Progressive Disclosure上下文窗口是 Agent 最稀缺的资源。如果把 100 个技能的完整文档全部塞进系统提示不等 Agent 开始工作Token 预算就耗尽了。Agent Skills 的设计方案是分层加载按需取用。平时只把技能的名字和描述约 100 tokens/个放在上下文里供 Agent 感知有哪些牌可以出。任务匹配上了才把对应技能的完整指令SKILL.md 正文上限 5000 tokens加载进来。执行过程中如果需要参考资料或脚本再按需读取。这样就算管理几百个技能Agent 的上下文也不会因为知识库太大而崩溃。三、标准目录结构每个技能是一个独立的目录结构如下skill-name/ ├── SKILL.md # 必需元数据 执行指令5000 tokens500 行 ├── scripts/ # 可选可执行脚本Python、Bash、Node.js ├── references/ # 可选参考文档、API 规范、领域知识 └── assets/ # 可选模板文件、静态资源这个结构背后有几条硬性约束目录名必须等于name字段。SKILL.md里 frontmatter 写的是name: pdf-processing对应的目录就必须叫pdf-processing大小写不一致会导致校验失败。SKILL.md 大小有上限。规范要求正文不超过 5000 tokens、不超过 500 行。这个限制并非任意设置——它对应渐进式披露第二阶段的预算超出这个范围就该把细节拆到 references 目录里。scripts 里的代码不会自动执行。Agent 会按照 SKILL.md 指令的引导在需要时调用对应脚本而不是加载技能就全量运行。四、SKILL.md 文件格式详解SKILL.md 是技能包的心脏由两部分构成YAML Frontmatter 和 Markdown 正文。4.1 YAML Frontmatter文件顶部三条横线之间的部分就是 frontmatter负责描述技能的元数据。必需字段---name:pdf-processingdescription:处理 PDF 文档的专业技能。适用场景提取文本、填写表单、 合并/拆分文件、OCR 识别扫描文档。---name字段的命名规则很严格长度 1-64 字符只允许小写字母、数字、连字符-不能以连字符开头或结尾不能出现连续连字符--正确示例pdf-processing、code-review-v2、incident-response错误示例PDF-Processing大写、-pdf以连字符开头、pdf--tools连续连字符description字段上限 1024 字符但实践中写好这个字段比写好正文更重要。因为它是渐进式披露第一阶段唯一暴露给 Agent 的信息——Agent 就靠这 100 来个字决定要不要激活这个技能。好的 description 应该包含能做什么、何时使用、关键词触发条件。可选字段---name:data-analysisdescription:数据清洗、统计分析与可视化。处理 CSV/Excel 结构化数据时使用。license:Apache-2.0compatibility:需要 Python 3.10依赖 pandas2.0、matplotlibmetadata:author:data-infra-teamversion:2.1tags:[analytics,visualization,pandas]allowed-tools:Bash(python:*)Read Write---各字段含义字段说明licenseSPDX 标识符MIT、Apache-2.0 等或引用文件路径compatibility运行环境要求上限 500 字符metadata任意键值对用于版本、作者、标签等扩展信息allowed-tools预授权工具白名单实验性字段减少执行时的确认提示4.2 Markdown 正文Frontmatter 结束后剩下的部分就是给 Agent 看的执行指令。这里没有固定格式但高质量的指令正文通常遵循这个结构## 目标 说明这个技能要达成什么结果。 ## 前置条件 列出运行前需要满足的条件环境、权限、输入格式等。 ## 执行步骤 1. 步骤一... 2. 步骤二... 3. 步骤三... ## 输出格式 描述期望的输出内容和格式规范。 ## 异常处理 常见错误情况及对应的处理策略。 ## 工具调用 说明何时、如何调用 scripts/ 中的脚本。指令正文的写作原则具体、可执行、消除歧义。模糊的指令“处理好数据”会产生随机结果清晰的步骤“用 pandas 读取 CSV检查空值列超过 30% 缺失率则删除该列”才能稳定复现。五、渐进式披露的三阶段模型这个机制是 Agent Skills 最核心的技术创新值得单独展开说清楚。-------------------------------------------------- | 整体上下文窗口 | | | | -------------------------------------------- | | | Discovery Layer常驻 | | | | skill-1: ~10 tokens (名称描述摘要) | | | | skill-2: ~10 tokens | | | | skill-N: ~10 tokens | | | -------------------------------------------- | | | | -------------------------------------------- | | | Activation Layer任务匹配时加载 | | | | 完整 SKILL.md 正文 5000 tokens | | | -------------------------------------------- | | | | -------------------------------------------- | | | Execution Layer执行时按需加载 | | | | references/xxx.md按需读取 | | | | scripts/xxx.py按需执行 | | | -------------------------------------------- | --------------------------------------------------阶段一Discovery发现系统启动时SkillRegistry 扫描技能目录只把每个技能的name和description汇总成一份 Skills Catalog 注入上下文。这个开销极小——100 个技能大约只需要 1000 tokens。Agent 可以随时查阅这份目录判断当前任务是否需要某个技能。阶段二Activation激活当 Agent 判断当前任务与某个技能匹配时触发激活。此时才把该技能的完整 SKILL.md 正文加载到上下文。触发方式有两种LLM 自主判断模型基于描述推理出需要用某个技能关键词匹配平台层面预设规则如用户消息包含合并 PDF时自动激活 pdf-processing。阶段三Execution执行执行指令时如果步骤中引用了 references 目录的文档才读取对应文件如果需要运行脚本才执行 scripts 目录下的代码。这种懒加载策略确保了上下文只包含当前真正需要的内容。六、一个完整示例代码审查技能把上面的内容串起来看一个实际的技能包。目录结构code-review/ ├── SKILL.md ├── references/ │ ├── style-guide.md │ └── security-checklist.md └── scripts/ └── lint_check.shSKILL.md---name:code-reviewdescription:执行结构化代码审查。适用场景Pull Request 审查、提交前检查、 安全审计。输出标准化审查报告包含问题分级和修改建议。license:MITmetadata:author:platform-teamversion:1.0allowed-tools:Bash Read---## 目标对提供的代码变更执行系统性审查输出包含问题分级的结构化报告。## 前置条件-代码变更范围已明确diff 或文件路径-已了解项目使用的语言和框架## 执行步骤1. 阅读 references/style-guide.md 了解代码风格规范 2. 运行 scripts/lint_check.sh 执行静态分析 3. 对照 references/security-checklist.md 检查安全项 4. 按照 P0/P1/P2 三级对发现的问题进行分类 5. 为每个问题提供具体的修改建议附带代码示例## 输出格式### 审查摘要-总体评级[通过/条件通过/不通过]-发现问题数P0 N 个 / P1 N 个 / P2 N 个### 详细问题列表每个问题包含文件路径、行号、问题描述、建议修改。## 异常处理-若 lint 工具未安装跳过自动检查仅执行人工审查-若文件过大1000 行分段处理每段单独输出这个技能包大约 350 tokens远低于上限。只要描述写准确Agent 在用户提到帮我 review 这段代码时就会自动激活它。八、小结Agent Skills 并不复杂——本质上就是一个规范化的文件夹加上一套加载机制。但它解决的问题很真实让程序性知识变得可移植、可版本控制、可按需调用。可移植性和渐进式披露是整个标准的两根支柱。前者让技能跨平台流通后者让技能的存在不增加额外的上下文负担。这两点结合起来才让数百个技能同时待命零成本常驻成为可能。下一篇将深入渐进式披露的技术实现——SkillRegistry 的内部机制、Token 预算控制策略以及多技能协同时的上下文切换问题。