【Claude code】创建自定义skill：从 SKILL.md 到可复用工作流

1. 为什么你的 Claude Code 需要一个自定义 skill

很多人第一次用 Claude Code 的时候，都是把它当成一个"更聪明的命令行补全"来用：问一句答一句，任务做完就散。但真正把 Claude Code 用顺手的人，几乎都会走到同一步——把那些反复出现的任务，沉淀成一个可复用的 skill。

所谓 skill，说白了就是给 Claude Code 装一个"专项工作手册"。它不是一个插件，也不是一段需要编译的代码，而是一个放在固定目录下的SKILL.md文件，加上可选的脚本、模板、参考文档。Claude Code 在接到任务时，会先扫一遍所有 skill 的元数据（name、description），判断"这个任务要不要用某个 skill"，确定要用之后，再去读SKILL.md正文里的具体步骤和规则。

这个机制的好处在于：你不需要每次都把一长串要求重新打一遍。比如你团队有一套固定的 React 组件写法、有一套固定的 Python 依赖安装规范、有一套固定的品牌配色，这些都可以写进 skill，之后 Claude Code 自动按你的规范来。

适合谁？三类人最该上手：一是每天重复写同类代码的开发者，二是需要让 AI 输出符合团队规范的人，三是想把"提示词工程"变成"可维护资产"的人。skill 的本质，就是把散落在聊天记录里的提示词，变成项目里可版本管理的文件。

我试过把"检测 Python 环境并安装缺失依赖"这件事做成 skill，之后每次让 Claude Code 处理一个陌生脚本，它都会先跑一遍环境检查，再决定装什么包，省掉了大量来回确认。下面从目录结构开始，一步步把它跑通。

2. TaoToken 前置准备：让 Claude Code 稳定调用模型

在写 skill 之前，得先保证 Claude Code 能稳定地调用到模型。Claude Code 本身是一个客户端，它需要一个兼容 Anthropic 接口的服务端点。这里我用 TaoToken 来做接入，它的 API 地址是https://taotoken.net/api，兼容 Anthropic 的 Messages 接口格式，Claude Code 可以直接对接。

先说清楚要准备的三件套，这是后面所有配置的基础：

API Key 的获取入口在控制台的 API Keys 页面，登录后新建一个即可。这里要提醒一句：Key 只在创建时完整显示一次，关掉页面就看不到了，所以生成后立刻复制到安全的地方。如果你还没账号，可以先到官网了解，再进控制台建 Key。

拿到 Key 之后，Claude Code 有两种接入方式。第一种是环境变量方式，适合临时验证：

export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_API_KEY="sk-你的key" export ANTHROPIC_MODEL="claude-sonnet-4-5"

第二种是写进配置文件，适合长期使用。Claude Code 会读取用户目录下的配置，把上面三项固化进去，之后开新终端也不用重新 export。具体路径各平台略有差异，核心就是 Base URL、Key、Model ID 这三项对齐。

如果你用的是 Claude Code 的 settings 文件，可以这样写：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的key", "ANTHROPIC_MODEL": "claude-sonnet-4-5" } }

配置完成后，先别急着写 skill，跑一个最小请求确认链路是通的。这一步很关键，因为后面 skill 加载失败时，你要能区分是"模型没连上"还是"skill 写错了"。验证命令和预期结果放在第 4 节，先把配置落地。

注意：Base URL 一定不要多加/v1之类的后缀，Claude Code 会自己拼接路径，多写反而会 404。Key 也不要提交到 Git 仓库，建议用环境变量或本地配置文件并加进.gitignore。

3. 可复制配置：SKILL.md 模板与目录结构

现在进入正题。一个最小可用的 skill，只需要一个目录加一个SKILL.md。先建目录：

# 进入项目根目录 mkdir -p .claude/skills/my-custom-skill cd .claude/skills/my-custom-skill touch SKILL.md

完整结构可以按需扩展，但核心永远是SKILL.md：

.claude/skills/your-skill-name/ ├── SKILL.md # 必需：元数据 + 指令正文 ├── scripts/ # 可选：可执行脚本（Python/Bash/JS） │ └── helper.py ├── templates/ # 可选：代码/文档模板 │ └── component.tsx ├── references/ # 可选：参考文档 │ └── api-spec.md └── examples/ # 可选：输入输出样例 └── usage.md

SKILL.md分两部分：顶部是 YAML 前置元数据，下面是 Markdown 指令正文。Claude Code 的读取顺序是——先读元数据判断要不要启用，确定启用后再读正文里的步骤和规则。所以元数据里的name和description写得准不准，直接决定 skill 会不会被触发。

下面是一个可直接复制的模板，我把它做成"品牌规范"场景，你可以照着改：

--- name: brand-guidelines description: 当创建演示文稿、文档或营销材料时，应用 Acme 品牌规范，确保配色、字体、Logo 使用一致 --- ## Overview 本 skill 提供 Acme 官方品牌规范。创建演示文稿、文档或对外材料时， 应用以下标准，确保所有输出符合视觉识别。 ## Brand Colors - Primary: #FF6B35 (Coral) - Secondary: #004E89 (Navy Blue) - Accent: #F7B801 (Gold) - Neutral: #2E2E2E (Charcoal) ## Typography - Headers: Montserrat Bold - Body text: Open Sans Regular - H1: 32pt / H2: 24pt / Body: 11pt ## Logo Usage 浅色背景用全彩 Logo，深色背景用白色 Logo， Logo 周围最小留白 0.5 英寸。 ## When to Apply - PowerPoint 演示文稿 - 对外分享的 Word 文档 - 营销材料 - 客户报告

注意 YAML 里的description是触发匹配的关键。它要写清楚"什么时候用"，而不是"这是什么"。比如写"应用品牌规范"就不如写"创建演示文稿、文档时应用品牌规范"——后者包含了触发场景的关键词，Claude Code 更容易匹配上。

再给一个更实用的例子，就是我前面提到的 Python 依赖检测 skill：

--- name: pip-install-skill description: 根据代码检测需要安装的 Python 包，并根据当前环境执行 pip 安装 --- ## Overview 根据当前代码检测需要的 Python 包，获取当前 Python 与 pip 环境， 对不存在的包执行安装。 ## Steps 1. 读取目标代码，提取 import 语句 2. 执行 `python -c "import sys; print(sys.executable)"` 确认解释器 3. 执行 `pip list` 获取已安装包 4. 对比差集，对缺失包执行安装 5. 安装命令使用镜像加速： `pip install xxx -i https://pypi.tuna.tsinghua.edu.cn/simple` ## Notes - 优先使用当前虚拟环境，不要污染全局 - 安装前打印将要执行的命令，便于确认

这个 skill 的价值在于：它把"看代码 → 查环境 → 装包"这条链路固化下来，Claude Code 每次遇到陌生脚本都会自动走一遍，不用你手动提醒。

4. 验证请求：一次创建、调用、成功的完整动作

配置和模板都就位后，跑一遍完整流程。第一步，确认模型链路是通的。在终端里发一个最小请求：

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数组，第一项text是模型回复。如果这里就报错，先别往下走，回到第 5 节排查。链路通了之后，启动 Claude Code，在项目根目录下它会自动扫描.claude/skills/目录。

第二步，查看 skill 是否被识别。在 Claude Code 里输入：

/skills list

你应该能看到brand-guidelines和pip-install-skill出现在列表里。想看某个 skill 的详情：

/skills info pip-install-skill

第三步，触发 skill。有两种方式。自动触发是直接描述任务，比如"帮我检查这段代码的依赖并安装缺失的包"，Claude Code 会根据description匹配到pip-install-skill。手动触发是用斜杠命令：

/pip-install-skill

第四步，观察执行过程。以 pip skill 为例，Claude Code 应该会依次打印：读取到的 import 列表、当前解释器路径、已安装包对比结果、将要执行的 pip 命令。如果它跳过了某一步，说明SKILL.md正文写得不够明确，回去把步骤拆细。

一个成功的信号是：你给它一段带import pandas的脚本，它会先pip list确认 pandas 不在，然后执行带镜像的安装命令，最后再 import 一次验证。整个过程不需要你手动介入。

提示：skill 的正文越像"操作手册"越好。写"安装缺失的包"太模糊，写"执行 pip list，对比 import 列表，对差集执行 pip install"就明确得多。Claude Code 是按步骤执行的，步骤越具体，结果越稳定。

5. 常见报错排查：401、local proxy failed 与 OAuth

skill 跑不通，八成不是 skill 本身的问题，而是接入层或配置层的问题。下面按真实报错逐个拆。

报错一：401 Unauthorized。这是最常见的。原因通常是 Key 写错、Key 过期，或者请求头字段名不对。Anthropic 接口用的是x-api-key，不是Authorization: Bearer。如果你在 settings 里写成了ANTHROPIC_AUTH_TOKEN而客户端读的是ANTHROPIC_API_KEY，也会 401。排查顺序：先确认 Key 没多余空格，再确认字段名，最后确认 Base URL 没多写路径。

报错二：local proxy failed / connection refused。这个报错说明客户端在往一个本地地址发请求，但那个地址没有服务在监听。常见于你之前配过某个本地转发工具，环境变量里残留了ANTHROPIC_BASE_URL=http://localhost:xxxx。解决办法是把环境变量清掉，重新指向https://taotoken.net/api。检查命令：

echo $ANTHROPIC_BASE_URL env | grep -i anthropic

把输出里指向 localhost 的项全部 unset，再重新 export 正确的值。

报错三：reading 'choices' of undefined。这个报错通常出现在用 OpenAI 格式去请求 Anthropic 端点，或者反过来。Anthropic 的响应结构是content[].text，OpenAI 是choices[].message.content。如果你在代码里按choices去解析，而服务返回的是 Anthropic 格式，就会读到 undefined。确认你用的 SDK 和端点格式一致。

报错四：OAuth 相关报错。如果你之前登录过官方账号，本地可能残留了 OAuth token，客户端会优先用它而不是你的 API Key。表现是请求发到了错误的端点，或者提示 token 无效。解决办法是清理本地凭据缓存，改用 API Key 方式。具体缓存路径各平台不同，核心是找到 credentials 文件删掉或重命名。

报错五：skill 不触发。模型链路正常，但/skills list里看不到你的 skill。检查三点：目录是不是在项目根目录的.claude/skills/下；SKILL.md的 YAML 有没有语法错误（比如冒号后没空格）；description里有没有触发场景的关键词。YAML 对缩进敏感，用两个空格，别用 Tab。

注意：排查时养成"分层验证"的习惯——先用 curl 验证模型链路，再用/skills list验证 skill 加载，最后才验证触发逻辑。一次只改一层，问题定位会快很多。

6. 把 skill 用起来：从单文件到可复用工作流

跑通第一个 skill 之后，真正的价值在于把它变成团队资产。几个实操建议。

第一，skill 要进版本控制。.claude/skills/目录直接提交到仓库，团队成员拉下来就能用同一套规范。这比在群里发提示词截图靠谱得多。

第二，description要持续打磨。它是触发匹配的唯一依据，写得越贴近真实任务描述，命中率越高。可以观察一段时间，看哪些任务没触发，反过来优化 description 的关键词。

第三，善用scripts/和templates/。纯文本指令能解决大部分问题，但涉及确定性计算或固定格式输出时，挂一个脚本更稳。比如代码格式化、依赖检查这类任务，脚本比让模型自由发挥可靠。

第四，skill 之间可以组合。一个"项目初始化"skill 可以调用"依赖安装"skill 和"代码规范"skill，形成一条完整链路。Claude Code 会按需加载，不用你手动串联。

如果你想把这类工作流长期跑在编码和 Agent 场景里，可以了解下 Coding Plan，它更适合高频、长时间的编码任务。需要生成或管理 Key 的时候，直接进 API Keys 页面操作；接入细节和字段说明，接入文档里有完整对照。模型能力本身想先试试手感，模型对话页面可以直接发请求验证。

最后留一个我踩过的坑：skill 的name不要用中文或空格，用短横线连接的英文，否则斜杠命令可能识别不了。description可以用中文，但关键词最好中英混写，覆盖不同表述习惯。把这些细节处理好，你的第一个自定义 skill 就能稳定跑起来了。