Claude Code Skills 深度解析：SKILL.md 参数传递与上下文预注入实战

1. 为什么你的 Claude Code Skills 总是触发不了或参数丢了如果你已经在 Claude Code 里写过几个 Skill大概率遇到过这两种情况一是明明装好了技能模型却像没看见一样死活不自动调用二是敲了/my-skill 参数结果模型回复里压根没用到你传进去的值。这两个问题看起来是玄学其实都指向同一套机制——SKILL.md 的参数传递与上下文预注入。Claude Code Skills 是 Anthropic 在 Claude Code 里引入的技能复用机制本质是把一段可复用的提示词、脚本、参考资料打包成一个目录让模型在合适的时候自动加载。它适合谁适合那些每天重复写同样提示词的开发者比如按团队规范 review PR生成符合约定的 commit message检查某个文件的安全问题。把这些固化成 Skill你就不用每次重新交代背景。但 Skill 真正难的地方不在写提示词而在于理解它的运行时行为哪些内容在模型看到之前就已经被填好了哪些是调用时才传进去的。这篇就围绕 SKILL.md 的配置骨架把参数传递$ARGUMENTS、$1和上下文预注入!命令、文件、${CLAUDE_PLUGIN_ROOT}拆开讲每个片段都能直接复制去用。同时我会说明怎么通过统一的 Key/API 通道 TaoToken 完成接入和调用验证避免你在多个 Key 之间来回切换。2. 前置准备用 TaoToken 统一 Key 与 API 通道在动手写 SKILL.md 之前先把调用通道理顺。Claude Code 需要能访问模型 API如果你手上有多个来源的 Key管理起来很麻烦。TaoToken 提供统一的 Key/API 通道官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 这个地址不加 UTM 参数。你需要做的准备只有三步第一步在控制台创建一个 API Key。打开 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 登录后进入 API Keys 页面新建一个 Key 并复制保存。这个 Key 就是后面 Claude Code 调用时要用的凭证。第二步确认你要用的模型。可以在模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 先试跑一句确认通道正常、模型可用再去配置 Claude Code。第三步把 Key 和 API 基址写进 Claude Code 的环境变量或配置里。Claude Code 读取的是ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY这类变量把基址指向 TaoToken 的 API 地址Key 填你刚创建的那个即可。注意API 基址用https://taotoken.net/api不要带任何查询参数官网链接才带 UTM。两者别混。如果你打算长期在 Claude Code 里跑编码任务、Agent 流程建议直接看 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 它针对编码场景做了额度规划比按次调用更省心。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 遇到字段不清楚可以对照。3. SKILL.md 配置骨架三级加载与 frontmatter 字段先把心智模型立住Skill 就是一张会自动填好的任务纸条。纸条上的字大部分是固定的但可以留两类空——一类等你调用时临时告诉它参数传递一类让它自己去查了填上上下文预注入。无论哪种空填空动作都发生在模型读到之前模型拿到的是成品它甚至不知道原文里有过占位符。这个填空分三级渐进式加载层级内容何时进入上下文体量L1 元数据name description会话一开始就注入始终在场约 100 词L2 正文SKILL.md 主体技能被触发时才注入建议 1.5k–2k 词L3 资源references/ scripts/ assets/模型按需读取/执行近乎无限L1 是真正的预注入你装的每个 Skill它的 name 和 description 在对话还没开始时就写进了系统提示这是模型判断该不该自动调用的唯一线索。所以 description 必须写成第三人称加具体触发短语# 好模型能准确判断何时触发 description: This skill should be used when the user asks to create a hook, add a PreToolUse hook, or mentions hook events. # 差太笼统技能几乎不会被自动触发 description: Provides guidance for working with hooks.frontmatter 里控制参数与注入行为的字段如下--- name: pr-check description: Review PR against project checklist when user asks to check PR or review pull request argument-hint: [pr-number] [priority] [assignee] allowed-tools: Read, Bash(git:*), Bash(gh:*) model: sonnet disable-model-invocation: true context: fork agent: Explore ---逐个说明name/description是 L1 预注入的全部内容argument-hint只是自动补全和/help里的说明书不参与实际替换allowed-tools限定可用工具用!注入命令时必须放行对应命令比如Bash(git:*)model可覆盖执行模型disable-model-invocation: true表示仅用户可调、模型不能自动触发适合部署、发送这类有副作用的操作user-invocable: false表示仅模型可调、用户看不到适合纯背景知识context: fork让技能在隔离子代理中运行不污染主会话。调用权限一览设置用户可调模型可调用途默认是是通用技能disable-model-invocation: true是否有副作用的操作user-invocable: false否是后台知识4. 上下文预注入!命令、文件与插件路径上下文预注入的核心是让纸条自带背景信息。当技能被触发、L2 正文加载时正文里可以嵌入三种会被实时替换的写法。第一种是!命令注入命令的实时输出## 当前状态 - 分支: !git branch --show-current - 改动: !git status --short运行时会先执行这些命令把标准输出内联进正文。模型看到的不是那句git branch而是已经变成- 分支: main的成品。这就是预注入最直白的体现命令在模型接手前就跑完了。用!时frontmatter 里要用allowed-tools: Bash(git:*)之类放行对应命令。第二种是文件注入文件内容Review src/api/users.ts for potential bugs.让运行时先把文件读进来再交给模型。它还能和参数组合成$1表示读取用户传进来那条路径所指的文件。第三种是${CLAUDE_PLUGIN_ROOT}插件内的可移植路径Run: !node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js插件型 Skill 专用自动解析为插件的绝对路径用来引用插件自带的脚本或模板避免硬编码。把三者串起来看一次完整时序。以官方 pr-check 技能为例--- name: pr-check description: Review PR against project checklist disable-model-invocation: true context: fork --- ## PR Context - Diff: !gh pr diff - Description: !gh pr view Review against [checklist.md](checklist.md). For each item, mark or with explanation.调用/pr-check时运行时的处理流水线是先做参数展开替换$ARGUMENTS/$1没有则末尾追加再执行命令注入跑gh pr diff、gh pr view并内联输出然后解析文件与${CLAUDE_PLUGIN_ROOT}最后把一张已物化的纯文本注入上下文。因为context: fork它进入独立子代理模型开始工作时只看到成品看不到任何占位符。5. 运行时参数传递$ARGUMENTS、$1与兜底规则Skill 有两个调用入口但共享同一套参数机制用户显式调用敲/skill-name 参数和模型自动调用根据 L1 描述判断相关后自行调用并传入参数。一个关键事实是传统的.claude/commands/*.md和新的.claude/skills/name/SKILL.md运行时加载方式完全一样只是文件布局不同所以下面的参数写法对两者通用。三种占位符写法# $ARGUMENTS全部参数当作一整个字符串 Fix issue #$ARGUMENTS following our coding standards. # /fix-issue 123 → Fix issue #123 following our coding standards. # $1 $2 $3位置参数分别对应第 1、2、3 个 Review PR #$1 with priority $2, then assign to $3. # /review-pr 123 high alice → Review PR #123 with priority high, then assign to alice. # 混合前几个用位置剩下的打包 Deploy $1 to $2 with options: $3 # /deploy api staging --force --skip-tests → Deploy api to staging with options: --force --skip-tests有一条几乎没人注意的兜底规则如果 SKILL.md 里根本没写$ARGUMENTS运行时会把参数以ARGUMENTS: 值的形式追加到内容末尾。也就是说参数永远不会丢区别只在于——写了占位符参数被精确插到指定位置没写占位符参数被兜底追加到结尾交由模型自行理解。再强调一次argument-hint只是说明书不参与传参。真正的传参靠$ARGUMENTS/$N。还有一种风格值得对照很多实用 Skill 几乎不用占位符而是把一连串动作写成自然语言指令让模型运行时自己去调工具收集上下文。比如一个提交流程 Skill它不预先传要提交哪些文件而是在正文里指挥模型先跑git status/git diff分析改动再分组生成 commit message——参数是模型在运行中动态产出的不是调用时传入的。这说明参数传递不是必需品正文指令 模型自主收集往往比硬塞参数更灵活。6. 验证请求确认参数与预注入真的生效配置写完必须验证。最直接的方式是造一个最小 Skill把参数和注入都放进去然后调用看输出。在.claude/skills/echo-test/SKILL.md写入--- name: echo-test description: Use when user asks to test skill params or verify skill injection argument-hint: [name] [env] allowed-tools: Bash(git:*) --- ## 参数验证 - 第一个参数: $1 - 第二个参数: $2 - 全部参数: $ARGUMENTS ## 上下文预注入验证 - 当前分支: !git branch --show-current然后在 Claude Code 里调用/echo-test alice staging预期结果模型回复里第一个参数显示alice第二个参数显示staging全部参数显示alice staging当前分支显示你仓库的真实分支名。如果分支那行还是原样的!git branch --show-current说明allowed-tools没放行Bash(git:*)或者命令执行失败。再验证兜底规则把上面 SKILL.md 里的$1/$2/$ARGUMENTS全删掉只留正文再调用/echo-test alice staging。你应该在模型看到的正文末尾发现ARGUMENTS: alice staging被追加进来。这一步能帮你确认参数不会丢这条规则确实生效。验证模型通道是否正常可以先用模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 跑一句简单请求确认返回正常再回到 Claude Code 里测 Skill。如果 Skill 调用报鉴权错误去 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 检查 Key 是否有效、是否复制完整。7. 本篇常见错误排查技能不自动触发。九成是 description 写得太笼统。模型对未触发的技能只看得见 L1 描述所以要写成第三人称加具体触发短语比如当用户说检查 PR或review pull request时使用而不是处理提交相关事务。参数没被替换。检查占位符拼写是$ARGUMENTS不是$ARGUMENT是$1不是$01。另外确认你调用时确实带了参数/my-skill后面空着$1自然为空。!命令没执行或报权限错误。frontmatter 里必须用allowed-tools放行对应命令比如Bash(git:*)、Bash(gh:*)。只写Bash有时不够精确建议带上命令前缀。文件读不到。路径要相对仓库根目录或者用$1让用户传绝对/相对路径。文件不存在时运行时不会报错只是注入为空模型会以为文件是空的。${CLAUDE_PLUGIN_ROOT}解析成字面量。这个变量只在插件型 Skill 里有效普通.claude/skills/目录下的 Skill 用不了会原样输出。普通 Skill 直接用相对路径。占位符替换不可逆。!cmd一旦跑完被内联模型无法重跑要拿最新状态只能靠下一次调用重新注入。$ARGUMENTS 是纯文本插值不做校验需要校验就在正文里显式写比如用 !echo $1 | grep -E ...验证环境名。把所有东西堆进 SKILL.md。那会破坏 L2 的精简性每次触发都白灌一堆上下文。细节挪到references/靠指针按需加载L3。还在用.claude/commands/。它是 legacy两者加载行为一致但目录格式能捆绑references/scripts/assets才能发挥完整的渐进式披露能力。新技能优先用 SKILL.md 目录格式。8. 把动态填充做成模型无感的预处理层Claude Code 的 Skill 之所以强大不在于写了一段提示词而在于它把动态填充做成了模型无感的预处理层。上下文预注入让技能自带实时背景——三级加载控制何时进上下文!//${CLAUDE_PLUGIN_ROOT}控制注入什么内容运行时参数传递让技能接受临时输入——$ARGUMENTS/$N精确插值外加末尾追加的兜底。两者殊途同归在模型读到之前把一张模板纸条填成成品。想清楚哪些空由用户填、哪些空由纸条自己查你就能设计出真正好用的 Skill。如果你还在为多 Key 管理头疼直接用 TaoToken 的统一通道接入把精力留给 Skill 设计本身。长期跑编码和 Agent 任务的话Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 的额度规划会比零散调用更稳。接入细节对照文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 即可遇到鉴权问题先查 API Keys 页面。