1. 从重复提示词到可复用技能Claude Skill 要解决的真实问题如果你已经在用 Claude Code 写代码大概率经历过这样的循环每次让它把字幕转成 Markdown、每次让它按固定格式生成周报、每次让它做域名头脑风暴你都得把那一大段提示词重新贴一遍。贴一次两次还行贴到第十次就开始怀疑人生——明明上周调好的提示词这周又得从聊天记录里翻出来。Claude SkillAgent Skills就是冲着这个痛点来的。它允许你把一段稳定的提示词、一套固定的处理流程沉淀成一个带SKILL.md的文件夹放进项目里。之后 Claude Code 会在需要的时候自动识别并加载它你只需要说一句「把这个 srt 转成笔记」剩下的交给 Skill。它适合谁适合所有把 Claude Code 当日常生产力工具的人写脚本的、做内容流水线的、维护多个项目的。核心检索词就三个——Claude Skill、SKILL.md、claude code。搞懂这三个你就能把「重复劳动」变成「一次配置、长期复用」。这篇我会从 SKILL.md 的文件结构讲起给出可直接复制的骨架、目录放置位置、加载验证步骤再讲清楚 Skill 的渐进式加载原理最后说明怎么通过 TaoToken 统一 Key 和 API 通道让 Claude Code 稳定调用自定义 Skill。全程可跟做不需要你先成为 Agent 专家。2. 前置准备用 TaoToken 统一 Key 与 API 通道在动手写 Skill 之前先把「通道」这件事解决掉。Claude Code 要调用模型就得有可用的 API 入口和 Key。我试过把 Key 散落在各个项目里结果换台机器就得重新配一遍非常难受。统一走 TaoToken 会省心很多一个 Key、一个 API 地址Claude Code、Codex 这类工具都能复用。TaoToken 在这里扮演的是统一的模型接入层你不需要在每个项目里维护不同的凭证。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基地址是 https://taotoken.net/api 这个地址不加 UTM 参数配置时直接用。具体操作分两步。第一步去控制台创建 API Key入口在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 创建完记得复制保存Key 一般只显示一次。第二步如果你不确定用哪个模型可以先去模型对话页面试一下地址是 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 确认模型能正常响应再往下走。注意Key 属于敏感凭证不要写进会提交到 Git 的文件里。建议用环境变量注入后面配置章节会给具体写法。如果你打算长期用 Claude Code 做编码和 Agent 任务可以关注 Coding Plan入口是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 它更适合高频、长周期的编码场景。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 遇到配置细节可以对照查。3. 可复制配置SKILL.md 骨架、目录位置与加载验证这一章是全文的技术核心我会把每一步都写成能直接抄的形式。先讲目录结构再讲 SKILL.md 的两段式写法然后讲怎么在 Claude Code 里验证加载。3.1 目录放置位置项目级与全局级Skill 的本质就是一个文件夹文件夹里必须有一个名为SKILL.md的文件大小写敏感别写成skill.md。项目级 Skill 放在项目根目录下的.claude/skills/里比如你的项目在E:\MySkillsProject那路径就是E:\MySkillsProject\.claude\skills\每个 Skill 是skills下的一个子文件夹文件夹名就是 Skill 的名字。比如做一个「字幕转 markdown」的 SkillE:\MySkillsProject\.claude\skills\字幕转markdown\SKILL.md如果你希望某个 Skill 在所有项目里都能用就把它放到用户级目录。Windows 下通常是C:\Users\你的用户名\.claude\skills\macOS/Linux 下是~/.claude/skills/。放进去之后它就变成全局 Skill 了。3.2 SKILL.md 骨架metadata 加指令两段式SKILL.md分两段上半部分是 metadata元数据用 YAML front matter 写下半部分是指令正文。metadata 要短因为它会被扫描进上下文指令要详细因为它是真正执行时加载的内容。先看 metadata 骨架--- name: 字幕转markdown description: 把 srt 字幕文件转换成结构化的 markdown 笔记 ---name是技能名description是给模型看的用途说明。这两项决定了 Claude Code 在扫描时能不能「认出」这个技能该在什么场景用。description 写得越准模型判断越靠谱。下半部分是指令正文也就是模型真正执行时读到的内容。它应该像一份操作手册把输入、处理规则、输出格式都写清楚## 任务 把用户提供的 srt 字幕文件转换成 markdown 笔记。 ## 处理规则 1. 读取 srt 文件按时间轴切分每条字幕。 2. 合并语义连续的短句去掉纯语气词。 3. 按内容主题分段每段给一个小标题。 ## 输出格式 - 输出到项目根目录文件名与原文件同名后缀改为 .md - 使用二级标题分节正文用普通段落 - 不要输出时间戳除非用户明确要求 ## 示例 输入xxx.srt 输出xxx.md包含分节标题与整理后的正文这样写的好处是模型不需要你每次重新解释规则它读一遍指令就知道该怎么干。你可以把任何重复性任务都按这个结构沉淀下来比如「来点选题」「周报生成」「接口文档转测试用例」。3.3 在 Claude Code 中加载与验证写完之后启动 Claude Code输入/skills命令。如果配置正确你会看到项目下的 Skill 被列出来包括你刚创建的「字幕转markdown」。验证方式是直接把一个 srt 文件拖进 Claude Code然后回车。正常情况下它会自动调用对应的 Skill开始处理并在项目根目录生成 markdown 文件。你可以在对话里看到它引用了哪个 Skill这就是加载成功的信号。如果/skills里没显示先检查三件事文件夹名和SKILL.md拼写是否正确、文件是否真的在.claude/skills/下、metadata 的 YAML 格式有没有写错比如少了---闭合。3.4 通过环境变量接入 TaoTokenClaude Code 调用模型需要 API 通道。把 TaoToken 的 Key 和地址通过环境变量注入避免硬编码。以 Windows PowerShell 为例$env:ANTHROPIC_BASE_URLhttps://taotoken.net/api $env:ANTHROPIC_API_KEY你的TaoToken KeymacOS/Linux 下export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEY你的TaoToken Key设置完重启 Claude Code让它读取新的环境变量。这样 Skill 的加载逻辑不变但底层模型通道统一走了 TaoToken换项目、换机器都只需要改这一处。4. 验证请求与成功结果从 srt 到 markdown 的完整链路配置完就该跑一次真实请求确认整条链路通了。我拿一个实际的 srt 文件做演示。第一步确认 Skill 被识别。启动 Claude Code 后输入/skills输出里应该能看到Available skills: - 字幕转markdown: 把 srt 字幕文件转换成结构化的 markdown 笔记第二步把 srt 文件拖进对话框回车。Claude Code 会先扫描本地所有SKILL.md的 metadata形成一个技能列表连同你的问题一起发给模型。模型判断这个问题该用「字幕转markdown」于是 Claude Code 把该 Skill 的指令正文加载进来模型按指令处理文件。第三步观察执行过程。你会看到它读取 srt、按规则合并句子、分节最后在项目根目录写出 markdown 文件。成功的结果是项目根目录多了一个同名.md文件打开后是整理好的笔记没有时间戳、没有语气词堆砌。这里的关键在于「渐进式披露」metadata 很短先让模型知道「有哪些技能可用」指令正文较长只在真正选中该技能时才加载。这样既省上下文又能让技能库无限扩展。你放二十个 Skill 进去平时也只占用很少的上下文只有被选中的那个才会展开。如果你想先确认模型本身是否正常可以回到模型对话页面发一条简单请求地址是 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 能正常回复说明通道没问题再回来排查 Skill 配置。5. 本篇常见错排查Skill 不加载、不触发、报错怎么办实际用下来问题基本集中在几个点上我按出现频率排一下。Skill 不出现在/skills列表里。九成是路径或文件名问题。确认是.claude/skills/技能名/SKILL.md不是.claude/skill/也不是SKILL.MD。Windows 下注意别让资源管理器把扩展名藏起来导致实际文件名变成SKILL.md.txt。Skill 出现了但模型不调用。通常是 description 写得太模糊。比如只写「处理文件」模型不知道什么时候该用。改成「把 srt 字幕文件转换成结构化 markdown 笔记」场景明确触发率会明显上升。metadata 解析失败。YAML front matter 必须以---开头、以---结尾中间不能有多余空行或缩进错误。name和description后面用冒号加空格中文没问题但别用 Tab 缩进。指令执行结果不符合预期。多半是指令正文写得太笼统。把处理规则拆成编号步骤给出输出格式和示例模型的可执行性会强很多。指令越像操作手册结果越稳定。API 请求报错或超时。先检查环境变量里的ANTHROPIC_BASE_URL是不是https://taotoken.net/apiKey 有没有多余空格。如果还是不通去接入文档对照排查地址是 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。需要重新生成 Key 的话去 API Keys 页面入口是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。想迁移到 Codex 但 Skill 不生效。Agent Skills 在 Codex 里还是实验性功能需要手动开启。把.claude/skills复制到.codex/skills然后编辑C:\Users\你的用户名\.codex\config.toml加上[features] skills true保存后重启 Codex 再试。6. 语义一致收尾把 Skill 变成你的长期资产Skill 真正有价值的地方不是省下那一次复制粘贴而是它把「你调好的提示词」变成了可版本管理的文件。你可以把它提交进 Git团队里谁拉下来都能用你可以按项目组织也可以放全局复用你甚至可以把开源社区里现成的 Skill 直接拷进.claude/skills/用起来。资源层的组织也值得顺手规范一下可执行脚本放scripts/参考文档放references/图片等素材放assets/。这样当指令需要读取额外资源时模型能按需加载而不是一次性把所有东西塞进上下文。这套「按需加载」的思路和 metadata 先行的设计是一脉相承的。至于 Skill 和 MCP 的关系可以简单理解成MCP 解决的是「模型能连到什么外部能力」Skill 解决的是「模型该按什么流程做事」。两者不冲突一个管连接一个管方法。你完全可以在同一个项目里既配 MCP 又用 Skill。最后给一个实用建议先别急着建十个 Skill。挑一个你每周都要重复三次以上的任务把它写成第一个SKILL.md跑通、调稳再复制这个模式扩展。通道这边长期编码和 Agent 任务可以走 Coding Plan入口是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 把 Key 和 API 统一好剩下的就是不断往.claude/skills/里加你的「技能资产」了。