企业官网建设流程全解析

1. 为什么你的 Claude Code 总是“记不住”项目规范

很多人第一次用 Claude Code 写业务代码时，都会经历一个相似的阶段：一开始觉得它挺聪明，能补全函数、能解释报错，但用着用着就发现，它总是记不住你们团队的约定。比如接口返回必须包一层data/meta/errors，比如组件文件名必须用 kebab-case，比如日志里禁止打印用户手机号。你每次开新会话都得重新交代一遍，交代完它答应得好好的，下一次换个文件又忘了。

这个问题的根源不在于模型能力，而在于你一直在用“一次性对话”的方式使用一个本该被工程化管理的工具。Claude Code 的技能系统（Skill System）就是为解决这件事设计的：它允许你把重复出现的领域知识、行为规则、工作流程，沉淀成一个个独立模块，在合适的时机自动注入到上下文里。你可以把它理解成给 Claude 装了一本“项目专属操作手册”，需要的时候它自己翻到对应那一页。

这篇文章面向的是希望把重复提示词沉淀为可复用技能的开发者。我会从 SKILL.md 的编写规范讲起，然后给出 Slash Command 的注册方式、Plugin 的挂载配置，最后附上验证技能是否被正确识别的完整操作步骤。整套流程你都可以直接复制到自己的项目里跑通。为了让请求链路更稳定，我会用 TaoToken 作为统一的模型接入入口，它的 API 地址是https://taotoken.net/api，兼容 Anthropic 的接口格式，Claude Code 可以直接对接。

在开始之前，先明确一个核心区分：Skill 和 Plugin 不是一回事。Skill 是知识包，本质是一份领域专家手册，核心文件是SKILL.md；Plugin 是分发与管理容器，核心文件是plugin.json，它可以包含多个 Skills、Commands、Agents 和 Hooks。一个 Plugin 可以装好几个 Skill，Plugin 负责“打包分发”，Skill 负责“执行注入”。理解了这个分层，后面的目录结构和加载优先级就不会乱。

2. TaoToken 前置准备：把 Claude Code 的请求链路接稳

在写第一个 Skill 之前，得先保证 Claude Code 能正常发请求。Claude Code 默认走 Anthropic 官方接口，但在国内网络环境下直连经常不稳定，表现为请求超时、流式响应中断、或者干脆卡在connecting状态。我试过比较省事的做法是把它指向一个兼容 Anthropic 协议的网关，TaoToken 就是这类服务，接口地址是https://taotoken.net/api，不需要额外装什么客户端，改几个环境变量就行。

第一步是拿到 API Key。打开https://taotoken.net/api-keys，登录后创建一个新的 Key，复制出来先存到安全的地方。注意这个 Key 只在创建时完整显示一次，关掉页面就看不到了。创建时可以给它起个名字，比如claude-code-dev，方便以后区分不同用途。

第二步是配置环境变量。Claude Code 读取的是ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY这两个变量。在 macOS 或 Linux 上，你可以直接写进~/.zshrc或~/.bashrc：

export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_API_KEY="sk-你的Key"

Windows 用户如果用的是 PowerShell，可以这样设置当前会话的变量：

$env:ANTHROPIC_BASE_URL="https://taotoken.net/api" $env:ANTHROPIC_API_KEY="sk-你的Key"

如果你希望持久化，可以在“系统属性 → 环境变量”里新建这两个用户变量，然后重开终端。改完之后执行echo $ANTHROPIC_BASE_URL确认一下有没有生效。

第三步是确认模型 ID。Claude Code 内部会调用类似claude-sonnet-4-5这样的模型标识，TaoToken 侧对这些模型名做了映射，你不需要改 Claude Code 的模型配置，保持默认即可。如果你在settings.json里手动指定过 model 字段，确保它写的是标准的 Claude 模型名，而不是别的厂商的命名。

这里有个容易踩的坑：有些人会把ANTHROPIC_BASE_URL写成带/v1后缀的地址，结果请求路径变成/v1/v1/messages，直接 404。TaoToken 的接入地址就是https://taotoken.net/api，不要自己加后缀。配置完成后，先别急着写 Skill，用一条最简单的请求验证链路是否通，具体命令在第四节给出。

3. 可复制配置：SKILL.md 目录结构与 Slash Command 注册

现在进入正题。Skill 的存放位置决定了它的作用范围和加载优先级，从高到低依次是：项目级.claude/skills/、用户级~/.claude/skills/、以及通过 Plugin 安装的目录。项目级只对当前项目生效，用户级对所有项目共享。日常开发建议把团队规范放项目级，把个人习惯放用户级。

一个标准的 Skill 目录长这样：

.claude/skills/my-api-skill/ ├── SKILL.md # 核心指令文件，必须 ├── scripts/ # 可执行脚本，可选 │ └── validate.py ├── references/ # 大型参考文档，按需加载 │ └── api-schema.json └── assets/ # 静态资源，可选 └── boilerplate.html

这四个目录对应不同的上下文消耗策略。SKILL.md在触发时注入上下文；scripts/里的脚本通过 Bash 工具执行，不占用上下文；references/通过文件读取工具按需加载，属于延迟加载；assets/作为输出素材，不读入上下文。这个设计的意义在于，你可以把体积很大的 API schema 放进references/，只在真正需要时才让模型去读，避免一上来就把上下文撑爆。

接下来是SKILL.md的写法。它采用 YAML frontmatter 加 Markdown 正文的结构。frontmatter 里最关键的三个字段是name、description和可选的allowed-tools。name是 Skill 的唯一标识，同时也是 Slash Command 的名称；description是 Claude 判断“何时激活这个 Skill”的依据，写法直接决定触发准确率。

下面是一份可以直接复制使用的配置，放在.claude/skills/my-api-skill/SKILL.md：

--- name: my-api-skill description: Handle REST API design and implementation following our company standards. Use this skill when the user asks to create, modify, or review API endpoints, request handlers, or response schemas. allowed-tools: Read, Edit, Bash --- ## API 设计规范 ### 命名约定 - 路径使用 kebab-case：`/user-profiles` 而非 `/userProfiles` - 资源名用复数：`/users` 而非 `/user` - 查询参数用 camelCase：`?pageSize=20` ### 响应格式 所有接口响应必须遵循以下结构： ```json { "data": {}, "meta": { "requestId": "..." }, "errors": [] }

错误处理

• 业务错误放在errors数组里，不要用 HTTP 状态码表达业务语义
• 每个错误对象必须包含code、message、field三个字段
• 禁止在错误信息里回显用户输入的原始内容

日志要求

• 禁止打印手机号、身份证号、银行卡号
• 请求日志必须带requestId

注意 `description` 的写法。好的写法是第三人称，明确说明“何时使用”，比如上面那句 `Use this skill when the user asks to create, modify, or review API endpoints`。差的写法是只写一句 `API design guidelines`，这样 Claude 很难判断什么时候该激活它。description 的字符预算会随上下文窗口大小动态调整，大约是上下文窗口的 2%，所以别写得太啰嗦，把触发场景说清楚就够了。 Skill 创建后会自动注册为同名 Slash Command，你可以在对话里直接输入 `/my-api-skill` 手动调用。如果你希望某个 Skill 不出现在命令菜单里，可以在 frontmatter 里加 `user-invocable: false`；如果希望它纯脚本执行、不调用模型，加 `disable-model-invocation: true`。 对于需要隔离上下文的重量级分析任务，可以用 `context: fork` 让它在独立子 Agent 中运行，避免污染主对话： ```yaml --- name: heavy-analysis description: Perform deep codebase analysis across multiple modules. Use this skill when the user requests a full architecture review. context: fork agent: code-explorer ---

如果你要把多个 Skill 打包分发，就需要一个 Plugin 容器。Plugin 的plugin.json大致长这样：

{ "name": "team-standards", "version": "1.0.0", "description": "Company-wide coding standards as reusable skills", "skills": [ "skills/my-api-skill", "skills/my-logging-skill" ] }

把 Plugin 目录放到项目里，或者通过/plugin install安装，里面的 Skills 就会被一起加载。Plugin 是分发单元，Skill 是执行单元，这个分层让团队可以共享一套规范，而不是每个人各自维护一份提示词。

4. 验证请求：确认 Skill 被正确识别与触发

配置写完不代表生效，必须验证。Claude Code 从 v2.1.0 起支持热重载，在~/.claude/skills或.claude/skills里新建或修改 Skill 文件后，不需要重启会话就能生效。如果你不确定，可以手动执行/reload-skills强制重新扫描。

验证分三步。第一步，查看已加载的 Skill 列表，在 Claude Code 会话里输入：

/skills

正常情况下你会看到my-api-skill出现在列表里，后面跟着它的 description 摘要。如果没看到，说明目录层级放错了，检查是不是把SKILL.md直接放在了.claude/skills/下而不是子目录里。每个 Skill 必须有自己的独立目录。

第二步，查看上下文占用：

/context

这个命令会显示当前 Skill 占用的 token 数量。Level 1 的元数据（name + description）常驻上下文，大约 100 tokens；Level 2 的SKILL.md正文只在触发时加载，通常控制在 5000 词以内。如果你发现某个 Skill 的元数据占用异常大，多半是 description 写太长了。

第三步，实际触发一次。在对话里输入一个符合 description 场景的请求，比如“帮我设计一个用户列表接口”，观察 Claude 是否自动加载了 API 规范。你也可以直接手动调用：

/my-api-skill 帮我 review 一下这个 handler

如果 Skill 被正确激活，Claude 的回复会遵循SKILL.md里定义的响应格式和命名约定。为了确认请求链路本身没问题，可以先用一条最小请求验证 TaoToken 接入是否正常：

curl https://taotoken.net/api/v1/messages \ -H "x-api-key: $ANTHROPIC_API_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": "reply with ok"}] }'

返回里能看到content字段和正常的usage统计，就说明 Base URL 和 Key 都对了。如果这一步就失败，先别折腾 Skill，回到第二节检查环境变量。

5. 本篇常见错排查：401、local proxy failed 与技能不触发

配置过程中最容易撞上的几类报错，我按出现频率排一下，并给出对应的定位方法。

第一类是401 Unauthorized。这个通常不是 Key 本身错了，而是环境变量没被 Claude Code 读到。常见原因是你在当前终端export了变量，但 Claude Code 是从另一个终端或 IDE 插件启动的，两者环境不共享。解决办法是在启动 Claude Code 的那个终端里重新export，或者把变量写进 shell 配置文件后重开终端。还有一种情况是 Key 复制时带了空格或换行，用echo $ANTHROPIC_API_KEY | wc -c看一下长度是否正常。

第二类是local proxy failed或连接超时。这多半是ANTHROPIC_BASE_URL写错了。正确值是https://taotoken.net/api，不要加/v1，不要加尾部斜杠。如果你之前配过别的代理工具，检查一下有没有残留的HTTP_PROXY/HTTPS_PROXY环境变量在干扰，可以用env | grep -i proxy排查。

第三类是reading choices相关的解析错误。这个报错通常出现在流式响应被中途截断时，根源是网络链路不稳定。可以先把max_tokens调小测试，确认是链路问题还是请求体问题。如果小请求正常、大请求失败，基本就是链路抖动，换用 TaoToken 这类稳定入口后一般能缓解。

第四类是 Skill 不触发。分两种情况：手动/my-api-skill能调用，但自动触发不灵，说明description写得不够具体，Claude 匹配不到。把触发场景写清楚，比如加上Use this skill when the user asks to...。另一种是手动也调不出来，说明 Skill 根本没加载，回到/skills命令确认列表里有没有它。如果用了 Plugin，检查plugin.json里的skills路径是不是相对于 Plugin 根目录的正确路径。

第五类是 OAuth 相关的报错。如果你之前登录过 Anthropic 官方账号，Claude Code 可能缓存了 OAuth token，和 API Key 模式冲突。可以执行/logout清掉登录态，然后确认走的是ANTHROPIC_API_KEY这条路径。这一步做完再重试请求。

排查时记住一个顺序：先验证裸请求（curl），再验证 Claude Code 能发请求，最后验证 Skill 被加载。任何一层失败都别往下走，否则问题会叠加，很难定位。

6. 把技能系统用起来：从单文件到团队共享

走到这里，你已经有了一个能跑通的 Skill。接下来值得做的是把它变成团队资产。单个SKILL.md适合个人快速试验，但当规范变多、参与的人变多，就需要 Plugin 来管理版本和分发。你可以把team-standards这个 Plugin 提交到内部仓库，新同学 clone 下来执行一次/plugin install，整套规范就到位了，不用再靠口头传达。

关于渐进式加载，再强调一个实践细节：把大块的参考文档放进references/，在SKILL.md正文里用一句话告诉 Claude“需要详细字段定义时读取 references/api-schema.json”。这样 Level 2 的正文保持精简，Level 3 的资源按需加载，上下文效率最高。我见过有人把几千行的 schema 直接贴进SKILL.md，结果每次触发都吃掉大量 token，响应变慢还容易丢细节。

如果你想把技能系统用在长期编码和 Agent 场景，可以了解一下 Coding Plan 这类按周期计费的方式，适合高频调用。需要看模型实际对话效果，可以直接在模型对话页测试。接入文档里有完整的接口说明和示例，排障时对照着看会快很多。

最后留一个可操作的小练习：把你项目里最常重复的那段提示词，比如“所有数据库查询必须走 repository 层”，抽成一个SKILL.md，放到.claude/skills/db-convention/下，然后用/skills确认它被加载，再发一个涉及数据库操作的请求看它是否自动生效。跑通这一遍，你就掌握了技能系统最核心的用法。