1. 为什么你的 Agent 总是“懂道理但干不好活”
如果你最近在折腾 Agent，大概率遇到过这种场面：模型把任务拆解得头头是道，真到执行环节却开始自由发挥——该调脚本的时候在编命令，该按团队规范走的时候自创流程。这不是模型变笨了，而是它缺一份“程序性知识”的说明书。
AgentSkills 就是冲着这个缺口来的。它用一套开放格式，把“某类任务该怎么做”沉淀成可复用的技能包，核心入口是一个叫 SKILL.md 的文件。你可以把它理解成给 Agent 看的操作手册：平时只露个封面（名称+描述），需要时才翻开正文，正文里再按需引用脚本和参考资料。这套机制叫渐进式披露（Progressive Disclosure），配合 Frontmatter 元数据，让技能既能跨工具复用，又不会一上来就把上下文塞爆。
这篇面向的是准备把 AgentSkills 规范落到自己项目里的开发者：我会拆开 SKILL.md 的 Frontmatter 字段、目录组织方式、渐进式披露的三层结构，给出可直接复制的骨架，并说明在 TaoToken 统一 Key/API 通道下接入 AI 工具时，配置该写在哪、怎么验证结构是否完整。适合谁？手上有多个 Agent 工具、想让技能包一次编写到处运行的人。
2. TaoToken 前置：把 Key 和通道先理顺
AgentSkills 本身是格式规范，不绑定任何平台。但你要真正跑起来验证技能是否被正确加载，总得有个模型通道。我习惯用 TaoToken 做统一入口，原因是它把模型对话、编码类 Agent、API Key 管理放在同一套体系里，切换工具时不用到处改配置。
先明确几个地址，后面配置会反复用到：
- 官网入口：https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=
- API 基址：https://taotoken.net/api
- 模型对话页：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite
- Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite
- 控制台：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite
- API Keys 管理：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite
- 接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite
- ClaudeCodeAnthropic 接入：https://taotoken.net/claudecode-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=claudecode&utm_campaign=rewrite
注意：API 基址不要加 UTM 参数，其余 deep link 建议带上，方便回溯来源。
拿到 Key 之后，你的 Agent 工具（无论是自研脚本还是现成的编码助手）只要把 base_url 指向https://taotoken.net/api，就能用同一把 Key 调用模型。这一步的意义在于：技能包的验证环境是统一的，不会出现“在 A 工具里能激活、在 B 工具里报错”的干扰。
3. 可复制配置：SKILL.md 骨架与目录结构
3.1 标准目录长什么样
每个技能是一个独立文件夹，名字必须和 Frontmatter 里的name完全一致，大小写都不能差。结构如下：
pdf-processing/ ├── SKILL.md # 必需：元数据 + 执行指令 ├── scripts/ # 可选：可执行脚本 │ └── extract.py ├── references/ # 可选：参考文档、API 规范 │ └── api-spec.md └── assets/ # 可选：模板、静态资源 └── report-template.md三条硬约束先记住：目录名等于 name 字段；SKILL.md 正文建议不超过 5000 tokens、500 行；scripts 里的代码不会自动执行，必须由正文指令显式引导调用。
3.2 Frontmatter 字段逐个拆
文件顶部两条---之间是 YAML Frontmatter。必需字段只有两个：
--- name: pdf-processing description: > 处理 PDF 文档的专业技能。适用场景：提取文本、填写表单、 合并拆分文件、OCR 识别扫描件。当用户提到 PDF、表单、扫描件时使用。 ---name的命名规则很严：1-64 字符，只允许小写字母、数字、连字符，不能以连字符开头或结尾，不能出现连续连字符。pdf-processing合法，PDF-Processing、-pdf、pdf--tools都会校验失败。
description上限 1024 字符，但它是渐进式披露第一阶段唯一暴露给 Agent 的信息。Agent 就靠这百来字判断要不要激活技能，所以必须写清三件事：能做什么、何时使用、触发关键词。
可选字段按需加：
--- name:>## 目标 说明这个技能要达成什么结果。 ## 前置条件 运行前需要满足的环境、权限、输入格式。 ## 执行步骤 1. 第一步，具体到命令或文件路径 2. 第二步，说明判断分支 3. 第三步，说明输出位置 ## 输出格式 期望的输出内容和格式规范。 ## 异常处理 常见错误及对应策略。 ## 工具调用 何时、如何调用 scripts/ 中的脚本。写作原则就一条：具体、可执行、消除歧义。“处理好数据”会产生随机结果，“用 pandas 读取 CSV，检查空值列，缺失率超 30% 则删除该列”才能稳定复现。
4. 验证请求：确认技能被正确加载
4.1 结构自查脚本
在技能目录同级跑一段 Python，快速校验命名和 Frontmatter 是否合规：
import re, pathlib, yaml def check_skill(skill_dir: str): p = pathlib.Path(skill_dir) md = p / "SKILL.md" assert md.exists(), "缺少 SKILL.md" text = md.read_text(encoding="utf-8") m = re.match(r"^---\n(.*?)\n---", text, re.S) assert m, "Frontmatter 格式错误" fm = yaml.safe_load(m.group(1)) name = fm.get("name", "") assert re.fullmatch(r"[a-z0-9]+(-[a-z0-9]+)*", name), f"name 不合规: {name}" assert p.name == name, f"目录名 {p.name} 与 name {name} 不一致" assert len(fm.get("description", "")) <= 1024, "description 超长" print(f"OK: {name}") check_skill("./pdf-processing")跑通输出OK: pdf-processing，说明命名和元数据这关过了。
4.2 用统一通道发一次请求
把技能描述拼进系统提示，通过 TaoToken 的 API 基址发一次对话请求，观察模型是否能识别技能：
curl https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-4-20250514", "messages": [ {"role": "system", "content": "可用技能：pdf-processing - 处理 PDF 文档，提取文本、填表单、合并拆分、OCR。"}, {"role": "user", "content": "帮我把这份扫描件里的文字提取出来"} ] }'如果返回内容里模型主动提到要调用 pdf-processing 或询问文件路径，说明 Discovery 层生效了。这一步在模型对话页也能手动验证，省去写脚本的功夫。
4.3 渐进式披露的三层验证
+------------------------------------------+ | Discovery 层（常驻） | | 每个技能约 10 tokens：name + description | +------------------------------------------+ | Activation 层（任务匹配时加载） | | 完整 SKILL.md 正文，< 5000 tokens | +------------------------------------------+ | Execution 层（执行时按需加载） | | references/ 文档、scripts/ 脚本按需读取 | +------------------------------------------+验证方法：先只注入 description，看模型能否判断该用哪个技能；再注入完整正文，看步骤是否被遵循；最后在正文里引用 references 文件，看模型是否按需读取而不是一次性全读。三层都通过，结构就算完整。
5. 本篇常见错排查
目录名和 name 不一致：最常见。name: pdf-processing对应目录必须叫pdf-processing，写成PDF-Processing或pdf_processing都会失败。校验脚本里那句p.name == name就是防这个。
description 写成功能清单：只写“处理 PDF”太泛，Agent 匹配不上。要带触发场景和关键词，比如“当用户提到 PDF、表单、扫描件时使用”。
正文超 5000 tokens：说明细节该拆到 references 里了。把 API 规范、风格指南这类长文档挪出去，正文只留步骤和引用路径。
scripts 不执行：脚本不会因为技能被激活就自动跑。必须在正文“执行步骤”里明确写“运行 scripts/xxx.sh”，Agent 才会调用。
allowed-tools 写太宽：Bash(*)这种全放开会带来风险，尽量收窄到具体命令前缀，比如Bash(python:*)。
接入时报 401：先确认 Key 是从 API Keys 页面生成的，且 base_url 用的是https://taotoken.net/api不带多余路径。接入文档里有各语言的完整示例，对照检查最快。
6. 把技能包接进你的工作流
结构验证通过后，下一步是让它真正参与日常。如果你主要做长期编码或 Agent 编排，Coding Plan 那条线更适合，技能包可以跟着项目走版本控制；如果只是临时验证某个技能的行为，模型对话页直接贴 description 试最快。
统一 Key 的好处在这里体现得很明显：技能包本身是平台无关的，换工具时只要改 base_url 和 Key，SKILL.md 一个字都不用动。可移植性和渐进式披露这两根支柱，前者让技能跨平台流通，后者让几百个技能同时待命也不撑爆上下文。
我自己的习惯是每个技能目录配一个check_skill脚本，提交前跑一遍，命名和 Frontmatter 的问题在本地就拦掉，别等到 Agent 加载失败再回头查。