门牌背面：SKILL.md暗字段拆解

Skills生态拆解 · 第8轮 · 设计模式提炼（2026-09-14）

概述

八轮拆到今天，SKILL.md 的可见面基本拆完了：正文结构有空货架审计，名字有命名六式，触发有触发工程专文。本期按轮次母题做最后一层——门牌背面那几颗没人拧的螺丝：frontmatter 里的扩展字段（allowed-tools、disable-model-invocation、model、license、metadata），以及由它们决定的「调用接口」。样本不追外部榜单：一边是随 Claude Code 直接派发、装机基数最大的官方内置件——它们的描述原文就在每次会话的货架清单里，逐字可查、引用零损耗；一边是本机在册430余件社区件暴露出的变体命名生态。核心发现一句话：社区教程大多停在 name + description 两行门牌，而官方内置件恰恰是在这层背面拉开差距的——字段即接口，接口即产品。

一、先把货架看全：frontmatter 一共七颗螺丝

口径说明：字段语义以官方文档为准（见参考来源），本表是写法视角的归纳，不复抄规范原文；具体字段的支持程度随版本演进，落地前以你本机文档为最终依据。

值得注意的生态位观察：本栏目此前的空货架审计盯着的是正文，而门牌背面这一层长期是教程空白段——绝大多数教程到 description 就停笔了。这恰恰是普通社区件和「用起来像软件」的件之间的分水岭。

二、七个可以直接抄的接口模式

模式1：正反双门——TRIGGER 与 SKIP 成对出现

官方 claude-api 件的描述原文（节选）：

TRIGGER when: code imports anthropic/@anthropic-ai/sdk…… SKIP: file imports openai/other-provider SDK……

正向门写「什么时候必须用我」，反向门写「什么时候绝对别叫我」。反门的价值常被低估：它省掉的不只是一次误触发和一段误加载的上下文，更是用户一次「它怎么自己跑起来了」的信任损耗。怎么抄：写完 description 后强制补一行 SKIP，问自己——我的件最容易被哪个邻居误认？同赛道竞品（对 claude-api 来说是 OpenAI SDK 项目）就是你的反门。

模式2：动作清单式描述——每个动词短语都是一个触发钩子

看两个内置件的描述原文：update-config 几乎是一张动作清单——「automated behaviors require hooks configured in settings.json」「permissions」「env vars」「hook troubleshooting」；fewer-permission-prompts 同款写法——「Scan your transcripts for common read-only Bash and MCP tool calls, then add a prioritized allowlist」。

模型的触发匹配是语义匹配，动宾短语（scan / add / configure / troubleshoot）比形容词（强大、高效、一站式）高出几个数量级的命中率。怎么抄：把 description 写成4-6个动宾短语，每个短语对应一个真实使用场景，然后删光所有自我夸奖。

模式3：力度做成参数，不要架三件

code-review 的描述原文写明了档位与开关：

low/medium: fewer, high-confidence findings; high→max: broader coverage, may include uncertain findings. Pass --comment to post review comments inline or --fix to apply the findings.

一个「代码审查」需求，弱写法是架三件（轻审查件、深审查件、自动修件），强写法是一件加参数。参数化的入口不需要花哨字段——直接写进 description，模型和用户都读得懂。这是对抗变体爆炸的第一道堤坝（见模式7）。怎么抄：找出你件里「做多狠」的那个维度，定义低中高三档的行为差异，白纸黑字写进描述。

模式4：验收契约前置——什么算「做完了」写进门牌

verify 的描述只有一句核心：「Verify that a code change actually does what it's supposed to by running the app and observing behavior」——把「跑测试」和「跑起来看行为」划清界限，验收标准就是件的边界。run 的描述则写了兜底：「If no project skill exists, falls back to built-in patterns」——没有项目专属方案时怎么办，提前声明，不给模型现场发挥的空间。怎么抄：在描述或正文第一段写两句话——完成的判据是什么；遇到没见过的情况退到哪里。

模式5：点火权分离——危险件只许人点

disable-model-invocation 是最被低估的一颗螺丝：拧上后模型不自动触发，只有用户显式斜杠调用才生效。这套分层在官方内置件里肉眼可见：审查、验收这类有副作用的件以斜杠入口示人；而 loop 干脆把点火权交给定时器——「Run a prompt or slash command on a recurring schedule (e.g. /loop 5m /foo)」，机器点火、件执行、人睡觉。

判断要不要收点火权，三条标准：花钱吗（长任务烧token）、出后果吗（改代码、发评论、删东西）、拦得住吗（半夜跑的你能不能中断）。三条中两条，就只许手点。怎么抄：危险件加 disable-model-invocation；想定时跑的活，点火权交给 loop 这类调度入口，而不是让模型看着办。

模式6：收权与自述——最小权限加一张名片

allowed-tools 让件在运行期只带必需工具：写 git 操作的件别带浏览器，只读文件的件别带执行权。license 和 metadata 则是发布者的名片：许可证让装机目录敢收你，署名、版本、来源让出问题时查有此人——本栏目安全三件套一轮提过，装机端的安全扫描已经开始看这些。

收权字段的真实价值不在安全，在信任：一个声明了工具边界的件，用户授权的心理成本低得多。怎么抄：发布前问一句「这个件最少需要哪几个工具」，把答案写进 allowed-tools。

模式7：变体即版本——一名一目录逼出来的发布学

SKILL.md 一名一目录、没有版本字段，于是本机在册清单里能看到一整套民间对策：course-video-maker 家族一路分出 -link、-zh、-zh-link；ericsson-ppt-writer 分出 -sc、-v2；gstack 与 gstack-local 并排注册；openstoryline 更干脆，拆成 -install 和 -use 两件——装和用各发一张门牌。

变体命名实际上是版本、语言、宿主、生命周期四个维度的手动外键。能用，但每多一个变体，触发面就多一分混乱——同名件对账那一轮已经清算过重影代价（一机六份pptx的装机审计犹在眼前）。怎么抄：语言变体加 -zh，宿主变体加宿主名，破坏性改版加 -v2 并在旧件描述里写明「已由某某接替」；凡是能合并进参数档位的（模式3），绝不开新件。

三、内置样本五维对比

¹ 内置件无社区活跃度口径，本栏改记分发方式；此表为接口设计视角的编辑评分，非功能横评——这五件的定位本就不同赛道，比的是「门牌写法」这一门手艺。

四、点火链路：一个请求从进门到执行

flowchart TD
    U["用户一句话"] --> M{"扫描在册描述"}
    M -->|"命中 description"| G["扩展字段闸门"]
    M -->|"不命中"| N["保持沉默"]
    G --> D{"禁自动点火"}
    D -->|"是且非斜杠"| N
    D -->|"放行"| T["allowed-tools 收权"]
    T --> MD{"model 字段换脑"}
    MD --> B["装载正文"]
    B --> R["按需加载脚本与引用"]
    R --> V["按验收契约执行"]
    V --> O["产出与汇报"]
    L["定时器 loop"] -->|"机器点火"| G

社区件普遍只修了这条链路的第一站（描述命中），后面五站全数放空；官方内置件把每一站都写成了显式契约。这就是「像玩具」和「像工具」的差别。

五、安装与使用命令

内置件零安装，斜杠即用：

/code-review              # 默认中等力度
/code-review high         # 更广覆盖，允许存疑发现
/code-review --fix        # 直接应用修复
/code-review --comment    # 评审意见内联到PR
/verify                   # 跑起来看行为，不是跑测试
/run                      # 启动并驱动本项目应用
/simplify                 # 复用与简化清理
/security-review          # 安全审查
/loop 5m /code-review     # 每5分钟定时点火一轮审查

社区件通用安装（skills.sh 体系）：

npx skills find <关键词>    # 搜市场
npx skills add <skill-name> # 装机

自建件落位：

mkdir -p .claude/skills/release-notes
# 在目录里放一个 SKILL.md，门牌写法见下节

六、动手：把你的第一个 Skill 升级成第二个

多数人的第一个件长这样（两行门牌，正文裸奔）：

---
name: release-notes
description: 整理 git 提交生成发版说明。
---

按本期七个模式升级后：

---
name: release-notes
description: 从 git log 生成周度发版说明，按模块分组并标注风险等级。力度可选 low（只列变更）或 high（含回滚方案）。TRIGGER when: 用户要求整理发版记录、changelog、release notes。SKIP: 用户只是想查某一次 commit 的内容。
allowed-tools: Bash(git log:*), Bash(git tag:*), Read, Write
disable-model-invocation: true
license: MIT
metadata:
  author: yourname
  version: "2.0"
---

（字段具体语法随版本演进，以官方文档与本机 claude 说明为准。）

六步升级清单：

1. description 补 SKIP 反门，挡住最可能的误认
2. 把「做多狠」写成分档，别为力度开新件
3. 写清完成判据——跑起来看，还是测试过就算
4. allowed-tools 做减法，只留必需工具
5. 有副作用的件拧上 disable-model-invocation
6. metadata 署名；版本走变体命名并在旧件里留接替声明

七、推荐排行榜

最值得抄的三个模式 1. 双门描述（TRIGGER/SKIP）——一行成本，误触减半 2. 力度参数化——一件顶三件，防变体爆炸 3. 验收契约前置——把「什么算完成」钉死在门牌上

最被低估的字段 1. allowed-tools——信任比安全先行 2. disable-model-invocation——点火权即权限 3. metadata——发布者唯一查得到的户口

红灯做法 1. description 写成散文，全是形容词没有动词 2. 同一功能架三件，靠名字区分力度 3. 危险件不设点火权，让模型半夜替你做主

结语

SKILL.md 的格式门槛低到两个小时能写出第一个件，这是生态繁荣的根，也是泥沙俱下的因。八轮拆下来，官方件和优质社区件的差距从不在文笔——而在门牌背面：权限声明了没有，点火权分了没有，验收标准立了没有，出处留了没有。这四问，就是从第一个件到第二个件之间的全部距离。

参考来源

1. anthropics/skills — 官方 Skills 仓库，SKILL.md 格式与官方件的原始出处
2. Claude Code 文档 · Skills — frontmatter 字段语义的权威口径
3. 本机在册清单（~/.claude/skills，430余件，2026-09-14 对账）— 变体命名生态与官方内置件描述原文的取证来源
4. 本栏目前文：《一个字段定生死：Skill触发工程》《Skill门店学：命名六式首拆》《正文七段：SKILL.md空货架审计》— 触发、命名、正文三层的既有拆解，本期为其补上字段层拼图

[!tip] 51学通信知识星球 星主：爱卫生（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。 星球定位：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。 当前规模：5200 篇主题 / 990 个回答，198 元/年。 加入福利：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。 AI 加持：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。