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.mdCodex 读的是.agents/skills/skill-name/SKILL.md两者文件名必须严格是SKILL.md大写文件夹名就是你的调用名。调用时 Claude Code 用/meeting-minutesCodex 用$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-demoMac / 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 标题层级让每次产出结构一致# 会议纪要 ## 一、会议基本信息 - 会议主题 - 会议时间 - 参会人员 - 会议背景 ## 二、核心讨论内容 用条目整理具体清楚使用会议中说的词语不确定的以及遇到错别字请让我确认。 ## 三、已确认结论 只写会议中已经明确的结论。如果没有写暂无明确结论需后续确认。 ## 四、待办事项 | 序号 | 事项 | 负责人 | 截止时间 | 当前状态 | 备注 | |---|---|---|---|---|---| | | | | | | | ## 五、风险与待确认问题 ## 六、会后可发送到群里的简短版本 控制在 150300 字语气自然可直接复制到工作群。 ## 七、需要补充的信息待办表格里没有负责人就写「待确认」没有截止时间也写「待确认」状态限定在待处理、处理中、已完成、待确认四个值里。这种约束看起来啰嗦但正是它让输出稳定。你可以把这份 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目录如果你只建了.claudeCodex 这边是空的自然调不出来。这也是为什么建议一个项目里两个目录都建内容复用同一份 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.mdClaude Code或.agents/skills/meeting-minutes/SKILL.mdCodex文件名大小写是否严格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.jsonCodex 在auth.json把鉴权方式改成 key 模式即可。排查顺序建议固定成先确认模型通道能单独跑通用模型对话页发一条消息再确认 Skill 目录和文件名最后确认调用前缀。三步里任何一步没过后面的都白搭。6. 从局部到全局以及后续怎么走局部 Skill 只服务当前项目路径是项目根目录下的.claude/skills和.agents/skills。全局 Skill 放在用户目录Windows 下是C:\Users\你的用户名\.claude\skills和C:\Users\你的用户名\.agents\skillsMac / 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.mdname 和文件夹名对齐description 写清触发场景。模型通道那边保持 Base URL 和 Key 稳定Skill 这边保持目录和字段规范两条线都稳了AI 的输出才会从「一本正经乱扯」变成「按你的规矩干活」。