1. 为什么你的 Skill 配了却没生效
很多人第一次接触 Skill 是在 Claude Code 里敲了个/斜杠命令，发现列表里空空如也，或者明明把SKILL.md放进去了，AI 却像没看见一样继续自由发挥。问题通常不在模型，而在目录位置、文件名大小写、frontmatter 字段这三件事上。Skill 本质是一份写给 AI 的工作说明书，它把「这类任务怎么做、先读什么、按什么顺序输出、哪些不能脑补」固定成文件，而不是每次开新对话都重新粘贴一大段提示词。你把它理解成给 AI 装的一个「岗位 SOP」就行：会议纪要、周报、翻译、PDF 处理，各占一个文件夹，互不干扰。
这篇用一个「会议纪要 Skill」当例子，把 Claude Code、Codex、VSCode 三条路径全部跑通。适合谁：已经在用 Claude Code 或 Codex 插件、想让 AI 输出稳定不跑偏的开发者；也适合完全没写过 Skill、只想先跑通第一个自定义 Skill 的小白。核心检索词就三个：Skill 怎么配置、SKILL.md 目录结构、Claude Code 与 Codex 的 Skill 路径差异。下面所有路径、字段、命令都可以直接复制，改掉项目名就能用。
先说结论，避免你走弯路：Claude Code 读的是项目根目录下的.claude/skills/<skill-name>/SKILL.md，Codex 读的是.agents/skills/<skill-name>/SKILL.md，两者文件名必须严格是SKILL.md（大写），文件夹名就是你的调用名。调用时 Claude Code 用/meeting-minutes，Codex 用$meeting-minutes。搞混这两个前缀，是新手最高频的翻车点。
2. TaoToken 前置：把模型通道先接稳
Skill 只是规则层，真正干活的是背后的模型。如果你在 Claude Code 或 Codex 里连模型都还没接通，Skill 配得再漂亮也不会触发。我习惯先把模型通道统一到一个兼容 Anthropic / OpenAI 协议的入口，再谈 Skill。TaoToken 在这里扮演的就是这个入口角色：它提供兼容的 Base URL 和 Key，让 Claude Code、Codex、Cline 这类工具都能指向同一个地址，省得每个工具单独折腾一遍鉴权。
你需要提前准备两样东西：一个 API Key，以及对应的 Base URL。Key 在控制台的 API Keys 页面生成，地址是 https://taotoken.net/api-keys ，生成后立刻复制保存，页面刷新就看不全了。Base URL 用 https://taotoken.net/api ，注意这个地址后面不要带斜杠，也不要自己拼/v1，工具内部会按协议补全。模型 ID 按你实际要用的填，比如claude-sonnet-4-5或gpt-5这类，具体以控制台模型列表为准，别照抄别人的。
这里有个容易踩的坑：Claude Code 走的是 Anthropic 协议，Codex 走的是 OpenAI 协议，两者对 Base URL 的拼接方式不一样。如果你把同一个地址硬塞给两个工具，其中一个大概率报 404 或model not found。正确做法是分别按各自文档填，Claude Code 的接入说明看 https://taotoken.net/doc ，里面有分工具的配置示例。想先验证 Key 是否有效，可以直接在模型对话页发一条消息试试： https://taotoken.net/chat ，能正常返回就说明通道没问题，再去配 Skill 就少一个变量。
如果你打算长期用 Skill 做编码或 Agent 类任务，调用量会比聊天大不少，可以顺手看下 Coding Plan 的额度说明： https://taotoken.net/coding-plan ，按需选，不用一上来就拉满。把模型通道确认能跑通之后，我们再进入 Skill 的目录搭建，这样出问题时你能快速判断是「模型没通」还是「Skill 没被读到」。
3. 可复制配置：SKILL.md 目录结构与字段
先建项目目录。Windows 下我习惯放D:\AIContent\office-skills-demo，Mac / Linux 换成你自己的路径即可。用 VSCode 打开这个文件夹，如果弹出「是否信任作者」，选信任，否则插件的一些文件写入会被拦。
Claude Code 的 Skill 目录长这样，注意.claude前面有个点：
office-skills-demo ├── .claude │ └── skills │ └── meeting-minutes │ └── SKILL.md ├── .agents │ └── skills │ └── meeting-minutes │ └── SKILL.md └── samples └── meeting-demo.txt.claude/skills/meeting-minutes/SKILL.md给 Claude Code 用，.agents/skills/meeting-minutes/SKILL.md给 Codex 用。两份内容可以完全一样，因为 SKILL.md 的格式是通用的。samples/meeting-demo.txt放一段测试用的会议原文，方便验证。
SKILL.md 的头部是 YAML frontmatter，只有两个必填字段，用三个短横线包起来：
--- name: meeting-minutes description: 整理会议纪要、会议录音转文字、项目例会、需求评审、客户沟通、待办事项跟踪时使用。输出真实清楚的会议纪要，不编造，把未确认事项标记为待确认，并生成待办表和群发简短版。 ---name必须和文件夹名一致，全小写、用连字符，别写中文或空格，否则调用名对不上。description是给模型判断「什么时候该用这个 Skill」的，写得越具体触发越准，把典型场景关键词都塞进去，比如「会议录音转文字」「需求评审」「待办跟踪」。很多人 Skill 不触发，就是 description 写得太笼统，只写了「整理文档」四个字。
frontmatter 下面是正文，也就是给 AI 的完整工作说明。我把它拆成核心原则、整理流程、输出格式三块。核心原则里明确写「不要编造信息，没有明确时间、负责人、截止日期就写待补充或待确认」「不要过度美化，讨论过的不写成已完成」，这几条是防止 AI 一本正经乱扯的关键。输出格式用固定的 Markdown 标题层级，让每次产出结构一致：
# 会议纪要 ## 一、会议基本信息 - 会议主题： - 会议时间： - 参会人员： - 会议背景： ## 二、核心讨论内容 用条目整理，具体清楚，使用会议中说的词语，不确定的以及遇到错别字请让我确认。 ## 三、已确认结论 只写会议中已经明确的结论。如果没有，写：暂无明确结论，需后续确认。 ## 四、待办事项 | 序号 | 事项 | 负责人 | 截止时间 | 当前状态 | 备注 | |---|---|---|---|---|---| | | | | | | | ## 五、风险与待确认问题 ## 六、会后可发送到群里的简短版本 控制在 150～300 字，语气自然，可直接复制到工作群。 ## 七、需要补充的信息待办表格里，没有负责人就写「待确认」，没有截止时间也写「待确认」，状态限定在待处理、处理中、已完成、待确认四个值里。这种约束看起来啰嗦，但正是它让输出稳定。你可以把这份 SKILL.md 直接复制到两个目录，内容一字不改。
4. 验证请求：三条路径跑通第一个 Skill
配置完先别急着写复杂规则，用一段真实会议内容验证。准备samples/meeting-demo.txt，随便写一段带负责人缺失、时间模糊的会议记录，比如「讨论了登录改版，张三说下周看看，李四负责接口，具体时间没定」。这种带「待确认」点的内容最能检验 Skill 有没有生效。
Claude Code 的调用方式是斜杠加文件夹名。在会话框输入：
/meeting-minutes 请根据 samples/meeting-demo.txt 的内容，帮我整理会议纪要/meeting-minutes后面空一行不是必须的，但建议加，视觉上更清楚。如果输入/后能看到meeting-minutes出现在候选列表里，说明 Skill 已经被读取。看不到就先重启 VSCode，或者按Ctrl + Shift + P输入「开发人员:重新加载窗口」回车。Claude Code CLI 用户直接重启 CLI 进程。
Codex 的调用方式是美元符号加文件夹名，注意是$不是/：
$meeting-minutes 请根据 samples/meeting-demo.txt 的内容，帮我整理会议纪要Codex 读的是.agents/skills目录，如果你只建了.claude，Codex 这边是空的，自然调不出来。这也是为什么建议一个项目里两个目录都建，内容复用同一份 SKILL.md。
验证成功的标志：输出里出现了「待确认」字样，待办表格里负责人和截止时间没有被 AI 瞎填，群发简短版控制在 300 字以内。如果 AI 把「下周看看」直接写成「张三负责，下周三完成」，说明 Skill 没被读到，它在用默认行为自由发挥。这时候回到目录检查三件事：文件夹名和name是否一致、文件名是否严格是SKILL.md、frontmatter 的三个短横线有没有写全。
VSCode 里还有个可选动作：安装微软的 Chat Customizations Evaluations 扩展，它能分析SKILL.md、.prompt.md、.agent.md这类文件，帮你检查提示词里的矛盾、歧义、规则冲突。不是必须装，我一般先不装，等 Skill 规则变复杂了再用来体检。
5. 本篇常见错排查：401、local proxy failed 与不触发
报错一：401 Unauthorized或invalid api key。这是模型通道的鉴权问题，跟 Skill 无关。检查 API Key 是否复制完整、有没有多余空格，Base URL 是否写成https://taotoken.net/api而不是带/v1的版本。Key 在 https://taotoken.net/api-keys 重新生成一个再试。如果 Claude Code 和 Codex 共用同一个 Key 但只有一个报 401，多半是协议拼接差异，分别按 https://taotoken.net/doc 里的示例核对。
报错二：local proxy failed或连接被拒。通常是本地代理端口没起来，或者工具配置里填了本地地址但服务没启动。先确认你填的 Base URL 是远端地址而不是127.0.0.1之类。如果之前配过本地转发，把配置清掉，直接用远端 Base URL 重试。
报错三：reading choices或返回结构解析失败。这类多半是模型 ID 填错，或者用了 OpenAI 协议的工具去请求 Anthropic 协议的模型。Codex 走 OpenAI 协议，Claude Code 走 Anthropic 协议，模型 ID 要和协议匹配。去控制台模型列表确认可用 ID，别照抄博客里的旧名字。
报错四：Skill 完全不触发，AI 自由发挥。按顺序查：目录是不是.claude/skills/meeting-minutes/SKILL.md（Claude Code）或.agents/skills/meeting-minutes/SKILL.md（Codex）；文件名大小写是否严格；name字段是否等于文件夹名；description是否写清了使用场景。改完重启 VSCode 或 CLI。如果用了 CC Switch 或 Cline MCP 这类工具，配置里要同时写全三件套：Base URL、API Key、Model ID，缺一个都会导致请求发不出去。
报错五：OAuth 相关报错。有些工具默认走 OAuth 登录流程，如果你用的是 API Key 模式，要在配置里显式关掉 OAuth 或选择 API Key 鉴权方式，否则它会一直尝试走登录页。具体开关位置看对应工具的 settings 文件，Claude Code 在settings.json，Codex 在auth.json，把鉴权方式改成 key 模式即可。
排查顺序建议固定成：先确认模型通道能单独跑通（用模型对话页发一条消息），再确认 Skill 目录和文件名，最后确认调用前缀。三步里任何一步没过，后面的都白搭。
6. 从局部到全局，以及后续怎么走
局部 Skill 只服务当前项目，路径是项目根目录下的.claude/skills和.agents/skills。全局 Skill 放在用户目录，Windows 下是C:\Users\你的用户名\.claude\skills和C:\Users\你的用户名\.agents\skills，Mac / Linux 对应~/.claude/skills和~/.agents/skills。全局的用法和局部完全一样，区别只是影响范围：全局对所有项目生效，局部只对当前项目生效。
我更推荐先把局部跑通。局部写错了方便改，不会污染其他项目，也不会动到全局配置。等你用真实任务跑过几次，确认这套会议纪要规则真的好用，再把它复制到全局目录。第一次写 Skill 别贪多，先解决一个明确问题，比如「会议纪要里不许编造负责人」，跑一遍看输出，发现规则不够清楚就继续调 description 和正文约束。
想找现成的 Skill 参考，优先看官方文档和仓库：Anthropic 的 skills 仓库、OpenAI 的 Codex Skills 文档，这两个是标准写法的源头。GitHub 上搜agent skills、claude skills、SKILL.md能找到大量社区实现，Star 多的通常经过真实使用检验。安全上留个心眼：只带SKILL.md的风险相对低，如果里面夹着.py、.sh、.bat、.ps1脚本，要先读一遍再决定用不用，别直接扔进项目里执行。
把会议纪要这个 Skill 跑通之后，你可以照同样的结构扩展周报、翻译、PDF 处理。每个 Skill 一个文件夹，一份 SKILL.md，name 和文件夹名对齐，description 写清触发场景。模型通道那边保持 Base URL 和 Key 稳定，Skill 这边保持目录和字段规范，两条线都稳了，AI 的输出才会从「一本正经乱扯」变成「按你的规矩干活」。