1. 从一次“技能失控”说起Agent Skill 到底解决什么问题如果你已经在 Claude Code 里写过几个自定义命令大概率遇到过这种局面同一个项目里塞了七八个技能每个技能的说明文档各写各的有的用自然语言描述参数有的直接贴 curl模型每次都要把全部内容读一遍才决定用哪个。结果就是上下文被撑爆、调用错技能、参数传错排查起来还得翻半天日志。Agent Skill 的核心思路其实很朴素用一份规范文档告诉模型“这件事该怎么做”。模型在 System Prompt 阶段只加载每个 SKILL.md 的 name 和 description用来判断当前用户问题该命中哪个技能命中之后才把那份 SKILL.md 的完整内容注入 Prompt按里面的说明执行操作。这个“先路由、后加载”的两段式设计是它比“把所有工具描述一次性塞进上下文”更省 token、也更可控的关键。但光有 SKILL.md 还不够。一个能跑起来的 Agent Skill 需要三样基础设施一个能执行 bash 的沙盒带完整文件系统、一条稳定的模型调用通道、以及一套依赖管理方式。前两样决定了技能能不能落地第三样决定了它能不能被团队维护。这篇就聚焦工程化落地用 SKILL.md 定义技能边界用 npm 管依赖用 TaoToken 统一 Key 和 API 通道接入模型调用最后完整走一遍“注册技能 → 触发调用 → 验证结果”的流程。适合谁看已经在用 Claude Code、想把手头零散脚本沉淀成可复用技能的开发者或者团队里多人共用一套 Agent 能力、需要统一入口和密钥管理的场景。下面所有配置都可以直接复制改路径使用。2. 前置准备TaoToken 统一 Key 与 Claude Code 环境2.1 为什么要在 Skill 体系里统一 KeyAgent Skill 一旦多起来最烦的不是写文档而是每个技能背后可能连着不同的模型服务、不同的 Key。今天这个技能用 A 平台的 Key明天那个技能用 B 平台的密钥散落在各个 settings 文件和环境变量里换个人接手就得重新问一遍“这个 Key 是哪来的”。TaoToken 在这里扮演的是统一入口的角色一个 Key、一条 API 通道Claude Code 和后续所有技能调用都走它。这样 SKILL.md 里不需要关心底层是哪家模型只需要按统一格式发请求。对团队来说密钥轮换、额度查看、调用排查都收敛到一个地方。需要提前拿到的两样东西一个可用的 API Key在控制台的 API Keys 页面创建确认接入地址API 基址是https://taotoken.net/api注意这个地址不带任何查询参数。控制台入口在这里https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite2.2 安装 Claude Code 并设置 npm 源Claude Code 推荐用 npm 安装这样版本管理和后续升级都方便。先确认 Node 版本建议 18 以上node -v npm -v如果 npm 拉包慢先切一个国内源这一步能省掉后面很多等待npm config set registry https://registry.npmmirror.com npm config get registry然后全局安装 Claude Codenpm install -g anthropic-ai/claude-code claude --version能打印出版本号就说明装好了。接下来是配置模型通道这一步决定了 Claude Code 请求发到哪里。2.3 配置 settings.json 接入 TaoTokenClaude Code 的配置分两层全局配置在用户目录下项目级配置在项目根目录的.claude/settings.json。做 Agent Skill 开发建议用项目级配置这样技能和模型通道跟着仓库走换机器不用重新配。在项目根目录创建.claude/settings.json{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: 你的_TaoToken_API_Key, ANTHROPIC_MODEL: claude-sonnet-4-5-20250929 } }三个字段的作用分别是ANTHROPIC_BASE_URL指定请求走 TaoToken 的 API 通道ANTHROPIC_AUTH_TOKEN填你在控制台创建的 KeyANTHROPIC_MODEL指定默认模型。如果你更习惯用环境变量也可以把这三项写进 shell 的 profile 文件效果一样。注意ANTHROPIC_BASE_URL只写到/api不要在后面拼/v1之类的路径Claude Code 会自己补全。配好之后启动一次 Claude Code随便问一句“你好”能正常回复就说明通道通了。如果报 401先回去检查 Key 有没有复制完整如果报连接超时检查 base url 有没有多写字符。3. 可复制的 SKILL.md 骨架与 npm 依赖管理3.1 SKILL.md 的目录结构与字段规范Claude Code 约定技能放在项目下的.claude/skills/目录每个技能一个子目录子目录里放一个SKILL.md。目录名建议用英文小写下划线和技能名保持一致方便排查。你的项目/ ├── .claude/ │ ├── settings.json │ └── skills/ │ └── parcel_acceptance_guidelines_lookup/ │ └── SKILL.md ├── package.json └── scripts/SKILL.md 的头部是 YAML front matter至少包含三个字段--- name: Parcel Acceptance Guidelines Lookup description: 这个skill用于查询寄件标准、禁限寄规定等业务规则当用户询问某物品能否寄送、寄送限制时使用 version: 0.0.1 ---name是技能标识description是路由依据——模型只靠这句话判断该不该用这个技能所以描述要写清楚“什么场景下用”而不是“这个技能是什么”。version方便后续迭代时追踪。3.2 一份可直接改用的 SKILL.md 骨架front matter 之后是正文正文才是命中技能后真正注入 Prompt 的内容。骨架建议按“端点 → 参数 → 固定参数 → 请求头 → 示例 → 注意事项”组织模型读起来结构清晰出错概率低。--- name: Parcel Acceptance Guidelines Lookup description: 查询寄件标准、禁限寄规定等业务规则用户询问物品能否寄送、寄送限制时使用 version: 0.0.1 --- ### 端点 POST http://your-internal-api.example.com/v1/robot ### 参数 - message (string, required): 用户咨询的问题例如草莓从深圳寄北京可以寄吗 ### 固定参数 json { sysCode: FS-ROBOT-CORE, appCode: , fromClient: PC, sender: 01448236, templateId: 5c3b0f831f80422694d8a3c9ac51dae9, convType: PERSON, capacity: [], messageType: TEXT, personifyDisable: true, faqThreads: [0.88, 0.85, 0.62] } ### 请求头 json { server-name: robot-dm, apikey: 从环境变量读取不要硬编码, Content-Type: application/json } ### 示例 用户: 草莓从深圳寄北京可以寄吗 bash curl --location --request POST http://your-internal-api.example.com/v1/robot \ --header server-name: robot-dm \ --header apikey: ${ROBOT_API_KEY} \ --header Content-Type: application/json \ --data-raw { sysCode: FS-ROBOT-CORE, message: 草莓从深圳寄北京可以寄吗, messageType: TEXT } ### 注意事项 1. 只有 message 参数需要动态传入其他参数保持固定 2. 用户问题必须带上目的地城市否则先追问目的地 3. 该接口只用于查询业务规则不执行实际下单这里有个容易踩的坑示例里的 apikey 千万别写死。SKILL.md 会被完整注入 Prompt硬编码的密钥等于直接暴露给模型上下文。正确做法是从环境变量读在 settings.json 或 shell 里配好。3.3 用 npm 管理技能依赖与脚本技能多了之后每个技能可能依赖不同的 CLI 工具或 SDK。用 npm 统一管理好处是package.json里一眼能看清这个项目需要什么新人 clone 下来npm install就能跑。初始化npm init -y npm install --save-dev anthropic-ai/claude-code然后在package.json里加几个脚本把常用操作固化下来{ name: agent-skill-demo, version: 1.0.0, scripts: { skill:list: ls -la .claude/skills, skill:validate: node scripts/validate-skill.js, claude: claude }, devDependencies: { anthropic-ai/claude-code: ^1.0.0 } }skill:validate可以自己写个小脚本检查每个 SKILL.md 的 front matter 是否完整、name 是否和目录名一致。这类校验脚本看着不起眼但技能超过五个之后能省掉大量“为什么这个技能不生效”的排查时间。// scripts/validate-skill.js const fs require(fs); const path require(path); const skillsDir path.join(process.cwd(), .claude, skills); const dirs fs.readdirSync(skillsDir); dirs.forEach((dir) { const skillPath path.join(skillsDir, dir, SKILL.md); if (!fs.existsSync(skillPath)) { console.error([缺失] ${dir} 下没有 SKILL.md); return; } const content fs.readFileSync(skillPath, utf-8); const hasName /^name:\s*./m.test(content); const hasDesc /^description:\s*./m.test(content); if (!hasName || !hasDesc) { console.error([字段缺失] ${dir} 的 front matter 不完整); } else { console.log([通过] ${dir}); } });跑一下npm run skill:validate输出全是通过就说明技能目录结构没问题。4. 完整验证流程从技能注册到一次成功调用4.1 注册技能并确认列表把上面那份 SKILL.md 放进.claude/skills/parcel_acceptance_guidelines_lookup/SKILL.md然后在项目根目录启动 Claude Codenpm run claude进入交互界面后执行斜杠命令/skills正常情况下会列出当前项目下所有已注册的技能包括刚放进去的那个。如果列表里没有先检查三件事目录层级是不是.claude/skills/技能名/SKILL.mdfront matter 的---有没有写全name字段有没有拼错。4.2 触发技能调用并观察路由技能列表确认后直接问一个能命中 description 的问题草莓从深圳寄北京可以寄吗模型会先根据 description 判断该用哪个技能命中后加载完整 SKILL.md然后按里面的端点、参数、示例去构造请求。你可以在 Claude Code 的输出里看到它调用了哪个技能、传了什么参数。如果模型没有命中技能而是自己瞎答通常是 description 写得太泛。把“查询业务规则”改成“用户询问某物品能否寄送、寄送限制时使用”命中率会明显提升。description 是路由的唯一依据值得多花几分钟打磨。4.3 用 curl 独立验证接口连通性在依赖模型之前先用 curl 单独验证技能背后的接口是通的这样能把“模型没调对”和“接口本身有问题”两类故障分开export ROBOT_API_KEY你的接口密钥 curl --location --request POST http://your-internal-api.example.com/v1/robot \ --header server-name: robot-dm \ --header apikey: ${ROBOT_API_KEY} \ --header Content-Type: application/json \ --data-raw { sysCode: FS-ROBOT-CORE, message: 草莓从深圳寄北京可以寄吗, messageType: TEXT }返回结构正常说明接口没问题接下来模型调用失败就只可能是 SKILL.md 描述或参数的问题。这一步看着多余但实测下来能省掉一半以上的排查时间。4.4 验证模型通道是否走通 TaoToken技能调用最终还是要经过模型。想确认请求确实走了 TaoToken 通道可以在 Claude Code 里问一个需要模型推理的问题比如“帮我把上面这个查询封装成一个函数”。如果模型能正常返回说明ANTHROPIC_BASE_URL和 Key 都生效了。想更直观地看调用情况去控制台的用量页面能看到刚才那次请求的记录。模型对话入口在这里可以单独测通道https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite5. 本篇常见错误排查5.1 技能不生效/skills 列表为空最常见的原因是目录层级不对。Claude Code 只认.claude/skills/这一层如果你放成了.claude/skill/或者skills/少了前面的点都不会被识别。另一个原因是 front matter 的---前后有空格或 BOM 字符用编辑器另存为 UTF-8 无 BOM 格式即可。还有一种情况是项目级配置和全局配置冲突。如果你在用户目录也放了 skills两边的技能会合并但同名技能以项目级为准。排查时先确认当前工作目录是不是项目根目录。5.2 模型不调用技能自己编答案description 写得太模糊是主因。判断标准很简单把 description 单独拿出来给一个不了解项目的人看他能不能判断出“什么情况下该用这个技能”。如果不能就重写。另外SKILL.md 正文里如果示例太少模型也可能因为不确定参数格式而放弃调用多补两个不同场景的示例能改善。5.3 请求报 401 或 403先确认 Key 有没有复制完整前后有没有多余空格。然后检查ANTHROPIC_BASE_URL是不是写成了https://taotoken.net/api/末尾多了斜杠或者拼了/v1。这两个都会导致鉴权失败。如果 Key 是在控制台刚创建的确认一下有没有启用状态。5.4 接口返回参数错误SKILL.md 里的固定参数如果和接口实际要求不一致就会报参数错误。排查方法是拿 SKILL.md 里的示例 curl 直接跑一遍对比接口文档。特别注意message这类必填字段有没有在示例里体现以及faqThreads这种数组字段的格式有没有写错。5.5 npm 脚本执行报错找不到模块npm run skill:validate报Cannot find module通常是没在项目根目录执行或者node_modules没装。先npm install再确认scripts/validate-skill.js的相对路径写对了。如果脚本里用了process.cwd()确保执行时的工作目录就是项目根目录。6. 把技能体系沉淀下来的几个实用做法技能跑通一次不难难的是三个月后还能维护。几个实测有效的做法SKILL.md 的 version 字段每次改动都递增配合 git 提交记录能快速定位是哪次改动导致技能失效description 单独维护一份清单放在项目 README 里方便团队 review 时一眼看出有没有技能描述重叠固定参数尽量抽到环境变量或配置文件SKILL.md 里只保留结构说明避免密钥和业务配置混在文档里。密钥和通道这块长期编码或 Agent 场景建议用 Coding Plan额度和调用方式更适合持续跑任务https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite接入细节和字段说明以官方文档为准遇到报错先翻文档再排查https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteKey 的创建和管理都在 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite如果你用的是 Claude Code 的 Anthropic 兼容模式接入说明在这里https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite最后留一个我踩过的坑SKILL.md 里的示例 curl 如果用了--data-raw加单引号包裹 JSON在某些 shell 下换行会出问题建议把 JSON 压成一行或者用--data payload.json从文件读。这个细节不影响模型理解但影响你手动复现时的成功率。