企业官网建设流程全解析

1. 从重复提示词到可复用能力：Claude Code Skills 到底解决什么问题

如果你刚开始用 Claude Code，大概率经历过这样的循环：每次开新会话，都要把同一套要求重新打一遍——「先读 package.json 再改代码」「提交前跑一遍 lint」「生成接口时按我们团队的目录规范来」。写三五次还能忍，写到第三十次就开始怀疑人生。Claude Code 的 Skills 机制，本质就是把这套重复提示词沉淀成一个可被自动加载的能力包，让模型在合适的时机自己把规则读进来，而不是你每次手动喂。

Skills 是什么？你可以把它理解成给 Claude Code 准备的「岗位说明书 + 工具箱」。一个 Skill 就是一个文件夹，里面放一份SKILL.md描述这个能力什么时候用、怎么用，需要的话再附带脚本、模板、参考文档。Claude Code 启动时会扫描指定目录，把这些说明注册进上下文；当你的请求命中某个 Skill 的描述范围，它就会主动加载对应内容并执行。

它适合谁？三类人最该上手：一是每天和 Claude Code 打交道的独立开发者，二是团队里想统一 AI 编码规范的技术负责人，三是把 Claude Code 当 Agent 跑自动化流程的人。前两类解决「一致性」，第三类解决「可编排」。

这篇教程的路径很明确：先把本地 Node/npm 环境确认好，装好 Claude Code，用 API key 接入模型，然后从零写一个自定义 Skill，最后跑一次真实调用确认它被加载生效。全程命令可复制，配置片段可直接改。我试过在 Windows 和 macOS 上各走一遍，坑主要集中在环境变量和目录位置，后面会逐个拆。

需要先说明一点：Claude Code 本身是客户端工具，它需要一个能说 Anthropic 协议的后端。你可以用官方账号，也可以用兼容 Anthropic 接口的 API 服务。本文用 TaoToken 作为接入示例，因为它同时提供模型对话、Coding Plan 和 API Keys 管理，配置项和官方格式一致，换别的服务商时改 Base URL 和 Key 即可。

2. Node/npm 环境与 Claude Code 安装：版本检查、全局安装与 API key 接入

这一章把地基打牢。Claude Code 依赖 Node 18 以上，低于这个版本会在启动时报错，所以第一步永远是查版本。

打开终端（Windows 用 PowerShell 或 CMD，macOS/Linux 用默认终端），执行：

node -v npm -v

如果node -v输出v18.x以下，或者提示 command not found，就去 Node 官网下载 LTS 版本安装。装完重开终端再查一次。npm 一般随 Node 一起装好，版本 9 以上都够用。

确认环境没问题后，全局安装 Claude Code：

npm install -g @anthropic-ai/claude-code

安装完成后验证：

claude --version

能打印出版本号就说明 CLI 装好了。如果提示权限错误（macOS/Linux 常见），在命令前加sudo，或者按 npm 官方建议配置用户级全局目录，避免每次都要提权。

接下来是接入模型。Claude Code 读取的配置优先级里，环境变量和settings.json都有效，推荐用配置文件，方便长期管理。先创建配置目录，再写文件。

Windows CMD：

if not exist "%USERPROFILE%\.claude" mkdir "%USERPROFILE%\.claude" notepad "%USERPROFILE%\.claude\settings.json"

macOS/Linux：

mkdir -p ~/.claude nano ~/.claude/settings.json

在文件里写入下面这段 JSON，把YOUR_API_KEY换成你在 TaoToken 控制台创建的 Key：

{ "env": { "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY", "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_MODEL": "claude-sonnet-4-5" } }

三个字段的作用要分清：ANTHROPIC_BASE_URL决定请求发到哪个服务，ANTHROPIC_AUTH_TOKEN是身份凭证，ANTHROPIC_MODEL指定默认模型。Model ID 必须和服务商支持的列表一致，写错了会在请求阶段报模型不存在。

还有一个容易漏的步骤：首次启动的引导标记。编辑或新建~/.claude.json（Windows 是C:\Users\你的用户名\.claude.json），写入：

{ "hasCompletedOnboarding": true }

不设这个字段，Claude Code 可能反复进入初始化流程。保存后重开一个终端让配置生效。

如果你同时维护多个服务商或多个 Key，手动改文件会很烦。可以用 CC Switch 这类配置切换工具来管理多套 Base URL + Key + Model 组合，切换时不用动原始文件。它的本质就是帮你改写上面那份settings.json，理解这一点后，出问题也知道去哪查。

到这里，环境、CLI、API key 三件事都齐了。下一章开始写 Skill。

3. 可复制的 Skill 目录结构与配置文件：SKILL.md 写法与加载路径

Skills 的核心是目录约定。Claude Code 会在几个固定位置扫描 Skill，最常用的是用户级目录~/.claude/skills/，放在这里的 Skill 对所有项目生效；项目级目录是<项目根>/.claude/skills/，只对当前项目生效。团队协作时把项目级 Skill 提交进仓库，所有人拉下来就能用，这是统一规范最省事的做法。

一个 Skill 的最小结构长这样：

~/.claude/skills/ └── api-convention/ ├── SKILL.md ├── templates/ │ └── controller.ts └── scripts/ └── check.sh

SKILL.md是必须的，其余都是可选资源。文件名必须全大写，扩展名.md，放错大小写会导致扫描不到。

SKILL.md的格式是 YAML frontmatter 加正文。frontmatter 里最关键的是name和description，前者是 Skill 标识，后者决定 Claude Code 什么时候加载它。description 写得越具体，命中越准。下面是一个真实可用的例子，作用是让 Claude 生成接口时遵守团队约定：

--- name: api-convention description: 当用户要求新增或修改 HTTP 接口、Controller、路由时使用。强制遵循本项目的分层结构、命名规范和错误码约定。 --- # 接口开发规范 ## 目录结构 - 路由定义放在 src/routes/ - 业务逻辑放在 src/services/ - 数据访问放在 src/repositories/ - 类型定义放在 src/types/ ## 命名约定 - 文件名使用 kebab-case，例如 user-profile.service.ts - 导出的函数使用 camelCase - 常量使用 UPPER_SNAKE_CASE ## 错误处理 - 统一抛出 AppError，禁止直接 throw new Error - 错误码定义在 src/constants/error-codes.ts - HTTP 状态码与业务错误码分离 ## 生成接口时的步骤 1. 先在 src/types/ 补类型 2. 再写 repository 层 3. 然后写 service 层 4. 最后写 route 并注册 5. 补一个最小单测

正文部分就是给模型的指令。写的时候记住一个原则：Skill 是给模型看的文档，不是给人看的博客。用短句、明确动词、可执行步骤，避免模糊表述。像「尽量保持代码整洁」这种话模型没法执行，改成「函数超过 50 行必须拆分」才有约束力。

如果 Skill 需要跑脚本，可以在正文里写明调用方式，比如「执行bash scripts/check.sh校验命名」。Claude Code 在获得授权后可以运行这些命令。涉及文件操作的脚本建议先 dry-run，确认输出符合预期再让它真正执行。

创建目录的命令，Windows 和 macOS 通用写法：

mkdir -p ~/.claude/skills/api-convention/templates mkdir -p ~/.claude/skills/api-convention/scripts

然后把你写好的SKILL.md放进去。放好后不用重启 Claude Code，新会话会自动扫描。想确认目录位置对不对，直接在 Claude Code 里问它「你当前加载了哪些 skills，路径是什么」，它会列出扫描结果，这是最快的自检方式。

4. 验证 Skill 是否生效：一次真实调用与结果确认

配置写完不验证，等于没配。这一章走一遍完整的调用链路，确认 Skill 真的被加载。

先进入一个测试项目目录，启动 Claude Code：

cd ~/projects/demo-api claude

启动后先做一次自检，输入：

列出你当前可用的 skills，以及它们的加载路径

如果api-convention出现在列表里，说明目录和文件名都没问题。如果没出现，八成是路径写错或SKILL.md的 frontmatter 格式有误，下一章会专门排。

确认加载后，发一个能命中 description 的请求：

帮我新增一个 GET /users/:id 接口，返回用户基本信息

正常情况下，Claude Code 会先声明它要使用api-convention这个 Skill，然后按你写的步骤走：先补类型，再写 repository、service、route，最后补测试。你可以观察它的输出顺序，如果它跳过了类型定义直接写路由，说明 Skill 正文的约束力不够，回去把步骤写得更硬一点。

验证成功的标志有三个：一是它明确提到使用了该 Skill；二是生成的文件落在你规定的目录里；三是命名符合 kebab-case 和 camelCase 约定。三个都满足，Skill 就算真正生效了。

再补一个进阶验证：故意发一个不该命中 Skill 的请求，比如「解释一下这段正则」，看它是否还会加载api-convention。如果加载了，说明 description 写得太宽泛，需要收窄触发条件。Skill 的精准度直接决定它会不会在不该出现的时候干扰模型。

如果你用的是项目级 Skill，可以把它提交进 git，然后让同事拉下来跑同样的请求，对比输出是否一致。这是团队落地 Skills 最直接的验收方式。

5. 常见报错排查：401、模型不存在、Skill 不加载与配置不生效

这一章按真实报错逐个拆。以下都是我实际遇到过的，对照着查能省不少时间。

401 或 invalid api key：Key 错了、过期了，或者复制时带了空格。检查settings.json里ANTHROPIC_AUTH_TOKEN的值，前后不能有空白字符。如果用的是环境变量方式，确认当前终端会话确实读到了变量，echo $ANTHROPIC_AUTH_TOKEN（Windows 用echo %ANTHROPIC_AUTH_TOKEN%）能打印出来才算生效。

model not found 或 reading choices 报错：ANTHROPIC_MODEL写的 Model ID 服务商不支持。去 TaoToken 控制台的模型列表里核对准确 ID，注意大小写和连字符。有些服务商要求带版本后缀，漏了就报这个错。

local proxy failed / connection refused：Base URL 写错，或者本地网络到该地址不通。先确认ANTHROPIC_BASE_URL是https://taotoken.net/api，不要多加路径或斜杠。然后用curl直接测一下连通性：

curl -I https://taotoken.net/api

能返回 HTTP 状态码说明网络没问题，报错就回到配置里查。

Skill 不加载：按顺序查四点。第一，目录是不是~/.claude/skills/，注意是skills复数。第二，SKILL.md是不是全大写。第三，frontmatter 的---是不是成对出现，YAML 缩进有没有用 Tab（必须用空格）。第四，description 是不是太窄，导致请求没命中。把 description 临时改宽一点测试，能加载就说明是触发条件的问题。

配置改了不生效：Claude Code 在启动时读配置，改完必须重开终端或重启会话。另外检查有没有多份配置文件冲突，比如同时设了环境变量和settings.json，环境变量优先级更高，会覆盖文件里的值。

OAuth 相关报错：如果你之前登录过官方账号，本地可能残留 OAuth 凭证，和 API key 模式冲突。清理~/.claude/下的凭证缓存文件，或者用 CC Switch 切到纯 API key 模式，能解决大部分冲突。

排查的核心思路是分层：先确认网络通不通，再确认 Key 有没有效，然后确认 Model ID 对不对，最后才查 Skill 本身。按这个顺序走，不会在错误的地方浪费时间。

6. 把 Skills 用起来：从单文件到团队规范的落地路径

走到这里，你已经有了一个能跑的 Skill。接下来是把它变成日常习惯。

第一步，把最常重复的提示词抽出来。翻一下你最近一周的 Claude Code 会话，找出出现三次以上的要求，每一个都值得做成 Skill。常见的有：提交信息格式、代码审查清单、接口开发规范、数据库迁移步骤、日志埋点约定。

第二步，给 Skill 配资源文件。纯文字说明能解决 80% 的问题，剩下 20% 靠模板和脚本。比如把常用的 Controller 模板放进templates/，让模型直接套用，比它自由发挥稳定得多。

第三步，项目级和用户级分开管。通用规范放用户级，项目特有的放项目级并提交进仓库。这样换项目时通用能力还在，项目规范跟着代码走。

第四步，定期清理。Skill 写多了会互相干扰，description 重叠的合并，半年没用过的删掉。保持每个 Skill 职责单一，命中才准。

如果你想把 Claude Code 当长期编码助手用，Coding Plan 比按量计费更适合高频场景，模型额度和并发都更宽松。配置方式和你现在写的那份settings.json完全一致，换一下 Base URL 和 Key 就行。需要管理多套配置时，API Keys 页面可以创建多个 Key 分别对应不同用途，配合 CC Switch 切换，不会互相污染。

最后留一个实用技巧：把 Skill 的SKILL.md当成代码来维护，改动走 git，写清楚每次调整的原因。三个月后你回头看，这份文件就是团队 AI 编码规范的活文档，比任何口头约定都管用。