企业官网建设流程全解析

1. 为什么我要自己写一个 SKILL 管理工具

Claude Code 的 SKILL 机制本质上是一套“可被模型按需加载的提示词包”，它把一段固定流程、一套领域知识或者一个工具调用规范，封装成 Markdown 加脚本的目录，模型在合适的时候自动读取并执行。它能做什么？简单说，就是把你反复交代给 Claude Code 的“套路”固化下来，下次一句话甚至一个斜杠命令就能触发。适合谁？已经用 Claude Code 写过几个项目、开始觉得每次都要重复描述需求很烦的开发者。

我一开始也是手动在.claude/skills下面建文件夹、写SKILL.md，写了两三个之后发现一个问题：创建靠记忆、安装靠拷贝、查看靠ls，三个动作全是手工活，而且不同平台对 SKILL 的目录命名还不一样。Claude Code 认.claude/skills，Codex 认自己的路径，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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_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_URL="https://taotoken.net/api" export ANTHROPIC_AUTH_TOKEN="sk-你的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 的 Markdown，frontmatter 里声明技能的名字、描述、触发条件，正文部分写具体的执行指令。模型在启动时会扫描技能目录，读取每个SKILL.md的元信息，当你的输入匹配到描述时，就把对应的正文加载进上下文。理解了这个机制，你就知道为什么目录结构和命名这么重要——扫描不到，技能就等于不存在。

先看一个标准的技能目录长什么样。假设技能名叫ascii-art-converter，放在用户级目录下：

~/.claude/skills/ └── ascii-art-converter/ ├── SKILL.md ├── scripts/ │ └── convert.py └── references/ └── styles.md

SKILL.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里加一段“自检”指令，让模型在加载技能后先复述一遍它理解的执行步骤，确认无误再动手。这个动作能挡掉很多因为描述歧义导致的错误执行。我现在的每个技能都带这段，实测下来返工率明显下降。技能这东西，写一次省一百次，值得花时间打磨。