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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 基址https://taotoken.net/api模型对话页https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewriteCoding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteAPI Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewriteClaudeCodeAnthropic 接入https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite注意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(encodingutf-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), fname 不合规: {name} assert p.name name, f目录名 {p.name} 与 name {name} 不一致 assert len(fm.get(description, )) 1024, description 超长 print(fOK: {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 tokensname 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 和 KeySKILL.md 一个字都不用动。可移植性和渐进式披露这两根支柱前者让技能跨平台流通后者让几百个技能同时待命也不撑爆上下文。我自己的习惯是每个技能目录配一个check_skill脚本提交前跑一遍命名和 Frontmatter 的问题在本地就拦掉别等到 Agent 加载失败再回头查。