摘要skill 的输入输出靠三张口$ARGUMENTS 传参、!command预载、context: fork 外派每个接口从怎么写一路讲到模型看到的题词。本机实测三个特性全军覆没反而看清机制参数走消息尾随预载与禁工具是配套设计外派是给失忆分身递任务书。字段体系画出能力边界——官方 20 字段、跨平台只认 6 个、version 不在列。可移植写法一句话正文写兜底句别赌机制。脱敏声明这一课没有要打码的东西——teach、commit.md、grill-me、humanizer-zh、baoyu 都是公开标本全文实名三件实验标本 lab-io-argslab-io-shellcmdlab-io-fork 就在项目里可复现我答错的题、我追问的话、我跑的实验全部照实录写。1、开场三个名字一次全军覆没底牌先亮。上一课收尾留的三个名字$ARGUMENTS、!command、context:fork我拿自家机器全测了一遍全军覆没。说好的脚本之后 skill 仅剩的机关上一课收尾的原话四次调用次次成功三个特性零生效。名字我见过不下十遍。官方文档把它们并排放着口气平铺读起来就像进阶语法学了就能用——我也确实这么以为过。测完才翻转过来正是用不了把这三个东西到底是什么逼了出来——怎么个用不了法三个名字各有一套。每个接口的说明书都写在它没发生时的反面。这一课跟着一句需求走每个接口从怎么写一路讲到最终喂给大模型的题词长什么样。三张口讲完再给一张全字段地图——skill 的能力边界就是这些字段画出来的。三张口只是前排地图才是全线。2、第一口·传参$ARGUMENTS从模板到成品题词2.1 流水线五步写、调、触发、处理、题词先把自己当时的理解摆上来。讲到变量那会儿我的理解是我写 skill 本质上是一些上下文注入到 LLM 的如果用变量就可以替换上下文的内容。“这话对了一半——把 skill 当注入的上下文准把变量当替换内容”只看到了现象。剩下那一半才是关键谁在替你替换什么时候替换的答案在五步流水线里。写、调、触发、处理、题词一步一走每步答一句模型此刻看到什么。五步以第一口走全样本后两口结构相同只走差异步。第一步写。正文不是文章是带槽的模板槽有六种写法$ARGUMENTS全量调用时带的全部参数$0、$1按位定位从 0 起数带引号算一个shell 的规矩$ARGUMENTS[N]带索引的切片$alpha命名参数frontmatter 里arguments: alpha beta按位置映射这个 arguments 字段节 7.2 正面讲${ARGUMENTS}花括号形态官方不认写了就是普通文本留它当负对照\$1反斜杠转义想要字面的$1时用。一个最小模板长这样正文就一行Fix GitHub issue $ARGUMENTS.第二步和第三步一起说。调用分两个入口斜杠直调/fix-issue 1234参数就是你跟的那串1234或者自然语言一句帮我修一下 1234 号 issue走 description 领地匹配——第 2 课讲过的路由不重讲。要紧的是触发层三口共用后面两口的触发也走这条路。第四步处理。填槽在这里发生——运行时的字符串工序模型没有出场。宿主拿着1234把 $ARGUMENTS 换掉换完才轮到下一步。我那个理解错就错在这不是模型看到模板再自己替换是模型看到之前替换已经完了。第五步题词。正规运行时上模型拿到的是成品Fix GitHub issue 1234.变量消失了模型不知道存在过 $ARGUMENTS——就像读信的人不知道填过表。2.2 兜底三分、转义与调用细则参数没填的时候三分兜底各管一种正文里一个占位符都没有——参数不丢追加成一段ARGUMENTS: 1234织进正文$1这类定位槽没被填——原样保留$1 就以 $1 的样子见面$alpha这类命名槽没被填——展开成空串无痕消失。第一条最有设计含量没槽也接参数——这是参数独立于占位符的伏笔2.3 的实测会接住它。替换族也不止参数CLAUDESKILLDIR、{CLAUDE_SKILL_DIR}、CLAUDESKILLDIR、{CLAUDE_PROJECT_DIR} 这些环境变量同在渲染期展开第 4 课编址用的 ${CLAUDE_SKILL_DIR} 就出生在渲染这一步。还有两条冷知识skill 可以叠加调用尾随参数传给叠在其中的每一个最多叠五个官方口子本机没验同一 skill 完全相同的重复调用只附加一条说明不重复注入——这条节 3 的渲染产物还会再见。兜底三分我背过动手题上当时空着没答上来。背不住不丢人丢人的是不落成设计兜底有三种走法可移植的写法只有一条——正文永远写兜底句别赌运行时替你想全。判断句立此参数是你说的话——调用那一刻就知道的才叫参数。这句先记住收口要拿它划第四条路的界。2.3 真机对照字面透传与消息尾随文档说有不等于机器上有。实验的账先摆平三个标本、一共四跑——lab-io-args 带参一跑、无参一跑lab-io-shellcmd 一跑lab-io-fork 一跑本节先走 args 的两跑。固定变量项目里建 lab-io-args六形态一字排开加转义负对照全新 general-purpose 子 agent 经 Skill 工具调用带参传 R1 R2 R3要求逐字引用看到的正文。防污染守则立一条子 agent 只许经 Skill 工具拿正文禁止直读标本文件——直读进眼的是盘上原文渲染管道没被验到。结果一行说完六形态全部字面透传$ARGUMENTS 见面还是 $ARGUMENTS连 $1 的反斜杠都原样躺着。无参那一跑兜底三分一条没发生。带参、无参两跑对出来的附加发现更值钱参数根本没走丢——它以消息尾随的方式到达模型从调用消息里读参不依赖正文占位符。我再开新会话补了条路径复测斜杠直调/lab-io-args 甲 乙 丙同样字面透传参数以独立 args 字段传给模型自行解释。两条调用路径一个结果本机支持矩阵全表第 5 节拼齐在这一格上闭合。实验代价记一笔三标本四跑合计约 20.5 万 subagent tokensn4、一台机器只证本机。边界声明补一句这轮测的是 SKILL.md 路径commands 命令文件那条路官方文档同样声明支持本机没测不替它打包票。对照看完接住 2.2 的伏笔参数可达和占位符替换是两件事。前者是本机也有的通用路后者赌运行时建没建填槽工序。可移植的写法由此定型兜底句就一句调用消息里尾随的文字就是输入。这句写在正文末尾模型读到它就把调用消息里尾随的文字认领为输入。3、第二口·预载!command把机器的现状搬进题词第二口管现场事实。模型要知道当前分支、改动清单就得自己跑 git——慢一步而且很多 skill 的指令干脆禁了它动工具。commit-commands 插件的 commit.md 给了标本级解法正文开头一个 Context 段四条预载。3.1 配套咬合预载与禁用工具是一对我第一遍读这份标本注意力全在四条命令上动手批改的时候才发现看漏了主线预载和一条消息、不准用其他工具是配套设计。禁了工具预载就是现场信息唯一的进村路——抽一半塌一半。我当时把这道题答成预载图省事防手写方向就错了这不是优化是依赖。机制五条条条带后果渲染前执行。官方原话“Claude Code runs the command and replaces the line with its output before Claude sees the skill content.”——命令是宿主跑的模型看到时输出已织进正文行首或紧随空白才识别多行预载用 ! 围栏块只扫一遍。预载输出不二次扫描输出里再藏一个 !cmd不会连环爆失败即中止整次调用——例外是搜索比对类命令的 exit 1没找到是合法结果其余要容忍就在命令后补|| true整行写成 - Files: !cat maybe-missing.txt 2/dev/null || true渲染期不弹权限窗。“- Current branch: !git branch --show-current这一行发到模型眼前时已经变成”- Current branch: main——命令没了输出在原位。3.2 权限两世界与本机对照第五条单独说这是我整课错得最狠的一题。动手题问预载命令会要求用户授权吗我答会 ask 要求授权——错。渲染期没有窗。没被 allowed-tools 覆盖、会话又没开自动放行整次调用直接中止执行期才轮到权限窗。两个世界守门的不一样。渲染产物还有三条边界顺路交代成品作为单条消息进对话跨回合驻留完全相同的重复调用只附加一条说明不重复注入——2.2 那条冷知识在这兑现第 3 课说过的压缩回贴每 skill 最多 5000 tokens、总预算 25000出处就是这条渲染规则政策开关 disableSkillShellExecution 拉闸时输出位置替换成 “[shell command execution disabled by policy]”。判断句预载是机器的现状——每次调用都不同、又必须赶在模型开眼前就位的才归它。本机对照lab-io-shellcmd 埋了行内加围栏共四处只读命令echo 和 git 查询。结果字面透传不执行、不拦截、没有政策占位文本。这格塌掉比参数那格重谁照搬 commit.md 的配套设计——正文禁工具、全靠预载——两半一起塌模型要么违令自己跑要么空着现状瞎写。4、第三口·外派context: fork把活派给失忆分身第三口不管内容管场地。大扫描、深研究的活挤在主对话里干中间过程的海量输出全灌进上下文。第 1 课算的那笔账到执行层又翻出来一轮。官方机制叫 context: fork我先借个我熟的类比立住主对话是诊室要听病史、要看病人fork 是检验科拿任务书照 SOP 独立干干完只回一张化验单。抽血的全过程大夫不用看着。4.1 失忆三后果正文必须自足第一遍学到这我是懵的分身凭什么看不见历史后来才回过味来——检验科不认识你是设计不是缺陷。失忆定了三件事看不见对话历史——正文必须是指令自足的任务书背景、输入、预期产出一样不能省中间噪音全留在房间——翻一百个文件的输出不过河回来的只有最终报告默认转后台跑——要当回合等结果background: false。正文必须自足我有实证。第 4 课盲测的 S2 就是一次手工 fork27 行的 SKILL.md执行子 agent 没有任何历史触发、跑脚本、读 rules.md、判四问、出报告全流程照走。任务书写到什么程度分身就干到什么程度。还有官方亲自出面澄清的命名陷阱a skill withcontext: forkdoesn’t run in a fork of the current conversation, which would hand the subagent everything you’ve discussed so far.context: fork 不在当前对话的分叉里跑——那会把此前聊过的一切都交给分身。名字里的 fork 有误导它不分叉当前对话是干净的隔离上下文。真要带历史分身官方处方是fork 对话那个操作不是这个字段。依赖历史的任务派给 context: fork等于把病历扣在诊室回头怪检验科不认识病人。4.2 两旋钮与工种缺省就是全工具我当时追问的是context: fork 是不是还有别的 context: xxxagent: Explore 是不是也有别的 agent: xxx分身要预先定义吗答案两句话context 的文档取值只有一个 forkagent 是旋钮管工种——Explore 只读检索、Plan 只读规划、general-purpose 全工具不写就缺省 general-purpose全工具。自定义工种也有放 .claude/agents/ 里8.4 拆。全工具三个字要停一下。第 4 课坑节里自作主张改了 tdd description 的那个测试代理就是全工具分身闯的祸——分身缺省自带全套锤子。派活前先挑工种只查不写的用 Explore要改文件才上 general-purpose别拿缺省偷懒。model:给分身单独配模型background:前面说过默认转后台。这组合不是生僻玩法官方自家 /code-review 从 v2.1.218 起就是 forked subagent 方式跑的官方 deep-research 示例更把三口拧进同一行 frontmattercontext: fork 派出去agent: Explore 限定只读正文 $ARGUMENTS 接研究主题。传参和外派在同一份标本里会师。分身收到的题词就是Research 参数 thoroughly: 1. Find relevant files… 2. Read and analyze… 3. Summarize…——仅此三行没有前情提要任务书必须自足落到实处。4.3 真机对照frontmatter 被忽略正文内联展开lab-io-fork 三旋钮全配子 agent 调用。结果frontmatter 被静默忽略正文以普通内容内联展开进调用方对话。执行子 agent 的自证原话能看到调用方完整历史——与官方文档声称的 fork 语义直接矛盾。这一格性质更瘆人失效也是静默的。不报错、不警告你以为派了出去其实没派。跟第 2 课空元数据静默失败是同族病。本机想真派活只剩一条路Agent 工具手工派——机制缺席人肉顶上。判断句立此外派是打包好的活——不依赖对话现场的才派得出去。5、为什么不工作三层模型与本机支持矩阵5.1 三层模型不是坏了是工序没建三份零支持的实验记录摆在一起有个问题我当场就问了出来为什么$ARGUMENTS会有问题话不通顺问题很真调用明明成功特性明明写了中间哪一环没发生把这条路劈成三层就看清了。SKILL.md 是静态文本躺在盘上谁都不碰运行时做三道工序——填槽、预载、派工模型只见运行时递来的成品。$ARGUMENTS 不是坏了是这台机器的 skill 路径没建填槽工序模板进了模型填槽那步从没发生过。三方证据对得上——四个子 agent、斜杠直调、本机运行时自带的诊断文档 diagnosing-skills说的是同一句话不是 bug是未实现。本机也留了替代路调用参数走独立 args 字段直接递给模型功能等价代价是 $1 按位定位这类精细填槽没了。5.2 矩阵与生态盘点越依赖运行时用得越少格子一块块填本机支持矩阵全表如下——实验数据外加我补测的斜杠直调格一台机器证不完我又追了一句那你看看我已装的 skill是不是有这三种接口全机盘点用户级两个目录 42 加 65 个外加插件缓存、捆绑技能全位置 grep 加人工复核数字是一条梯度argument-hint 5 处$ARGUMENTS 占位符只剩 4 个 commands 文件SKILL.md 正文里零!cmd预载 2 个 commandscontext: fork 全机零。越依赖运行时实现装机用得越少——个人 skill 全收敛到静态正文等于整个生态在自发地不赌机制。拿 skills.sh 榜单对一眼find-skills 以 370 万 installs 居头名grill-me 130 万、tdd 100 万、teach 77 万本机这几个标本都排在生态头部头部也这样。盘点路上我自己踩了两个坑各打一个真实错误mention 不等于 use——诊断类 skill 满篇字段名那是说明书在解释字段算数的使用要看真跑起来的那次。复核动作命中行落在文档、说明书类文件里的划掉。grep 误报——npm ERR!、#DIV/0!、Sheet1!A1带着反引号字面量长得跟语法一模一样复核动作命中行逐条人工过目。自动盘点加人工复核缺一不可——第 3 课检查单必须跑全文的盘点版。带走句立此全文的判断都从它长出来官方规范是上限不是保证。6、配置面板总览frontmatter 解剖skill 能力的边界线6.1 字段总数三层口径20、18、6地图从一桩嘀咕开始。我盯着两份标本对不上账tdd 的 frontmatter 只有 name 和 description 两行commit.md 怎么多出一个 allowed-tools有没有一张完整的字段清单有而且不止一张。frontmatter 是 SKILL.md 顶上的 YAML 声明区---必须顶格第一行解析失败 skill 照样加载、字段全空——又一处静默下面的 Markdown 是执行区。字段清单分三层口径Claude Code 官方文档逐字定义 20 个并声明全部可选、仅推荐 descriptioncommands 文件接受同一套字段少 name 和 paths18 个agentskills.io 开放标准只认 6 个name、description、license、compatibility、metadata、allowed-tools。“All fields are optional. Onlydescriptionis recommended so Claude knows when to use the skill.”全部字段可选仅推荐 description。社区流传的14 字段清单普遍混进了 version——version 不是官方字段20 个的表里没有它未识别字段被静默忽略官方惯例是写进 metadata.version。这条规矩有现成标本baoyu 顶格那行version: 1.117.3被静默忽略homepage 和依赖声明躺在 metadata 里——官方示例连版本号都建议写 metadata.version。连带一个教训字段的权威是官方文档的字段表不是编辑器校验器——validator 曾把官方明文支持的 allowed-tools 报成不支持相关 issue 链最老一条以 not planned 关闭v2.1.53 还能复现好在只是编辑器黄线报告者自己说得清楚skill 在 CLI 里完全正常纯属校验器误报。三层口径还有一层实用含义能带走几样。Codex 只读 name 和 description可见性开关得另写在 agents/openai.yaml 的 policy 里子代理是纯 TOML 文件OpenCode 据社区实测非亲测连等价物都没有。6.2 五站时间轴20 个字段不是平面清单是一条时间轴上各站上岗存储站文件本体和 YAML 解析路由站要不要触发——description、when_to_use、paths、disable-model-invocation、user-invocable 在这里拦人UI 站/ 菜单和补全提示——name、argument-hint 只到这里name 兼在 L1 清单——第 1 课讲过的常驻元数据层渲染站正文进场前的填槽和预载——arguments、shellallowed-tools 的票在这里先查一道注入/执行站跑起来之后——context、agent、model、background、hooksallowed-tools 也在这站继续管。五站走完模型拿到的还是那份成品frontmatter 原文从头到尾没进过模型的眼睛。6.3 三种读者三种失效一张配置面板三种读者三种失效给模型读的description写不好不触发给运行时读的context 这类写了机器不支持静默失效给人读的argument-hint、name写不清不会调。模型永远看不到 frontmatter 原文。字段影响它只走三条途径——L1 清单里的 name 加 descriptionwhen_to_use 拼进来合计截断 1536 字符、渲染后的成品正文、运行时行为的改变。模型可见的预算就 1536 个字符其余 17 个字段全在幕后。字段体系值得花三大节原因也在这这些字段直接画出 skill 的能力边界——能被谁触发、在哪跑、能动什么全是 frontmatter 说了算。回头看三张口传参的填槽和预载都发生在渲染站外派改道在注入站让三张口被触发的 description 住在路由站——三口在这张时间轴上各有座位。最后补一句带走判句跨工具分发时最值钱正文是资产集成层是方言——跨工具分发的 skill 只依赖那 6 个标准字段兼容性写 compatibility自定义信息进 metadata扩展字段按 Claude Code 方言用。7、字段逐个过上路由与输入——模型看不见的恰恰决定触不触发20 个字段逐个过。我给自己定的讲法是一问四答——怎么配置、怎么生效、注入时模型看到什么、什么场景用例子的挑选标准是高装机真身优先找不到真身才自己写。name 和 description 第 2 课讲透不重讲回指一句description 是唯一常驻模型的字段官方叫它 “the primary triggering mechanism”写法要 pushy。7.1 argument-hint写给人看的参数提示teach 的真身五行---name:teachdescription:Teach the user a new skill or concept,within this workspace.disable-model-invocation:trueargument-hint:What would you like to learn about?---argument-hint 只在斜杠补全的 UI 里出现告诉敲命令的人这里该带什么参数。四问答完配置一行字符串生效在补全 UI模型看到什么——永远看不到适合参数复杂的 skill给人递提示。全机 argument-hint 一共 5 处例子拿装机榜上最知名的那个teach77 万 installs。成本一行写了对人纯赚。7.2 arguments命名参数的按位映射2.1 露过面的 arguments: 字段正面回答它声明命名参数的名字表按位置映射给alpha、alpha、alpha、beta 这类命名槽。lab-io-args 里我写的就是arguments: alpha beta——调用带两个词第一个填 $alpha第二个填 $beta。没填的命名槽展开成空串兜底三分第三条。本机态度照旧静默忽略。场景是槽位固定的参数模板表单味重的 skill 用它比全量 $ARGUMENTS 规整。7.3 disable-model-invocation一个开关三连效果grill-me 的真身---name:grill-medescription:A relentless interview to sharpen a plan or design.disable-model-invocation:true---正文只有一行“Call the Skill tool with “grilling”.”——模型不能自动触发它想用只能由人从 / 菜单点或者模型读到正文这句手动链再去调 Skill 工具。130 万 installs 的标本亲自示范关闭自动、保留手动的完整姿势。开关拨到 true官方文档写明三件事一起发生这个开关把描述从模型上下文摘除——是隐藏不是降权阻止子代理的 skills 预加载8.4 闭合定时任务不自动跑。用户手动 / 调用永远留门。场景高风险、强流程、贵手续的 skill 收紧触发面——拷问人这种活确实不该被模型自作主张发起。teach 也是同款配置教学这种多会话的活同样不该被顺手发起。它跟 skillOverrides 分工两层这个字段是作者写死的默认skillOverrides 是使用者的运行时覆盖四档——on、name-only、user-invocable-only、off/skills 菜单改落 settings.local.json不管插件 skill。作者定底线用户拿自由。7.4 paths 与 user-invocable两把方向相反的闸paths 限定自动激活的文件条件glob 模式与仓库路径规则的 glob 写法同格式手动调用不受限。拿它压误报数据库迁移 skill 配上paths: [db/migrations/**]一行模型读到闲聊里随口提到 migration 也不会扑上去。注意 commands 文件不支持这个字段。user-invocable 是反向开关方向跟 disable-model-invocation 相反设 false 是只许模型用、从 / 菜单隐藏——纯内部工序型 skill 的收法。顺带一个拼写坑官方文档是 user-invocablevalidator 报错文本里拼成 user-invokable以文档为准。7.5 when_to_usedescription 的加座when_to_use 是 Claude Code 扩展字段内容拼进 description 之后进 L1 清单共享 1536 字符预算。场景description 讲我是什么when_to_use 补什么时候想起我——触发短语、边界声明都有地方搁。路由与输入一族过完数一数argument-hint、arguments、disable-model-invocation、paths、user-invocable、when_to_use——五个模型永远看不见唯一沾边的 when_to_use 也只是拼进清单。路由这一层模型能看到的从来只有 description 那一句。8、字段逐个过下形态、权限、环境、记账——决定 skill 在哪跑、能跑什么8.1 形态四件套context、agent、model、background4.2 拆过 context 和 agent补全成四件套——它们联合生效才构成一次完整派工。model:给派工单独指定模型只影响当前回合不持久化。background:默认 true 转后台但四种情形强制同步-p 或 SDK 模式、禁后台任务的环境变量、同一 skill 重复调用、定时任务。还有两条藏在文档细节里后台 fork 用窄工具集background: false 才给全工具集——这跟 4.2 的缺省全工具分两层后台与否管一层工种缺省管另一层fork 里的文件编辑绕过 checkpoint回退靠 git。同站还有个 effort推理力度 low 到 max 五档——它不属于四件套是给分身单配的力度旋钮覆盖会话默认值重活配 high一句的事不必。8.2 allowed-tools 与 disallowed-tools票和反向票allowed-tools 是权限主角。我当时的追问“skill 里写的agent 调用的时候就不需要再询问了啊”——票确实免了询问的窗但只保一轮直觉缺的正是这一环。机制四个齿轮票是声明运行时按轮登记——skill 被调用的那个回合票面工具免确认免的是运行时问用户那道窗不是 agent 之间讲客气单轮清零官方原话 “Clears when you send your next message”——你下一条消息发出票作废免询问不等于越级——deny 规则、disableSkillShellExecution 这类总开关压在票之上。齿轮咬合着回看第二口渲染期查的也是 allowed-tools 这张票——预载命令逐条对票无票即中止到了执行期同一张票继续管模型自己的工具调用——权限两世界一张票贯穿。票面写法支持Bash(git:*)前缀匹配行内串和 YAML 列表都行。humanizer-zh 的票是一列四项改文风的技能读写加问询正好够用allowed-tools:-Read-Write-Edit-AskUserQuestion反面搭档 disallowed-tools 一句说清生效期间它把工具从池子里拿走下一条消息恢复别的工具还在时它不能拿走 EndConversation——allowed-tools 发证disallowed-tools 收证。残余风险如实留。我盯着这套机制问过“那不就是很危险直接声明 allowed-tools 在 skill 里啊”——是危险票是作者写的装的时候没人替你审。实锤在此官方插件 commit.md 自己就漏了三条票——Context 预载 git diff、git branch、git log票面只写了 git addstatuscommit。按渲染期规则推推论未实测换到会执行预载的机器上这三行就是三处中止点。纪律只有一条装前审票——来源与权限装的时候记。8.3 hooks、shell 与记账四件hooksskill 被调用时注册全会话存续——进阶件知道有这扇门就行。shell给 !cmd和围栏块指定解释器默认 bash可选 powershell。指定了环境里不存在的 shell整次调用直接失败——shell: bash with no bash available fails the invocation.Windows 环境这是必考题环境假设是设计项shell 字段照目标环境定。记账四件——version、metadata、license、compatibility——是另一族运行时谁都不读但决定溯源与可携带。version 前面正过名写 metadata.versionmetadata 是自由 YAML 地皮运行时忽略键名起得独特点防撞车license 和 compatibility 官方口径是 “accepted but unused”前者挂许可证后者 500 字符内写环境要求多数 skill 用不上。learn 考古的彩蛋在这收。我当时盯着 learn 开头那句 teach 约定嘀咕这是原版还是我改写的考古结果上游仓库根本没有 learn本机文件创建和修改时间同一秒两目录同步写入本地生成的。frontmatter 里没有 source 也没有版本来源只能靠文件系统考古。所以记账四件不是仪式版本写 metadata.version出处写 metadata跟装前审票是同一条纪律的两半。8.4 分身定义文件19 个 camelCase 字段的另一族4.2 留的尾巴——自定义工种长什么样——答案在 .claude/agents/*.md。另一族 frontmatter官方文档载约 19 个字段camelCase 命名disallowedTools、permissionMode、memory、isolation跟 skill 的 kebab-case 正好相反两族字段别混算。仅 name 和 description 必填文件正文整体成为分身的系统提示description 供模型派活路由。本机两个真身对照着看最清楚。documents 插件的 visual-judgetools 只给 Read 和 Bash——视觉验收员只许看和跑只读命令想改文件也没锤子feature-dev 插件的 code-architect 配了 10 个工具——全能工种只读任务用它等于白担一份风险。tools 就是分身版 allowed-tools工具箱越小风险面越小。这族里对 skill 体系最重要的字段是 skills:——启动时给分身预载 skill 全文上限 32 个。skill 进子代理的官方通道不止 context: fork 一条7.3 的三连在这闭合的正是阻止预载那件disable-model-invocation: true 的 skill不能被预载。20 个字段到此走完全景收进一张表9、收口三问归位一张选型检查单然后去写你自己的全文的判断收成接口三问输入在调用那一刻就知道吗——参数写模板加兜底句现场事实必须赶在模型开眼前就位吗——预载allowed-tools 逐条配票活打包好了、不依赖对话现场吗——外派形态四件套跑到一半才知道的输入——问用户。第四问没有字段管它管在正文里而且最容易跟第一问混主题宽窄、引不引用这类跑到一半才冒头的偏好参数接不住。baoyu 的输入金字塔一句带过显式指定、EXTEND.md 持久配置、运行时提问、脚本默认值四层递减——问用户是最后手段不是第一反应。字段侧收成一张选型检查单字段画像即物种识别——tdd 两行最小集是判断型commit.md 加权限是现场型teach 加参数提示是传参型deep-research 加形态是外派型baoyu 加元数据是发行型检查单留一份文字版在正文判据不锁在图上纯判断两行最小集带参全量 $ARGUMENTS 写进正文就够一个 frontmatter 字段都不用要按位切槽才补 argument-hint 和 arguments要现场预载加逐条配票派活形态四件套危险操作disable-model-invocation 收紧触发面。轮到你了微实操只有一步拿三问加检查单审你手头那个 skill——先答三问再按答案补 frontmatter 声明和正文兜底句就那句调用消息里尾随的文字就是输入最后本机直调一遍判自己机器走哪条路带参直调让模型逐字引用它看到的正文第一行——看到 Fix GitHub issue 1234你的运行时建了填槽工序看到 Fix GitHub issue $ARGUMENTS没建参数走消息尾随兜底句就是让模型把尾随文字认领为输入的那半边。两种结果都是有效实验。交出来的东西也简单一份三问答卷一条实测过的兜底句。回收开场的底牌三个特性在我这台机器上全军覆没一点不碍事——判断力和可移植的写法已经到手。机制在哪个运行时落地是运行时的事怎么写、怎么审、怎么兜底是这一课交给你的事。带走三样接口三问与三张口调用时已知→参数开眼前就位→预载打包不依赖现场→外派跑到一半才知→问用户参数是你说的话预载是机器的现状外派是打包好的活。官方规范是上限不是保证失效是静默的可移植写法是兜底句加只依赖 6 个标准字段——正文是资产集成层是方言。frontmatter 是能力边界20186 三层口径version 不是字段模型永远看不到 frontmatter 原文字段画像即物种识别选型检查单对着配。临走三问你要写一个 review skill需要模型一睁眼就看到当前分支名和未提交改动且正文禁止它自己跑 git——这归三问里的哪一问frontmatter 动哪个字段正文配哪句话同事发来一个 skill顶格写着 version: 2.0还配了 context: fork在你机器上不派活也不报错——两处各是哪一层的失效分别查哪里你的 skill 会清理构建产物模型一激动自己触发就出事——哪个字段能关掉自动触发、给人留手动门拨下去之后模型那边的 description 去哪了三道都答对了这一课才算真的带走。第一课算上下文的账第二课把 description 修成路由表第三课把正文改成快照第四课把脚本关在门外这一课装上三张口、画全了字段地图。下一课是第 6 课·调试skill 不干活、干错活、干坏活的时候怎么定位问题出在哪一层——第 4 课现搓的 skill-audit 体检器从实验道具转正成为常备工具。共约 7883 字 · 阅读约 20 分钟如果这篇文章对你有帮助欢迎转发给需要的同事和朋友。 
长河君 · 2026/10/17 8:43:57 · 阅读 1.2k 如何写 Skill 第5课，输入输出接口：skill 的三张口
摘要skill 的输入输出靠三张口$ARGUMENTS 传参、!command预载、context: fork 外派每个接口从怎么写一路讲到模型看到的题词。本机实测三个特性全军覆没反而看清机制参数走消息尾随预载与禁工具是配套设计外派是给失忆分身递任务书。字段体系画出能力边界——官方 20 字段、跨平台只认 6 个、version 不在列。可移植写法一句话正文写兜底句别赌机制。脱敏声明这一课没有要打码的东西——teach、commit.md、grill-me、humanizer-zh、baoyu 都是公开标本全文实名三件实验标本 lab-io-argslab-io-shellcmdlab-io-fork 就在项目里可复现我答错的题、我追问的话、我跑的实验全部照实录写。1、开场三个名字一次全军覆没底牌先亮。上一课收尾留的三个名字$ARGUMENTS、!command、context:fork我拿自家机器全测了一遍全军覆没。说好的脚本之后 skill 仅剩的机关上一课收尾的原话四次调用次次成功三个特性零生效。名字我见过不下十遍。官方文档把它们并排放着口气平铺读起来就像进阶语法学了就能用——我也确实这么以为过。测完才翻转过来正是用不了把这三个东西到底是什么逼了出来——怎么个用不了法三个名字各有一套。每个接口的说明书都写在它没发生时的反面。这一课跟着一句需求走每个接口从怎么写一路讲到最终喂给大模型的题词长什么样。三张口讲完再给一张全字段地图——skill 的能力边界就是这些字段画出来的。三张口只是前排地图才是全线。2、第一口·传参$ARGUMENTS从模板到成品题词2.1 流水线五步写、调、触发、处理、题词先把自己当时的理解摆上来。讲到变量那会儿我的理解是我写 skill 本质上是一些上下文注入到 LLM 的如果用变量就可以替换上下文的内容。“这话对了一半——把 skill 当注入的上下文准把变量当替换内容”只看到了现象。剩下那一半才是关键谁在替你替换什么时候替换的答案在五步流水线里。写、调、触发、处理、题词一步一走每步答一句模型此刻看到什么。五步以第一口走全样本后两口结构相同只走差异步。第一步写。正文不是文章是带槽的模板槽有六种写法$ARGUMENTS全量调用时带的全部参数$0、$1按位定位从 0 起数带引号算一个shell 的规矩$ARGUMENTS[N]带索引的切片$alpha命名参数frontmatter 里arguments: alpha beta按位置映射这个 arguments 字段节 7.2 正面讲${ARGUMENTS}花括号形态官方不认写了就是普通文本留它当负对照\$1反斜杠转义想要字面的$1时用。一个最小模板长这样正文就一行Fix GitHub issue $ARGUMENTS.第二步和第三步一起说。调用分两个入口斜杠直调/fix-issue 1234参数就是你跟的那串1234或者自然语言一句帮我修一下 1234 号 issue走 description 领地匹配——第 2 课讲过的路由不重讲。要紧的是触发层三口共用后面两口的触发也走这条路。第四步处理。填槽在这里发生——运行时的字符串工序模型没有出场。宿主拿着1234把 $ARGUMENTS 换掉换完才轮到下一步。我那个理解错就错在这不是模型看到模板再自己替换是模型看到之前替换已经完了。第五步题词。正规运行时上模型拿到的是成品Fix GitHub issue 1234.变量消失了模型不知道存在过 $ARGUMENTS——就像读信的人不知道填过表。2.2 兜底三分、转义与调用细则参数没填的时候三分兜底各管一种正文里一个占位符都没有——参数不丢追加成一段ARGUMENTS: 1234织进正文$1这类定位槽没被填——原样保留$1 就以 $1 的样子见面$alpha这类命名槽没被填——展开成空串无痕消失。第一条最有设计含量没槽也接参数——这是参数独立于占位符的伏笔2.3 的实测会接住它。替换族也不止参数CLAUDESKILLDIR、{CLAUDE_SKILL_DIR}、CLAUDESKILLDIR、{CLAUDE_PROJECT_DIR} 这些环境变量同在渲染期展开第 4 课编址用的 ${CLAUDE_SKILL_DIR} 就出生在渲染这一步。还有两条冷知识skill 可以叠加调用尾随参数传给叠在其中的每一个最多叠五个官方口子本机没验同一 skill 完全相同的重复调用只附加一条说明不重复注入——这条节 3 的渲染产物还会再见。兜底三分我背过动手题上当时空着没答上来。背不住不丢人丢人的是不落成设计兜底有三种走法可移植的写法只有一条——正文永远写兜底句别赌运行时替你想全。判断句立此参数是你说的话——调用那一刻就知道的才叫参数。这句先记住收口要拿它划第四条路的界。2.3 真机对照字面透传与消息尾随文档说有不等于机器上有。实验的账先摆平三个标本、一共四跑——lab-io-args 带参一跑、无参一跑lab-io-shellcmd 一跑lab-io-fork 一跑本节先走 args 的两跑。固定变量项目里建 lab-io-args六形态一字排开加转义负对照全新 general-purpose 子 agent 经 Skill 工具调用带参传 R1 R2 R3要求逐字引用看到的正文。防污染守则立一条子 agent 只许经 Skill 工具拿正文禁止直读标本文件——直读进眼的是盘上原文渲染管道没被验到。结果一行说完六形态全部字面透传$ARGUMENTS 见面还是 $ARGUMENTS连 $1 的反斜杠都原样躺着。无参那一跑兜底三分一条没发生。带参、无参两跑对出来的附加发现更值钱参数根本没走丢——它以消息尾随的方式到达模型从调用消息里读参不依赖正文占位符。我再开新会话补了条路径复测斜杠直调/lab-io-args 甲 乙 丙同样字面透传参数以独立 args 字段传给模型自行解释。两条调用路径一个结果本机支持矩阵全表第 5 节拼齐在这一格上闭合。实验代价记一笔三标本四跑合计约 20.5 万 subagent tokensn4、一台机器只证本机。边界声明补一句这轮测的是 SKILL.md 路径commands 命令文件那条路官方文档同样声明支持本机没测不替它打包票。对照看完接住 2.2 的伏笔参数可达和占位符替换是两件事。前者是本机也有的通用路后者赌运行时建没建填槽工序。可移植的写法由此定型兜底句就一句调用消息里尾随的文字就是输入。这句写在正文末尾模型读到它就把调用消息里尾随的文字认领为输入。3、第二口·预载!command把机器的现状搬进题词第二口管现场事实。模型要知道当前分支、改动清单就得自己跑 git——慢一步而且很多 skill 的指令干脆禁了它动工具。commit-commands 插件的 commit.md 给了标本级解法正文开头一个 Context 段四条预载。3.1 配套咬合预载与禁用工具是一对我第一遍读这份标本注意力全在四条命令上动手批改的时候才发现看漏了主线预载和一条消息、不准用其他工具是配套设计。禁了工具预载就是现场信息唯一的进村路——抽一半塌一半。我当时把这道题答成预载图省事防手写方向就错了这不是优化是依赖。机制五条条条带后果渲染前执行。官方原话“Claude Code runs the command and replaces the line with its output before Claude sees the skill content.”——命令是宿主跑的模型看到时输出已织进正文行首或紧随空白才识别多行预载用 ! 围栏块只扫一遍。预载输出不二次扫描输出里再藏一个 !cmd不会连环爆失败即中止整次调用——例外是搜索比对类命令的 exit 1没找到是合法结果其余要容忍就在命令后补|| true整行写成 - Files: !cat maybe-missing.txt 2/dev/null || true渲染期不弹权限窗。“- Current branch: !git branch --show-current这一行发到模型眼前时已经变成”- Current branch: main——命令没了输出在原位。3.2 权限两世界与本机对照第五条单独说这是我整课错得最狠的一题。动手题问预载命令会要求用户授权吗我答会 ask 要求授权——错。渲染期没有窗。没被 allowed-tools 覆盖、会话又没开自动放行整次调用直接中止执行期才轮到权限窗。两个世界守门的不一样。渲染产物还有三条边界顺路交代成品作为单条消息进对话跨回合驻留完全相同的重复调用只附加一条说明不重复注入——2.2 那条冷知识在这兑现第 3 课说过的压缩回贴每 skill 最多 5000 tokens、总预算 25000出处就是这条渲染规则政策开关 disableSkillShellExecution 拉闸时输出位置替换成 “[shell command execution disabled by policy]”。判断句预载是机器的现状——每次调用都不同、又必须赶在模型开眼前就位的才归它。本机对照lab-io-shellcmd 埋了行内加围栏共四处只读命令echo 和 git 查询。结果字面透传不执行、不拦截、没有政策占位文本。这格塌掉比参数那格重谁照搬 commit.md 的配套设计——正文禁工具、全靠预载——两半一起塌模型要么违令自己跑要么空着现状瞎写。4、第三口·外派context: fork把活派给失忆分身第三口不管内容管场地。大扫描、深研究的活挤在主对话里干中间过程的海量输出全灌进上下文。第 1 课算的那笔账到执行层又翻出来一轮。官方机制叫 context: fork我先借个我熟的类比立住主对话是诊室要听病史、要看病人fork 是检验科拿任务书照 SOP 独立干干完只回一张化验单。抽血的全过程大夫不用看着。4.1 失忆三后果正文必须自足第一遍学到这我是懵的分身凭什么看不见历史后来才回过味来——检验科不认识你是设计不是缺陷。失忆定了三件事看不见对话历史——正文必须是指令自足的任务书背景、输入、预期产出一样不能省中间噪音全留在房间——翻一百个文件的输出不过河回来的只有最终报告默认转后台跑——要当回合等结果background: false。正文必须自足我有实证。第 4 课盲测的 S2 就是一次手工 fork27 行的 SKILL.md执行子 agent 没有任何历史触发、跑脚本、读 rules.md、判四问、出报告全流程照走。任务书写到什么程度分身就干到什么程度。还有官方亲自出面澄清的命名陷阱a skill withcontext: forkdoesn’t run in a fork of the current conversation, which would hand the subagent everything you’ve discussed so far.context: fork 不在当前对话的分叉里跑——那会把此前聊过的一切都交给分身。名字里的 fork 有误导它不分叉当前对话是干净的隔离上下文。真要带历史分身官方处方是fork 对话那个操作不是这个字段。依赖历史的任务派给 context: fork等于把病历扣在诊室回头怪检验科不认识病人。4.2 两旋钮与工种缺省就是全工具我当时追问的是context: fork 是不是还有别的 context: xxxagent: Explore 是不是也有别的 agent: xxx分身要预先定义吗答案两句话context 的文档取值只有一个 forkagent 是旋钮管工种——Explore 只读检索、Plan 只读规划、general-purpose 全工具不写就缺省 general-purpose全工具。自定义工种也有放 .claude/agents/ 里8.4 拆。全工具三个字要停一下。第 4 课坑节里自作主张改了 tdd description 的那个测试代理就是全工具分身闯的祸——分身缺省自带全套锤子。派活前先挑工种只查不写的用 Explore要改文件才上 general-purpose别拿缺省偷懒。model:给分身单独配模型background:前面说过默认转后台。这组合不是生僻玩法官方自家 /code-review 从 v2.1.218 起就是 forked subagent 方式跑的官方 deep-research 示例更把三口拧进同一行 frontmattercontext: fork 派出去agent: Explore 限定只读正文 $ARGUMENTS 接研究主题。传参和外派在同一份标本里会师。分身收到的题词就是Research 参数 thoroughly: 1. Find relevant files… 2. Read and analyze… 3. Summarize…——仅此三行没有前情提要任务书必须自足落到实处。4.3 真机对照frontmatter 被忽略正文内联展开lab-io-fork 三旋钮全配子 agent 调用。结果frontmatter 被静默忽略正文以普通内容内联展开进调用方对话。执行子 agent 的自证原话能看到调用方完整历史——与官方文档声称的 fork 语义直接矛盾。这一格性质更瘆人失效也是静默的。不报错、不警告你以为派了出去其实没派。跟第 2 课空元数据静默失败是同族病。本机想真派活只剩一条路Agent 工具手工派——机制缺席人肉顶上。判断句立此外派是打包好的活——不依赖对话现场的才派得出去。5、为什么不工作三层模型与本机支持矩阵5.1 三层模型不是坏了是工序没建三份零支持的实验记录摆在一起有个问题我当场就问了出来为什么$ARGUMENTS会有问题话不通顺问题很真调用明明成功特性明明写了中间哪一环没发生把这条路劈成三层就看清了。SKILL.md 是静态文本躺在盘上谁都不碰运行时做三道工序——填槽、预载、派工模型只见运行时递来的成品。$ARGUMENTS 不是坏了是这台机器的 skill 路径没建填槽工序模板进了模型填槽那步从没发生过。三方证据对得上——四个子 agent、斜杠直调、本机运行时自带的诊断文档 diagnosing-skills说的是同一句话不是 bug是未实现。本机也留了替代路调用参数走独立 args 字段直接递给模型功能等价代价是 $1 按位定位这类精细填槽没了。5.2 矩阵与生态盘点越依赖运行时用得越少格子一块块填本机支持矩阵全表如下——实验数据外加我补测的斜杠直调格一台机器证不完我又追了一句那你看看我已装的 skill是不是有这三种接口全机盘点用户级两个目录 42 加 65 个外加插件缓存、捆绑技能全位置 grep 加人工复核数字是一条梯度argument-hint 5 处$ARGUMENTS 占位符只剩 4 个 commands 文件SKILL.md 正文里零!cmd预载 2 个 commandscontext: fork 全机零。越依赖运行时实现装机用得越少——个人 skill 全收敛到静态正文等于整个生态在自发地不赌机制。拿 skills.sh 榜单对一眼find-skills 以 370 万 installs 居头名grill-me 130 万、tdd 100 万、teach 77 万本机这几个标本都排在生态头部头部也这样。盘点路上我自己踩了两个坑各打一个真实错误mention 不等于 use——诊断类 skill 满篇字段名那是说明书在解释字段算数的使用要看真跑起来的那次。复核动作命中行落在文档、说明书类文件里的划掉。grep 误报——npm ERR!、#DIV/0!、Sheet1!A1带着反引号字面量长得跟语法一模一样复核动作命中行逐条人工过目。自动盘点加人工复核缺一不可——第 3 课检查单必须跑全文的盘点版。带走句立此全文的判断都从它长出来官方规范是上限不是保证。6、配置面板总览frontmatter 解剖skill 能力的边界线6.1 字段总数三层口径20、18、6地图从一桩嘀咕开始。我盯着两份标本对不上账tdd 的 frontmatter 只有 name 和 description 两行commit.md 怎么多出一个 allowed-tools有没有一张完整的字段清单有而且不止一张。frontmatter 是 SKILL.md 顶上的 YAML 声明区---必须顶格第一行解析失败 skill 照样加载、字段全空——又一处静默下面的 Markdown 是执行区。字段清单分三层口径Claude Code 官方文档逐字定义 20 个并声明全部可选、仅推荐 descriptioncommands 文件接受同一套字段少 name 和 paths18 个agentskills.io 开放标准只认 6 个name、description、license、compatibility、metadata、allowed-tools。“All fields are optional. Onlydescriptionis recommended so Claude knows when to use the skill.”全部字段可选仅推荐 description。社区流传的14 字段清单普遍混进了 version——version 不是官方字段20 个的表里没有它未识别字段被静默忽略官方惯例是写进 metadata.version。这条规矩有现成标本baoyu 顶格那行version: 1.117.3被静默忽略homepage 和依赖声明躺在 metadata 里——官方示例连版本号都建议写 metadata.version。连带一个教训字段的权威是官方文档的字段表不是编辑器校验器——validator 曾把官方明文支持的 allowed-tools 报成不支持相关 issue 链最老一条以 not planned 关闭v2.1.53 还能复现好在只是编辑器黄线报告者自己说得清楚skill 在 CLI 里完全正常纯属校验器误报。三层口径还有一层实用含义能带走几样。Codex 只读 name 和 description可见性开关得另写在 agents/openai.yaml 的 policy 里子代理是纯 TOML 文件OpenCode 据社区实测非亲测连等价物都没有。6.2 五站时间轴20 个字段不是平面清单是一条时间轴上各站上岗存储站文件本体和 YAML 解析路由站要不要触发——description、when_to_use、paths、disable-model-invocation、user-invocable 在这里拦人UI 站/ 菜单和补全提示——name、argument-hint 只到这里name 兼在 L1 清单——第 1 课讲过的常驻元数据层渲染站正文进场前的填槽和预载——arguments、shellallowed-tools 的票在这里先查一道注入/执行站跑起来之后——context、agent、model、background、hooksallowed-tools 也在这站继续管。五站走完模型拿到的还是那份成品frontmatter 原文从头到尾没进过模型的眼睛。6.3 三种读者三种失效一张配置面板三种读者三种失效给模型读的description写不好不触发给运行时读的context 这类写了机器不支持静默失效给人读的argument-hint、name写不清不会调。模型永远看不到 frontmatter 原文。字段影响它只走三条途径——L1 清单里的 name 加 descriptionwhen_to_use 拼进来合计截断 1536 字符、渲染后的成品正文、运行时行为的改变。模型可见的预算就 1536 个字符其余 17 个字段全在幕后。字段体系值得花三大节原因也在这这些字段直接画出 skill 的能力边界——能被谁触发、在哪跑、能动什么全是 frontmatter 说了算。回头看三张口传参的填槽和预载都发生在渲染站外派改道在注入站让三张口被触发的 description 住在路由站——三口在这张时间轴上各有座位。最后补一句带走判句跨工具分发时最值钱正文是资产集成层是方言——跨工具分发的 skill 只依赖那 6 个标准字段兼容性写 compatibility自定义信息进 metadata扩展字段按 Claude Code 方言用。7、字段逐个过上路由与输入——模型看不见的恰恰决定触不触发20 个字段逐个过。我给自己定的讲法是一问四答——怎么配置、怎么生效、注入时模型看到什么、什么场景用例子的挑选标准是高装机真身优先找不到真身才自己写。name 和 description 第 2 课讲透不重讲回指一句description 是唯一常驻模型的字段官方叫它 “the primary triggering mechanism”写法要 pushy。7.1 argument-hint写给人看的参数提示teach 的真身五行---name:teachdescription:Teach the user a new skill or concept,within this workspace.disable-model-invocation:trueargument-hint:What would you like to learn about?---argument-hint 只在斜杠补全的 UI 里出现告诉敲命令的人这里该带什么参数。四问答完配置一行字符串生效在补全 UI模型看到什么——永远看不到适合参数复杂的 skill给人递提示。全机 argument-hint 一共 5 处例子拿装机榜上最知名的那个teach77 万 installs。成本一行写了对人纯赚。7.2 arguments命名参数的按位映射2.1 露过面的 arguments: 字段正面回答它声明命名参数的名字表按位置映射给alpha、alpha、alpha、beta 这类命名槽。lab-io-args 里我写的就是arguments: alpha beta——调用带两个词第一个填 $alpha第二个填 $beta。没填的命名槽展开成空串兜底三分第三条。本机态度照旧静默忽略。场景是槽位固定的参数模板表单味重的 skill 用它比全量 $ARGUMENTS 规整。7.3 disable-model-invocation一个开关三连效果grill-me 的真身---name:grill-medescription:A relentless interview to sharpen a plan or design.disable-model-invocation:true---正文只有一行“Call the Skill tool with “grilling”.”——模型不能自动触发它想用只能由人从 / 菜单点或者模型读到正文这句手动链再去调 Skill 工具。130 万 installs 的标本亲自示范关闭自动、保留手动的完整姿势。开关拨到 true官方文档写明三件事一起发生这个开关把描述从模型上下文摘除——是隐藏不是降权阻止子代理的 skills 预加载8.4 闭合定时任务不自动跑。用户手动 / 调用永远留门。场景高风险、强流程、贵手续的 skill 收紧触发面——拷问人这种活确实不该被模型自作主张发起。teach 也是同款配置教学这种多会话的活同样不该被顺手发起。它跟 skillOverrides 分工两层这个字段是作者写死的默认skillOverrides 是使用者的运行时覆盖四档——on、name-only、user-invocable-only、off/skills 菜单改落 settings.local.json不管插件 skill。作者定底线用户拿自由。7.4 paths 与 user-invocable两把方向相反的闸paths 限定自动激活的文件条件glob 模式与仓库路径规则的 glob 写法同格式手动调用不受限。拿它压误报数据库迁移 skill 配上paths: [db/migrations/**]一行模型读到闲聊里随口提到 migration 也不会扑上去。注意 commands 文件不支持这个字段。user-invocable 是反向开关方向跟 disable-model-invocation 相反设 false 是只许模型用、从 / 菜单隐藏——纯内部工序型 skill 的收法。顺带一个拼写坑官方文档是 user-invocablevalidator 报错文本里拼成 user-invokable以文档为准。7.5 when_to_usedescription 的加座when_to_use 是 Claude Code 扩展字段内容拼进 description 之后进 L1 清单共享 1536 字符预算。场景description 讲我是什么when_to_use 补什么时候想起我——触发短语、边界声明都有地方搁。路由与输入一族过完数一数argument-hint、arguments、disable-model-invocation、paths、user-invocable、when_to_use——五个模型永远看不见唯一沾边的 when_to_use 也只是拼进清单。路由这一层模型能看到的从来只有 description 那一句。8、字段逐个过下形态、权限、环境、记账——决定 skill 在哪跑、能跑什么8.1 形态四件套context、agent、model、background4.2 拆过 context 和 agent补全成四件套——它们联合生效才构成一次完整派工。model:给派工单独指定模型只影响当前回合不持久化。background:默认 true 转后台但四种情形强制同步-p 或 SDK 模式、禁后台任务的环境变量、同一 skill 重复调用、定时任务。还有两条藏在文档细节里后台 fork 用窄工具集background: false 才给全工具集——这跟 4.2 的缺省全工具分两层后台与否管一层工种缺省管另一层fork 里的文件编辑绕过 checkpoint回退靠 git。同站还有个 effort推理力度 low 到 max 五档——它不属于四件套是给分身单配的力度旋钮覆盖会话默认值重活配 high一句的事不必。8.2 allowed-tools 与 disallowed-tools票和反向票allowed-tools 是权限主角。我当时的追问“skill 里写的agent 调用的时候就不需要再询问了啊”——票确实免了询问的窗但只保一轮直觉缺的正是这一环。机制四个齿轮票是声明运行时按轮登记——skill 被调用的那个回合票面工具免确认免的是运行时问用户那道窗不是 agent 之间讲客气单轮清零官方原话 “Clears when you send your next message”——你下一条消息发出票作废免询问不等于越级——deny 规则、disableSkillShellExecution 这类总开关压在票之上。齿轮咬合着回看第二口渲染期查的也是 allowed-tools 这张票——预载命令逐条对票无票即中止到了执行期同一张票继续管模型自己的工具调用——权限两世界一张票贯穿。票面写法支持Bash(git:*)前缀匹配行内串和 YAML 列表都行。humanizer-zh 的票是一列四项改文风的技能读写加问询正好够用allowed-tools:-Read-Write-Edit-AskUserQuestion反面搭档 disallowed-tools 一句说清生效期间它把工具从池子里拿走下一条消息恢复别的工具还在时它不能拿走 EndConversation——allowed-tools 发证disallowed-tools 收证。残余风险如实留。我盯着这套机制问过“那不就是很危险直接声明 allowed-tools 在 skill 里啊”——是危险票是作者写的装的时候没人替你审。实锤在此官方插件 commit.md 自己就漏了三条票——Context 预载 git diff、git branch、git log票面只写了 git addstatuscommit。按渲染期规则推推论未实测换到会执行预载的机器上这三行就是三处中止点。纪律只有一条装前审票——来源与权限装的时候记。8.3 hooks、shell 与记账四件hooksskill 被调用时注册全会话存续——进阶件知道有这扇门就行。shell给 !cmd和围栏块指定解释器默认 bash可选 powershell。指定了环境里不存在的 shell整次调用直接失败——shell: bash with no bash available fails the invocation.Windows 环境这是必考题环境假设是设计项shell 字段照目标环境定。记账四件——version、metadata、license、compatibility——是另一族运行时谁都不读但决定溯源与可携带。version 前面正过名写 metadata.versionmetadata 是自由 YAML 地皮运行时忽略键名起得独特点防撞车license 和 compatibility 官方口径是 “accepted but unused”前者挂许可证后者 500 字符内写环境要求多数 skill 用不上。learn 考古的彩蛋在这收。我当时盯着 learn 开头那句 teach 约定嘀咕这是原版还是我改写的考古结果上游仓库根本没有 learn本机文件创建和修改时间同一秒两目录同步写入本地生成的。frontmatter 里没有 source 也没有版本来源只能靠文件系统考古。所以记账四件不是仪式版本写 metadata.version出处写 metadata跟装前审票是同一条纪律的两半。8.4 分身定义文件19 个 camelCase 字段的另一族4.2 留的尾巴——自定义工种长什么样——答案在 .claude/agents/*.md。另一族 frontmatter官方文档载约 19 个字段camelCase 命名disallowedTools、permissionMode、memory、isolation跟 skill 的 kebab-case 正好相反两族字段别混算。仅 name 和 description 必填文件正文整体成为分身的系统提示description 供模型派活路由。本机两个真身对照着看最清楚。documents 插件的 visual-judgetools 只给 Read 和 Bash——视觉验收员只许看和跑只读命令想改文件也没锤子feature-dev 插件的 code-architect 配了 10 个工具——全能工种只读任务用它等于白担一份风险。tools 就是分身版 allowed-tools工具箱越小风险面越小。这族里对 skill 体系最重要的字段是 skills:——启动时给分身预载 skill 全文上限 32 个。skill 进子代理的官方通道不止 context: fork 一条7.3 的三连在这闭合的正是阻止预载那件disable-model-invocation: true 的 skill不能被预载。20 个字段到此走完全景收进一张表9、收口三问归位一张选型检查单然后去写你自己的全文的判断收成接口三问输入在调用那一刻就知道吗——参数写模板加兜底句现场事实必须赶在模型开眼前就位吗——预载allowed-tools 逐条配票活打包好了、不依赖对话现场吗——外派形态四件套跑到一半才知道的输入——问用户。第四问没有字段管它管在正文里而且最容易跟第一问混主题宽窄、引不引用这类跑到一半才冒头的偏好参数接不住。baoyu 的输入金字塔一句带过显式指定、EXTEND.md 持久配置、运行时提问、脚本默认值四层递减——问用户是最后手段不是第一反应。字段侧收成一张选型检查单字段画像即物种识别——tdd 两行最小集是判断型commit.md 加权限是现场型teach 加参数提示是传参型deep-research 加形态是外派型baoyu 加元数据是发行型检查单留一份文字版在正文判据不锁在图上纯判断两行最小集带参全量 $ARGUMENTS 写进正文就够一个 frontmatter 字段都不用要按位切槽才补 argument-hint 和 arguments要现场预载加逐条配票派活形态四件套危险操作disable-model-invocation 收紧触发面。轮到你了微实操只有一步拿三问加检查单审你手头那个 skill——先答三问再按答案补 frontmatter 声明和正文兜底句就那句调用消息里尾随的文字就是输入最后本机直调一遍判自己机器走哪条路带参直调让模型逐字引用它看到的正文第一行——看到 Fix GitHub issue 1234你的运行时建了填槽工序看到 Fix GitHub issue $ARGUMENTS没建参数走消息尾随兜底句就是让模型把尾随文字认领为输入的那半边。两种结果都是有效实验。交出来的东西也简单一份三问答卷一条实测过的兜底句。回收开场的底牌三个特性在我这台机器上全军覆没一点不碍事——判断力和可移植的写法已经到手。机制在哪个运行时落地是运行时的事怎么写、怎么审、怎么兜底是这一课交给你的事。带走三样接口三问与三张口调用时已知→参数开眼前就位→预载打包不依赖现场→外派跑到一半才知→问用户参数是你说的话预载是机器的现状外派是打包好的活。官方规范是上限不是保证失效是静默的可移植写法是兜底句加只依赖 6 个标准字段——正文是资产集成层是方言。frontmatter 是能力边界20186 三层口径version 不是字段模型永远看不到 frontmatter 原文字段画像即物种识别选型检查单对着配。临走三问你要写一个 review skill需要模型一睁眼就看到当前分支名和未提交改动且正文禁止它自己跑 git——这归三问里的哪一问frontmatter 动哪个字段正文配哪句话同事发来一个 skill顶格写着 version: 2.0还配了 context: fork在你机器上不派活也不报错——两处各是哪一层的失效分别查哪里你的 skill 会清理构建产物模型一激动自己触发就出事——哪个字段能关掉自动触发、给人留手动门拨下去之后模型那边的 description 去哪了三道都答对了这一课才算真的带走。第一课算上下文的账第二课把 description 修成路由表第三课把正文改成快照第四课把脚本关在门外这一课装上三张口、画全了字段地图。下一课是第 6 课·调试skill 不干活、干错活、干坏活的时候怎么定位问题出在哪一层——第 4 课现搓的 skill-audit 体检器从实验道具转正成为常备工具。共约 7883 字 · 阅读约 20 分钟如果这篇文章对你有帮助欢迎转发给需要的同事和朋友。