1. 为什么你的 AI 总是“差点意思”从一份 SKILL.md 工作交接文档说起你有没有遇到过这种情况同一个模型别人用起来像资深专家你用起来像刚入职的实习生。问它一个团队内部的流程问题它答得头头是道但全是废话让它按你们公司的规范输出一份文档它每次都换个格式。问题不在模型在于你没给它一份“工作交接文档”。Claude Skill 就是干这个的。它是 Anthropic 在 2025 年 10 月正式发布的能力扩展机制核心思想特别朴素把团队里那些“老员工脑子里的隐性经验”整理成 AI 能读懂的文件让 AI 接手任务时像翻交接文档一样快速上手。而这份交接文档的核心载体就是一个叫SKILL.md的 Markdown 文件。我试过把一个内容团队的选题规范、标题公式、配图要求、审核清单全部塞进一个 SKILL.md结果同一个模型在没装 Skill 之前写出来的标题像机器翻译装上之后能稳定产出符合团队调性的东西。差别不在于模型变聪明了而在于它终于知道“我们这边是怎么干活的”。这篇文章聚焦的是落地写法不是概念科普。我会给你一份可以直接复制的 SKILL.md 目录结构和字段模板演示一次从空白文件夹到 AI 真正按文档执行任务的完整验证流程并且把 MCP 工具调用怎么嵌进 Skill、Anthropic 官方规范里哪些字段是必须的全部讲清楚。适合谁看手里有团队经验想沉淀成 AI 能力的运营、产品、技术负责人以及想让 Claude Code 或 Cline 这类工具真正懂你项目规范的开发者。核心检索词先摆出来Claude Skill 是什么、SKILL.md 怎么写、Skill 和 MCP 怎么配合、Anthropic Skill 规范。你带着这几个问题往下看每一步都有可复制的东西。2. 前置准备TaoToken 接入与 Skill 运行环境搭建在写 SKILL.md 之前得先让 AI 能跑起来。Claude Skill 的执行依赖模型能力而模型调用需要一个稳定的接入层。这里我用 TaoToken 作为统一接入入口它兼容 Anthropic 官方 API 格式配置一次就能在 Claude Code、Cline、Codex 这些工具里复用。先说清楚 Skill 和 MCP 的关系因为很多人在这里绕晕。MCP 是 Model Context Protocol你可以把它理解成 USB 接口标准规定了 AI 怎么统一连接外部工具和数据源。Skill 是插进这个 USB 口的 U 盘里面装的是操作手册、脚本和参考资料。MCP 解决“怎么连上工具”Skill 解决“连上之后怎么把活干好”。一个 Skill 里完全可以写清楚“遇到需要查数据库的时候调用哪个 MCP 服务”。所以前置准备分两块一块是模型接入一块是 Skill 文件系统的挂载位置。模型接入这块你需要拿到三样东西Base URL、API Key、Model ID。TaoToken 的 API 地址是https://taotoken.net/api注意这个地址不加任何查询参数。API Key 在控制台创建地址是https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentskill_md_guide。Model ID 根据你用的模型填比如claude-sonnet-4-20250514这类。如果你用的是 Claude Code配置方式是在项目根目录或者用户目录下创建.claude/settings.json把接入信息写进去。如果你用的是 Cline配置在 VS Code 的设置里搜索 Cline 的 API Provider 配置项。如果你用的是 Codex配置在~/.codex/auth.json。这三个工具的配置逻辑一样Base URL 填 TaoToken 的 API 地址Key 填你创建的 KeyModel ID 填你要用的模型。Skill 文件系统的挂载位置Anthropic 官方规范里Skill 放在.claude/skills/目录下每个 Skill 一个子文件夹。Claude Code 会自动扫描这个目录读取每个 Skill 的元数据。Cline 和 Codex 也支持类似的机制具体路径看工具文档但结构是一致的。这里有个坑要注意Skill 的元数据是始终加载的大概 100 个 token 左右相当于一张名片。AI 启动时会把所有 Skill 的名片看一遍知道有哪些能力可用。当你发出的请求和某个 Skill 的名片匹配上AI 才会去读那个 Skill 的 SKILL.md 正文。执行过程中需要跑脚本、查参考文档时才会去打开对应文件。这套机制叫渐进式披露好处是装再多 Skill 也不会把上下文撑爆。所以你的 SKILL.md 写法要配合这个机制元数据部分要精准让 AI 能快速判断“这个任务该不该用我”正文部分要详细把步骤、注意事项、边界情况都写清楚脚本和参考文档放在子目录里正文里用相对路径引用。3. 可复制配置SKILL.md 目录结构与字段模板这一节是核心直接给你能复制的东西。先看目录结构再看 SKILL.md 的字段模板最后看一个嵌入了 MCP 调用的完整示例。目录结构长这样.claude/skills/ └── content-handover/ ├── SKILL.md ├── scripts/ │ ├── check_title_length.py │ └── format_output.py ├── references/ │ ├── brand_voice.md │ └── past_cases.md └── assets/ └── template.mdSKILL.md是核心指令文档相当于工作 SOP。scripts/放预写好的代码脚本AI 不用临时造轮子。references/放参考文档遇到不确定的细节随时翻阅。assets/放模板和素材保证输出质量。SKILL.md 的字段模板Anthropic 官方规范里必须包含的是 YAML frontmatter 里的name和description正文部分自由发挥。下面是我实测下来最稳的写法--- name: content-handover description: 当用户需要撰写符合团队规范的内容、检查标题长度、或按照品牌调性输出文案时使用此 Skill。适用于公众号、技术博客、产品文档的写作与审核场景。 --- # 内容团队工作交接文档 ## 角色定义 你现在是内容团队的资深编辑熟悉我们的选题标准、标题公式、配图规范和审核流程。你的任务不是自由创作而是按照下面的 SOP 执行。 ## 工作流程 ### 第一步确认任务类型 用户请求分为三类 - 写新内容走「创作流程」 - 检查已有内容走「审核流程」 - 改写或润色走「改写流程」 ### 第二步创作流程 1. 读取 references/brand_voice.md确认当前品牌调性 2. 读取 references/past_cases.md找 2-3 个相似选题的历史案例 3. 按照 assets/template.md 的结构起草 4. 运行 scripts/check_title_length.py 检查标题长度 5. 运行 scripts/format_output.py 格式化输出 ### 第三步审核流程 1. 检查标题是否在 20-30 字之间 2. 检查开头 100 字是否包含核心检索词 3. 检查是否有空洞概述如「随着...的发展」 4. 检查段落长度是否在 4-6 行 5. 输出审核报告标注问题位置和修改建议 ### 第四步改写流程 1. 保留原文核心信息 2. 按照 references/brand_voice.md 调整语气 3. 替换空洞表达为具体案例或数据 4. 重新运行审核流程 ## MCP 工具调用 当需要查询历史内容数据时调用 MCP 服务 content-db - 查询接口content-db.query(keyword, limit) - 返回字段title, url, publish_date, performance_score - 使用场景在创作流程第二步如果 past_cases.md 里没有匹配案例调用此 MCP 服务补充 当需要检查敏感词时调用 MCP 服务 sensitive-check - 查询接口sensitive-check.scan(text) - 返回字段has_sensitive, matched_words, suggestion ## 注意事项 - 不要编造历史案例past_cases.md 里没有的就走 MCP 查询 - 标题长度检查必须运行脚本不要目测 - 输出格式必须用 format_output.py 处理不要手动调整 - 遇到脚本报错先检查 Python 环境再检查输入参数这个模板里description字段特别关键。它是 AI 判断“这个任务该不该用这个 Skill”的唯一依据。写法上要包含触发场景和适用范围不要写“这是一个内容 Skill”这种废话。要写“当用户需要撰写符合团队规范的内容、检查标题长度、或按照品牌调性输出文案时使用”。MCP 工具调用部分我写的是伪代码形式的接口描述。实际使用时你需要根据你接入的 MCP 服务把真实的工具名和参数写进去。Anthropic 官方规范里Skill 可以通过allowed-tools字段声明可以调用哪些工具但更常见的做法是在正文里用自然语言描述调用逻辑让模型自己决定什么时候调。脚本部分check_title_length.py的内容很简单import sys import re def check_title_length(title): # 去掉标点和空格后计算中文字符数 cleaned re.sub(r[^\u4e00-\u9fa5a-zA-Z0-9], , title) length len(cleaned) if 20 length 30: return fPASS: 标题长度 {length} 字符合规范 else: return fFAIL: 标题长度 {length} 字应在 20-30 字之间 if __name__ __main__: title sys.argv[1] if len(sys.argv) 1 else print(check_title_length(title))format_output.py负责把输出整理成固定格式这里不展开你按自己团队的需求写就行。配置写完后目录结构应该是完整的。接下来验证它是否真的生效。4. 验证请求从空白到 AI 按文档执行任务配置写完了不代表生效。这一节演示怎么验证 AI 是否真的读了你的 SKILL.md并且按里面的流程执行。验证分三步检查元数据是否被加载、检查正文是否被读取、检查脚本是否被调用。第一步检查元数据。在 Claude Code 里输入/skills命令或者直接问 AI“你现在有哪些 Skill 可用”如果配置正确AI 会列出content-handover这个 Skill并且复述它的 description。如果没列出来说明目录结构不对或者 frontmatter 格式有问题。第二步检查正文是否被读取。给 AI 一个明确匹配 description 的任务比如“帮我写一篇关于 Claude Skill 的技术博客标题要符合团队规范。”观察 AI 的响应。如果它真的读了 SKILL.md它应该会提到“我先读取品牌调性文档”或者“我需要运行标题长度检查脚本”。如果它直接开始写说明正文没被加载。第三步检查脚本是否被调用。这是最关键的验证。AI 在写完标题后应该会运行check_title_length.py。你可以在 Claude Code 的终端输出里看到脚本执行记录。如果脚本报错AI 应该根据 SKILL.md 里的注意事项先检查 Python 环境再检查参数。我实测下来最容易出问题的环节是脚本路径。SKILL.md 里写的是相对路径scripts/check_title_length.py但 AI 执行时的当前工作目录可能不是 Skill 根目录。解决办法是在 SKILL.md 里写清楚“所有脚本路径相对于本 Skill 根目录执行前先 cd 到 Skill 根目录。”另一个验证方法是故意给一个边界情况。比如给一个 35 字的标题看 AI 是否按流程运行脚本并报告 FAIL。如果 AI 说“这个标题有点长建议缩短”但没有运行脚本说明它没严格按 SOP 执行。这时候你需要回到 SKILL.md把“必须运行脚本不要目测”这条规则写得更强硬甚至可以加一句“如果跳过脚本检查视为任务失败”。验证通过的标准是AI 在接到匹配任务时会主动读取 references 里的文档、运行 scripts 里的脚本、按照 assets 里的模板输出。整个过程你能在日志里看到文件读取和脚本执行的记录。如果这些都发生了说明你的 SKILL.md 真正生效了。这里补一句 MCP 的验证。如果你的 SKILL.md 里写了调用 MCP 服务验证方法是给一个需要查历史数据的任务看 AI 是否调用了对应的 MCP 工具。比如问“帮我找一下我们之前写过的关于 MCP 的文章。”如果 AI 调用了content-db.query并返回了结果说明 MCP 集成成功。如果 AI 说“我没有访问历史数据的能力”说明 MCP 服务没配置好或者 SKILL.md 里的调用描述不够明确。5. 常见报错排查401、local proxy failed、reading choices、OAuth这一节对照真实报错给你排查路径。这些错误我在配置过程中基本都踩过一遍。401 Unauthorized这是最常见的接入错误。报错信息通常是{error: {type: authentication_error, message: invalid x-api-key}}。原因有三个Key 填错了、Key 过期了、Base URL 填错了。排查顺序先检查 Base URL 是不是https://taotoken.net/api注意不要多加/v1或者斜杠再检查 Key 是否完整复制有没有多余空格最后去控制台确认 Key 状态。如果用的是 Claude Code检查.claude/settings.json里的ANTHROPIC_API_KEY和ANTHROPIC_BASE_URL两个字段。local proxy failed这个报错通常出现在 Cline 或 Codex 里信息是Error: local proxy failed to start或者connect ECONNREFUSED 127.0.0.1:xxxx。原因是工具试图启动一个本地代理来转发请求但代理启动失败。排查检查端口是否被占用换个端口检查防火墙是否拦截了本地回环地址如果是公司网络环境检查是否有网络策略限制。解决办法是在工具设置里关闭“使用本地代理”选项直接走 Base URL 请求。reading choices 报错这个报错信息通常是Cannot read properties of undefined (reading choices)。原因是 API 返回格式和工具预期的格式不匹配。TaoToken 兼容 Anthropic 官方格式但有些工具默认走 OpenAI 格式。排查检查工具的 API Provider 设置确认选的是 Anthropic 而不是 OpenAI检查 Model ID 是否填对有些模型名在 Anthropic 和 OpenAI 下不一样检查请求体里是否有多余参数。如果工具支持自定义请求头确认anthropic-version头是否正确。OAuth 相关报错如果你用的是 Claude Code 的 OAuth 登录方式可能会遇到OAuth token expired或者invalid_grant。原因是 OAuth token 有有效期过期后需要重新授权。排查运行claude login重新走授权流程检查系统时间是否准确时间偏差会导致 token 验证失败如果用的是 API Key 方式而不是 OAuth检查配置里是否误开了 OAuth 选项。Skill 不生效的排查如果接入没问题但 Skill 不生效排查顺序检查.claude/skills/目录是否存在检查 SKILL.md 的 frontmatter 格式name和description必须用---包裹检查 description 是否包含触发关键词检查文件编码是否是 UTF-8检查 AI 的响应里是否提到了读取 Skill 文件。如果 AI 说“我没有找到相关 Skill”说明元数据没被加载如果 AI 说“我找到了 Skill 但没有读取正文”说明 description 匹配度不够需要调整措辞。脚本执行报错如果 AI 调用了脚本但报错常见原因是 Python 环境问题。排查确认python3命令可用确认脚本有执行权限确认脚本里的依赖库已安装确认传入参数格式正确。如果脚本输出乱码检查系统编码设置。如果脚本超时检查是否有死循环或者网络请求。这里给一个排查清单你可以对照着过一遍报错关键词可能原因排查动作401Key 或 Base URL 错误检查配置字段重新创建 Keylocal proxy failed本地代理端口冲突关闭代理选项换端口reading choicesAPI 格式不匹配切换 Provider 为 AnthropicOAuthToken 过期重新登录授权Skill 不生效元数据未加载检查目录和 frontmatter脚本报错环境或参数问题检查 Python 和输入排查完这些基本能覆盖 90% 的配置问题。剩下的 10% 通常是工具版本太旧更新到最新版再试。6. 语义一致 CTA把交接文档变成团队资产写到这里SKILL.md 的写法、验证流程、排错路径都讲完了。最后说一个我自己的经验Skill 的价值不在于写得多复杂而在于写得够具体。我见过很多人写 SKILL.md写成了“你要认真负责地完成任务”这种空话。AI 读了等于没读。真正有效的写法是把“认真负责”翻译成“标题长度必须在 20-30 字之间运行 check_title_length.py 验证”把“注意品牌调性”翻译成“读取 references/brand_voice.md按照里面的语气示例调整”。你团队里那些“老员工知道但没写下来”的东西才是 SKILL.md 最该装的内容。比如“遇到用户投诉先安抚情绪再解决问题”、“写技术文档要先给结论再给论证”、“标题里不要用‘震惊’这种词”。这些隐性经验一旦写成文档AI 就能稳定执行新人也能照着学。如果你还没开始写建议从最小的 Skill 开始。一个 SKILL.md一个脚本一个参考文档先跑通验证流程。跑通之后再往里加 MCP 调用、加更多脚本、加更复杂的流程。接入配置方面API Key 在控制台创建地址是https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentskill_md_guide。接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentskill_md_guide里面有各工具的详细配置步骤。如果你想先验证模型对话效果可以用模型对话页面https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentskill_md_guide直接测试。长期做编码和 Agent 任务的话Coding Plan 页面在https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentskill_md_guide。最后留一个实用技巧SKILL.md 写完后让 AI 自己读一遍然后问它“你觉得这个文档里哪些地方写得不够清楚执行时可能会卡住”AI 会给你一份改进建议。这个反向验证方法比你自己反复读十遍都管用。