企业官网建设流程全解析

1. 为什么你的 Claude Code 需要 Agent Skills

如果你已经在用 Claude Code 写代码，大概率经历过这样的循环：每次开新会话，都要把团队代码规范、目录约定、提交信息格式重新贴一遍；换个项目，提示词又得改一版；同事问你「怎么让 Claude 按我们的方式写测试」，你只能把那段两百行的 prompt 复制过去。提示词本身没有版本管理，也没法被自动触发，时间一长就变成一堆散落在聊天记录里的碎片。

Agent Skills 想解决的就是这件事。它把「行为规范 + 专业知识 + 使用时机的组合」固化成一个文件夹，核心是一个SKILL.md文件，用 Markdown 写清楚这个技能做什么、什么时候用、具体规则是什么。Claude Code 启动时会先读取所有技能的元数据（name和description），判断当前任务是否相关；相关才加载SKILL.md正文；正文里引用的脚本、示例、参考文档，只在真正需要时才读。这套机制叫渐进式披露，好处是技能可以写得很细，但不会一上来就把上下文窗口塞满。

它适合谁？适合那些已经把 Claude Code 当日常工具、手里攒了一堆重复提示词、想让团队共享同一套 AI 行为规范的开发者。你不需要会写插件，只要会写 Markdown，就能搭出一个可复用、可 Git 管理、可跨项目迁移的技能骨架。下面我从目录结构开始，一步步把SKILL.md和settings.json配好，最后用一次真实调用验证它到底有没有被加载。

2. TaoToken 前置：把模型接入准备好

Claude Code 要跑起来，得先有一个能调通的模型入口。我这边习惯用 TaoToken 做统一接入，它的 API 地址是https://taotoken.net/api，兼容 Anthropic 的接口格式，Claude Code 直接改环境变量就能接上。官网在https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=，注册后在控制台生成 API Key 即可。

拿到 Key 之后，在终端里配置两个环境变量。Claude Code 读取的是ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY，把 base url 指向 TaoToken 的 API 地址，Key 填你生成的那串：

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

如果你不想每次开终端都 export，可以写进~/.zshrc或~/.bashrc。Windows 下用 PowerShell 的话是$env:ANTHROPIC_BASE_URL="https://taotoken.net/api"，写法不同但思路一样。

注意：ANTHROPIC_BASE_URL后面不要带/v1，Claude Code 会自己拼路径。多带一层容易出现 404，这是我自己踩过的坑。

Key 的管理入口在控制台的 API Keys 页面，建议给 Claude Code 单独建一个 Key，方便按项目区分用量。如果你还没生成，可以去https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite创建。接入文档在https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite，里面有不同客户端的配置示例，遇到字段对不上可以对照查。

环境变量配好后，先跑一次claude确认能正常对话，再往下做技能配置。如果这一步就报鉴权错误，后面技能加载的问题会被掩盖，排查起来更麻烦。

3. 可复制配置：SKILL.md 骨架与 settings.json

3.1 技能目录放哪里

Claude Code 的技能有两个位置：个人全局技能放在~/.claude/skills/，项目专用技能放在项目根目录的.claude/skills/。团队协作场景我建议用项目级，跟着 Git 走，谁拉下来都能用。个人常用的小工具放全局，跨项目复用。

每个技能是一个独立文件夹，文件夹名就是技能标识，里面必须有一个SKILL.md。最小结构长这样：

.claude/ └── skills/ └── python-naming-standard/ └── SKILL.md

如果技能需要附带脚本或参考文档，就在同级加scripts/、examples/、references/目录，然后在SKILL.md正文里用相对路径引用。这样核心规则保持在SKILL.md里，大块资料拆出去按需加载。

3.2 SKILL.md 的元信息骨架

SKILL.md开头是一段 YAML 元信息，用三个短横线包起来，然后是 Markdown 正文。元信息里name和description最关键，description直接决定 Claude 会不会自动触发这个技能，所以要写清楚「做什么」和「什么时候用」。

--- name: python-naming-standard description: 当用户要求编写、重构或审查 Python 代码时使用，确保内部辅助函数遵循 _internal_ 前缀规范。 --- ## 指令 1. 所有内部辅助函数必须以 `_internal_` 前缀命名。 2. 发现不符合规则的代码时，主动提出修改建议。 3. 提交前检查命名规范是否被违反。 ## 示例 - 正确：`def _internal_calculate_risk():` - 错误：`def _calculate_risk():` ## 参考 详细命名约定见 ./references/naming.md

name只支持小写字母、数字和短横线，最长 64 字符。description建议控制在 1024 字符以内，写得太泛会导致误触发，写得太窄又可能该触发时不触发。我的经验是把触发场景写具体，比如「当用户要求编写、重构或审查 Python 代码时」，比单写「Python 规范」命中率高很多。

除了这两个字段，还有几个可选字段值得了解。allowed-tools可以声明技能激活时允许无授权使用的工具；disable-model-invocation设为true时禁止自动触发，只能手动/name调用；user-invocable设为false则从斜杠菜单隐藏，作为后台增强能力。这些按需加，初期不用全上。

3.3 settings.json 里启用技能

技能文件放好后，还要在 Claude Code 的配置里确认技能目录被扫描。项目级配置在.claude/settings.json，个人级在~/.claude/settings.json。一个启用技能的配置片段如下：

{ "skills": { "enabled": true, "paths": [ ".claude/skills", "~/.claude/skills" ] } }

enabled打开技能系统，paths列出扫描目录。如果你只用一个位置，保留对应那条即可。改完配置重启 Claude Code，它会在启动时重新读取技能元数据。

提示：settings.json是标准 JSON，不能写注释。多写一行//会导致整个配置解析失败，技能静默不加载，这个坑很隐蔽。

3.4 用动态变量让技能更灵活

SKILL.md正文里可以插入动态变量，调用时自动替换。常用的有$ARGUMENTS（全部参数）、$ARGUMENTS[0]（按索引取）、$0（第一个参数的简写）、${CLAUDE_SESSION_ID}（当前会话 ID）。比如做一个会话日志技能：

--- name: session-logger description: 记录当前会话活动到日志文件。 --- 请将以下内容写入日志文件： logs/${CLAUDE_SESSION_ID}.log $ARGUMENTS

调用/session-logger 用户登录成功，它会生成一个带会话 ID 的日志文件，内容就是传入的参数。这种写法适合把重复的日志、提交、检查动作沉淀成技能。

4. 验证请求：一次真实调用看加载是否生效

配置写完，得验证技能真的被加载了。我用的办法是造一个必然触发技能的任务，然后看输出是否符合技能规则。

先确认目录结构：

mkdir -p claude-test/.claude/skills/python-naming-standard cd claude-test

把上面那段SKILL.md写进.claude/skills/python-naming-standard/SKILL.md，然后在项目根目录启动：

claude

进入交互后输入任务：

帮我写一个计算用户折扣的函数

如果技能加载成功，Claude 生成的函数名会带_internal_前缀，比如：

def _internal_get_discount(user_score): if user_score > 90: return 0.8 elif user_score > 70: return 0.9 return 1.0

如果生成的是def get_discount(...)，说明技能没被触发。这时候先别急着改SKILL.md，按下面顺序排查。

另一种验证方式是手动调用。如果技能没有设disable-model-invocation，可以在对话里输入/python-naming-standard，看斜杠菜单里有没有这个技能。菜单里能出现，说明元数据被正确读取；菜单里没有，问题出在目录或配置层。

还可以让 Claude 自述当前可用技能。输入「列出你当前加载的所有技能」，它会根据系统提示里的元数据回答。这个方法能快速确认技能是否进入了发现层。

5. 本篇常见错排查

技能不生效，原因基本集中在几个地方。下面按我实际遇到的频率排。

目录层级不对。最常见的是把SKILL.md直接放在.claude/skills/下，而不是放在技能子文件夹里。正确路径是.claude/skills/技能名/SKILL.md，中间必须有一层文件夹。少了这层，Claude Code 扫描不到。

YAML 元信息格式错误。三个短横线必须独占一行，name和description的冒号后面要有空格。用中文冒号、漏掉结尾的---、缩进用了 Tab，都会导致元信息解析失败。解析失败时技能不会报错，只是静默不加载，所以写完最好用 YAML 校验工具过一遍。

description 写得太泛或太窄。写「帮助写代码」会到处误触发，写「处理 2024 版财务 PDF 表单第三页」又几乎不会命中。判断标准是：把 description 读给一个不了解你项目的人听，他能不能判断出什么时候该用。

settings.json 解析失败。多一个逗号、多一行注释，整个文件就废了。改完用python -m json.tool .claude/settings.json验证一下，能打印出格式化结果才算合法。

环境变量没生效。ANTHROPIC_BASE_URL或ANTHROPIC_API_KEY没配好，Claude Code 根本连不上模型，技能自然无从加载。先在终端echo $ANTHROPIC_BASE_URL确认值正确，再启动claude。

技能名不符合规范。name里出现大写字母、下划线、空格，都会导致技能被跳过。只用小写字母、数字、短横线，最长 64 字符。

改了技能没重启。技能元数据在 Claude Code 启动时加载，运行中改SKILL.md不会热更新。改完退出重进一次。

排查时有个通用思路：先确认技能出现在斜杠菜单里（发现层通过），再确认自动触发时输出符合规则（加载层通过），最后确认引用的脚本或参考文档能被读到（资源层通过）。三层分开定位，比一股脑改文件高效得多。

6. 把技能用起来：从骨架到团队资产

技能骨架搭好之后，真正让它产生价值的是持续沉淀。我的做法是每次发现自己在重复某段提示词，就停下来问一句：这段东西是不是该变成一个技能？如果是，就新建一个文件夹，把规则写进SKILL.md，把大块资料拆到references/，把可执行逻辑放到scripts/。

团队场景下，项目级技能跟着仓库走，Code Review 时顺便审SKILL.md的变更，规范就自然沉淀下来了。新同事拉下代码，Claude Code 自动按团队规范工作，不需要额外培训。这比维护一份没人看的 Wiki 有效得多。

如果你想把技能用在长期编码或 Agent 工作流上，可以了解下 Coding Plan，它更适合高频、长会话的场景：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite。想先在对话里验证模型对技能的理解，用模型对话入口更轻量：https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite。接入过程中遇到字段或鉴权问题，直接查接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite。

技能不是一次写完就完事的，它更像代码，需要迭代。先从一个最小的SKILL.md开始，跑通一次调用，再慢慢加规则、加资源、加脚本。等你手里攒了五六个技能，会发现 Claude Code 的行为越来越像团队里那个熟悉规范的老手，而不是每次都要从头解释的新人。