一个高质量的 Skill 应该长什么样：从 SKILL.md 到 references 的配置骨架

1. 为什么你的 Agent 总是“差点意思”从一次代码审查说起你让 AI 帮你做代码审查它看了一段代码给出了几条通用建议“变量命名可以更清晰”、“建议加单元测试”、“考虑异常处理”。说得都对但没什么用——它不知道你项目的规范Service 层禁止直接调用 Mapper、Controller 不允许写业务逻辑、所有接口必须返回统一的ResultT格式。你补充了这些背景知识AI 的审查结果立刻好了很多。但下次开新对话你又得重新说一遍。这个场景几乎每个做 Agent 落地的人都遇到过模型能力没问题缺的是“领域知识”的稳定注入方式。Skill 就是解决这个问题的工程化载体——它是一份给 AI Agent 看的“专家手册”把特定领域的知识、流程、约束写成 Agent 能理解的结构化文档Agent 遇到相关任务时自动加载。一个高质量的 Skill 不是“写了就行”而是“Agent 读完就能干活”。这篇文章聚焦 Agent Skill 的工程化落地以SKILL.md的description与references/组织为主线给出可复制的目录结构与配置骨架并说明如何用 TaoToken 统一 Key/API 通道接入 AI 工具。适合正在做 Agent 应用、想让 Skill 从“能跑”到“稳定可维护”的开发者。2. 前置准备用 TaoToken 统一 Key 与 API 通道在写 Skill 之前先把接入层理顺。做 Agent 开发最烦的一件事是不同工具、不同模型、不同 SDK 各有一套 Key 和 Base URL环境变量散落各处换一个模型就要改一遍配置。我的做法是用 TaoToken 统一管理 Key 和 API 通道让 Skill 的加载验证、模型对话、编码 Agent 都走同一个入口。TaoToken 的定位是统一的模型 API 接入层官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 这个地址不加 UTM 参数直接用于代码里的 base_url。你需要先拿到一个 API Key。进入控制台创建控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content创建后把 Key 写进环境变量不要硬编码到 Skill 文件里。Skill 是给 Agent 读的知识文档Key 是运行时凭证两者必须分离。下面这段是通用的环境变量配置# 写入 shell 配置macOS/Linux 用 ~/.zshrc 或 ~/.bashrc export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/apiWindows PowerShell 用$env:TAOTOKEN_API_KEYsk-你的key $env:TAOTOKEN_BASE_URLhttps://taotoken.net/api如果你用的是 Claude Code 这类编码 AgentTaoToken 提供了对应的接入文档配置方式在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里有说明。ClaudeCodeAnthropic 的专用接入页在 https://taotoken.net/ClaudeCodeAnthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 按文档把 base_url 指向 TaoToken 即可不用改 Skill 本身的任何内容。注意Skill 文件里只写“如何调用模型”的说明不写 Key。Agent 执行时从环境变量读取这样 Skill 可以安全地提交到 Git 仓库。3. 可复制的 Skill 目录结构与 SKILL.md 骨架3.1 目录结构分层是核心一个 Skill 就是文件系统上的一个文件夹。最简单的 Skill 只需要一个SKILL.md但高质量的 Skill 一定是分层的。下面这个结构可以直接复制code-review/ ├── SKILL.md # 必须主文件Agent 触发后第一个读 ├── agents/ │ └── openai.yaml # 可选UI 展示元数据 ├── references/ # 可选详细参考文档按需加载 │ ├── naming-rules.md # 命名规范 │ ├── layer-rules.md # 分层规范 │ └── api-standards.md # API 设计规范 ├── scripts/ # 可选自动化脚本 │ └── lint_check.py # 自动检查脚本 └── assets/ # 可选模板等资源 └── review-template.md # 审查报告模板这里的关键设计是渐进式披露Skill 的内容不是一次性全部加载而是分三级按需加载。元数据description始终可见约 100 字Agent 用来判断要不要触发主文件正文在触发时加载控制在 3000 字以内Agent 用来理解任务、制定方案references/里的详情在 Agent 判断需要时才读放具体的规范、API 定义、流程细节。这意味着如果你把所有知识都塞进SKILL.md正文每次触发都会消耗大量上下文窗口。把详细内容拆到references/Agent 只在需要时才去读效率高得多。上下文窗口是公共资源不要浪费。3.2 descriptionSkill 的门面写成路由规则description是整个 Skill 最关键的字段它决定了 Agent 什么时候调用这个 Skill。写得好Agent 能精准识别场景写得差要么该触发不触发要么不该触发乱触发。好description需要回答三个问题做什么、什么时候用、什么时候不用。烂的写法description: 处理 PDF 文件太宽泛。“处理”是读取还是编辑是提取文本还是转格式Agent 不知道什么时候该触发。好的写法description: 读取、创建、编辑 PDF 文件支持文本提取、页面渲染、 格式转换。当用户需要处理 .pdf 文件时使用包括查看内容、 修改格式、合并拆分、添加水印等场景。不用于纯文本文件 .txt / .md的处理。明确了能力范围读取、创建、编辑、触发场景.pdf 文件、反面条件不用于纯文本。写清楚“什么时候不用”比写清楚“什么时候用”更能减少误触发。比如一个“API 文档生成”Skill如果只写“生成 API 文档”Agent 在用户问“这个 API 怎么调用”时也可能触发——但用户要的是使用说明不是生成文档。加上“不用于 API 使用教程或接口调试”误触发率会明显下降。一句话description是给 Agent 看的路由规则不是给人看的产品介绍。不要写成营销文案要写成精准的触发条件。3.3 SKILL.md 主文件骨架Agent 读完就能干活主文件是 Skill 被触发后 Agent 第一个读到的内容。它需要回答一个问题Agent 读完这份文件后能不能直接开始干活好主文件通常包含四个部分使用顺序、关键入口、必守约束、参考资料。下面是一个可以直接复制的骨架--- name: code-review description: 按照项目规范进行代码审查检查分层架构、命名规范、 异常处理和 API 设计。当用户要求审查代码、检查 PR、 或询问代码质量时使用。不用于代码格式化或 lint 检查。 --- # code-review ## 使用顺序 - 先看 references/layer-rules.md确认分层约束 - 再看 references/naming-rules.md确认命名规范 - 改 API 时才看 references/api-standards.md ## 关键入口 - Controller 层src/main/java/com/example/controller/ - Service 层src/main/java/com/example/service/ - Repository 层src/main/java/com/example/repository/ ## 必守约束 - Controller 不允许写业务逻辑只能做参数校验和路由 - Service 层禁止直接调用 Mapper必须通过 Repository - 所有接口返回 ResultT不要裸返 POJO - 异常统一在 GlobalExceptionHandler 处理不要在业务代码里 try-catch ## 参考资料 - references/layer-rules.md - references/naming-rules.md - references/api-standards.md对比一下烂主文件大段解释“什么是代码审查”、“为什么要做代码审查”、“常见的代码问题包括命名不规范、缺少异常处理……”——Agent 读完知道了“代码审查是什么”但不知道“在这个项目里怎么做”。这些概念性知识 Agent 本来就知道不需要你教。主文件是操作手册不是百科全书。3.4 references 拆分清单按需加载的粒度references/的拆分粒度直接决定加载效率。拆得太粗一个文件几千字Agent 读一次就吃掉大量上下文拆得太细文件太多Agent 要读好几个才能拼出完整信息。我的经验是按“任务维度”拆每个文件对应一类判断控制在 500 到 1500 字。以代码审查 Skill 为例拆分清单如下文件内容何时加载layer-rules.md分层架构约束、各层职责边界每次审查都读naming-rules.md类名/方法名/变量名规范、包结构约定每次审查都读api-standards.md接口命名、返回格式、错误码定义涉及 API 改动时读exception-rules.md异常分类、全局处理、日志规范涉及异常处理时读主文件里用“使用顺序”告诉 Agent 先读哪个、后读哪个、什么条件下才读哪个。这样 Agent 不会一次性把所有 reference 都加载进来而是根据当前任务选择性读取。3.5 约束怎么写解释 Why不堆 MUST约束是 Skill 里最重要的部分它告诉 Agent 哪些红线不能碰。但怎么写约束效果差距很大。堆命令的写法- 必须使用 HNSW 索引 - 绝不能在 Controller 里写业务逻辑 - 所有查询必须分页Agent 会严格遵守但问题是当场景变化时它不知道什么时候可以变通。“必须使用 HNSW”——如果数据量很小、写入很频繁呢IVFFlat 可能更合适。但你写了“必须”Agent 就不敢换。解释原因的写法- HNSW 在查询密集场景下延迟更低。RAG 的写入频率远低于 查询频率所以默认选 HNSW。如果数据量小且写入频繁 可以考虑 IVFFlat。 - Controller 的职责是接收请求、校验参数、返回响应。 业务逻辑放 Controller 会导致1无法复用2无法 做单元测试3改业务需求时要同时改 Controller 和 Service。 - 不分页的查询在数据量增长后会拖垮数据库。所有列表查询 默认分页上限 100 条。Agent 理解了背后的原因能在场景变化时自己判断。你给它理由它能推导出 How。语气上口语化比格式化更容易被正确执行。格式化的“sessionId 是会话主键语义历史查询必须做归属校验”读起来像法律条文口语化的“sessionId 是会话的身份证。查历史记录时必须确认是这个用户的不能让 A 看到 B 的对话”多了一个类比和一个具体错误场景Agent 更容易理解约束的实际含义和违反后果。4. 验证请求一次可执行的 Skill 加载验证写完 Skill 后必须验证它能不能被正确加载和触发。下面用 Python 走一遍完整流程读取SKILL.md的 frontmatter、解析description、模拟 Agent 的路由判断最后通过 TaoToken 发一次真实请求确认通道可用。4.1 解析 SKILL.md 的 frontmatterimport re import yaml from pathlib import Path def load_skill(skill_dir: str) - dict: skill_path Path(skill_dir) / SKILL.md text skill_path.read_text(encodingutf-8) # 提取 --- 包裹的 frontmatter match re.match(r^---\n(.*?)\n---\n(.*)$, text, re.DOTALL) if not match: raise ValueError(SKILL.md 缺少 frontmatter) meta yaml.safe_load(match.group(1)) body match.group(2) return { name: meta.get(name), description: meta.get(description), body: body, body_len: len(body), } skill load_skill(./code-review) print(name:, skill[name]) print(description:, skill[description][:80], ...) print(body 字数:, skill[body_len])运行后你应该看到name: code-review、description的前 80 字、以及body的字数。如果body_len超过 3000说明主文件太长了该往references/拆了。4.2 通过 TaoToken 验证模型通道Skill 本身是静态文档但 Agent 触发 Skill 后要调用模型。用 TaoToken 的 API 端点发一次请求确认 Key 和通道都正常import os from openai import OpenAI client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL], # https://taotoken.net/api ) resp client.chat.completions.create( modelgpt-4o-mini, messages[ {role: system, content: 你是一个代码审查助手。}, {role: user, content: Controller 里写了业务逻辑有什么问题}, ], ) print(resp.choices[0].message.content)如果返回了正常内容说明 TaoToken 通道可用。这一步的意义在于把 Skill 的加载验证和模型通道验证分开出问题时能快速定位是 Skill 文件格式错了还是 API 配置错了。4.3 模拟 Agent 的路由判断最后一步把description喂给模型让它判断一个用户请求该不该触发这个 Skill。这是验证description质量最直接的方法def should_trigger(description: str, user_query: str) - bool: prompt f下面是一个 Skill 的描述 {description} 用户的请求是{user_query} 请判断这个请求是否应该触发该 Skill。只回答 yes 或 no。 resp client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: prompt}], temperature0, ) return resp.choices[0].message.content.strip().lower().startswith(yes) # 应该触发 print(should_trigger(skill[description], 帮我审查一下这个 PR 的代码)) # 不应该触发 print(should_trigger(skill[description], 帮我把这段代码格式化一下))如果第一个返回True、第二个返回False说明description的触发条件和反面条件都写清楚了。如果第二个也返回True说明反面条件不够明确需要回去改description。5. 本篇常见错排查5.1 Skill 不触发description 太宽泛或缺少触发词最常见的问题是 Agent 该用 Skill 时没用。原因通常是description写得太抽象比如“处理数据”、“优化代码”。Agent 匹配不到具体场景。修正方法是把用户可能说的原话写进description比如“当用户要求审查代码、检查 PR、或询问代码质量时使用”。触发词越具体命中率越高。5.2 Skill 乱触发缺少反面条件反过来Agent 在不该用 Skill 时用了。比如一个“生成 API 文档”Skill在用户问“这个 API 怎么调用”时也触发了。修正方法是加反面条件“不用于 API 使用教程或接口调试”。反面条件比正面条件更能减少误触发因为正面条件往往有重叠反面条件能划清边界。5.3 上下文被撑爆主文件太长references 没拆如果每次触发 Skill 后模型响应变慢、或者开始“忘记”前面的指令很可能是主文件太长。检查body_len超过 3000 字就该拆。把详细的规范、示例、API 定义移到references/主文件只保留使用顺序、关键入口、必守约束、参考资料四个部分。5.4 约束被忽略堆了 MUST 但没解释原因Agent 没有遵守约束往往不是因为它不听话而是因为约束写成了孤立的命令。比如“必须使用 HNSW 索引”Agent 不知道为什么要用遇到边界情况就不敢判断。改成解释原因“HNSW 在查询密集场景下延迟更低RAG 写少读多所以默认选 HNSW”Agent 就能在场景变化时自己推导。5.5 API 调用失败base_url 或 Key 配置错误Skill 加载正常但模型调用报错先检查三件事TAOTOKEN_BASE_URL是否指向https://taotoken.net/api注意不要带 UTM 参数TAOTOKEN_API_KEY是否从环境变量正确读取Key 是否在控制台里还有效。如果用的是 Claude Code检查接入文档里的配置项是否和当前版本一致。排障时优先看 API Keys 页面确认 Key 状态再看接入文档核对 base_url。6. 把 Skill 接入你的日常工作流Skill 写完之后真正的价值在于持续使用和迭代。我的做法是把 Skill 目录纳入项目仓库和代码一起版本管理。每次发现 Agent 在某个场景下表现不好就回去改对应的description或references/文件而不是在对话里临时补充背景知识。这样改一轮Skill 就上一个台阶。如果你还在用零散的对话做 Agent 开发建议先把接入层统一到 TaoToken。模型对话场景可以直接在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里试长期做编码 Agent 或需要稳定跑批任务的可以看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API Keys 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后留一个实用技巧每次改完description用第 4.3 节的should_trigger函数跑一组正反用例确认触发判断没退化。这比凭感觉改要靠谱得多。