1. 为什么你的 Agent 总是“记不住流程”从一次真实翻车说起先说一个我踩过的坑。去年帮一个做跨境电商的朋友搭客服 Agent需求很朴素客户问退货先查订单状态再对照退货政策判断是否符合条件符合就引导填表不符合就解释原因并给替代方案。我当时的做法很“程序员”——把所有规则、政策、话术、判断逻辑全写进一个 3000 字的 system prompt 里。前三天跑得挺好第四天开始出问题模型偶尔跳过查订单直接回答政策偶尔把“7 天无理由”和“15 天质量问题”搞混偶尔在客户情绪激动时还在机械念条款。我加了更多约束prompt 涨到 5000 字结果 Token 成本上去了稳定性反而更差。这个问题的本质不是模型笨而是我把“能力”和“知识”和“执行”全揉在一坨文本里了。Agent Skill 要解决的就是这件事把一份可复用的工作手册拆成**元信息什么时候用、指令怎么做、参考查什么、脚本跑什么**四层让 Agent 按需加载而不是每次把整个知识库塞进上下文。这篇文章面向三类人一是正在用 Claude Code、Cline、Cursor 这类工具做自动化但 Skill 还停留在“高级提示词文件夹”阶段的开发者二是想把团队 SOP 沉淀成 Agent 可调用能力的工程负责人三是被 MCP 和 Skill 的关系绕晕、不知道该把逻辑放哪一层的人。读完你能拿到一套可直接复制的目录模板、一份能跑的 SKILL.md 配置、一次本地加载验证的完整命令以及一张 Skill 与 MCP 的职责边界对照表。核心检索词先明确Agent Skill 是什么、SKILL.md 怎么写、Reference 和 Script 怎么组织、Agent Skill 与 MCP 的区别。这几个问题串起来就是一篇能跟做的工程落地指南。2. TaoToken 前置准备把模型调用通道先打通Skill 本身是文件系统里的目录结构但你要验证它、调试它、让 Agent 真正跑起来得先有一个稳定的模型调用入口。我用的是 TaoToken 的 API 通道原因是它兼容 Anthropic 的接口格式Claude Code 和 Cline 这类工具改个 Base URL 就能接上不用折腾额外适配层。2.1 你需要准备的三样东西在开始写 Skill 之前先把这三件套拿到手后面所有配置都围绕它们展开Base URLhttps://taotoken.net/api注意 API 调用不加 UTM 参数保持干净API Key去控制台创建地址是https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentconsole创建后立刻复制保存页面刷新就不再完整显示。Model IDClaude 系列常用的是claude-sonnet-4-5-20250929这类带日期的完整 ID具体以文档页为准文档入口在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc。注意API Key 只在创建时完整展示一次建议直接写进本地环境变量文件别贴在聊天窗口或代码注释里。2.2 环境变量配置macOS / Linux打开终端编辑 shell 配置文件。如果你用 zshmacOS 默认# 编辑 ~/.zshrc echo export ANTHROPIC_BASE_URLhttps://taotoken.net/api ~/.zshrc echo export ANTHROPIC_API_KEYsk-你的实际Key ~/.zshrc source ~/.zshrc # 验证是否写入成功 echo $ANTHROPIC_BASE_URL echo $ANTHROPIC_API_KEY | head -c 8Windows 用户用 PowerShell[Environment]::SetEnvironmentVariable(ANTHROPIC_BASE_URL, https://taotoken.net/api, User) [Environment]::SetEnvironmentVariable(ANTHROPIC_API_KEY, sk-你的实际Key, User) # 重开终端后验证 $env:ANTHROPIC_BASE_URL2.3 为什么 Skill 验证阶段特别需要稳定通道Skill 调试有个特点你会反复触发同一个 Skill观察它是否在正确的时机被加载、是否正确读取了 Reference、是否正确调用了 Script。这个过程可能几十次请求起步。如果通道不稳定你根本分不清是 Skill 配置写错了还是网络抖动了。所以先把通道固定下来再动 Skill 目录能省掉大量“以为是配置问题其实是连接问题”的排查时间。如果你后面要做长期编码类 Agent比如让 Claude Code 持续跑一个项目可以考虑 Coding Plan 方案入口在https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-plan按量或包月看你任务密度选。3. 可复制配置SKILL.md 目录模板与完整配置片段这一节是全文最核心的部分给你一套能直接cp -r的目录结构以及每个文件的完整内容。3.1 标准 Skill 目录结构我以“会议总结助手”为例这个场景足够简单又能覆盖 Reference 和 Script 两种资源类型。目录放在 Claude Code 默认读取的 skills 路径下mkdir -p ~/.claude/skills/meeting-summarizer/{references,scripts,assets} cd ~/.claude/skills/meeting-summarizer touch SKILL.md touch references/finance-policy.md touch scripts/upload_summary.py touch assets/example-input.txt最终结构长这样~/.claude/skills/meeting-summarizer/ ├── SKILL.md ├── references/ │ └── finance-policy.md ├── scripts/ │ └── upload_summary.py └── assets/ └── example-input.txt四个部分的职责边界要记清楚SKILL.md是入口和规则references/放需要模型阅读理解的长文档scripts/放需要真正执行的程序assets/放示例输入输出帮模型对齐预期。3.2 SKILL.md 完整配置片段这是最关键的文件。注意 frontmatter 里的name和description是模型第一眼看到的内容直接决定它能不能在正确时机匹配到这个 Skill。--- name: meeting-summarizer description: 将会议录音转写文本总结为结构化纪要包含参会人员、议题、决定三部分。当用户提供会议记录、讨论文本、录音转写并要求总结时触发。涉及预算、采购、报销内容时需读取 references/finance-policy.md 做合规提醒。用户提到上传同步归档时执行 scripts/upload_summary.py。 --- # 会议总结助手 ## 目标 把非结构化的会议讨论文本转成固定三段式纪要参会人员、议题、决定。 ## 触发条件 - 用户粘贴或指向一段会议讨论文本 - 用户明确说总结会议整理纪要提取待办 - 文本中出现多人对话格式如张三李四 ## 执行步骤 1. 通读全文识别所有发言人姓名去重后列入参会人员 2. 用一句话概括本次会议的核心议题写入议题 3. 提取所有达成共识的结论合并为一段写入决定 4. 检查文本中是否出现金额、预算、采购、报销关键词 - 若出现读取 references/finance-policy.md - 对照规则判断是否超标在纪要末尾追加合规提示段落 5. 若用户提到上传同步归档调用 scripts/upload_summary.py把纪要正文作为参数传入 ## 输出格式 - 参会人员用顿号分隔的姓名列表 - 议题一句话不超过 50 字 - 决定一段话不超过 200 字 - 合规提示仅当涉及财务时出现列出超标项和建议审批层级 ## 禁止事项 - 不得臆造文本中未出现的参会人员 - 不得把讨论过程中的分歧写成决定 - 不得在未读取 finance-policy.md 的情况下对金额合规性下结论 ## 示例 输入见 assets/example-input.txt 输出 - 参会人员张三、李四、王五、赵六、孙七 - 议题确定下月社区志愿活动的地点、时间、人数、预算及分工。 - 决定活动定在公园周六上午九点按 50 人规模和 1000 元预算执行赵六负责场地申请孙七负责宣传其余成员配合物资采购与分组。3.3 Reference 文件配置references/finance-policy.md放的是长文档模型只在触发条件满足时才读。内容我截取关键部分# 集团财务手册节选 ## 第一章 办公设备采购 1. 笔记本电脑、显示器最低使用年限 3 年 2. 标准办公电脑单价不得超过 10000 元 3. 高性能工作站 10000-20000 元需部门总监审批 4. 单笔采购总额超过 50000 元必须三方公开招标 ## 第二章 国内差旅标准 1. 一线城市住宿补贴 800 元/晚新一线及二线 500 元/晚其他 350 元/晚 2. 飞行 4 小时以内仅限经济舱高铁限二等座 ## 第三章 商务招待 1. 普通客户人均不超过 150 元重要客户不超过 300 元需提前报备 2. 原则上不报销酒精类饮品 ## 第四章 日常零星报销 1. 单笔 500 元以下可由员工自主报销 2. 500-5000 元由部门主管在系统内审批 *注所有金额单位为人民币。违反限额且未获特批的申请财务部予以退回。*3.4 Script 文件配置scripts/upload_summary.py是一个可执行脚本模型不读它的源码只调用它#!/usr/bin/env python3 import sys import time import hashlib def upload_summary(content: str) - None: doc_id hashlib.md5(content.encode()).hexdigest()[:8] print(f[upload] 正在上传纪要字符数{len(content)}) time.sleep(0.5) print(f[upload] 文档 ID{doc_id}) print(f[upload] 归档路径/meetings/2025/summary_{doc_id}.md) print([upload] 上传成功) if __name__ __main__: if len(sys.argv) 1: upload_summary(sys.argv[1]) else: print([upload] 错误未接收到纪要内容, filesys.stderr) sys.exit(1)给脚本加执行权限chmod x ~/.claude/skills/meeting-summarizer/scripts/upload_summary.py3.5 如果你用 Cline 或 Codex配置写法Cline 的 MCP 配置放在cline_mcp_settings.json如果你要把 Skill 里的脚本包装成 MCP 工具格式如下{ mcpServers: { meeting-uploader: { command: python3, args: [/Users/你的用户名/.claude/skills/meeting-summarizer/scripts/upload_summary.py], env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的实际Key } } } }Codex 用户如果走auth.json方式文件在~/.codex/auth.json{ base_url: https://taotoken.net/api, api_key: sk-你的实际Key, model: claude-sonnet-4-5-20250929 }三件套Base URL Key Model ID在任何工具里都是必须对齐的缺一个就会报认证或模型不存在。4. 验证请求本地加载与调用实测配置写完不算完得验证 Skill 真的被加载、真的按预期触发。这一节给你完整的验证流程和预期输出。4.1 验证 Skill 目录被识别先确认 Claude Code 能扫到你的 Skill。启动 Claude Code 后输入斜杠命令查看可用 Skill 列表claude # 进入交互界面后输入 /skills预期输出里应该出现meeting-summarizer描述是你写在 frontmatter 里的那段。如果没出现检查三件事目录是否在~/.claude/skills/下、SKILL.md文件名是否大小写正确、frontmatter 的---是否闭合。4.2 验证基础触发准备一段测试文本直接粘贴给 Claude Code张三那我们开始吧今天主要是把下个月社区志愿活动的安排一次性定下来。 李四我建议活动放在公园人多也方便组织。 王五可以不过要提前申请场地不然可能有风险。 赵六场地申请我可以负责这周内给大家结果。 孙七人数最好先有个范围方便准备物资。 张三那就先按 50 人左右来估算吧。 李四上次的手套还能用但垃圾袋需要再买。 王五预算要不要设个上限避免超支。 张三预算控制在 1000 以内优先用现有物资。 孙七时间我建议周六上午天气也不会太热。 李四九点集合应该比较合适。 赵六我周三前把申请结果同步到群里。 张三好那报名截止时间定在周四晚上。 王五周五可以统一分组和采购。 孙七我来负责写报名文案和活动当天的合影安排。 张三安全方面提醒大家带水活动结束简单总结一下就行。 张三那今天就到这大家按分工推进。预期输出- 参会人员张三、李四、王五、赵六、孙七 - 议题确定下月社区志愿活动的地点、时间、人数、预算及分工。 - 决定活动定在公园周六上午九点按 50 人规模和 1000 元预算执行赵六负责场地申请孙七负责宣传其余成员配合物资采购与分组。注意这里没有出现“合规提示”因为 1000 元预算属于零星报销范围且文本没触发采购超标判断。这说明 Reference 没有被加载符合渐进式披露的设计。4.3 验证 Reference 按需加载再发一段带财务敏感信息的文本李四这次团建我想申请买两台高性能工作站预算大概 18000 一台。 王五这个金额是不是要审批 张三先记下来回头走流程。预期输出会在纪要末尾多出一段合规提示高性能工作站单价 18000 元落在 10000-20000 元区间需部门总监审批。两台合计 36000 元未超过 50000 元招标线无需公开招标。如果这段没出现说明模型没去读references/finance-policy.md。排查方向SKILL.md 里的触发条件是否写清楚了“涉及金额、预算、采购、报销时读取”以及 Reference 文件路径是否写对。4.4 验证 Script 执行发一段带“上传”关键词的请求把上面的会议纪要上传归档。预期终端输出[upload] 正在上传纪要字符数156 [upload] 文档 IDa3f8c21e [upload] 归档路径/meetings/2025/summary_a3f8c21e.md [upload] 上传成功4.5 用 API 直接验证模型通道如果你想绕过 Claude Code直接用 curl 验证通道和模型是否正常curl https://taotoken.net/api/v1/messages \ -H x-api-key: $ANTHROPIC_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-5-20250929, max_tokens: 128, messages: [ {role: user, content: 用一句话说明 Agent Skill 和 MCP 的区别} ] }返回 200 且 body 里有content数组说明通道、Key、Model ID 三件套全部对齐。想快速对比不同模型的表现可以到模型对话页https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentchat直接试。5. 本篇常见错排查401、local proxy failed、OAuth 与路径问题这一节按真实报错来每条都给你现象、原因、修法。5.1 401 Unauthorized现象curl 或 Claude Code 返回{error:{type:authentication_error,message:invalid x-api-key}}。原因通常是三类Key 复制时带了空格或换行、环境变量没生效、Key 被撤销。排查命令# 检查环境变量是否真的存在 echo Key 长度${#ANTHROPIC_API_KEY} # 正常应该是 40 字符如果是 0 说明没设置成功 # 检查是否有隐藏字符 echo $ANTHROPIC_API_KEY | cat -A # 如果行尾出现 ^M 或多余空格说明复制时带入了不可见字符修法重新从控制台复制 Key用export ANTHROPIC_API_KEYsk-xxx直接赋值不要经过中间文件。如果用的是auth.json确认 JSON 里没有多余逗号。5.2 local proxy failed / connection refused现象Claude Code 报API Error: local proxy failed to connect或ECONNREFUSED。原因Base URL 写成了http://localhost:xxxx这类本地代理地址或者环境变量里残留了旧的代理配置。排查# 查看当前 Base URL echo $ANTHROPIC_BASE_URL # 应该输出 https://taotoken.net/api # 检查是否有其他代理变量干扰 env | grep -i proxy如果输出里有HTTP_PROXY或HTTPS_PROXY指向本地端口先 unset 掉unset HTTP_PROXY HTTPS_PROXY ALL_PROXY然后确认ANTHROPIC_BASE_URL是https://taotoken.net/api不带尾部斜杠。5.3 OAuth token 过期或冲突现象Claude Code 提示OAuth token expired或反复要求登录。原因Claude Code 默认走 OAuth 登录流程如果你同时设置了ANTHROPIC_API_KEY两者会冲突。修法明确走 API Key 模式清掉 OAuth 缓存# 查看 Claude Code 配置目录 ls ~/.claude/ # 删除 OAuth 相关缓存注意备份 rm -f ~/.claude/credentials.json然后在~/.claude/settings.json里显式指定{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的实际Key } }5.4 Skill 不触发 / 触发了但读不到 Reference现象发了会议文本模型直接自由发挥没走 Skill 格式。原因description写得太泛比如只写“帮助总结会议”。模型在第一层元数据匹配时无法判断相关性。修法把 description 写成“场景 动作 触发词”结构参考 3.2 节里的写法。另外确认SKILL.md的 frontmatter 用三个短横线闭合YAML 缩进用空格不用 Tab。Reference 读不到多半是路径问题。SKILL.md 里写references/finance-policy.md是相对 Skill 根目录的不要写成绝对路径或./references/。5.5 Script 执行权限或解释器问题现象调用脚本时报Permission denied或python3: command not found。修法# 加执行权限 chmod x ~/.claude/skills/meeting-summarizer/scripts/upload_summary.py # 确认 python3 路径 which python3 # 如果输出为空装一个或用绝对路径 /usr/bin/python3如果脚本里用了第三方库记得在 Skill 目录下建requirements.txt并在 SKILL.md 里说明安装命令否则换台机器就挂。5.6 报错对照速查表报错关键词最可能原因一句话修法401 invalid x-api-keyKey 带空格或未生效重新 export用cat -A查隐藏字符local proxy failedBase URL 指向本地改成https://taotoken.net/apiOAuth token expiredOAuth 与 API Key 冲突删 credentials.jsonsettings.json 显式配 KeySkill 不触发description 太泛改成“场景动作触发词”Reference 读不到路径写法错误用相对 Skill 根目录的路径Permission denied脚本没执行权限chmod x6. 把 Skill 和 MCP 的边界划清楚然后动手做第一个回到开头那个客服 Agent 的坑。后来我把它拆了订单查询、退货政策判断、工单创建这三个动作走 MCP因为要连真实系统、要认证、要审计而“先安抚再解释”“7 天和 15 天的适用场景”“什么情况下给替代方案”这些规则写成 Skill。改完之后prompt 从 5000 字降到 800 字稳定性反而上来了。一句话记边界MCP 负责“能连什么、能取什么、能调什么”Skill 负责“碰到什么场景、用什么步骤、按什么标准处理”。两者不是替代关系是协作关系。一个 MCP 服务可以被多个 Skill 共用一个 Skill 也可以建立在多个 MCP 之上。你现在就可以动手把团队里最常重复的那套流程——不管是周报生成、代码评审、还是客户投诉分级——按第 3 节的目录模板建一个 Skill先只写 SKILL.md跑通基础触发再加 Reference最后加 Script。每加一层用第 4 节的方法验证一次。三层都跑通你就有了一个真正可复用的 Agent 能力单元而不是又一个躺在文件夹里的提示词。需要创建 Key 或查看完整接入文档走这两个入口API Keys 在https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-keys接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc。Claude Code 专项配置参考https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaudecode。