企业官网建设流程全解析

1. 为什么 SKILL.md 写好了，Claude Agent 却像没看见

很多人第一次接触 skill 规范，都会卡在同一个地方：文件明明按官方结构写好了，SKILL.md放在.claude/skills/下，name和description也填了，结果让 Claude Agent 干活时，它压根不加载这个 skill，或者加载了却像没读一样，行为完全不受约束。

我试过把一份写得很细的SKILL.md丢进项目，结果 agent 该用pdfplumber的地方自己换成了别的库，该走备份流程的地方直接跳步。排查半天才发现，问题不在 skill 内容本身，而在“规范翻译”这一层——也就是把 skill 的字段、目录结构、加载机制，正确映射成 Claude Agent 能读懂的配置。skill 规范（agentskills.io 那套）和 Claude Agent 的实际读取逻辑之间，隔着一层需要手动对齐的映射关系。

这篇就聚焦这个映射场景：把skill、description这些字段翻译成 Claude Agent 可读的配置，交付能直接复制的settings.json与config.toml骨架，给出 CC Switch / Cline 的接入步骤，最后用一个验证动作确认 skill 真的加载了、description 真的生效了。适合已经在写 skill、但被“写了不生效”折磨过的同学。

核心检索词先摆出来：SKILL.md 是什么、能做什么、适合谁。SKILL.md 是 skill 规范里的核心文件，一个 skill 就是一个目录，SKILL.md是必需项，顶部 YAML 元数据加正文 Markdown 指令；它能让 Claude Agent 在匹配到任务时按需加载你的领域知识、脚本和参考文档。适合所有想让 agent 稳定复现某类任务的人。

2. 前置：TaoToken 统一 Key 与 skill 目录约定

在动手翻译配置之前，先把两件事定下来：模型访问入口和 skill 的存放位置。

模型访问这块，我用 TaoToken 的统一 Key 来打通。它的好处是一个 Key 就能覆盖 Claude 系列模型的调用，不用在多个平台之间来回切配置。官网入口在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 基址是 https://taotoken.net/api （这个不加 UTM）。后面settings.json和config.toml里的base_url都指向它。

skill 目录约定这块，Claude Agent 的扫描逻辑遵循 skill 规范的三层加载：会话一开始只加载所有SKILL.md的name+description（每个约 50~100 token），模型根据description判断要不要用；决定用了才加载整个SKILL.md正文（建议 5k token 内）；正文里引用了references/、scripts/、assets/才按需加载。所以目录结构必须规范：

my-skill/ ├── SKILL.md # 必需：YAML 元数据 + Markdown 指令 ├── scripts/ # 可选：可执行脚本 ├── references/ # 可选：参考文档 └── assets/ # 可选：模板、静态资源

SKILL.md顶部的 YAML 必须严格按规范写，name要和目录名一致、最大 64 字符，description最大 1024 字符。这两个字段是“翻译”的关键——它们决定了 agent 会不会激活这个 skill。

注意：description不是随便写的简介，它是 agent 决策是否加载 skill 的唯一依据。写得太窄该触发时不触发，写得太宽不该触发时乱触发。

3. 可复制配置：settings.json 与 config.toml 骨架

这一节是重点，直接给能复制的骨架。Claude Agent 侧的配置主要落在settings.json，Cline 这类客户端用config.toml，两者字段含义要对齐。

3.1 settings.json 骨架（Claude Agent / Claude Code）

{ "model": "claude-sonnet-4-5", "apiKey": "sk-your-taotoken-key", "baseURL": "https://taotoken.net/api", "skills": { "enabled": true, "directories": [ ".claude/skills", ".agents/skills", "~/.claude/skills" ], "autoDiscovery": true, "maxScanDepth": 5, "maxScanDirs": 2000 }, "skillActivation": { "mode": "model-driven", "allowUserOverride": true, "overridePrefix": "/skill-" }, "context": { "protectSkillContent": true, "dedupeActivatedSkills": true } }

逐字段说明。baseURL指向 TaoToken 的 API 基址，apiKey用你在控制台生成的 Key。skills.directories是 agent 扫描 skill 的目录列表，项目级.claude/skills优先级高于用户级~/.claude/skills，.agents/skills是跨客户端通用约定，建议都留着。maxScanDepth和maxScanDirs是防止扫描过深目录树拖慢启动，规范里建议 4~6 层、2000 个目录上限。skillActivation.mode设为model-driven表示由模型根据description语义匹配决定激活，allowUserOverride允许用户用/skill-xxx显式指定。context.protectSkillContent很关键——它保证已激活的 skill 内容在上下文压缩时不被裁掉，否则聊到后面 agent 会“忘记” skill 规则。

3.2 config.toml 骨架（Cline 等客户端）

[model] provider = "openai-compatible" model_id = "claude-sonnet-4-5" base_url = "https://taotoken.net/api" api_key = "sk-your-taotoken-key" [skills] enabled = true directories = [".claude/skills", ".agents/skills"] auto_discovery = true max_scan_depth = 5 [skills.activation] mode = "model-driven" allow_user_override = true override_prefix = "/skill-" [skills.context] protect_skill_content = true dedupe_activated_skills = true

config.toml和settings.json的字段是一一对应的，只是命名风格从驼峰换成了下划线。provider用openai-compatible是因为 TaoToken 的 API 兼容 OpenAI 协议格式，Claude 系列模型通过这个协议也能正常调用。

3.3 SKILL.md 字段到配置的映射表

把 skill 规范字段翻译成 agent 可读配置，对应关系如下：

description的写法直接决定激活率。规范建议用祈使句，聚焦“用户想干嘛时用这个 skill”，而不是“这个 skill 能做什么”。比如：

--- name: csv-analyzer description: Analyze CSV and tabular data files — compute summary statistics, add derived columns, generate charts, and clean messy data. Use this skill when the user has a CSV, TSV, or Excel file and wants to explore, transform, or visualize the data, even if they don't explicitly mention "CSV" or "analysis." ---

对比一下差的写法description: Process CSV files.——太窄，用户说“帮我看看这个表格”就触发不了。

4. CC Switch / Cline 接入步骤与验证动作

配置骨架有了，接下来是接入和验证。这一步不做，你永远不知道 skill 到底加载没有。

4.1 CC Switch 接入

CC Switch 用来在多个 Claude 配置之间切换。接入 TaoToken 的步骤：

第一步，在 CC Switch 里新增一个 provider，base_url填https://taotoken.net/api，api_key填你的 TaoToken Key。

第二步，把上面 3.1 的settings.json内容合并进当前 profile，重点是skills.directories要包含你实际放 skill 的目录。

第三步，切换到这个 profile，重启 Claude Agent 会话，让 skill 扫描重新执行。

4.2 Cline 接入

Cline 走config.toml。在 Cline 的设置里找到配置文件路径，把 3.2 的内容写进去，api_key换成你的 Key。保存后 Cline 会在下次会话启动时重新扫描 skill 目录。

4.3 验证动作：调用一次确认 skill 加载与 description 生效

光看配置不叫验证，要实际跑一次。准备一个测试 skill，目录结构：

.claude/skills/csv-analyzer/ ├── SKILL.md └── scripts/ └── summarize.py

SKILL.md里写一条只有这个 skill 才知道的规则，比如“输出统计结果时必须用 markdown 表格，且表头固定为 Metric / Value”。然后在会话里发一条能匹配description的提示：

我有个 CSV 在 data/sales.csv，帮我算一下各列汇总，用表格给我。

观察 agent 的执行过程。如果 skill 生效，它会按SKILL.md里的规则输出固定表头的表格；如果没生效，它会用默认格式。更严谨的做法是看执行日志里的工具调用历史，确认出现了读取SKILL.md的动作。

再验证一次“不该触发”的情况，发一条不相关的提示：

帮我写个斐波那契函数。

如果 agent 没去加载csv-analyzer，说明description的边界控制得当。规范建议准备约 20 条查询，8~10 条应触发、8~10 条不应触发，每条跑 3 次算触发率，应触发的触发率高于 0.5 算通过。

5. 本篇常见错排查

配置和验证跑下来，最容易踩的坑集中在这几类。

5.1 skill 完全不加载

先查目录。agent 只认包含SKILL.md的目录，文件名大小写敏感，skill.md不行，必须SKILL.md。再查settings.json里的skills.directories有没有包含实际路径。如果 skill 放在项目级目录但项目没被标记为可信，部分实现会跳过加载，这是安全考量。

5.2 description 不触发

description写得太窄或太泛都会出问题。太窄比如只写了“处理 CSV”，用户说“分析这个表格”就匹配不上；太泛比如“处理数据文件”，用户说“改一下 Excel 公式”也会误触发。规范建议聚焦“用户想达成什么目标”，并明确列出适用场景，哪怕用户没直接点明领域词。

5.3 YAML 解析失败导致 skill 被跳过

description里带冒号（比如时间戳、URL）没加引号，宽松解析器能过，严格解析器直接报错跳过整个 skill。解决办法是用引号包起来，或者用 YAML 块标量（|或>）写多行文本。这也是为什么同一个 skill 在 A 客户端能用、B 客户端不能用。

5.4 激活后 agent 行为不受约束

检查context.protectSkillContent是否为true。如果为false，长会话里 skill 内容可能被上下文压缩裁掉，agent 就“忘记”规则了。另外确认dedupeActivatedSkills开启，避免同一 skill 反复注入。

5.5 脚本执行卡住

skill 里的脚本如果在非交互式 shell 里等待输入（比如input()、read -p），agent 会无限挂起。脚本所有输入必须通过命令行参数、环境变量或 stdin 传入，并且提供--help说明用法，报错信息要包含“发生了什么”和“下一步怎么办”。

6. 把 Key 和 skill 配置一次对齐

回到开头那个问题：SKILL.md 写好了却不生效，本质是规范字段和 agent 配置没对齐。把name、description映射到 skill 索引，把目录约定映射到skills.directories，把激活和上下文保护映射到skillActivation和context，这层翻译做对了，skill 才会真正被 agent 用起来。

模型访问这块，用 TaoToken 的统一 Key 把base_url和api_key一次配好，后面不管切 CC Switch 还是 Cline，都只改客户端不改 Key。需要生成或管理 Key 的话，控制台在 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，Key 管理页在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。

如果你还在调 skill 的接入和排障，建议先把 API Keys 和接入文档过一遍：接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。想先确认模型对话是否正常，可以去模型对话页 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 发一条测试。长期跑编码和 Agent 任务的话，Coding Plan 在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，Claude Code 相关配置参考 https://taotoken.net/claude-code-anthropic?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。

最后留一个实操建议：每次改完description，别只看配置文件，一定跑一次“应触发 + 不应触发”的对照测试。skill 这东西，写得好不好，agent 用不用，只有实际调用一次才知道。