1. 为什么我要自己写一个 SKILL 管理工具Claude Code 的 SKILL 机制本质上是一套“可被模型按需加载的提示词包”它把一段固定流程、一套领域知识或者一个工具调用规范封装成 Markdown 加脚本的目录模型在合适的时候自动读取并执行。它能做什么简单说就是把你反复交代给 Claude Code 的“套路”固化下来下次一句话甚至一个斜杠命令就能触发。适合谁已经用 Claude Code 写过几个项目、开始觉得每次都要重复描述需求很烦的开发者。我一开始也是手动在.claude/skills下面建文件夹、写SKILL.md写了两三个之后发现一个问题创建靠记忆、安装靠拷贝、查看靠ls三个动作全是手工活而且不同平台对 SKILL 的目录命名还不一样。Claude Code 认.claude/skillsCodex 认自己的路径AgentSkills 开放标准又是另一套。结果就是我在 Claude Code 里写好的技能换到 Codex 里根本加载不出来排查半天才发现是文件夹名字不对。所以这一篇的目标很明确跑通一个自定义 SKILL 从创建、安装到查看的完整生命周期并且把模型侧的接入统一到 TaoToken 的 Key 和 API 通道上这样无论你后面用 Claude Code 还是别的编码 Agent模型调用这一层不用反复换配置。下面我会给出可复制的目录结构、配置文件片段、安装命令以及验证技能被正确识别的具体动作。整个过程我实测下来最容易卡住的不是写技能本身而是路径和规范对不上所以排障部分我会写得细一点。2. TaoToken 统一 Key 接入 Claude Code 的前置准备在动手写 SKILL 之前先把模型通道理顺。Claude Code 默认走 Anthropic 官方接口但很多人的网络环境并不方便直连而且不同工具各配一套 Key 很麻烦。TaoToken 提供的是统一的 API 通道一个 Key 可以对接多种模型Claude Code、Codex、Cline 这些工具都能复用同一套配置。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。先说清楚一个概念避免新手绕弯Claude Code 读取模型配置靠的是环境变量主要是ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN这两个。你把 Base URL 指向 TaoToken 的 API 地址把 Key 填进去Claude Code 就会把请求发到这条通道上模型侧由 TaoToken 转发。SKILL 本身是本地文件跟模型通道无关但 SKILL 执行时如果需要模型推理走的就是这条通道所以先把通道配好后面验证技能调用时才能看到完整效果。获取 Key 的路径是登录后在控制台的 API Keys 页面创建地址是 https://taotoken.net/console/api-keys 。创建完复制那串以sk-开头的字符串注意只显示一次丢了就重新建一个。这里有个细节Key 不要直接写进会提交到 Git 的文件里建议放在 shell 的配置文件或者项目的.env里并且把.env加进.gitignore。配置方式分两种临时生效和永久生效。临时的话直接在终端里 export关掉窗口就没了适合先测试export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你的Key永久生效就写进~/.zshrc或者~/.bashrc然后source一下。Windows 用户如果用 PowerShell对应的是$env:ANTHROPIC_BASE_URL这种写法或者直接在系统环境变量里加。配完之后用echo $ANTHROPIC_BASE_URL确认一下有没有生效这一步别省我见过太多人配完没 source 就开始排查别的问题。如果你还想在 Claude Code 里指定具体模型可以在启动时加参数或者在配置文件里写。模型 ID 的写法参考 TaoToken 文档里的模型列表文档地址是 https://taotoken.net/doc 。这里要提醒一句Base URL 和 Key 是必填的Model ID 是可选的不填的话 Claude Code 会用默认模型。三件套凑齐之后模型侧接入就算完成了接下来才是 SKILL 的正题。3. SKILL 目录结构与可复制配置片段SKILL 的核心其实就一个文件SKILL.md。它是一份带 YAML frontmatter 的 Markdownfrontmatter 里声明技能的名字、描述、触发条件正文部分写具体的执行指令。模型在启动时会扫描技能目录读取每个SKILL.md的元信息当你的输入匹配到描述时就把对应的正文加载进上下文。理解了这个机制你就知道为什么目录结构和命名这么重要——扫描不到技能就等于不存在。先看一个标准的技能目录长什么样。假设技能名叫ascii-art-converter放在用户级目录下~/.claude/skills/ └── ascii-art-converter/ ├── SKILL.md ├── scripts/ │ └── convert.py └── references/ └── styles.mdSKILL.md是必须的scripts和references是可选的。脚本放可执行逻辑引用文件放模型按需读取的补充资料。下面是一个可以直接复制的SKILL.md片段注意 frontmatter 的字段--- name: ascii-art-converter description: 将输入的英文字母或单词转换为 ASCII 艺术字支持标准、粗体、3D、简约、花体五种风格。当用户要求生成 ASCII 艺术字、字符画、文字横幅时使用。 --- # ASCII Art Converter ## 使用场景 用户输入一段英文文本要求转换成 ASCII 艺术字。 ## 执行步骤 1. 解析用户输入提取待转换文本和风格偏好。 2. 若未指定风格默认使用 standard。 3. 调用 scripts/convert.py 生成结果或直接按 references/styles.md 中的字符表手工拼装。 4. 返回转换结果并询问是否需要其他风格。 ## 约束 - 文本长度建议不超过 20 个字符。 - 主要支持英文字母和数字。frontmatter 里的name必须和文件夹名一致description要写清楚“什么时候用”这是模型判断是否加载技能的唯一依据写得越具体触发越准。很多人技能不生效问题就出在 description 太笼统比如只写“处理文本”模型根本不知道什么时候该调用。不同平台的目录差异是另一个坑。Claude Code 认~/.claude/skills/用户级和项目根目录下的.claude/skills/项目级。Codex 认的是自己的路径通常是~/.codex/skills/。AgentSkills 开放标准则建议放在~/.agentskills/下。如果你想让一个技能在多个工具里都能用要么在每个目录下都放一份要么用软链接指过去。我自己的做法是维护一份源文件然后用脚本同步到各个目录避免改了一处忘了另一处。安装技能本质上就是把技能文件夹放到正确的目录下。手动安装就是cp -r或者mv自动安装就是让 Claude Code 帮你拷贝。不管哪种方式放完之后都要重启 Claude Code因为技能列表是在启动时扫描的运行中新增的目录不会被识别。这一点和很多插件机制不一样别指望热加载。4. 验证 SKILL 被正确识别与调用配置和目录都就位之后怎么确认技能真的被加载了最直接的方式是在 Claude Code 里输入斜杠命令。启动 Claude Code输入/会弹出可用命令列表如果你看到自己定义的技能名出现在里面说明扫描成功。比如我那个转换技能输入/ascii-art-converter就能直接触发。如果斜杠列表里没有先别急着改代码按这个顺序排查。第一确认目录路径对不对ls ~/.claude/skills/看看文件夹在不在。第二确认SKILL.md的 frontmatter 格式正确name和文件夹名一致description非空。第三确认 Claude Code 是重启过的。这三步能解决八成问题。技能被识别之后还要验证它能被正确调用。有两种触发方式一种是斜杠命令显式调用另一种是自然语言描述触发。显式调用最稳适合调试。自然语言触发考验的是 description 的匹配度。我测试的时候会故意用不同的说法比如“帮我把 HELLO 转成字符画”和“生成一个 ASCII 横幅”看模型能不能都命中。调用成功之后模型会读取SKILL.md的正文并执行。如果技能里引用了脚本比如scripts/convert.py模型会尝试运行它。这时候如果脚本有依赖没装就会报错。所以技能开发完之后最好在本地先把脚本单独跑一遍确认能执行再交给模型调用。我踩过的坑就是脚本里用了某个第三方库本地环境有但 Claude Code 的执行环境没有结果调用时报模块找不到。验证模型侧通道是否正常工作可以在技能执行过程中观察。如果技能需要模型推理而 Base URL 或 Key 配错了会直接报 401 或者连接失败。这时候回到第 2 节检查环境变量。如果技能只是本地脚本执行、不涉及模型调用那通道配错也不影响但这种情况很少大部分技能都需要模型参与。一个完整的验证流程是这样的启动 Claude Code输入斜杠命令看到技能响应输入测试文本拿到转换结果再换一种自然语言说法重复一次。两次都成功说明技能从创建到调用整条链路是通的。如果只有斜杠命令能触发、自然语言不行那就是 description 的问题回去改描述。5. 常见报错与排查对照技能开发和使用过程中报错集中在几个地方。我把遇到过的真实报错和对应原因整理出来方便你对照。第一个是401 Unauthorized或者authentication_error。这个基本是 Key 的问题要么没配、要么配错、要么 Key 失效了。检查ANTHROPIC_AUTH_TOKEN的值确认没有多余空格确认 TaoToken 控制台里这个 Key 还是启用状态。如果用的是项目级.env确认 Claude Code 启动时加载了这个文件。第二个是local proxy failed或者连接超时。这个通常是 Base URL 写错了或者网络到不了。确认ANTHROPIC_BASE_URL是https://taotoken.net/api注意结尾不要多加斜杠或者路径。如果确认地址没错还是连不上检查一下本地网络环境。第三个是reading choices相关的报错类似Cannot read properties of undefined (reading choices)。这个一般出现在响应格式不符合预期的时候可能是模型 ID 写错了导致返回体结构不对。检查你指定的 Model ID 是否在 TaoToken 支持的列表里不确定就先不指定用默认模型跑通再说。第四个是技能不生效斜杠列表里看不到。前面说过优先查目录路径、frontmatter 格式、是否重启。还有一个容易忽略的点文件夹名里有大写或者特殊字符。技能名建议全小写加连字符避免空格和中文兼容性最好。第五个是脚本执行报错比如command not found或者ModuleNotFoundError。这是运行环境的问题不是技能本身的问题。确认脚本有可执行权限chmod x确认依赖装在了 Claude Code 能访问的环境里。如果脚本用了 Python注意 shebang 写的是#!/usr/bin/env python3还是别的路径。第六个是 OAuth 相关的报错。如果你之前用官方登录方式配过 Claude Code环境变量和 OAuth 凭证可能冲突。这时候清掉旧的凭证统一用 API Key 方式。具体就是检查~/.claude下有没有残留的认证文件有的话备份后删掉重新用环境变量启动。排查的核心思路是分层先确认模型通道通不通再确认技能目录扫没扫到最后确认技能逻辑对不对。三层分开查比一上来就改代码高效得多。我一般会先用一个最简单的技能就一个SKILL.md正文只写“输出 hello”测试能跑通说明框架没问题再往上加复杂度。6. 把技能管理固化成长期习惯跑通一个技能之后真正有价值的是把这套流程变成习惯。我现在每遇到一个重复三次以上的操作就会考虑把它写成技能。比如固定的代码审查清单、特定的提交信息格式、某个项目的部署步骤这些都可以封装。技能写多了之后你会发现 Claude Code 越来越“懂你”因为你的工作方式被固化进了它的可加载知识里。关于技能的存放我的建议是分两层通用的、跨项目复用的放用户级目录~/.claude/skills/跟具体项目强相关的放项目级.claude/skills/并提交到仓库这样团队其他人拉下来就能用。项目级的技能记得在.gitignore里排除掉本地测试用的临时技能避免污染仓库。模型通道这边统一用 TaoToken 的 Key 之后切换工具不用重新配。你可以在 https://taotoken.net/api-keys 管理你的 Key在 https://taotoken.net/doc 查模型和接口文档。如果后面要长期跑编码任务或者 Agent 流程可以看看 Coding Plan地址是 https://taotoken.net/coding-plan 按用量规划比临时充值省心。想先试试模型对话效果的直接去 https://taotoken.net/ 的模型对话页面体验。最后说一个实用技巧技能写完之后在SKILL.md里加一段“自检”指令让模型在加载技能后先复述一遍它理解的执行步骤确认无误再动手。这个动作能挡掉很多因为描述歧义导致的错误执行。我现在的每个技能都带这段实测下来返工率明显下降。技能这东西写一次省一百次值得花时间打磨。