1. 从一份“看起来没问题”的 SKILL.md 说起很多人第一次写 Skill会把它当成一篇说明文档来写开头介绍背景中间罗列概念结尾补一段注意事项。写完自己读一遍逻辑通顺、排版漂亮感觉已经完成了。结果丢给 Agent 一跑要么根本不触发要么触发了却按自己的理解乱做最后得出一个结论——“Skill 这东西不靠谱”。问题往往不在 Agent而在写作者对 Skill 的定位。Markdown 是给人读的Skill 是给 Agent 调用的。这两件事的目标完全不同人读文档可以靠上下文脑补、靠经验补全缺失信息Agent 不会脑补它只会根据你给出的结构化信号去判断“要不要用、怎么用、用到什么程度”。我试过把同一份内容分别写成纯 Markdown 文档和带 frontmatter 的 SKILL.md前者在自然语言任务里几乎不会被选中后者只要 description 写得准命中率立刻不一样。这个差异不是玄学而是因为 Agent 发现 Skill 的机制决定了它先看的是轻量索引而不是正文。一个 Skill 目录通常长这样my-skill/ ├── SKILL.md ├── references/ ├── scripts/ ├── assets/ └── metadata-or-ui-config.yamlSKILL.md 只是入口文件它负责告诉 Agent这个 Skill 叫什么、什么时候该用、使用时遵循什么流程。真正让它变成“能力”的是入口说明背后的资源组织、触发机制和执行约束。所以 Skill 不等于 SKILL.md更不等于一份 Markdown 文档。本文就围绕这个差异从 description 字段切入给出可复制的模板和一次完整的加载验证动作让你理解为什么 Skill 必须结构化。2. TaoToken 前置让 Agent 稳定调用 Skill 的接入准备在讨论 Skill 结构之前得先有一个能稳定跑 Agent 的入口。Skill 的触发、加载、渲染都依赖模型侧的判断能力如果接入层不稳定description 写得再好也可能因为请求失败而看不到效果。我这边用的是 TaoToken 的 API 来做 Agent 调用它的接入方式比较直接适合用来验证 Skill 的触发行为。TaoToken 的官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 注意 API 地址后面不加 UTM 参数。如果你要管理密钥可以走 API Keys 页面要验证模型对话是否正常可以用模型对话页面如果是长期做编码类 Agent可以看 Coding Plan。这里要强调一点Skill 的触发判断发生在模型侧所以你的 Base URL、Key、Model ID 三件套必须配置正确。很多“Skill 不生效”的案例最后排查下来是接入层根本没通模型压根没收到请求。所以在写 SKILL.md 之前先把下面这些配置确认一遍。对于 Claude Code 这类工具配置通常落在 settings 文件里对于 Cline 这类带 MCP 的编辑器配置会写在 MCP 的 JSON 里对于 Codex则可能涉及 auth.json。不管哪种核心都是三件套对齐。下面给一个通用的 JSON 配置片段路径和字段名按你实际使用的工具调整{ base_url: https://taotoken.net/api, api_key: sk-你的密钥, model: claude-sonnet-4-20250514, timeout: 60 }如果你用的是 TOML 风格的配置可以写成[provider] base_url https://taotoken.net/api api_key sk-你的密钥 model claude-sonnet-4-20250514配置完成后先做一次最小请求验证确认模型能正常返回再去写 Skill。否则你无法区分“Skill 没触发”和“请求没发出去”。这一步看起来和 Skill 无关但它是后面所有验证动作的前提。3. 可复制配置SKILL.md 模板与 description 写法现在进入核心部分。一个能被 Agent 稳定解析的 SKILL.md关键在 frontmatter 里的字段尤其是 description。description 不是介绍文案而是触发器。它决定了 Agent 在什么任务下会选中这个 Skill。先看一个反例description: Help with reports.问题不是它短而是它没有边界。周报算 report 吗PR 总结算 report 吗线上事故复盘算 report 吗Agent 只能猜。猜的结果就是要么不触发要么乱触发。更好的写法是把触发场景、边界和用户可能说的话放进去description: Use when the user asks to generate a weekly report from Notion records, summarize this weeks completed work, classify items by scope, or produce a Chinese weekly status update. 触发词周报、weekly report、本周完成、状态同步。这类描述更像路标而不是名片。它告诉 Agent看到哪些任务应该进来哪些任务不该进来。对于中英混用的团队建议在 description 里同时包含中英文触发词例如 review code / 审查代码这样不同语言的自然语言查询都能命中。下面给一份完整的 SKILL.md 模板你可以直接复制修改--- name: weekly-report description: Use when the user asks to generate a weekly report from Notion records, summarize this weeks completed work, classify items by scope, or produce a Chinese weekly status update. 触发词周报、weekly report、本周完成、状态同步。 version: 1.0.0 allowed-tools: - read_file - run_script context: inline --- # Weekly Report Skill ## 何时使用 当用户提到周报、本周完成、状态同步或要求从 Notion 记录生成本周总结时使用。 ## 执行流程 1. 读取 references/notion-fields.md确认字段映射。 2. 调用 scripts/fetch_notion.py 拉取本周记录。 3. 按 scope 分类生成中文周报。 4. 输出前检查是否包含阻塞项和下周计划。 ## 边界 - 不处理月度总结。 - 不处理 PR 描述生成。 - 如果 Notion 记录为空提示用户补充数据不要编造内容。 ## 参考材料 - references/notion-fields.md - references/report-template.md注意几个设计点。第一正文只保留核心流程和判断规则大段规范、案例、API 文档放到 references/ 里按需读取。第二allowed-tools 明确声明需要哪些工具避免 Agent 在执行时越权。第三context 字段决定是注入主会话还是 fork 到子代理前者适合持续指导当前任务后者适合调研、总结这类不想污染主会话的工作。description 的写法还有一个容易被忽略的点当安装的 Skill 很多时初始 Skill 列表会受到上下文预算限制描述可能被压缩甚至部分 Skill 会被省略。所以触发词要前置边界要简洁最重要的信息放在开头。不要把“这个 Skill 很强大”这种话写在前面Agent 不关心。4. 验证请求一次 Agent 加载 Skill 的完整动作写完 SKILL.md 之后必须验证它是否真的被加载。判断一个 Skill 有没有价值不是看它写得多完整而是看它有没有改变 Agent 的行为。先准备一组测试提示词帮我从 Notion 生成这周周报 把今天 GitLab 的 fix/feat/hotfix 提交同步到 Notion 帮我 review 这个 GitLab MR 为这个 Bug 生成禅道修复备注观察它们是否命中对应 Skill是否读取该读的 reference是否运行该运行的脚本是否给出符合团队习惯的输出。如果一个 Skill 只有在用户精确喊出名字时才工作它还只是一个手册如果用户自然描述需求时它也能稳定接管流程它才真正进入了 Agent 的工作系统。从运行机制上看Agent 处理 Skill 的管线大致是发现 Skill、建立索引、判断触发、读取正文、渲染上下文、执行任务、验证结果。发现阶段通常只读取 name、description、路径等轻量信息不会把所有 SKILL.md 全部塞进上下文。触发可以来自用户显式输入 /skill-name也可以来自模型根据 description 判断任务相关。渲染阶段会处理参数和动态上下文有些实现会在模型看到 Skill 前先执行命令、读取文件或展开环境信息并且通常只展开一轮避免递归展开带来的风险。如果你想用代码方式验证可以写一个最小检查脚本确认 Skill 目录能被扫描到、frontmatter 能被解析import os import re def scan_skills(root): skills [] for name in os.listdir(root): skill_dir os.path.join(root, name) skill_file os.path.join(skill_dir, SKILL.md) if not os.path.isfile(skill_file): continue with open(skill_file, r, encodingutf-8) as f: content f.read() match re.match(r^---\n(.*?)\n---, content, re.S) if not match: print(f[WARN] {name} 缺少 frontmatter) continue front match.group(1) desc re.search(rdescription:\s*(.), front) skills.append({ name: name, description: desc.group(1).strip() if desc else , location: skill_file, }) return skills for s in scan_skills(./skills): print(s[name], -, s[description][:60])运行后如果能看到每个 Skill 的 name 和 description说明索引层没问题。接下来再通过 Agent 实际发一次自然语言请求观察它是否选中了正确的 Skill。这一步的预期结果是Agent 在回复中体现出它读取了 SKILL.md 的流程比如按步骤拉取数据、按模板输出而不是自由发挥。5. 本篇常见错排查401、local proxy failed 与 OAuth 报错Skill 不生效的原因很多时候不在 Skill 本身而在接入层或配置层。下面按真实报错来排查。第一种是 401 Unauthorized。这通常意味着 API Key 无效或没有正确带上。检查你的配置里 api_key 是否和 TaoToken 控制台里的一致Base URL 是否写成了 https://taotoken.net/api 而不是首页地址。如果用的是 Claude Code检查 settings 里的环境变量有没有被覆盖如果用的是 Cline MCP检查 JSON 里的字段名是否拼错。第二种是 local proxy failed。这类报错一般出现在本地代理层可能是端口占用、进程没起来或者配置里的地址指向了一个不存在的本地服务。排查顺序是先确认代理进程是否运行再确认端口是否被占用最后确认配置里的地址和端口是否匹配。如果你没有使用本地代理检查配置里是否误留了 proxy 相关字段。第三种是 reading choices 相关报错。这通常发生在响应解析阶段模型返回的结构和客户端预期不一致。可能原因是 Model ID 写错或者请求参数里带了客户端不支持的字段。解决办法是先用最小请求验证模型能正常返回再逐步加参数。第四种是 OAuth 报错。如果你用的是需要 OAuth 的工具检查 token 是否过期、回调地址是否配置正确。有些工具会把 OAuth 和 API Key 两种模式混用确认你当前用的是哪一种。还有一个高频问题是 Skill 触发了但执行不稳定。由于 LLM 行为有随机性同一个 Skill 多次执行可能得到不同结果。建议对输出不做逐字一致的断言而是做关键动作校验比如是否读了 references/ 下的文件、是否运行了 scripts/ 下的脚本、是否输出了符合模板的结构。如果这些关键动作稳定说明 Skill 的流程约束是有效的。另外当用户通过 /skill-name 反复手动触发同一个 Skill 时之前的上下文可能会污染下一轮行为。稳妥的做法是每次手动触发时清空上下文、重新加载渲染后的 Skill 内容确保复现一致。6. 把 Skill 当成可执行配置来维护回到最初的问题Skill 为什么不是 Markdown。因为 Markdown 的终点是“人读懂了”而 Skill 的终点是“Agent 执行对了”。这两者之间隔着一整套结构化信号name 用于索引description 用于触发frontmatter 用于声明权限和上下文策略references 和 scripts 用于渐进披露。如果你要长期维护一批 Skill建议把 description 当成接口文档来写把正文当成流程规范来写把 references 当成按需加载的知识库来写。每次新增边界时先问自己这是改 description 的触发词还是改正文的流程还是新增一个 reference。能补规则就不要重写整份文档这样维护成本才可控。最后留一个实用技巧给每个 Skill 准备一组回归测试提示词每次修改 description 或正文后跑一遍观察触发准确率和误触发率。触发准确率看的是用户自然描述任务时它是否被正确选中误触发率看的是不该用它的时候它是否乱入。这两个指标稳定了Skill 才算真正落地。