1. 从一次“日报翻车”说起Agent Skills 到底解决什么问题如果你刚接触 Agent Skills可以先把它理解成“给 AI 装技能包”每个技能是一个文件夹里面用SKILL.md写清楚这个技能叫什么、什么时候触发、具体怎么做再配上脚本和参考资料。Claude Code 是目前对 Agent Skills 支持比较完整的工具之一它会在合适的时机读取技能的元数据判断该不该加载完整指令这就是所谓的渐进式披露。我最早踩的坑很典型让 AI 写一份程序员日报第一版格式完全不对我把公司《日报格式规范》贴进去内容又变成了模板复读再补上真实工作数据它还是不知道数据从哪来。来回折腾四轮本质问题是——我把“技能说明、参考资料、执行脚本、Prompt”全塞在一次对话里模型每次都要重新理解一遍。Agent Skills 的思路是把这套东西固化下来SKILL.md负责声明和指令scripts/放可执行脚本references/放参考资料。你只需要在对话里说“帮我生成今天的日报”Claude Code 就会根据description匹配到对应技能再加载完整内容执行。这篇就按这个场景带你把SKILL.md和 Prompt 的组织方式跑通并且用 TaoToken 统一 Key 接入避免在多个工具之间来回换配置。适合谁看刚装好 Claude Code、想自己写第一个 Skill 的开发者手里有多个模型通道、想统一管理的同学以及被 Prompt 越写越长、越写越乱折磨过的人。2. 前置准备用 TaoToken 统一 Key 和 API 通道在写SKILL.md之前先把模型通道理顺。Claude Code 默认走 Anthropic 官方通道但很多人的实际环境里会同时用多个模型配置散落在不同文件里改一次要翻半天。TaoToken 的作用就是提供一个统一的 Key 和 API 入口Claude Code、Coding Plan、模型对话都走同一个地址配置只维护一份。你需要先拿到一个 API Key。打开控制台创建即可控制台入口https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteAPI Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite创建完 Key 之后记住两个地址用途地址官网https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI Basehttps://taotoken.net/api注意API Base 后面不要手动加/v1之类的后缀Claude Code 和多数 SDK 会自己拼接路径多写反而会 404。如果你还没装 Claude Code先按官方方式装好然后确认claude --version能正常输出。接下来所有配置都围绕两个文件Claude Code 的settings.json和 TaoToken 侧的config.toml骨架。前者管 Claude Code 怎么发请求后者管通道和模型映射两边对齐就不会出现“Key 明明对但一直 401”的情况。3. 可复制配置settings.json 与 config.toml 骨架先给 Claude Code 的settings.json。这个文件一般放在用户目录下的.claude/settings.json没有就新建。核心是把请求指向 TaoToken 的 API Base并用环境变量注入 Key避免把明文 Key 写进仓库。{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoTokenKey, ANTHROPIC_MODEL: claude-sonnet-4-20250514 }, permissions: { allow: [ Read, Write, Bash(git:*) ] } }几个参数说明一下。ANTHROPIC_BASE_URL指向 TaoToken 的 API 地址这是统一通道的关键ANTHROPIC_AUTH_TOKEN填你在控制台创建的 KeyANTHROPIC_MODEL按你实际可用的模型名填不确定就先留空让服务端默认。permissions.allow是 Claude Code 的权限白名单写 Skill 时经常要读文件、跑脚本先把Read、Write放开Bash按需收窄比如只允许git相关命令。再给一份config.toml骨架用于 TaoToken 侧的通道与模型映射。放在项目根目录或你习惯的配置目录都行[provider] name taotoken base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY [models] default claude-sonnet-4-20250514 fast claude-haiku-4-20250514 [skills] root ./.claude/skills auto_load trueapi_key_env表示从环境变量读 Key比硬编码安全。skills.root指向你存放技能文件夹的目录auto_load true让 Claude Code 启动时扫描技能元数据。这样SKILL.md放在./.claude/skills/日报生成/SKILL.md就能被自动发现。接着写第一个SKILL.md。注意 frontmatter 里的name和description是给模型做匹配用的description要写清楚“什么时候用”而不是“这个技能多厉害”。--- name: daily-report description: 当用户要求生成日报、周报或工作总结时使用。适用于需要按公司固定格式输出、并读取本地工作记录文件的场景。触发词包括日报、周报、工作总结、report。 --- # 日报生成技能 ## 执行步骤 1. 读取 ./data/today-tasks.md提取今日完成任务列表。 2. 按以下格式输出不要增删章节 ## 今日完成 - 任务名一句话说明 ## 明日计划 - 任务名一句话说明 ## 风险与阻塞 - 无 / 具体描述 3. 如果 today-tasks.md 不存在先提示用户补充不要编造内容。这里的关键点description里把触发词写全模型匹配时命中率更高正文用编号步骤而不是大段散文模型执行更稳定明确“不要编造”避免它拿训练数据里的假任务凑数。4. 验证请求一条命令确认配置生效配置写完别急着开对话先用一条命令确认通道通不通。Claude Code 支持非交互模式可以直接发一条最小请求claude -p 只回复两个字通了 --output-format text如果返回“通了”说明settings.json里的 Base URL 和 Key 都生效了。如果报 401优先检查 Key 是否复制完整、有没有多余空格报 404 就检查 Base URL 是不是被手动加了/v1。通道确认后再验证 Skill 是否被加载。在项目目录下启动 Claude Code输入claude然后在对话里输入“帮我生成今天的日报”。正常表现是Claude Code 先读取daily-report技能的元数据匹配到description里的触发词再加载完整SKILL.md接着去读./data/today-tasks.md。如果它直接开始编内容说明技能没被扫描到检查skills.root路径和auto_load是否为true。想单独验证模型通道也可以走模型对话页面发一条测试模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite成功结果长这样返回内容严格按“今日完成 / 明日计划 / 风险与阻塞”三段输出且任务名来自你本地的today-tasks.md不是模型自己编的。到这一步SKILL.md配置和 TaoToken 统一 Key 就算跑通了。5. 本篇常见错排查报错一401 Unauthorized。九成是 Key 问题。先确认ANTHROPIC_AUTH_TOKEN和你在控制台创建的一致再确认环境变量没有被系统里旧的同名变量覆盖。可以在终端echo $ANTHROPIC_AUTH_TOKEN看一眼实际值。报错二404 Not Found。检查ANTHROPIC_BASE_URL是否写成了https://taotoken.net/api/v1。正确写法就是https://taotoken.net/api路径由客户端拼接。报错三技能不触发。先看description里有没有写触发词。模型是靠这段文字做匹配的你写“用于生成文档”用户说“帮我写日报”匹配不上很正常。把“日报、周报、工作总结”这类词直接写进去。报错四技能触发了但读不到文件。Claude Code 的工作目录是启动时所在的目录./data/today-tasks.md是相对路径。如果你在别的目录启动路径就对不上。要么用绝对路径要么固定在工作目录启动。报错五脚本执行被权限拦截。settings.json的permissions.allow没放开对应命令。写 Skill 时如果需要跑 Python 脚本把Bash(python:*)加进去但别直接放开Bash(*)范围太大。报错六多个 Skill 同时命中。两个技能的description都写了“日报”模型可能选错。解决办法是让描述更具体比如一个写“生成研发日报”另一个写“生成运营日报”用领域词区分。6. 继续往下走把 Skill 和 Coding Plan 串起来跑通第一个 Skill 之后你会发现真正花时间的不是写SKILL.md而是维护 Prompt 的组织方式。我的习惯是SKILL.md只放流程和格式约束长参考资料放references/可执行逻辑放scripts/三者用相对路径互相引用。这样改格式不用动脚本改脚本不用动说明。如果你打算把 Agent Skills 用在长期编码或自动化任务上建议把通道切到 Coding Plan额度模型更适合高频调用Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite接入文档里有各语言 SDK 的完整示例需要接自己项目时对着改就行接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewriteClaude Code 相关的配置细节官方文档页也有对应说明Claude Code 接入https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite最后留一个实用技巧每写完一个 Skill先用claude -p 触发词做一次非交互验证确认能被匹配到再放进正式对话流程。这样比在长对话里反复调试快得多也不会把上下文越堆越乱。
