企业官网建设流程全解析

1. SKILL.md 到底是什么，为什么 Claude Code 需要它

如果你最近在折腾 Claude Code，大概率会遇到一个词：SKILL.md。简单说，它就是给 AI 助手写的一份「岗位说明书」——用 YAML 头声明这个技能叫什么、什么时候该被调用，再用 Markdown 正文写清楚它具体要干什么、怎么干、干到什么程度算合格。它解决的问题很直接：Claude Code 默认不知道你团队内部的业务流程，比如「客户反馈怎么综合成主题报告」「PRD 怎么按标准审计」，这些知识以前只能靠每次对话里反复粘贴提示词，现在可以固化成一个可复用的技能文件。

适合谁用？三类人最需要：一是经常给 AI 写长提示词、想把它沉淀成资产的产品/运营同学；二是要给团队统一 AI 工作流的研发；三是已经在用 MCP 接外部工具、想让 Claude Code 在合适时机自动触发特定流程的开发者。SKILL.md 和 MCP 是互补关系——MCP 负责「能连到什么外部系统」，SKILL.md 负责「连上之后按什么流程做事」。

我实测下来，一个写得好的 SKILL.md 能明显减少重复沟通。比如你写一个feedback-synthesis技能，之后只要说「对 data/q4-feedback.csv 运行反馈综合」，Claude Code 就会自动匹配到这个技能并按你定义的步骤执行，而不是每次都要你重新解释一遍分析逻辑。这篇就按「YAML 结构设计 → 正文写法 → 在 Claude Code 里验证被识别和调用」的顺序，把可直接复制的模板和字段说明都给你。

2. 前置准备：TaoToken 接入与 Claude Code 环境配置

在写 SKILL.md 之前，得先让 Claude Code 能正常跑起来。Claude Code 需要一个兼容 Anthropic 接口的 API 端点，这里用 TaoToken 来做接入，它的 API 地址是https://taotoken.net/api，控制台在https://taotoken.net/console，API Keys 管理页在https://taotoken.net/api-keys。整个流程分三步：拿 Key、配环境变量、验证连通。

第一步，去控制台创建 API Key。登录后进入 API Keys 页面，新建一个 Key，复制出来（只显示一次，务必存好）。这个 Key 就是后面所有配置里的ANTHROPIC_AUTH_TOKEN。

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

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

Windows PowerShell 用户用：

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

第三步，如果你用的是 Claude Code 的配置文件方式（比如~/.claude/settings.json），可以写成 JSON：

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

这里ANTHROPIC_MODEL填你要用的模型 ID，具体可用模型在模型对话页能看到。配好之后，SKILL.md 才有地方被加载和调用。如果你还没配好，先去 API Keys 页面拿 Key，再对照接入文档走一遍，别急着写技能文件——环境不通，后面验证步骤全都会失败。

3. SKILL.md 的 YAML 头与正文结构：可复制模板

SKILL.md 分两大部分：顶部的 YAML front matter（用---包起来）和下面的 Markdown 正文。YAML 头只有两个必填字段，但这两个字段决定了技能能不能被正确匹配。

--- name: feedback-synthesis description: 将客户反馈综合成带有可操作洞察的主题报告。当用户提及反馈分析、NPS 综合、支持工单主题、客户情绪或客户之声时自动调用。 ---

name必须是小写字母加连字符，唯一，之后用/feedback-synthesis就能手动调用。description是最关键的一行——它不只是给人看的，更是给 Claude Code 做语义匹配用的。写法要点：用用户平时会说的话，把触发场景的关键词都塞进去。比如用户会说「帮我分析一下这批反馈」「做个 NPS 综合」「看看工单都在抱怨什么」，那 description 里就要覆盖「反馈分析」「NPS 综合」「工单主题」「客户情绪」这些词。写得太抽象（比如「处理数据」）会导致匹配不上。

正文部分建议按固定结构写，下面是一个可直接复制的完整模板：

# 反馈综合 ## 目的 将原始客户反馈转化为可操作的洞察报告，供产品团队用于优先级决策。 ## 预期输入 - **必填：** 包含反馈文本且列名为 feedback 的 CSV，或每行一条的纯文本文件 - **可选：** 用于筛选的日期范围（默认最近 30 天） - 支持格式：CSV、JSON、纯文本 - 最低要求：至少 10 条反馈条目 ## 流程 1. **读取并验证输入文件** - 确认文件存在且格式符合预期 - 识别反馈列 - 报告记录数量 2. **识别主题** - 阅读所有反馈条目 - 按常见话题分组，目标 4-8 个主题 - 如需严格分类，使用 resources/categories.md 中的类别定义 3. **分析每个主题** - 统计出现频率与百分比 - 评估情感倾向（正面、负面、混合） - 提取 2-3 条逐字原文引述 4. **生成报告** - 遵循 resources/output-template.md 中的模板 - 包含执行摘要、主题分析和建议 - 保存至 reports/feedback-synthesis-YYYY-MM-DD.md 5. **质量检查** - 验证所有主题都有支持性引述 - 确认百分比总和约为 100% - 检查建议是否具有可操作性 ## 输出格式 生成文件：reports/feedback-synthesis-YYYY-MM-DD.md 结构：执行摘要（3-5 条要点）、主题分析（频率/情感/引述/影响）、建议（按优先级排序）、方法论 ## 质量标准 - 每个主题至少包含 2 条支持性引述 - 引述为源数据逐字原文，非转述 - 情感评估需解释推理过程 - 建议需与特定主题相关联 - 文件成功保存至指定路径 ## 边缘情况 - **数据稀疏（少于 10 条）：** 生成报告时附带样本量有限的说明 - **格式混杂：** 若反馈列不明确，请用户指定 - **条目过长（超过 500 字）：** 先摘要再分类 - **非英文内容：** 注明语言后继续处理，不尝试翻译 ## 使用示例 - "对 data/customer-feedback-q4.csv 运行反馈综合" - "仅针对 11 月的 feedback.csv 运行反馈综合" - "运行反馈综合，只需给我前三大主题"

几个写法上的坑要注意：流程部分用命令式语气（「读取文件」），不要用被动句（「文件应被读取」）；输入要求越具体越好，「CSV 文件」太模糊，要写「列名为 feedback 的 CSV」；质量标准是让 Claude Code 自我检查用的，写清楚它才会在完成前真的去核对。

4. 在 Claude Code 中验证技能被识别与调用

写完 SKILL.md 只是第一步，得确认 Claude Code 真的能加载并触发它。技能文件一般放在项目的.claude/skills/目录下，每个技能一个子目录，里面放SKILL.md：

mkdir -p .claude/skills/feedback-synthesis # 把上面写的 SKILL.md 放到这个目录

放好之后，启动 Claude Code，先做一次「识别验证」——直接问它有哪些可用技能：

/skills

如果配置正确，你应该能在列表里看到feedback-synthesis，并且 description 显示的是你写的那段触发描述。如果列表里没有，说明文件路径不对或 YAML 头格式有问题（比如---没闭合、缩进用了 Tab）。

接着做「调用验证」。手动调用用斜杠命令：

/feedback-synthesis 对 data/q4-feedback.csv 运行反馈综合

自动触发则用自然语言，模拟真实用户会说的话：

帮我分析一下 data/q4-feedback.csv 里的客户反馈，做个主题报告

如果 description 写得够好，Claude Code 会自动匹配到feedback-synthesis并开始执行流程。实测下来，触发成功时你会看到它先读取文件、报告记录数量，然后按你定义的步骤走。如果它没触发而是自己瞎分析，八成是 description 里的关键词没覆盖到用户的实际说法，回去补词。

验证通过后，可以进一步测边缘情况，比如喂一个只有 5 条数据的文件，看它是否按你写的「数据稀疏」分支处理。这一步能暴露流程描述里的歧义。

5. 常见报错与排查：401、local proxy failed、reading choices

配置和调用过程中最容易撞上几个典型报错，这里逐个对照排查。

401 Unauthorized / authentication_error：这是 Key 的问题。先确认ANTHROPIC_AUTH_TOKEN是不是完整复制了（别漏字符、别带空格），再去 API Keys 页面看这个 Key 是否被禁用或删除。如果用的是 settings.json，注意 JSON 里不能有注释，尾逗号也会导致解析失败。改完环境变量记得重开终端或source ~/.zshrc。

local proxy failed / connection refused：通常是ANTHROPIC_BASE_URL写错了。正确值是https://taotoken.net/api，注意结尾不要多加/v1或斜杠。如果你本地有别的工具占用了同名环境变量，也会冲突，用echo $ANTHROPIC_BASE_URL确认实际生效的值。

reading 'choices' 相关报错：这个报错一般出现在接口返回格式和客户端预期不一致时。检查你填的ANTHROPIC_MODEL是否是当前可用的模型 ID，模型名写错会导致返回体结构异常。去模型对话页确认可用模型列表，把 ID 原样复制。

OAuth / login 相关报错：如果你之前用官方账号登录过 Claude Code，本地可能残留了 OAuth 凭证，和现在的 Token 方式冲突。清掉旧的凭证缓存（一般在~/.claude/下），只保留环境变量方式。

技能不触发：不是报错但更常见。排查顺序是——文件是否在.claude/skills/<name>/SKILL.md、YAML 的name是否和目录名一致、description是否包含用户会说的关键词。这三条占不触发原因的九成。

排查时建议开一个干净终端，逐条echo环境变量确认，别在多个配置文件之间来回改，容易互相覆盖。

6. 把技能沉淀成团队资产：下一步怎么走

SKILL.md 真正的价值在于复用和组合。当你写完第一个技能后，可以按几种常见模式扩展：转换模式（乱数据→规整报告）、调查模式（回答具体问题并给证据）、生成模式（按参数生成文档）、同步模式（从外部系统拉数据更新本地）、审计模式（对照标准检查现有产物）。选哪种取决于你的任务——有数据要整理用转换，要回答问题用调查，要按规格创建用生成。

组合技能时，可以在正文的「相关 Skill」里互相引用，比如prd-audit用feedback-synthesis的洞察来审核 PRD。这样 Claude Code 在处理复杂任务时能串起多个技能。

如果你打算长期用 Claude Code 跑编码和 Agent 任务，可以考虑 Coding Plan，它更适合高频、长周期的使用场景。技能文件写好后，配合稳定的 API 接入，整个工作流就能固化下来，团队里谁用都是同一套流程。