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/consoleAPI 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或~/.bashrcexport ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你的KeyWindows PowerShell 用户用$env:ANTHROPIC_BASE_URLhttps://taotoken.net/api $env:ANTHROPIC_AUTH_TOKENsk-你的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.mdmkdir -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 接入整个工作流就能固化下来团队里谁用都是同一套流程。