1. 先搞清楚 Claude Skills 到底解决什么问题Claude Skills 是 Anthropic 在 Claude Code 里推出的一套「技能包」机制本质是把指令、可执行脚本和参考资源打包成一个目录让模型在需要时按需加载。它能做的事很具体把你反复交代的工作流固化下来下次一句话触发不用再贴一遍长提示词。适合谁适合每天要在 Claude Code 里重复做同类任务的人比如固定格式的代码审查、日志分析、接口联调、文档生成。我最初接触时的痛点是每次让 Claude Code 分析一段代码都要重新写「先用类比解释、再画流程图、最后列易错点」这一长串要求写多了自己都烦。Skills 出现后这套要求被写进一个SKILL.md模型只在相关场景才加载完整内容平时只读名称和描述token 消耗明显下降。这就是它宣传的「渐进式披露」元数据常驻、正文按需、关联文件最后加载。一个 Skill 的目录结构很固定your-skill-name/ ├── SKILL.md # 必填主文件 ├── scripts/ # 可选可执行代码 ├── references/ # 可选参考文档 └── assets/ # 可选模板/字体/图标SKILL.md分两段YAML 前置元数据name和description负责让模型判断「什么时候用我」正文负责说明「具体怎么做」。理解这一点后面所有配置都是围绕它展开的。2. 接入前的准备TaoToken 统一 Key 与 API 通道在跑通 Skill 之前得先让 Claude Code 有一个稳定的模型通道。我用 TaoToken 做统一入口好处是 Key 和 API 地址集中管理切换模型不用改一堆环境变量。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 。先拿到 Key进入控制台创建 API Key页面在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite Key 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。创建后复制那串sk-开头的字符串只显示一次先存到本地密码管理器。注意Key 不要写进会提交到 Git 的文件里。用环境变量或本地settings.json并确认.gitignore已排除。Claude Code 读取配置的常见位置是用户目录下的~/.claude/settings.json。下面这段是接入 TaoToken 的最小配置把ANTHROPIC_BASE_URL指向 TaoToken 的 API 地址ANTHROPIC_AUTH_TOKEN填你的 Key{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的Key, ANTHROPIC_MODEL: claude-sonnet-4-5 } }如果你更习惯用 shell 环境变量等价写法是export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你的Key配置完先别急着建 Skill先验证通道通不通否则后面报错分不清是 Skill 写错还是 Key 没生效。3. 从 anthropics/skills 拉示例并手写第一个 SKILL.md官方示例仓库是anthropics/skills里面有不少可直接参考的复杂案例。先把它拉到本地看结构git clone https://github.com/anthropics/skills.git cd skills ls你会看到若干技能目录每个目录里都有SKILL.md。挑一个读它的 YAML 头和正文感受「描述怎么写才让模型判断得准」。看完就动手写自己的第一个。创建目录注意路径是 Claude Code 默认扫描的用户级技能目录mkdir -p ~/.claude/skills/explain-code然后在~/.claude/skills/explain-code/SKILL.md写入下面这份可复制模板--- name: explain-code description: 通过视觉图表和类比来解释代码。适用于解释代码运行原理、教授代码库知识或当用户询问“这段代码是怎么工作的”时。 --- 在解释代码时请务必包含以下内容 1. **以类比开头**将代码比作日常生活中的事物。 2. **绘制图表**使用 ASCII 艺术图展示流程、结构或相互关系。 3. **逐步引导**按步骤说明代码执行过程中发生了什么。 4. **强调易错点**指出常见的错误或误区。 保持解释过程具有对话感。对于复杂概念可以运用多个类比。这里有两个细节值得说。name建议用短横线小写和目录名保持一致避免模型匹配时混淆。description是渐进式披露的第一层写得越具体模型越知道何时触发写得太泛它可能在不该用的时候也加载浪费 token。写完保存Skill 就已经「存在」了。Claude Code 启动时会扫描~/.claude/skills下所有目录把每个SKILL.md的元数据预加载进系统提示。4. 用 skill-creator 生成自定义技能手写适合简单技能复杂技能用skill-creator更省事。它本身也是一个 Skill作用是引导你把自己的需求整理成规范的SKILL.md和目录结构。思路是让模型先「学习」skill-creator 的规则再让它帮你产出新技能。在 Claude Code 里直接对话让它读取 skill-creator 的内容并生成新技能。典型交互是这样请参考 skill-creator 的规范帮我创建一个名为 log-triage 的技能。 用途分析应用日志按错误级别归类提取高频异常并给出排查建议。 要求正文包含分类步骤、输出格式示例以及一个可选的 Python 脚本用于统计。模型会返回一份SKILL.md草稿和目录建议。你把它落到本地mkdir -p ~/.claude/skills/log-triage/scripts把生成的SKILL.md写入~/.claude/skills/log-triage/SKILL.md脚本写入scripts/下。一个带脚本的技能目录长这样log-triage/ ├── SKILL.md └── scripts/ └── count_levels.pyscripts/count_levels.py可以是一个简单统计脚本import sys from collections import Counter levels Counter() for line in sys.stdin: for lv in (ERROR, WARN, INFO, DEBUG): if lv in line: levels[lv] 1 break for lv, n in levels.most_common(): print(f{lv}: {n})在SKILL.md正文里引用它说明「需要统计时运行python scripts/count_levels.py输入为日志文件」。这样模型在第三层按需加载脚本平时不占上下文。5. 验证请求与成功结果配置和技能都就位后逐条验证。第一步确认通道curl https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的Key \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-5, max_tokens: 64, messages: [{role: user, content: 回复 OK}] }返回里带content字段且文本为OK说明 Key 和地址都对。若返回 401检查 Key 是否复制完整返回 404检查ANTHROPIC_BASE_URL是否漏了/api。第二步验证 Skill 被加载。在 Claude Code 里执行/skills列表里应出现explain-code和log-triage。没有的话检查目录层级是不是多套了一层正确路径是~/.claude/skills/explain-code/SKILL.md不是~/.claude/skills/explain-code/explain-code/SKILL.md。第三步显式触发/explain-code 帮我分析这段排序函数的执行流程成功时模型会按你写的四步输出先类比、再 ASCII 图、然后分步、最后易错点。隐式触发则直接问「这段代码是怎么工作的」模型应自动匹配到该技能。第四步验证带脚本的技能。准备一个日志文件printf ERROR db timeout\nINFO start\nWARN retry\nERROR db timeout\n app.log python ~/.claude/skills/log-triage/scripts/count_levels.py app.log输出ERROR: 2、WARN: 1、INFO: 1说明脚本可用。再在对话里让它分析app.log观察是否按技能正文的格式归类并给建议。6. 本篇常见错误排查报错一Skill not found。多数是目录名和name字段不一致或路径不在~/.claude/skills下。项目级技能放在项目根的.claude/skills用户级放在~/.claude/skills别混。报错二模型不触发技能。检查description是否太笼统。把「帮助处理代码」改成「当用户要求解释代码运行原理或询问这段代码怎么工作时使用」触发率会明显提升。报错三401 / invalid api key。Key 失效或环境变量没被读取。用echo $ANTHROPIC_AUTH_TOKEN确认若用settings.json确认 JSON 没有多余逗号导致解析失败。报错四脚本执行权限或路径错误。SKILL.md里引用脚本要用相对技能目录的路径如scripts/count_levels.py。Python 脚本确保有执行权限或显式用python调用。报错五token 消耗异常高。通常是正文太长或引用了大文件却没做按需加载。把大段参考文档移到references/正文只留触发条件和步骤。报错六修改后不生效。Claude Code 需要重启会话重新扫描技能目录。改完SKILL.md后退出重进再/skills确认。排查顺序建议固定先 curl 验通道再/skills验加载最后显式触发验内容。这样每层独立出问题能快速定位。7. 继续深入与统一入口跑通第一个技能后想验证模型对话效果可以直接用模型对话页 https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 把技能里的提示词贴进去对比输出。长期做编码和 Agent 任务的话Coding Plan 在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 适合把多个技能串成工作流。接入细节和参数说明看文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite Key 管理回到 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。一个实用经验判断某个任务值不值得写成 Skill看它一天会不会重复两次以上。会就固化不会先别写免得技能目录越堆越乱。写的时候把「触发条件」和「执行步骤」分开前者进description后者进正文这是让技能稳定命中的关键。
