编写自定义 Skill：SKILL.md 规范、触发词设计与发布流程（TaoToken 实践）

1. 从一次 Skill 不触发说起CodeX 自定义 Skill 的完整落地路径CodeX 自定义 Skill 是什么简单说它是你写给 CodeX 的一套“可复用指令包”——把一段固定流程、一套输出格式、一类重复劳动封装成一个能被自然语言触发的模块。适合谁适合每天在终端里反复敲同类提示词的开发者、需要把团队规范固化进工具链的技术负责人以及想把个人工作流沉淀成资产的人。它的核心载体就是 SKILL.md一个带 YAML 头的 Markdown 文件放在~/.codex/skills/或项目根目录的.codex/skills/下。我遇到过一个很典型的问题Skill 写好了放进目录重启 CodeX输入触发词毫无反应。日志里连一条匹配记录都没有。排查了半天最后发现是触发词里混进了一个零宽空格——肉眼完全看不出来但正则编译后就是匹配不上。这类问题不是个例而是自定义 Skill 落地过程中最高频的坑之一。这篇内容就围绕这条完整路径展开SKILL.md 的 YAML 元数据规范怎么写、触发词怎么设计才既准又稳、发布流程怎么从本地走到团队共享以及如何通过 TaoToken 统一 Key 和 API 通道完成调用验证。每一步都给可复制的配置和命令不空谈概念。你跟着做至少能避开我踩过的那几个坑。需要先明确一点CodeX 的 Skill 机制本质上是“本地规则匹配 上下文注入 模板渲染”三件事的组合。YAML 头决定“什么时候触发”正文模板决定“触发后输出什么”context 字段决定“触发时需要哪些上下文变量”。三者缺一不可任何一环出问题表现都是“不触发”或“触发了但输出不对”。所以下面按这个顺序拆开讲。2. TaoToken 前置准备统一 Key 与 API 通道的配置方法在写 Skill 之前先把调用通道理顺。CodeX 的 Skill 在触发后如果需要调用模型生成内容走的是你配置的 API 通道。如果你同时用多个模型供应商Key 管理会变得很碎。TaoToken 在这里的作用是提供一个统一的 API 入口把 Key 和 Base URL 收敛成一套配置Skill 里不用关心底层换没换模型。先拿到 Key。访问https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentskill_md_guide在控制台里创建一个 API Key。创建时注意权限范围如果你只是本地调试 Skill选默认的调用权限即可不需要开管理权限。Key 创建后只显示一次复制下来存到安全的地方。接下来配置 CodeX 的 API 通道。CodeX 的配置文件通常在~/.codex/config.yaml如果你用的是兼容 OpenAI 接口的客户端配置项名称可能略有不同但核心三件套是一样的Base URL、API Key、Model ID。以 TaoToken 为例# ~/.codex/config.yaml api: base_url: https://taotoken.net/api api_key: sk-你的TaoToken密钥 model: claude-sonnet-4-20250514 timeout: 60这里 Base URL 填https://taotoken.net/api不要加多余的路径后缀。Model ID 根据你实际要用的模型填TaoToken 的模型列表可以在文档里查到https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentskill_md_guide。如果你不确定用哪个先用一个通用对话模型跑通流程再换专用模型。配置完成后先别急着写 Skill用一条最简单的请求验证通道是否通。可以用 curlcurl -X POST https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的TaoToken密钥 \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 回复 OK}], max_tokens: 10 }如果返回里能看到choices字段和正常的文本内容说明通道没问题。如果返回 401检查 Key 有没有复制完整、有没有多余空格。如果返回local proxy failed检查 Base URL 是不是写成了带路径的形式或者本地网络环境有没有拦截。这一步跑通之后再进入 Skill 编写否则后面出问题你分不清是 Skill 的锅还是通道的锅。TaoToken 的 Coding Plan 适合长期做 Agent 类 Skill 的场景如果你打算把 Skill 用在持续编码任务里可以了解一下https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentskill_md_guide。不过对于单次调试按量调用就够了不用一上来就上套餐。3. SKILL.md 规范与可复制配置YAML 元数据与触发词设计SKILL.md 的灵魂在 YAML 头。很多人把它当普通 Markdown 写结果 Skill 加载失败或者永远不触发。下面给一份可直接复制的模板然后逐字段拆解。--- name: git-commit-helper version: 1.0.0 description: 根据 git diff 生成符合 Conventional Commits 规范的 commit message author: your-name trigger: patterns: - 生成\\s*(commit|提交)\\s*(message|信息|内容)? - 写\\s*(个|一个|条)?\\s*commit - commit\\s*(信息|怎么写|message) - !不要生成 commit - !不用了 priority: 80 context: [git, diff] --- 好的我来帮你生成 commit message。 当前分支{{branch}} 变更文件{{changed_files}} 建议的 commit message {{suggested_message}} 是否要执行回复“是”或“否”。name字段用 kebab-case别用空格。我见过有人写Git Commit HelperCodeX 解析时把空格当分隔符Skill 直接加载失败。老老实实用连字符。version遵循语义化版本。刚写的 Skill 标0.1.0测试一周没问题再升1.0.0。CodeX 会对比本地和远程版本低于远程时提示更新。trigger.patterns是最关键的部分。CodeX 把这些 pattern 编译成正则表达式去匹配用户输入不做模糊匹配。你写“生成 commit message”用户说“帮我生成一个 commit message”中间多了“一个”就匹配不上。所以要用正则覆盖常见变体。上面模板里\\s*处理空格(commit|提交)处理中英文混用。注意 YAML 里反斜杠要转义写\\s而不是\s。否定模式用!前缀优先级高于普通模式。用户说“不要生成 commit”时Skill 直接跳过不会误触发。priority取值 0-100默认 50。多个 Skill 同时匹配时选最高的。通用工具类设 60-80业务专用设 90 以上避免被抢走。context字段很多人忽略但它能大幅提升精度。上面指定[git, diff]只有对话上下文里出现过这两个关键词Skill 才激活。这能防止在非 git 场景下误触发。注意context 里声明的变量才会被注入模板没声明的变量永远是空。正文模板支持{{variable}}变量引用和{% if %}条件分支。变量必须在 context 里声明否则取不到值。条件分支的变量同理。循环用{% for item in list %}。这些语法不复杂但变量名写错时 CodeX 可能抛异常而不打印排查起来很烦。建议在模板末尾加一个{{debug_info}}把上下文关键信息打出来定位问题用。触发词设计有四条原则。第一用动词名词组合别用单个词。“翻译”太常见改成“翻译这段文本”。第二覆盖同义词和口语化表达别指望用户按你的文档说话。第三用正则增强灵活性但注意转义。第四设置否定模式防止误触发。我一般先收集 20-30 条真实用户输入提取高频短语作为 pattern而不是拍脑袋想。4. 验证请求与成功结果Skill 触发与模型调用实测配置写好了怎么验证 Skill 真的能触发分两步先验证 Skill 匹配再验证模型调用。第一步本地加载。把 SKILL.md 放到~/.codex/skills/git-commit-helper/SKILL.md然后执行热加载codex reload如果输出里有Loaded skill: git-commit-helper说明文件解析成功。如果没有检查 YAML 头有没有语法错误比如缩进用了 Tab、冒号后面没空格、引号不配对。第二步触发测试。在 CodeX 对话里输入“帮我写一个 commit”观察是否命中。命中的表现是 Skill 的模板内容被渲染出来变量被替换成实际值。如果没命中打开日志tail -f ~/.codex/logs/codex.log | grep -i skill日志里会告诉你匹配结果。matched表示 pattern 命中context not satisfied表示上下文变量缺失skipped due to negative pattern表示被否定词拦截。第三步验证模型调用。如果 Skill 模板里需要调用模型生成内容比如生成 commit message 正文这时候走的是你在第 2 节配置的 TaoToken 通道。可以在 Skill 模板里加一段调用逻辑或者直接在 CodeX 里让 Skill 触发后调用模型。验证方法是看返回内容是否正常以及日志里有没有 API 报错。一个完整的成功结果长这样你输入“帮我写一个 commit”CodeX 匹配到git-commit-helper注入branch和changed_files变量渲染模板然后调用 TaoToken 通道生成suggested_message最后输出好的我来帮你生成 commit message。 当前分支feature/skill-demo 变更文件src/skill.ts, README.md 建议的 commit message feat(skill): add custom skill loader 是否要执行回复“是”或“否”。看到这个输出说明 Skill 从触发到调用全链路通了。如果中间任何一步断了按第 5 节的排查表定位。5. 常见报错排查401、local proxy failed、reading choices、OAuthSkill 落地过程中报错集中在几个地方。下面按真实报错对照排查。401 UnauthorizedKey 无效或没带上。检查~/.codex/config.yaml里的api_key有没有复制完整有没有多余空格或换行。TaoToken 的 Key 以sk-开头创建后只显示一次如果丢了就重新创建一个。另外检查请求头里Authorization: Bearer sk-xxx格式对不对Bearer 和 Key 之间有一个空格。local proxy failed本地代理或网络层拦截。检查 Base URL 是不是写成了https://taotoken.net/api/v1这种带路径的形式正确写法是https://taotoken.net/api。另外检查本地有没有配置系统级代理如果有确认代理规则没有拦截 TaoToken 域名。这个报错和 Skill 本身无关是通道层的问题。reading choices 报错通常是返回体结构不符合预期。可能原因有三个Model ID 写错了导致返回了错误结构请求体里messages格式不对或者max_tokens设得太小返回被截断。检查 Model ID 是否在 TaoToken 文档的模型列表里检查请求体 JSON 是否合法。OAuth 相关报错如果你用的是需要 OAuth 授权的客户端检查 token 有没有过期。CodeX 的某些版本会缓存 OAuth token过期后需要重新授权。如果是 API Key 模式一般不会遇到 OAuth 问题。确认你用的是 Key 模式而不是 OAuth 模式。Skill 匹配但无输出日志显示matched但对话里没反应。大概率是模板里的变量名写错了CodeX 渲染时抛异常但没打印。解决办法是在模板里加{{debug_info}}把上下文打出来逐个核对变量名。另一个可能是 context 里声明的变量在对话上下文中不存在比如你声明了[git]但当前对话没出现过 git 相关词变量为空导致渲染失败。Skill 完全不触发日志里连matched都没有。检查 pattern 里有没有零宽空格或不可见字符。用cat -A SKILL.md查看文件零宽空格会显示为特殊字符。另外检查 priority 是不是被其他 Skill 抢走了临时把 priority 调到 99 测试。排查顺序建议先看日志有没有匹配记录再看 context 是否满足再看模板渲染是否报错最后看 API 通道是否通。按这个顺序大部分问题能在五分钟内定位。6. 发布流程与团队共享从本地到仓库的完整路径Skill 调试通了怎么让团队用上CodeX 提供三种方式按场景选。本地安装最简单直接把 SKILL.md 放到~/.codex/skills/下重启或codex reload就能用。适合个人调试阶段改完即生效。项目级安装是在项目根目录创建.codex/skills/把 SKILL.md 放进去。只有在这个项目里打开 CodeX 时才生效适合团队项目专用工具。这种方式的好处是 Skill 跟着代码仓库走新人 clone 下来就能用不用额外配置。共享仓库适合多项目复用。在~/.codex/config.yaml里配置skills: repositories: - url: https://github.com/your-team/codex-skills.git branch: main path: skills/然后执行codex skills syncCodeX 会克隆仓库并加载所有 SKILL.md。团队更新 Skill 后成员重新 sync 即可。版本管理靠 SKILL.md 头部的version字段本地版本低于远程时 CodeX 会提示更新。发布前建议做三件事。第一在 SKILL.md 末尾加## Tests章节列出 5-10 个测试输入和期望输出下次改代码时快速验证有没有破坏原有功能。第二检查 pattern 里有没有零宽空格用cat -A过一遍。第三确认 context 字段声明的变量在真实对话里能取到值别声明了用不上的变量。一个 Skill 只做一件事。“生成 commit message”就只做这个别想着顺便生成 changelog。拆成多个 Skill每个专注一个场景维护起来轻松得多。我试过把三个功能塞进一个 Skill结果触发词互相干扰priority 调来调去都不对最后拆开才消停。发布节奏上先写最小可用版本只覆盖最常用的 3-5 个触发词回复模板只输出核心内容。发布给团队用收集一周反馈再迭代。CodeX 热加载很方便没必要一次到位。踩过的坑多了自然就熟练了。下次遇到 Skill 不触发先检查 pattern 里有没有零宽空格——别问我怎么知道的。如果你在接入过程中遇到通道配置问题可以对照 TaoToken 的接入文档排查https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentskill_md_guide。需要验证模型返回是否正常可以用模型对话页面快速测试https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentskill_md_guide。长期做编码类 Skill 的话Coding Plan 的通道稳定性会更好一些。