摘要:装了上百个 skill 之后,病不长在单个技能身上,长在"之间":领地之间有叠有缝,名字之间按座次裁决,开关分作者、用户、管理端三层,目录里的条目污染账本。这篇用我自己三个库的审计账当教材,把四种之间病的机理、官方座次表、四态开关和卫生四条一次讲透,文末附一份十分钟的个人库对账清单。
老规矩先交底:文里的机制、数字、目录结构全部为真,涉及身份的细节一律化名。
1、你有几个 skill?------三个对不上的数
备这节课的时候,我给自己出了道送分题:你有几个 skill?本以为张口就来,实际我答不上来。
我盘了三个个人级目录,得到三个数(2026-10-16 当日实测):
- ~/.zcode/skills 下 43 条
- ~/.agents/skills 下 71 条
- ~/.claude/skills 下 10 条
三个数,没有一个能回答那个问题。
先说 43:全是软链,本体在 .agents,于是同一个技能在 /skills 列表里占两行,ask-matt 就注册了两回。再说 10:~/.claude 这个目录,我现在用的 host 根本不读,gitnexus 七条、baoyu,再加两个零散小件,整库全暗,装了等于没装。
71 里也不干净:8 个 zip 备份加 1 个 _archive 混在扫描路径里,另有 19 个技能只在这一个库有一份(比对口径:目录名归一化)。同一技能最多三处落盘,这就是我库的真面目。
对账还盘出一条更气人的。官方文档说,软链指向同一目标只装载一次,原话是 "loads the skill once even if several locations point at the same target"(官方 skills 文档,2026-10-16 现查)。可我的列表就是双行,这条去重没跨 .zcode 和 .agents 两个目录生效。官方规范是上限,不是保证,这个系列里它不是第一次违约。诚实交代:双行是不是双倍烧描述 token,我没测出来,可观测的事实只有列表条目本身。
学员那边,账同样对不上。动手题里我问他,zip 会被装载吗、你的 skill 为什么数不清,他先回了句"啥意思",我把题目掰开,问格式怎么统一、往哪挪,处方给得倒干脆:"是的。挪出去。"再追问为什么数不清,他给了句大实话:"skill 就数不清了。"处方对,病根说不上来。这不怪他,当时我也说不清。
账面和实况对不上的那一刻,光会写描述、改正文就不够了,还得有另一门手艺。这篇回答的就是:单条描述都及格,为什么几十个 skill 凑到一张桌上还是出事?
2、先说清:这不是讲扫描和触发的那篇
上一课收尾,有学员把问题递了过来:
所以这一课,主要学的什么?skill 怎么被扫描到?以及怎么自动触发调用吗?
(本会话学员原话,2026-10-16 当堂提问)
我的回答是"不完全是"。扫描,第 2 课讲过,装载器怎么把目录翻成菜单;触发,第 6 课也讲过,三道关:单条描述超 1024 整个技能丢弃,拼接超 1536 截断,到菜单那层约 250 字符再截一道,好在只影响展示不影响装载。这两套都是旧知识,这节课要还讲它们,就白开了。
这位学员其实替所有读者问了同一个问题:新东西到底是什么?我的答案是一个词:之间。
第一课到第七课,全是"治一个"的手艺:
- 一条描述怎么写
- 一个字段什么意思
- 一个技能怎么活过预算。
可你回头看节 1 那笔账,43、71、10 对不上,没有一条病长在"一个"身上。双注册,就是节 1 那个"同一个技能占两行",是两个目录之间的事;整库全暗,是 host 和目录之间的事;zip 躺在扫描路径里,是文件和装载器之间的事。单条写得对,只保证一个 skill 上桌;这桌饭打不打架,要看菜和菜之间。
我把同桌之后的病归成四类,每类认领一个"之间":
- 领地之间的叠和缝
- 名字之间的座次
- 开关之间的三层角色
- 条目之间的卫生。
四套旧机制都碰过:触发和装载讲透了,名字解析和开关只擦过边。新病灶全长在"之间"。下面这张图就是全文目录,后面四节一节一种病,这笔账最后一节结。
3、领地之间:一个活两个抢,一个活没人接
多 skill 的触发质量,不取决于单条描述写得多好,取决于领地之间有没有叠、有没有缝。
3.1 两种病,两个标本
四病地图的第一支,病只有两种,我机器上各躺着一个标本。叠,一个活两个抢:第 2 课的四主角实验里,docx 和 pdf 在"把这份 Word 转成 PDF"上真实争抢过,两条描述都够得着这个活。缝,该接的没人接:pr 的描述短到只剩六个词,连"写 PR 描述"这层意思都明明白白写在里面,第 2 课收作业时它真漏报过一次。叠是浪费,缝是失守,都不用构造。
3.2 相邻不是冲突:动词分界
正面标本是 Matt Pocock 的三兄弟,pr、tdd、code-review,就装在我机器上(一手:本机在装原文)。两条描述对光看:
pr 那条我逐个数过:Use when writing a PR body.,六个词。code-review 那条是一整串,开头就是 "Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes",往后还挂着 Use when 清单,越写越具体。两条都含 PR,按"撞词就打架"的直觉它们该抢,实际各干各的:一个管写,一个管审,动词把领地切开了。
你问"帮我写 PR 描述",意图落在写的那侧;问"审一下这个分支",落在审的那侧。tdd 更狠,三个触发词 test-first、red-green-refactor、integration tests 直接钉死领地。三条单看质量参差,拼在一起无缝无叠:领地相邻,不等于冲突。
3.3 分工说明写正文治不了
docx 和 pdf 打架那阵,我动过一个念头:在两个 SKILL.md 的正文里各写一段"我们俩怎么分工"。没用,而且错得有内容。触发决策发生在正文注入之前:模型挑人的那一刻,视野里只有 frontmatter 菜单里那几行描述(L1),正文(L2)一个字都还没进来。你在 L2 里写什么分工,挑人的人根本看不见。治触发的东西只能写进 L1:两条描述各写正例,再各补一句负边界,形如"已有 X 处理 Y 时不用我"。
3.4 社区管这叫 precision 和 recall
这套叠缝说法有个国际版。agentic-patterns 上有一篇把技能触发当分类问题讲的文章(检索二手,2026-10-16 抓取),叠被叫作 precision 病,原话 "The skill loads on prompts it does not own.";缝是 recall 病,该装不装,never loads。中文的叠缝,和他的 precision/recall 一一对得上。
那位作者还给了两样我没给的东西。一是量:他测过一个路由型技能,描述把四个专家的活全揽了,在自己该接的 2 条之外误触了归专家的 3 条,precision 只有 0.40,原话是 "Broad 'router' descriptions absorb their own specialists."。先交代口径:0.40 是他自家评测环境的实验值,不是统计量,看方向够用。二是负边界为什么要写,他一句话顶我十句:
Include the negative region --- it is most of real traffic.
(agentic-patterns.com《Skill Activation as a Precision/Recall Measurement》,2026-10-16 检索,英文原句照抄)
划界的正面示范在 Matt Pocock 手里。他的 ask-matt 是个路由器,只荐不执行;每对兄弟技能的边界,他写的都是"一条具体判据":"The line between them, and it is usually one concrete test rather than a matter of taste."(aihero.dev 作者自述,2026-10-16 检索)判据,不是口味。这正好接回 3.3:判据写进描述的负边界,写别的层都没用。
4、名字之间:重名不报错,按座次裁决
重名不报错,也不走"谁具体谁赢",它走一张固定座次表:企业 > 个人 > 项目;治遮蔽的唯一真药是改名。
4.1 七行座次表
地图第二支,管名字。先交代直觉错在哪。配置体系里我们的肌肉记忆是"谁具体谁赢":项目配置盖个人配置,近的盖远的,CLAUDE.md 就这么干。skill 的名字解析不走这条。官方文档 "Resolve skills that share a name" 一节我 2026-10-16 逐字核过:"Enterprise over personal, and personal over project"。企业压个人,个人压项目,跟谁具体没关系;文档自带的例子就是 deploy,企业下发的 deploy 压你个人的,你个人的压项目里的。
整张座次表一共七行。你的技能压捆绑技能和内置命令,算一行;但压不过它们的别名,又是一行;技能压 .claude/commands 文件;项目目录嵌套时双载,子目录那个要用 /apps/web:deploy 这样的限定名调;插件技能以全名双载,互不打架;claude.ai 同步技能撞了短名,只认全名。
加上企业压个人压项目那条主线,恰好七行,全画在下面这张表里,行文不铺开。座次是死的,你唯一能动的变量,就是名字本身。
4.2 三个咬人的冷知识
第一个,肉眼查重不算数。官方的撞名判定忽略大小写、空格和不可见字符,"Code Review" 和 code-review 就是重名。这条引的是官方规则,本机没复现过,口径先摆在这。自查重名,得先归一化再比。
第二个,有两个名字你永远拿不到:保留名 synced(任意大小写都算)和 anthropic-skills 前缀。撞上了不报错,技能永不加载,静默消失。你以为是手滑,其实是踩了保留字。
第三个,"压过内置命令"带但书。4.1 那行但书,值得单独拎出来:你的同名技能确实压捆绑技能和内置命令,但压不过它们的别名,命令本身让路,别名不让。
4.3 社区回声与两处裂缝
这张表,社区有买账的。hussainweb 在 TIL 里复述的口诀和官方一个方向:
Enterprise: These are managed settings deployed organization-wide. They always win
(hussainweb.me TIL《Claude Code Skill Precedence》,2026-10-16 检索,英文原句照抄)
裂缝也有两处,性质不一样。第一处是实测打脸:anthropics/claude-code 的 issue #26598,楼主在 v2.1.45 上实测,同名自定义技能并没有遮蔽内置命令,补全面板里两个都在;issue 后来被 bot 以长期无活动关闭,没有修复结论。文档承诺的座次,那一版装载器没兑现。引这条必须带版本语境,最新版行为我没验证。
第二处是以讹传讹:dev.to 上 max_quimby 的《Write Skills That Load》白纸黑字写内置命令 "will shadow your skill",方向整个反了,官方明明是你的技能压内置命令。座次这种"文档一句话、验证要装环境"的知识,转两道手就反了。
这类担忧不是极客的矫情。Reddit 的 r/ClaudeAI 上有普通用户问:Can skills cancel each other out, or override each other (e.g., writing or research skills)? 这句朴素的话,恰好就是节 3 和本节的民间版(2026-10-16 检索)。
4.4 近亲:双注册不是遮蔽
最后辨析一个容易混的。我的技能列表里 ask-matt 出现两行,这不是遮蔽,是双注册:同一个技能被两个目录同时指到。节 1 引过官方那条软链去重承诺,它在我机器上没跨目录生效,.zcode 和 .agents 各算各的,列表就是双行。节 1 说过,上限不是保证。
插件的命名空间是另一个近亲。我的列表里有一行 "documents:docx (also loadable as docx)":插件技能注册全名 documents:docx,短名 docx 没人占用时可以裸用;哪天我自己建个 docx,短名归我,插件退回全名。claude.ai 的同步技能没这待遇,撞了短名就只认全名。同样是外来户,座次不一样。
5、开关之间:作者管默认,用户管覆盖
开关分三层,各管一段:作者开关管默认,用户开关管覆盖,管理端只收不放;插件技能不受用户开关管。
5.1 作者的两个镜像字段
地图第三支,管开关。作者侧有两个镜像字段(官方 "Control who can invoke a skill" 一节,2026-10-16 现查)。
disable-model-invocation: true 挡模型不挡人,官方列了六个效应:
- 描述移出上下文
- 子代理预载不带它
- 定时任务不跑
- 模型想绕道复现会被拦
- commit 前的自动运行解除
- 而你在菜单里敲 /名字 照样跑。
user-invocable: false 反过来,挡人不挡模型:从菜单里藏起来,描述还在,模型照常自主触发。两个字段各挡一边,写串了就挡错对象。
我机器上有五处在用 disable-model-invocation:grill-me、ask-matt、implement、handoff、claude-handoff,全是"只许人点名"的路数(本机实测,第 5 课解剖字段时数过)。
5.2 用户的四态开关
用户侧的开关叫 skillOverrides,官方定的形态是一个 map:键是技能名,值是四态之一,没配置一律视为 on。四态各自拦住谁、放过谁,先用文字摆一遍:on 全量可见;name-only 只给模型留名字,描述收走;user-invocable-only 菜单标 user-only,模型哑、人可调;off 全隐,连菜单都不进。/skills 菜单里选中技能按 Space 循环四态,改动写进 settings.local.json------拨的时候盯一眼菜单上的状态名,别拨过头,off 一拨,菜单里连它自己都不显示了。细表如下:
两条例外要单记。一,管理端(managed settings)能匹配别名,但只能收紧不能放松。thejavaguy 把这层机理讲得最直白:"skillOverrides obeys the four-scope layering: managed > local > project > user, and a stronger scope wins."(thejavaguy.org,2026-10-16 检索;他的四作用域是个人归纳,措辞以官方为准)同一个开关写进不同 settings 文件,强的作用域赢,这就是"只收不放"的机理。二,插件技能不受 skillOverrides 管,想动插件,去插件启停。
5.3 name-only 治不了抢戏
最常见的误用:嫌一个技能抢戏,把它设成 name-only。没用。name-only 态下名字还在上下文里,理论上仍可被调用,只是失去了领地描述,触发从"看菜谱"退化成"猜菜名"。
抢戏的根子是描述写得太宽,你把描述收走,模型只剩一个名字,反而更瞎。这个态的正确读法是"模型哑、用户仍调",quiz 考这题,学员一次答对。正解两条:用户侧设 user-invocable-only(菜单标 user-only),或者回作者侧把 disable-model-invocation 老实加上。
5.4 别人交过的作业:15 天从 16 到 48
这套开关不是我空想出来的,真有人当日常工具在使。dev.to 上 shimo4228 记了他 15 天的账(检索二手,2026-02 发文,2026-07 编辑):
Over 15 days with ECC, my skills grew from 16 to 48.
(shimo4228《15 Days of Skill Sprawl in Claude Code》,dev.to,2026-10-16 检索,英文原句照抄;ECC 为原文缩写,未展开)
15 天里他审计了三轮,触发线定得很硬:任何单层超过 10 个技能就审。审完的动作全走作者开关,19 个没用过的技能批量加上 disable-model-invocation: true。文末那句我认为最值钱:"The 'number' of skills has no value." 技能数量本身没有价值。他还提醒,技能太多时列表会被悄悄截断:"More is not better." 截断预算具体是多少,检索到的几个源报过三种数:8,000、15,000、16,000 字符,互相打架,随版本漂移,我不给准数。
对照我自己:手头的四个 settings 文件(用户级、项目级、本地覆盖)翻遍,skillOverrides 一处都没有。社区已经有人把开关用成日常,我机器上一次治理动作都没发生过。这是我盘点完最臊的一行账。
6、条目之间:zip 不装载,但账本记得它
装载器的扫描单元是"目录下的 SKILL.md",zip 是单个文件,不解压,里面的技能对装载器不存在;但 zip 躺在扫描路径里,账本记得它。账实相符,是一切治理的起点。
6.1 zip 为什么不装载
地图最后一支,管条目。动手题第三问我问学员:zip 里的 skill 会被装载吗?他答:"不会,因为文件名不规范。"结论对了,机制错了,批改时我把这题改成了一道填空题,他自己把空填上了。
机理一句话:装载器扫的是"目录下的 SKILL.md",zip 是一个文件,运行时不解压,里面的 SKILL.md 根本不在文件系统路径上。装载器看不见的不是"坏文件",是"不存在的文件"。所以改名救不了 zip:文件名规范不规范,和装载判定完全无关。
这个归因偏差我单独记了一笔:面对"没装载",人的第一反应是"东西坏了",很难想到"东西不在场"。同一组动手题里还有同款:一道题他先答"不知道为什么",压根没上桌;另一道结论对了(不可见),理由却是"应该是不会扫那个目录",用的是"应该",而证据就在他自己的技能列表里。批改记录里,这种"结论对、证据虚"的答案比"结论错"更值得记。
6.2 卫生四条
库从哪治起?我从盘点结果里反推出四条,做成下面这张清单:
文字版放这,图没渲染也照单能做:
- 前缀分域:域语义写进目录名,别碰 name 字段(6.3)。
- 备份出库:zip 不装载但占账,挪出扫描路径。
- 镜像二选一:软链镜像必有双注册,要么拆链收敛,要么知情接受,最糟的是不知道。
- 归一化查重:大小写、空格、不可见字符都归一了再比(4.2)。
四条里我最想展开的是备份出库。.agents 那 71 条里混着 8 个 zip 和 1 个 _archive,其中两个备份的名字长这样:评审类skillA.bak-20260825.zip 和 评审类skillA2026.8.25备份.zip(化名,命名格式原样)。一个是纯数字年月日,一个"2026.8.25"加"备份"俩字,两种格式并存,这就是库数不清的直接原因:每次数,都得先裁决 zip 算不算条目、_archive 算不算。
zip 惰性,不装载,可它躺在扫描路径里,账本就得记它。
学员的药方,两条动作:格式统一成 bak-YYYYMMDD 后缀,完整形态如 评审类skillA.bak-20260825.zip,原名在前、日期段在后、扩展名保留;挪出扫描路径,搬到与技能目录平级的地方,比如 skills-backup(格式那条是我摆的候选,他点的头);机制那问他给了句大实话:"skill 就数不清了"。账都对不上,前面讲的四种病全是空谈。
6.3 前缀该放哪一层
卫生第一条的前缀分域,底下还压着个更深的问题:前缀写在哪一层?候选层三个,能站的只有两个。
目录层,站得住。skills.sh 上技能按 owner/repo/skill-name 三段式展示,比如 mattpocock/skills/tdd,域就是目录,天然分域,name 字段一个字不用动。我库里的 gitnexus-、评审类- 前缀,也是这层的习惯(本机目录命名,一手)。
插件层,官方答案。anthropics 自家的技能仓库不搞 name 前缀,靠插件市场分发,装出来自动带命名空间,比如 document-skills@anthropic-agent-skills(anthropics/skills 仓库 README,2026-10-16 经 GitHub API 抓取;@ 是安装坐标,装好注册的是"插件名:技能名"的冒号全名,和 4.4 的 documents:docx 同一个机制)。Matt Pocock 被问到"要不要给技能加前缀"时,把问题整个判成上游问题:
I'll close this. I see this as an upstream problem - either skills.sh can ship an alias mechanism, or you can install a plugin via upcoming Claude Plugin support, which automatically namespaces.
(Matt Pocock,mattpocock/skills issue #357 关闭语,经 discussion #585 转引,2026-10-16 抓取,英文原句照抄)
name 字段层,没人这么干,因为会静默失败。VS Code 官方文档(微软官方,非 Anthropic 官方)的红线是 "Do not manually add namespace prefixes to the skill name field.",手写前缀进 name 字段,技能静默装载失败(VS Code 官方文档,2026-10-14 版,2026-10-16 抓取)。又是静默:保留名静默消失,预算超限静默截断,前缀写错层静默失败,这门手艺里最贵的词就是"静默"。
最后把两套秩序摆正。开放标准 agentskills.io 规定 name 必须等于父目录名、64 字符以内、小写字母数字连字符,通篇没有全局唯一性条款,唯一性靠"一目录一技能"间接成立;Claude Code 这边,官方明说不要求名字唯一,同名走座次。两套秩序不矛盾,管的层不同:标准层管格式,装载层管仲裁。前缀是目录和域的命名习惯,不是 name 字段的内容。
7、治理的单位是"之间"
回到开头那三个数,现在能重新对账了。
- 43 个软链不是错账,是我选了软链镜像两个个人目录,代价是双注册。至于双行是不是双倍烧描述 token,节 1 说过我没测出来,这笔先挂账,哪天有工具能量了再结。
- 71 里有 9 个该出库:8 个 zip 加 1 个 _archive,备份没走库外;另有 19 个只在 .agents 有一份,它们的问题是太孤单,不是重复。
- 10 条全暗也不是故障,是 .claude 这个目录 host 不读,gitnexus 七条、baoyu,加两个零散小件,都在等一个搬家决定。
账可以不对,但要知道差在哪。治理不等于卸载,这一课从头到尾,没有一个动作是卸载技能本体。
如果你只带走一句话,带走这句:治理的单位不是一条描述,而是一片描述、几个目录和几层开关。单条写得对只保证上桌,体系理得顺,这桌饭才不打架。
落地证据我也交一下:quiz 五题全对,连续第二课满分;动手四题(zip 题按填空重做后计对),系列头一回全对。最让我踏实的不是分数,是那道隔了两课的交错题:两条描述,一条 800 字符,一条 780,他答"装载,但拼接截断"。单看 800 不超 1024,第一关放行;拼起来 1580 超 1536,第二关截断。第 6 课的知识隔了几百轮对话还在,这才算进了长期记忆。
7.1 轮到你了:三个动作,十分钟
轮到你了,输入就是你自己的 skill 库,三个动作,十分钟:
- 数账:每个技能目录数一遍条目(Git Bash 里
ls ~/.agents/skills | wc -l,PowerShell 换Get-ChildItem | Measure-Object),再开 /skills 菜单数条数。对不上是预期结果,差值按上一节三分类归因:双注册、该出库、整库暗,完成分类就算通过。哪个 host 读哪个目录,以你自己 host 的技能列表为准,我的 host 读 .zcode 和 .agents,不读 .claude。 - 拨开关:在 /skills 菜单里挑一个最近抢戏的技能,按 Space 拨到 user-only。拨完打开 settings.local.json 确认 skillOverrides 落值;别挑插件技能,它们不受这个开关管(5.2)。
- 查重名:按 4.2 的三查口径归一化,大小写、空格、不可见字符。前两查一条管道能跑:
ls ~/.agents/skills | tr 'A-Z' 'a-z' | tr -d ' ' | sort | uniq -d;不可见字符肉眼扫,量力而行。查到了就改目录名,别把前缀写进 name 字段(6.3 的静默失败)。
做完你手里会多一张账实对照清单,和一个被拨动的开关。治理的第一步不是大扫除,是对账。
带走三样
- 治理的单位是"之间":一片描述、几个目录、几层开关;开关三层各管一段,作者管默认、用户管覆盖、管理端只收不放,插件豁免。单条及格只保证上桌。
- 触发层的病只有两种,叠和缝;药只有负边界,而且只能写进描述,写正文没用。重名不报错,按座次裁决,遮蔽的真药是改名------座次动不了,能动的只有名字。
- 账实相符是一切治理的起点:zip 不装载,但账本记得它;账可以不对,但要知道差在哪。
临走三问(凭记忆自测,别翻回去)
- 两个技能抢同一个活,你在其中一个的正文第一段写上"X 场景请用另一个技能",下次那个场景来了,它还抢吗?
- 项目 .claude/skills 里有一个 deploy,你个人目录里也有一个 deploy,同事赌"项目里的更具体,项目赢",你押哪边,依据是哪句话?
- 你把旧版技能打成 zip 丢进 ~/.agents/skills,名字改得完全合规,它会被装载吗?
三道都答对了,这一课才算真的带走。
这个系列写到这儿:第一课到第七课,治的都是"一个",从 frontmatter 怎么写一路讲到子代理预载;这一课把镜头拉远,开始治"一片",模块三只剩最后一课。下一篇,第 9 课·评测:技能写完、治理完,好坏怎么量?考试怎么出?下回拆卷子。
共约 5872 字 · 阅读约 15 分钟
如果这篇文章对你有帮助，欢迎转发给需要的同事和朋友。