企业官网建设流程全解析

1. 从零写一个 skill.md，为什么我卡在了第一步

刚接触 Claude Code Skill 的时候，我以为最难的是 Prompt 怎么写。真正上手才发现，卡住我的是更前面的问题：skill.md 的 YAML 骨架到底长什么样，哪些字段是必须的，写完之后怎么确认它真的被 Claude Code 加载了。

Skill 本质上就是一段结构化的提示词，把"做事流程"写成文件，让 AI 照着执行。它适合谁？适合那些每周每月都在重复同一套操作、步骤固定、格式固定的人。比如月报生成、代码审查清单、踩坑文章骨架，这些场景的共同点是：输入明确、输出格式固定、步骤可复用。

但光知道原理没用。我第一次写 skill.md 的时候，name 和 description 写反了位置，正文里步骤编号混乱，结果 Claude Code 根本没触发这个 Skill。后来才搞明白，YAML frontmatter 的格式要求比想象中严格，description 的措辞直接决定触发命中率。

这篇就按我踩过的坑，从 skill.md 的 YAML 骨架开始，到用 TaoToken 统一 Key 跑通一次可复现的调用验证，把整个链路走一遍。你跟着操作，应该能在半小时内跑通自己的第一个 Skill。

2. 前置准备：TaoToken 统一 Key 与 API 通道

在写 skill.md 之前，先把调用通道搭好。Claude Code 需要能访问模型，我用 TaoToken 统一管理 Key，好处是不用在多个配置文件里来回改。

TaoToken 是一个 API 通道服务，官网在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 地址是 https://taotoken.net/api 。它的作用是让你用一个 Key 就能调用多种模型，Claude Code 的配置里只需要填这一个地址和 Key。

你需要先拿到 API Key。登录后进入控制台，在 API Keys 页面创建一个新 Key。地址是 https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。创建的时候注意复制完整，Key 只显示一次。

拿到 Key 之后，Claude Code 的 settings.json 需要配置接入。这个文件的位置在用户目录下的 .claude 文件夹里。Windows 是 C:\Users\你的用户名.claude\settings.json，macOS/Linux 是 ~/.claude/settings.json。

配置骨架如下：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "你的TaoToken Key" } }

这里有个细节：ANTHROPIC_BASE_URL 填的是 https://taotoken.net/api ，不要加多余的路径。ANTHROPIC_API_KEY 填你刚才复制的 Key。保存之后重启 Claude Code，配置才会生效。

如果你用的是 Claude Code 的 Anthropic 接入模式，可以参考官方文档确认参数格式： https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。文档里有不同客户端的配置示例，对照着改不容易出错。

配置完成后，可以先在终端里跑一个简单请求验证通道是否通。用 curl 测试：

curl https://taotoken.net/api/v1/messages \ -H "Content-Type: application/json" \ -H "x-api-key: 你的TaoToken Key" \ -H "anthropic-version: 2023-06-01" \ -d '{ "model": "claude-sonnet-4-20250514", "max_tokens": 100, "messages": [{"role": "user", "content": "回复 OK"}] }'

如果返回里有正常的文本内容，说明 Key 和通道都没问题。这一步很重要，因为后面 Skill 触发失败的时候，你需要先排除是不是通道本身的问题。

3. skill.md 的 YAML 骨架与 Prompt 结构

通道通了之后，开始写 skill.md。一个 Skill 最少只需要一个文件，放在 ~/.claude/skills//skill.md。文件夹名就是 Skill 名，用小写加短横线。

skill.md 由两部分组成：头部 YAML frontmatter 和正文 Markdown body。YAML 部分只有两个必须字段：name 和 description。

--- name: monthly-report description: 根据日报数据和工作记录，按固定模板生成月度工作报告 ---

name 是 Skill 的唯一标识，必须和文件夹名一致，用小写加短横线。description 是一句话描述，Claude 根据它判断什么时候触发这个 Skill。这里的关键心得是：description 写得越具体，触发命中率越高。写"处理文档"这种模糊描述，Claude 可能在你需要的时候不触发，不需要的时候乱触发。

正文部分就是 Prompt 结构。我把它分成四块：工作空间、执行步骤、输出格式、注意事项。

工作空间告诉 Claude 去哪里找数据：

## 工作空间 - 日报目录：~/reports/daily/ - 输出目录：~/reports/monthly/ - 项目路径：~/projects/

执行步骤用编号列表，每步写清楚做什么：

## 执行步骤 1. 读取指定月份的日报 Excel，提取工作内容 2. 从各项目目录抓取当月 Git 提交记录 3. 询问用户加班时长、问题建议、项目角色是否有变化 4. 按模板生成月报草稿 5. 输出 .docx 文件到指定目录

输出格式约束结果：

## 输出格式 - 标题居中 14pt - 章节标题 11pt 加粗 - 正文 11pt，首行缩进 2 字符 - 特定段落标签加粗，正文不加粗

注意事项是兜底规则，防止 Claude 自由发挥：

## 注意事项 - 不确定的信息主动询问用户，不要自行编造 - 第六章不得与第三章内容重复 - 下月计划只写进行中的项目，已结项的不写

把这四块写清楚，一个可用的 skill.md 骨架就成型了。完整示例：

--- name: monthly-report description: 根据日报数据和工作记录，按固定模板生成月度工作报告 --- # 月报生成 Skill 当用户提供月份信息时，自动采集数据并按模板生成月报。 ## 工作空间 - 日报目录：~/reports/daily/ - 输出目录：~/reports/monthly/ ## 执行步骤 1. 读取指定月份的日报 Excel，提取工作内容 2. 从各项目目录抓取当月 Git 提交记录 3. 询问用户加班时长、问题建议、项目角色是否有变化 4. 按模板生成月报草稿 5. 输出 .docx 文件到指定目录 ## 输出格式 - 标题居中 14pt - 章节标题 11pt 加粗 - 正文 11pt，首行缩进 2 字符 ## 注意事项 - 不确定的信息主动询问用户，不要自行编造 - 下月计划只写进行中的项目，已结项的不写

写完之后保存，重启 Claude Code。在对话里输入 /skills 可以查看所有可用 Skill，如果列表里出现了 monthly-report，说明加载成功。

4. 验证请求：跑通一次可复现的调用

Skill 加载成功只是第一步，真正要验证的是它能不能按预期执行。我用的验证方法是：给一个明确的输入，看输出是否符合 skill.md 里定义的格式和步骤。

在 Claude Code 里输入：

/monthly-report 2025年6月

如果 Skill 触发成功，Claude 会按步骤执行：先读取日报目录，再抓取 Git log，然后问你三个问题。你回答之后，它会生成草稿文件。

验证的时候重点看三件事：

第一，步骤有没有被跳过。如果 Claude 直接生成了内容，没有问你加班时长和问题建议，说明执行步骤的约束不够强。解决办法是在步骤里加"必须按顺序执行"的约束。

第二，输出格式对不对。打开生成的 .docx 文件，检查标题字号、章节加粗、正文缩进是否符合 skill.md 里的定义。如果格式不对，把真实样本给 Claude 看，比口头描述"标题大一点"高效得多。

第三，触发是否稳定。同样的输入多跑几次，看结果是否一致。如果每次输出差异很大，说明 Prompt 结构里的约束不够明确。

我实测下来，第一版 Skill 几乎不可能完美。我的月报 Skill 迭代了五版才稳定：第一版只出文本没有 docx，第二版格式不对，第三版部分章节内容太泛，第四版角色信息缺失，第五版才加入交互确认点。

如果你在验证的时候想单独测试模型对话是否正常，可以用 TaoToken 的模型对话页面快速验证： https://taotoken.net/model-chat?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite 。这个页面可以直接发消息，确认通道和模型都没问题，排除是 Skill 配置的问题还是通道的问题。

对于需要长期跑编码任务或者 Agent 场景的，可以考虑 Coding Plan： https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。它适合那种需要持续调用、不想每次手动配 Key 的场景。

5. 常见报错排查清单

Skill 跑不通的时候，按这个清单逐项排查。

Skill 不触发：先检查文件夹名和 name 字段是否一致，必须都是小写加短横线。再检查 description 是否太模糊，改成更具体的场景描述。最后确认 settings.json 里的配置有没有生效，重启 Claude Code 再试。

触发后报 API 错误：检查 ANTHROPIC_BASE_URL 是否填的 https://taotoken.net/api ，不要多加路径。检查 API Key 是否复制完整，有没有多余空格。用第 2 节的 curl 命令单独测试通道。

步骤被跳过：在 skill.md 的执行步骤里加"必须按顺序执行"的约束，把步骤编号写得更明确。如果某一步特别重要，可以在注意事项里再强调一遍。

输出格式不对：把真实样本文件放到 Skill 文件夹里，在 skill.md 里引用它作为格式参照。口头描述格式的效果很差，给样本最直接。

生成内容与预期不符：检查注意事项里的边界约束是否明确。比如"不要自行编造"、"不得重复"这类规则，要写清楚具体场景。

Skill 加载了但列表里看不到：确认文件路径是否正确。用户级是 ~/.claude/skills//skill.md，项目级是 <项目根目录>/.claude/skills//skill.md。文件必须叫 skill.md，大小写敏感。

修改 skill.md 后不生效：Claude Code 不会热加载，每次修改后需要重启。如果重启后还是不生效，检查文件编码是否是 UTF-8。

排查的时候有个原则：先排除通道问题，再排查 Skill 配置。通道问题用 curl 测，Skill 问题看日志和输出。分清楚是哪一层的问题，解决起来快很多。

6. 接入文档与后续迭代

Skill 跑通之后，下一步是迭代优化。我的经验是：第一版先求能用，不要指望一步到位。格式问题拿真实样本给 Claude 看，内容规则逐章打磨，触发不灵敏就优化 description。

如果你在配置 settings.json 或者接入 Claude Code 的时候遇到问题，接入文档里有不同客户端的完整配置示例： https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。对照着改，比到处搜教程快。

API Key 的管理在控制台： https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。如果 Key 泄露了，在这里删除重建。

Claude Code 的 Anthropic 接入模式可以参考： https://taotoken.net/claudecode-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=claudecode-anthropic&utm_campaign=rewrite 。里面有专门针对 Claude Code 的配置说明。

最后说一个我踩过的坑：Skill 文件是纯文本，你一定能读懂。用别人的 Skill 之前，先读一遍全文，确认没有 rm、del、curl 这类危险指令。看不懂的就不要用，这和"不要运行你看不懂的 shell 命令"是一个道理。

我的月报 Skill 从第一版到稳定用了大概两周，中间改了五版。最耗时的不是写 skill.md，而是想清楚每个步骤的输入输出和边界条件。但一旦跑通，每个月省下的半小时是实打实的。你可以从自己最烦的重复劳动开始，先写一个最小可用的 skill.md，跑通之后再慢慢加规则。