1. 从零理解 Agent Skills它到底解决了什么痛点如果你最近在 Claude Code、Codex 或者 Cursor 里频繁看到「Skill」这个词却还没搞明白它和 Prompt、MCP 到底差在哪那这一节先把概念捋清楚。Agent Skills也叫 Claude Skills本质上是一种带目录的说明书或者说是一种渐进式披露提示词的机制。它把提示词拆成三层元数据、指令、资源。只有元数据是必定加载进模型上下文的指令和资源都按需加载。你可以把元数据类比成一本书的目录指令层对应正文资源层对应附录。AI 使用 Skill 时先把目录塞进提示词然后根据任务需要决定是否翻阅正文和附录。相比传统 Prompt 一次性把所有内容灌进上下文或者 MCP 把工具描述全量塞入Agent Skills 最大的好处是大幅降低 token 消耗与提示词复杂度。2025 年 12 月 18 日Anthropic 正式把 Agent Skills 发布成开放标准这意味着它和 MCP 一样正在朝通用、跨平台规范的方向走。Codex、Cursor、Opencode 等工具陆续加入支持。对开发者来说这意味着你写一份 Skill可以在多个 Agent 工具里复用。那它适合谁如果你符合下面任意一条这篇攻略就是写给你的用 Claude Code 做日常编码想让 AI 记住你的项目规范、写作风格、常用流程用 Codex 或 Cursor希望把重复性的提示词工程沉淀成可复用资产已经在用 MCP但发现工具描述太占上下文想用 Skill 来管理提示词层想搭建一个能自动跑脚本、读文档、调工具的完整 Agent 工作流。我试过把「字幕转 Markdown」这个流程从纯 Prompt 改写成 Skill上下文占用从每次约 3000 token 降到 400 token 左右而且触发更稳定。原因就在于元数据只有几十个 token模型先看到目录确认要用才加载指令。这一节先建立认知Skill 不是替代 MCP也不是替代 Prompt它是提示词的分层管理方案。下一节我们进入实操先把 TaoToken 的 Key 和 API 通道准备好因为后面所有验证都要走这条统一通道。2. TaoToken 前置准备统一 Key 与 API 通道配置在真正写 Skill 之前你需要一个稳定的模型调用通道。Claude Code 默认走 Anthropic 官方但很多开发者手里有多个模型来源切换起来很麻烦。TaoToken 的作用就是统一 Key 和 API 通道让你在 Claude Code、Codex、Cline 等工具里用同一套凭证调用不同模型。先访问官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册账号然后进入控制台创建 API Key。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在「API Keys」页面点击创建复制生成的 Key格式通常以sk-开头。接下来是 Claude Code 的配置。Claude Code 读取的配置文件在用户目录下WindowsC:\Users\{你的用户名}\.claude\settings.jsonmacOS / Linux~/.claude/settings.json如果.claude目录不存在手动创建。然后新建或编辑settings.json写入下面的内容{ env: { ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥, ANTHROPIC_BASE_URL: https://taotoken.net/api, API_TIMEOUT_MS: 3000000, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: 1 } }注意ANTHROPIC_BASE_URL填的是https://taotoken.net/api不要加 UTM 参数也不要带尾部斜杠。API_TIMEOUT_MS设成 3000000 毫秒是为了避免长任务超时。CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC设为 1 可以关掉非必要流量减少干扰。如果你之前登录过 Claude 官方账号还需要跳过 onboarding。找到用户目录下的.claude.json添加一行hasCompletedOnboarding: true保存后重启终端。验证配置是否生效可以在终端执行claude --version然后启动 Claude Code输入/status查看当前使用的 Base URL 和模型。如果显示的是taotoken.net/api说明通道已经切换成功。对于 Codex 用户配置文件在~/.codex/config.toml或C:\Users\{用户名}\.codex\config.toml。你需要同时配置模型通道和开启 Skills 功能model claude-sonnet-4-20250514 model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY [features] skills true然后在环境变量里设置TAOTOKEN_API_KEY为你的 TaoToken 密钥。Windows 可以用setx TAOTOKEN_API_KEY sk-xxxmacOS/Linux 在~/.zshrc或~/.bashrc里加export TAOTOKEN_API_KEYsk-xxx。这里有个坑要注意Codex 的base_url和 Claude Code 的ANTHROPIC_BASE_URL虽然都指向 TaoToken但 Codex 走的是 OpenAI 兼容格式Claude Code 走的是 Anthropic 格式。TaoToken 的/api端点同时兼容两种协议所以填同一个地址没问题。配置完成后你可以用模型对话功能快速验证 Key 是否可用https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。在页面里选一个模型发一条测试消息如果能正常返回说明 Key 和通道都没问题。这一节的核心是三件套Base URL、Key、Model ID。无论你后面用 Claude Code、Codex 还是 Cline这三个要素都要对齐。下一节我们开始写第一个 Skill。3. 可复制配置Skill 目录结构与 SKILL.md 模板Agent Skills 的目录结构非常固定只要符合规范就能生效。核心规则有三条Skill 以文件夹形式存在文件夹里必须有SKILL.md文件文件名必须是大写SKILL加小写.md扩展名。在 Claude Code 里Skill 可以放在两个位置项目级{项目根目录}/.claude/skills/{skill名称}/SKILL.md全局级~/.claude/skills/{skill名称}/SKILL.mdWindows 是C:\Users\{用户名}\.claude\skills\Codex 的路径把.claude换成.codex即可。全局 Skill 对所有项目生效项目级只对当前项目生效。一个完整的 Skill 目录推荐结构如下.claude/skills/字幕转markdown/ ├── SKILL.md ├── scripts/ │ └── screenshot.py ├── references/ │ └── style-guide.md └── assets/ └── template.pngSKILL.md是必须的scripts、references、assets都是可选的资源层。脚本放scripts补充文档放references图片等资源放assets。下面是一个可直接复制的SKILL.md模板--- name: 字幕转markdown description: 当用户提供 SRT 字幕文件并希望转换成 Markdown 笔记时调用。适用于视频字幕整理、课程笔记生成、访谈记录转写等场景。 --- 你是一个专业的字幕文本处理助手任务是把 SRT 字幕文件转换成 Markdown 笔记。 ## 处理规则 1. 禁止任何删减、总结或省略必须保留所有文字内容。 2. 按语义段落合并字幕行不要逐行输出。 3. 在关键位置插入截图占位符格式为 Screenshot-[HH:MM:SS]。 4. 输出文件保存为 output/{原文件名}.md。 ## 后续处理 Markdown 生成完毕后调用 scripts/screenshot.py 对视频进行截图 并将占位符替换为实际图片链接。元数据部分用六个横杠包裹name是 Skill 名称description最重要——它决定了 AI 在什么时机调用这个 Skill。描述要写清楚触发场景而不是功能罗列。比如「当用户提供 SRT 字幕文件并希望转换成 Markdown 笔记时调用」就比「字幕转换工具」好得多因为前者告诉模型什么时候该用。指令部分用 Markdown 格式写可以加粗、列表、代码块。指令越具体AI 执行越稳定。比如「禁止任何删减」比「尽量保留原文」更明确。对于 Codex 用户还需要在config.toml里确认[features]下skills true已开启。Cline 用户如果通过 MCP 方式接入需要在 MCP 配置里指定 Skill 目录路径。这里给出一个 Cline MCP 配置示例放在cline_mcp_settings.json里{ mcpServers: { agent-skills: { command: npx, args: [-y, taotoken/agent-skills-mcp], env: { TAOTOKEN_API_KEY: sk-你的密钥, SKILLS_DIR: .claude/skills } } } }注意SKILLS_DIR指向你的 Skill 根目录TAOTOKEN_API_KEY用上一节创建的 Key。这样 Cline 就能通过 MCP 读取并触发本地 Skill。配置写完后重启 Claude Code 或 Codex输入/skills命令应该能看到你定义的 Skill 列表。如果没显示检查三点文件夹名是否正确、SKILL.md大小写是否匹配、元数据是否用六个横杠包裹。4. 验证请求与成功结果触发 Skill 并检查输出配置写好了接下来要验证 Skill 是否真的能被触发。这一节用「字幕转 Markdown」这个例子走完整流程。首先准备测试文件。在项目根目录放一个.srt字幕文件比如demo.srt。然后启动 Claude Codecd skill-project claude进入交互界面后输入/skills你应该看到Available Skills: - 字幕转markdown: 当用户提供 SRT 字幕文件并希望转换成 Markdown 笔记时调用...这说明元数据已经被正确加载。接下来把demo.srt拖进终端或者直接输入文件路径然后回车。Claude Code 会识别出这是 SRT 文件并询问是否使用「字幕转markdown」Skill。选择 yes。此时发生的关键动作是AI 上下文里一开始只有元数据确认使用后Claude Code 才把SKILL.md下半部分的指令加载进去。这就是渐进式披露。你可以观察终端输出会看到类似Loading skill: 字幕转markdown Reading demo.srt... Generating output/demo.md...如果 Skill 里配置了scripts/screenshot.py并且项目目录里有对应的.mp4视频AI 会继续调用脚本python scripts/screenshot.py脚本执行成功后输出目录会生成带图片的 Markdown 文件。脚本的代码本身不会进入 AI 上下文只有执行结果会返回这样进一步节省 token。验证成功的标志有三个/skills能列出你的 Skill拖入对应文件后AI 主动询问是否使用该 Skill输出目录生成了预期格式的文件。对于 Codex 用户流程类似。启动codex后输入/skills然后提供测试文件。Codex 的实验性 Skills 功能需要config.toml里skills true已开启否则/skills命令不会显示任何内容。如果你想验证模型通道是否正常工作可以在 Skill 触发后观察请求日志。TaoToken 控制台的「日志」页面会显示每次调用的模型、token 消耗、耗时。如果看到 200 状态码和正常的 token 计数说明 Base URL、Key、Model ID 三件套都对齐了。这里有个细节Claude Code 在加载 Skill 指令时会把SKILL.md的正文部分作为 system prompt 的一部分发送。如果你在指令里写了「调用 scripts/screenshot.py」AI 会生成对应的工具调用请求由 Claude Code 执行本地脚本。脚本的 stdout 会返回给 AI但脚本源码不会。实测下来一个配置正确的 Skill 从触发到输出整个过程在 10 到 30 秒之间取决于文件大小和是否调用外部脚本。如果超过 60 秒没反应检查API_TIMEOUT_MS是否设得够大以及网络通道是否稳定。5. 本篇常见错误排查401、local proxy failed、reading choices、OAuth这一节整理实际使用中最容易遇到的四类报错每一类都给出原因和修复步骤。401 Unauthorized这是最常见的错误通常出现在启动 Claude Code 或 Codex 后第一次请求模型时。报错原文类似API Error: 401 {error:{message:Invalid API key,type:authentication_error}}原因有三个Key 填错、Key 过期、Base URL 和 Key 不匹配。修复步骤打开settings.json确认ANTHROPIC_AUTH_TOKEN是完整的sk-开头字符串没有多余空格。然后确认ANTHROPIC_BASE_URL是https://taotoken.net/api不是官网首页地址。如果 Key 是在 TaoToken 控制台创建的去控制台确认状态是「启用」。修改后重启终端。local proxy failed这个报错通常出现在 Claude Code 启动时Error: local proxy failed to start原因是 Claude Code 内部会启动一个本地代理来转发请求如果端口被占用或配置文件格式错误代理起不来。修复步骤先检查settings.json是否是合法 JSON可以用python -m json.tool settings.json验证。然后检查是否有其他 Claude Code 进程在运行用ps aux | grep claude或任务管理器结束残留进程。如果还不行删除~/.claude下的缓存目录保留settings.json重启。reading choices 报错这个错误出现在模型返回格式异常时Error: reading choices: unexpected end of JSON input原因是模型返回的响应不是标准 OpenAI 格式通常是 Base URL 指向了不兼容的端点。修复步骤确认 Codex 的config.toml里base_url是https://taotoken.net/api并且model_provider配置正确。如果你在 Codex 里混用了 Anthropic 格式的地址就会出这个错。Codex 走 OpenAI 兼容格式Claude Code 走 Anthropic 格式两者不能互换。OAuth 相关报错如果你之前登录过 Claude 官方账号可能会遇到Error: OAuth token expired或者启动时一直卡在登录页面。原因是 Claude Code 优先使用 OAuth 凭证而不是settings.json里的 Key。修复步骤找到~/.claude.json确认hasCompletedOnboarding: true已添加。然后删除~/.claude下的credentials.json或类似凭证文件。重启后 Claude Code 会跳过 OAuth直接使用settings.json里的配置。对于 Codex 的auth.json如果你用的是 API Key 模式确保~/.codex/auth.json里没有残留的 OAuth token。正确的内容应该是{ OPENAI_API_KEY: sk-你的TaoToken密钥 }如果文件里有tokens字段说明还在用 OAuth 模式需要删掉整个文件重新生成。排查时记住一个原则先看报错关键词再定位配置文件最后重启验证。大部分问题都出在 Base URL、Key、Model ID 这三件套没有对齐。如果你在 Cline 或 MCP 场景下遇到问题检查cline_mcp_settings.json里的env字段是否传入了正确的TAOTOKEN_API_KEY。6. 从 Skill 到工作流长期编码与 Agent 的落地建议当你跑通第一个 Skill 后接下来要考虑的是如何把它变成日常开发的一部分。这一节给几条落地建议。第一把重复提示词沉淀成 Skill。如果你发现自己每次都在 Claude Code 里粘贴同一段项目规范、代码风格要求、提交信息格式那就把它写成 Skill。元数据描述写「当用户要求生成提交信息时调用」指令里放你的格式模板。这样每次 AI 都会自动加载不用重复输入。第二Skill 和 MCP 配合使用。Skill 负责提示词层MCP 负责工具调用层。比如你有一个「帮我写作」Skill指令里写「写完后调用 GitHub MCP 的 create repository 工具创建仓库」。这样 Skill 管理写作风格和流程MCP 执行具体操作。两者各司其职上下文占用也最优。第三资源层按需加载。不要把大段文档直接塞进SKILL.md而是放到references/目录在指令里写「如果需要参考写作风格读取 references/style-guide.md」。AI 只会在需要时读取平时不占上下文。第四脚本执行要容错。Skill 里的 Python 脚本依赖本地环境不同机器上 ffmpeg、python 版本可能不一致。建议在脚本里加 try-except失败时返回明确的错误信息而不是直接崩溃。这样 AI 能根据错误信息决定是否重试或跳过。第五长期编码场景用 Coding Plan。如果你每天都要用 Claude Code 或 Codex 跑大量任务按量计费可能不划算。TaoToken 的 Coding Plan 提供包月套餐适合高频使用https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。配置方式和按量 Key 一样只是计费模式不同。第六版本管理你的 Skill。把.claude/skills目录纳入 Git 仓库这样团队里每个人都能用同一套 Skill。全局 Skill 放个人目录项目 Skill 放项目仓库分工清晰。最后给一个实际经验我维护了一个「代码审查」Skill元数据描述是「当用户提交 PR 或要求审查代码时调用」指令里定义了检查清单命名规范、错误处理、测试覆盖、性能隐患。每次审查时 AI 自动加载这份清单输出结构化报告。这个 Skill 帮我省掉了大量重复沟通。如果你想把 Skill 分享给团队可以把整个文件夹打包别人拖进.claude/skills就能用。社区里也有现成的 Skill 集合比如 GitHub 上的 Awesome Claude Skills 仓库可以直接下载复用。接入文档和 API Keys 管理入口在这里https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 文档地址https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。Claude Code 专项接入说明https://taotoken.net/claude-code?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 。