1. 从零理解 SkillSKILL.md 到底是什么能解决什么问题如果你之前一直在 Claude Code 里反复粘贴同一段提示词比如「帮我解释这段 C 代码用类比讲画个流程图指出指针和内存的坑」那你其实已经在写 Skill 了只是没把它固化下来。Skill 的本质就是把这种零散的、每次都要重敲的 Prompt整理成一份标准化的工作手册让 Claude Code 在合适的时机自动读取并执行。我先把三个核心概念摆清楚避免后面混淆Skill是一个文件夹里面装着 SKILL.md 以及可选的脚本、参考资料、模板资源。Claude Code 启动时会扫描指定目录下的所有 Skill 文件夹把每个 SKILL.md 的元信息读进上下文形成一个「技能索引」。SKILL.md是这个文件夹的核心文件文件名必须全大写后缀是 .md。它由两部分组成顶部用 YAML front matter 写元信息name、description、user-invocable、priority下面用 Markdown 写具体规则。元信息决定「什么时候触发」正文决定「触发后怎么干」。Claude Code是执行环境。它负责加载 Skill、匹配用户意图、调用脚本、读取参考文档最后按 SKILL.md 里的规则输出结果。为什么值得花 30 分钟学这个因为普通 Prompt 有三个硬伤复用性差换个会话就没了稳定性差同样的输入输出可能跑偏共享性差没法用 Git 传给团队。Skill 把这三件事一次性解决——写一次永久复用规则绑定后输出统一文件夹可以直接提交到仓库。我试过把常用的 C 代码解释流程做成 Skill之后每次只要贴代码Claude Code 就会自动按「生活类比 → ASCII 流程图 → 逐行解释 → 新手坑」这个固定结构输出不用再重复交代格式。这就是 Skill 最直接的价值。这一篇的目标很明确带你从建文件夹开始写出第一个可用的 SKILL.md接入 Claude Code跑通验证。全程复制粘贴就能完成不需要你懂 Claude Code 的源码也不需要写复杂配置。在动手之前先确认你的环境里已经装好 Claude Code 并能正常启动。如果你还没配置模型接入可以先用 TaoToken 的模型对话快速验证一下模型是否可用地址是 https://taotoken.net/api 对话入口在 https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmodel-chat 。确认模型能正常回话之后再往下走避免把环境问题和 Skill 问题混在一起排查。2. TaoToken 前置准备把 Claude Code 的模型接入先跑通Skill 能不能生效前提是 Claude Code 能正常调用模型。很多人卡在第一步不是 SKILL.md 写错了而是模型接入本身没通。所以这一节先把接入这件事讲透再进入 Skill 编写。Claude Code 需要一个兼容 Anthropic 接口的 Base URL 和 API Key。TaoToken 提供的就是这套接入能力Base URL 填 https://taotoken.net/api Key 在控制台的 API Keys 页面生成。整个链路是Claude Code 发请求 → TaoToken 转发 → 模型返回 → Claude Code 渲染结果。Skill 的加载和匹配发生在 Claude Code 本地不依赖网络但触发后的推理必须走通模型。具体操作分三步。第一步生成 API Key。打开 https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-keys 登录后创建一个新的 Key复制保存。这个 Key 只显示一次丢了就得重建。第二步配置 Claude Code 的环境变量。在终端里设置 ANTHROPIC_BASE_URL 和 ANTHROPIC_API_KEYexport ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的KeyWindows 用户用 PowerShell$env:ANTHROPIC_BASE_URLhttps://taotoken.net/api $env:ANTHROPIC_API_KEYsk-你的Key想永久生效就写进 shell 配置文件比如 ~/.zshrc 或 ~/.bashrc然后 source 一下。第三步验证接入。启动 Claude Code随便问一句「你好确认一下连接」能正常回复就说明通了。如果报 401说明 Key 不对或没生效如果报连接超时检查 Base URL 有没有多写斜杠或少了 https。这里有个容易踩的坑Base URL 末尾不要加 /v1 或 /messagesClaude Code 会自己拼接路径。你只需要填到 https://taotoken.net/api 这一层。另外 Key 不要提交到 Git用环境变量或本地配置文件管理。接入通了之后Claude Code 的模型能力就到位了。接下来写 Skill本质是在这个能力之上加一层「行为约束」。如果你打算长期用 Claude Code 做编码和 Agent 任务可以考虑 Coding Plan入口在 https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-plan 适合高频调用场景。3. 可复制配置SKILL.md 模板、目录结构与完整示例这一节是全文的核心给你一份可以直接复制粘贴的 SKILL.md 模板以及配套的目录结构。我们以「C 代码解释」这个 Skill 为例因为它足够典型涉及元信息、规则、脚本、参考文档、模板资源五类内容。先看目录结构。Skill 可以放在两个位置个人级全局可用和项目级仅当前项目。个人级一般放在 ~/.claude/skills/ 下项目级放在项目根目录的 .claude/skills/ 下。我们以个人级为例~/.claude/skills/ └── cpp-code-explain/ ├── SKILL.md ├── scripts/ │ └── cpp-helper.py ├── references/ │ └── cpp-basics.md └── assets/ └── ascii.txt文件夹名 cpp-code-explain 必须和 SKILL.md 里的 name 字段完全一致小写加连字符这是 Claude Code 匹配的关键。下面是 SKILL.md 的完整内容直接复制--- name: cpp-code-explain description: 针对C代码进行解释必须用生活类比ASCII流程图指出新手常见坑适配C/Qt开发场景当用户问C代码解释、代码逻辑、指针问题、Qt代码讲解时触发。 user-invocable: true priority: 90 --- # C代码解释Skill规则 ## 重要使用 scripts 自动分析代码风险 在开始解释前请先调用 scripts/cpp-helper.py 分析代码中的指针、内存、智能指针把结果展示给用户。 ## 重要参考 references 资料确保准确 解释代码时必须参考 references/ 文件夹里的 cpp-basics.md。 ## 1. 解释流程必须按顺序执行 1. 先用**生活类比**开头把C代码逻辑比作日常事物比如快递分拣、餐厅点餐、工厂流水线 2. 画**ASCII流程图**用文本画出代码的执行顺序、数据流向使用 assets/ascii.txt 模板 3. 逐行**简洁解释**用大白话不说专业黑话重点讲核心逻辑参考 references/cpp-basics.md 4. 指出**新手常见坑**C特有的易错点比如指针、内存泄漏、左/右值引用、智能指针使用 ## 2. 风格要求 - 语言口语化避免晦涩术语适配C初学者 - 结构每部分分点清晰重点加粗 - 限制不生成多余代码只做解释不额外拓展无关知识 ## 3. 禁止事项 - 禁止用纯代码堆砌解释必须搭配类比和流程图 - 禁止跳过常见坑部分 - 禁止解释过于复杂控制在300字内核心逻辑500字内完整说明 ## 4. 调用脚本分析 先运行 scripts/cpp-helper.py 自动识别指针/智能指针/内存风险。元信息里四个字段的作用要记牢name 是技能标识必须和文件夹名一致description 是触发机制Claude Code 靠它判断什么时候调用这个 Skill所以要写清楚「做什么 什么场景触发」user-invocable 设为 true 后可以用 /cpp-code-explain 手动调用priority 是优先级0 到 100越高越先触发多个 Skill 冲突时靠它排序。接下来是 scripts/cpp-helper.py用来提取代码里的风险点# C 代码解释小助手 # AI 会调用它自动提取关键信息 def analyze_code(code): lines code.split(\n) result [] for i, line in enumerate(lines): if * in line and (int in line or char in line or std in line): result.append(f行{i1} 发现指针可能涉及内存操作) if unique_ptr in line or shared_ptr in line: result.append(f行{i1} 发现智能指针安全度高) if new in line or delete in line: result.append(f行{i1} 发现内存创建/释放注意泄漏风险) return \n.join(result) if __name__ __main__: test_code int main() { unique_ptrint ptr make_uniqueint(10); } print(analyze_code(test_code))references/cpp-basics.md 放基础知识点供模型解释时参考# C基础知识点参考供AI解释代码时使用 ## 1. 指针核心概念 - 指针存储内存地址的变量类比快递单号通过单号能找到对应快递。 - 语法int* ptr 表示指向int类型的指针*ptr 表示指针指向的数据。 ## 2. 智能指针核心概念 - unique_ptr独占所有权类比专属快递盒不能共享。 - shared_ptr共享所有权类比多人共用一个快递柜。 - 核心优势自动释放内存不用手动写 delete避免内存泄漏。 ## 3. C基础语法 - make_uniqueint(10)C11及以上标准创建unique_ptr的安全方式。 - 作用域变量离开作用域会自动销毁智能指针同步释放内存。assets/ascii.txt 统一流程图样式 ASCII 流程图标准AI 必须遵守 【开始】 │ ▼ 【步骤1】 │ ▼ 【步骤2】 │ ▼ 【结束】 C 专用流程图模板 开始 → 定义变量/指针 → 赋值/创建 → 执行逻辑 → 释放/结束这套结构的好处是职责分离SKILL.md 管规则scripts 管自动化分析references 管知识准确性assets 管输出格式统一。你写其他 Skill 时可以按需裁剪最简单的 Skill 只需要一个 SKILL.md 就够了。4. 验证请求与成功结果在 Claude Code 里跑通第一个 Skill文件都建好之后进入验证环节。这一步的目标是确认 Claude Code 能识别到 Skill、能正确触发、能按规则输出。先重启 Claude Code让它重新扫描 skills 目录。然后在对话框里输入你现在有哪些skill如果配置正确Claude Code 会列出它扫描到的所有 Skill你应该能看到 cpp-code-explain。这一步是「加载验证」确认文件夹被识别。接着做「内容验证」输入/cpp-code-explain skill中有哪些内容手动调用会强制触发这个 SkillClaude Code 会读取 SKILL.md 并复述里面的规则。如果它能说出「生活类比、ASCII流程图、逐行解释、新手坑」这四个步骤说明 SKILL.md 被正确解析了。最后做「功能验证」贴一段 C 代码#include memory int main() { std::unique_ptrint ptr std::make_uniqueint(10); int* raw new int(5); delete raw; return 0; }按规则Claude Code 应该先调用 scripts/cpp-helper.py 分析风险点输出类似「行3 发现智能指针安全度高」「行4 发现指针可能涉及内存操作」「行5 发现内存创建/释放注意泄漏风险」然后用生活类比解释这段代码画一个 ASCII 流程图逐行讲清楚最后指出新手坑。如果输出结构符合预期说明整个链路通了加载 → 触发 → 脚本调用 → 参考文档读取 → 按规则输出。这时候你已经完成了第一个自定义 Skill。验证过程中有两个细节值得注意。一是脚本调用不是自动的需要在 SKILL.md 里明确写「请先调用 scripts/cpp-helper.py」模型才会去执行。二是 references 和 assets 的路径要写相对路径相对于 Skill 文件夹不要写绝对路径否则换台机器就失效。跑通之后你可以把这个文件夹复制到项目级的 .claude/skills/ 下让团队共享。也可以提交到 Git别人 clone 下来就能用。这就是 Skill 相比普通 Prompt 最大的优势——可传递、可版本管理。5. 本篇常见错排查401、local proxy failed、reading choices 报错怎么解这一节把验证过程中最容易撞上的报错集中讲一遍对照着排查能省很多时间。401 报错。表现是 Claude Code 启动后任何请求都返回 401 Unauthorized。原因通常是 API Key 没生效或写错了。排查顺序先确认环境变量 ANTHROPIC_API_KEY 的值和 TaoToken 控制台里的一致注意不要有多余空格再确认 ANTHROPIC_BASE_URL 填的是 https://taotoken.net/api 末尾没有多余斜杠最后确认当前终端会话确实加载了这些变量可以用 echo $ANTHROPIC_API_KEY 检查。如果是新开的终端窗口记得重新 source 配置文件。local proxy failed。表现是请求发不出去提示本地代理失败。这通常是环境里残留了代理配置或者 Base URL 写成了本地地址。检查 http_proxy、https_proxy 这些环境变量如果有就清掉。同时确认 Base URL 是 https://taotoken.net/api 而不是 localhost 或 127.0.0.1。Claude Code 直连即可不需要额外代理层。reading choices 报错。表现是模型返回结构解析失败提示读取 choices 字段出错。这多半是 Base URL 路径拼错了比如多写了 /v1 或 /messages导致返回体格式和 Claude Code 预期的不一致。把 Base URL 改回 https://taotoken.net/api 这一层让 Claude Code 自己拼接路径。Skill 不生效。表现是输入 /cpp-code-explain 没反应或者问「有哪些 skill」时列表里没有。排查三点文件夹名和 name 字段是否完全一致必须都是小写加连字符文件名是否严格是 SKILL.md全大写不能写成 skill.md 或 Skill.mddescription 是否写清楚了触发场景。改完重启 Claude Code或者输入「重新加载所有Skill」。AI 输出不按规则。表现是 Skill 触发了但输出结构乱。解决办法是把规则写得更具体禁止事项、格式要求、示例都写清楚用 /技能名 手动调用强制触发比自动匹配更稳在规则里用加粗强调「必须」「禁止」「按顺序」强化模型记忆。OAuth 相关报错。如果你用的是需要 OAuth 的接入方式报错通常和 token 过期有关。重新走一遍授权流程或者改用 API Key 方式接入后者更简单直接。排查的核心思路是分层先确认模型接入通不通401、proxy、choices 属于这一层再确认 Skill 加载对不对文件夹名、文件名、description 属于这一层最后确认规则执行准不准规则写法属于这一层。分层排查能快速定位问题在哪一层不用盲目改配置。6. 语义一致 CTA把 Skill 用起来从验证到长期编码跑通第一个 Skill 之后你会发现它的价值不在「省一次打字」而在「把工作流固化下来」。C 代码解释只是一个例子同样的方法可以套用到接口文档生成、Git 提交规范检查、Qt 编译错误排查、内存泄漏定位这些高频场景。你高频用的每一段 Prompt都值得做成一个 Skill。如果你在接入或排障过程中遇到问题API Keys 页面和接入文档是最直接的入口Key 管理在 https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-keys 接入说明在 https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc 。想先验证模型能力再动手写 Skill可以用模型对话快速试https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmodel-chat 。如果你打算把 Claude Code 长期用于编码和 Agent 任务Skill 会越攒越多调用频率也会上来这时候 Coding Plan 更合适https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-plan 。它面向的就是这种持续、高频的编码场景。最后给一个实用建议每写完一个 Skill先在项目里用一周观察输出是否稳定、触发是否准确再决定要不要提交到团队仓库。Skill 的迭代成本很低改 SKILL.md 就行不用动代码。把规则写细、把脚本补上、把参考文档放进去一个 Skill 就能从「能用」变成「好用」。