两个没有一行代码的Skill：domain-modeling与codebase-design逐段拆解

概述

本期回到 Round 2 的单点深拆，但选了一对特殊样本：mattpocock/skills 仓库里的 domain-modeling（总榜第 58，累计 52.7 万安装）和 codebase-design（总榜第 59，51.2 万安装）。它们特殊在三点：第一，整个 Skill 目录里没有任何脚本——对比同仓库 wizard 的 8.6KB template.sh、diagnosing-bugs 的 hitl-loop.template.sh，这两个是纯文字 Skill，只靠提示词工程拿到 50 万级安装；第二，它们的 description 里都藏着同一条「库触发器」——「when another skill needs...」，即一个 Skill 可以声明自己是其他 Skill 的依赖库；第三，它们一个管「说什么词」（领域词汇表），一个管「怎么设计」（深模块方法论），合起来构成这个 280 万安装仓库的地基层。本文基于 2026-08-31 抓取的 skills.sh 榜单和 GitHub 仓库文件树逐段拆解。

一、它们在生态里的位置

先摆数据（skills.sh 全时段总榜，2026-08-31 实时抓取）：

两个主角正好卡在榜单的「中腰部第一梯队」：比不过 grill-me（100万）这种入口级爆款，但稳稳压过绝大多数独立仓库的头部 Skill。仓库级总安装 280 万，总榜前八占六席。从文件树看，domain-modeling 全目录 4 个文件约 8.5KB（SKILL.md 3361 字节 + CONTEXT-FORMAT.md 2299 + ADR-FORMAT.md 2766 + openai.yaml 101），codebase-design 约 11.8KB（SKILL.md 6488 + DEEPENING.md 2559 + DESIGN-IT-TWICE.md 2691 + openai.yaml 102）。

二、评测对比表

注：后两行为上一轮已拆解样本，供横向对照。安装命令均为：

# 方式A：Claude Code 插件市场（托管更新）
claude plugins install mattpocock-skills

# 方式B：skills.sh CLI，可选单一 skill
npx skills@latest add mattpocock/skills

三、逐段拆 domain-modeling：给项目装一本「活词典」

3.1 frontmatter：一条 description 埋了三个触发器

name: domain-modeling
description: Build and sharpen a project's domain model. Use when the user
  wants to pin down domain terminology or a ubiquitous language, record an
  architectural decision, or when another skill needs to maintain the
  domain model.

注意它没有 disable-model-invocation: true——与 wayfinder 的「只许用户召唤」相反，这是模型可自动挂载的纪律型 Skill。description 列了三个触发场景，第三个最值得抄：「or when another skill needs to maintain the domain model」。这是 Skill 生态里罕见的「依赖声明」写法——它不指望用户记住自己，而是让仓库里其他 Skill（wayfinder 的 grilling 工单、to-spec、triage）在需要维护词汇表时自动找到它。一个佐证是仓库根目录的 .changeset/domain-modeling-trigger-context-adr.md 变更文件：作者用 changesets 专门迭代过这个 Skill 的触发词，description 不是写完就扔的摆设，而是被持续调优的「检索接口」。

3.2 正文第一段：用「负面空间」划边界

Actively build and sharpen the project's domain model as you design. This is the active discipline... (Merely reading CONTEXT.md for vocabulary is not this skill — that's a one-line habit any skill can do. This skill is for when you're changing the model, not just consuming it.)

第一段就干了一件多数 Skill 作者不做的事：声明自己不是什么。读词汇表不算用我，只有改词汇表才算。这防止了模型把「翻了一眼 CONTEXT.md」当成「已执行 domain-modeling」的虚假满足——触发边界从「主题相关」收紧到「行为特定」。

3.3 文件结构：两种布局 + 惰性创建

正文先给出两种仓库布局的 ASCII 图：单上下文仓库一根 CONTEXT.md 加 docs/adr/；多上下文仓库根目录放 CONTEXT-MAP.md 索引，每个子包（ordering、billing）各有自己的词汇表和 ADR 目录——这是把 DDD 的 bounded context 落到文件系统约定上。紧接着是全篇最实用的一句纪律：

Create files lazily — only when you have something to write.

第一个术语敲定才建 CONTEXT.md，第一份 ADR 需要写才建 adr 目录。对比大量 Skill 一上来就让 agent 铺一套空模板目录的做法，惰性创建避免了「模板先行、内容烂尾」的仓库垃圾。

3.4 会话中的五个动作：一个可执行的访谈协议

「During the session」一节列了五个具体行为，每个都带示范台词：

1. Challenge against the glossary——用户用词与词汇表冲突时当场指出：「你的词汇表定义 cancellation 是 X，你现在说的像 Y，到底是哪个？」
2. Sharpen fuzzy language——模糊词立刻追问精确化：「你说 account，是指 Customer 还是 User？这是两个东西。」
3. Discuss concrete scenarios——用编造的边界场景压测概念关系。
4. Cross-reference with code——用户陈述与代码矛盾时摆上台面：「代码在取消整个 Order，你刚说支持部分取消，哪个是对的？」
5. Update CONTEXT.md inline——术语一敲定立刻写入，正文原话是「Don't batch these up — capture them as they happen」。

第五条的反面教训很真实：agent 默认倾向于「最后汇总再写」，而访谈式工作流里信息会漂移，批量回写等于制造失忆。

3.5 词汇表纯度条款与 ADR 三重门

两条硬约束收尾。其一是 CONTEXT.md 的纯度：「totally devoid of implementation details... It is a glossary and nothing else.」 词汇表只定义「是什么」，不许长成 spec 或草稿本——文件单一职责。配套的 CONTEXT-FORMAT.md 给出格式规范，最有味道的是每个术语必须带 _Avoid_ 行：

**Customer**:
A person or organization that places orders.
_Avoid_: Client, buyer, account

强制列出同义替换词，等于给模型装了一个「禁用词表」——下次它想写 client 时会意识到该写 Customer。其二，ADR 不是想写就写，三条件全满足才许建：难以逆转、缺上下文会令人费解、真实权衡的产物，缺一即跳过。这是用可判定条件管住了 agent 最爱犯的「文档过载」病。

四、逐段拆 codebase-design：一个 Skill 就是一套术语表

4.1 description 即定位：这 Skill 的本体是词汇

description: Shared vocabulary for designing deep modules. Use when the user
  wants to design or improve a module's interface, find deepening
  opportunities, decide where a seam goes, make code more testable or
  AI-navigable, or when another skill needs the deep-module vocabulary.

第一句不是「Help the user design」（帮用户设计），而是「Shared vocabulary」（共享词汇）——它自我定位为术语层而非流程层。结尾同样挂了库触发器「when another skill needs the deep-module vocabulary」。

4.2 八个术语 + 每个术语的禁用词

正文 Glossary 一节定义 Module、Interface、Implementation、Depth、Seam、Adapter、Leverage、Locality 八个词，开头是一句断言式指令：

Use these terms exactly — don't substitute "component," "service," "API," or "boundary." Consistent language is the whole point.

每个词条都带 _Avoid_。几个定义值得全文引用：

• Interface 是「调用者正确使用模块必须知道的一切」——不只类型签名，还包括不变量、顺序约束、错误模式、所需配置、性能特征。刻意比 TypeScript 的 interface 宽。
• Seam（明确注明借自 Michael Feathers）是「不改那处代码就能改变行为的位置」，并注明避免用 boundary——因为会和 DDD 的 bounded context 撞词。
• Depth 定义为杠杆率：调用者每学一单位接口能撬动多少行为。

对 LLM 而言这种设计收益极高：模型的最大毛病之一是同义词漂移（一会儿说 component 一会儿说 service），禁用词表把漂移钉死。

4.3 四条设计原则，两条判据直接可执行

• Depth is a property of the interface, not the implementation——深模块内部可以全是小件，只要不暴露进接口。
• The deletion test：想象删掉这个模块，若复杂度凭空消失，它是透传；若复杂度在 N 个调用点重新出现，它在挣饭吃。
• The interface is the test surface——想绕过接口测内部，说明模块形状不对。
• One adapter means a hypothetical seam. Two adapters means a real one. 一个实现配一个接口是假接缝，两个实现才证明接缝真实存在——一句话干掉了「为抽象而抽象」。

「Designing for testability」用正反 TypeScript 代码对示范两条：接受依赖而非创建（processOrder(order, paymentGateway) vs 内部 new StripeGateway()）、返回结果而非制造副作用（calculateDiscount(cart): Discount vs 原地改 cart.total）。

4.4 最罕见的段落：Rejected framings

Skill 末尾专门有一节「拒绝的框架」：明确拒绝 Ousterhout 原版「深度=实现行数/接口行数」的比值定义（会奖励灌水实现）、拒绝把 interface 窄化为 TS 关键字、拒绝 boundary 一词。一个提示词文件里写明「我反对哪些主流说法」，等于给模型接种了对抗训练数据里旧定义的疫苗。这是我拆了几十个 SKILL.md 里第一次见到的段落设计。

4.5 附属文件：DESIGN-IT-TWICE 的并行子代理协议

codebase-design 的渐进披露做得很干净：SKILL.md 只管词汇与原则，两个附属文件按需加载。DEEPENING.md 管依赖分类与接缝纪律；DESIGN-IT-TWICE.md（借 Ousterhout 同名章节）是一个完整的多代理编排协议：

flowchart TD
    A[选定深化候选模块] --> B[Step1 写问题空间说明给用户看]
    B --> C[Step2 并行发射 3+ 子代理]
    C --> D[代理1: 极简接口 1-3个入口]
    C --> E[代理2: 最大化灵活性]
    C --> F[代理3: 为最常见调用者优化]
    C --> G[代理4: 端口与适配器]
    D & E & F & G --> H[各产出: 接口/用例/隐藏实现/依赖策略/权衡]
    H --> I[Step3 顺序呈现给用户]
    I --> J[按 depth/locality/seam 三维对比]
    J --> K[给出有立场的推荐或混合方案]

三个细节：第一，每个子代理拿到不同的设计约束，逼出真正分化的方案而不是同一方案的三个措辞；第二，brief 里必须同时注入 SKILL.md 术语和 CONTEXT.md 术语，让子代理的命名与架构语言、领域语言对齐——这里就是它与 domain-modeling 的组合点；第三，结尾要求 agent 表态（「Be opinionated — the user wants a strong read, not a menu」），明令禁止甩四个方案让用户自己挑的甩锅行为。

五、把这对 Skill 放回仓库看：三层架构中的词汇层

mindmap
  root((mattpocock/skills 三层))
    流程层 编排
      wayfinder 规划地图
      ask-matt 阶段守卫
      to-tickets 拆票
    纪律层 方法
      tdd
      grilling 访谈
      domain-modeling 词汇表维护
      codebase-design 深模块词汇
      diagnosing-bugs
    基础设施
      setup-matt-pocock-skills
      issue-tracker 适配 GitHub/GitLab/local
      每目录 agents/openai.yaml

两个观察收尾。其一，仓库本身的工程化程度就是最好的广告：.agents/adr/ 里有《0002-ship-as-a-claude-code-plugin》这样吃自己狗粮的架构决策记录，.out-of-scope/ 目录专门写「本仓库不做什么」（如只支持主流 issue tracker），.changeset/ 里躺着对触发词的修订——Skill 仓库被当作正经软件产品来维护，这是它与「一个 md 文件走天下」的业余仓库拉开数量级差距的原因。其二，每个 Skill 目录里那个 ~100 字节的 agents/openai.yaml 暴露了分发野心：同一份 SKILL.md 同时服务 Claude Code 插件市场、skills.sh CLI 和 OpenAI 系 agent 三条管道。词汇层 Skill 最适合这种多端分发——没有脚本依赖，纯提示词即全部资产。

六、多维度排行榜

• 最值得抄的 description 写法：库触发器「or when another skill needs...」——让你的 Skill 被其他 Skill 依赖
• 最值得抄的正文段落：Rejected framings——写明你反对什么
• 最值得抄的文件格式：CONTEXT-FORMAT 的 _Avoid_ 禁用词行
• 最值得抄的门槛设计：ADR 三重门（难逆转+令人费解+真权衡，缺一不写）
• 不适合的场景：没有既定领域语言的小脚本仓库上 domain-modeling 属杀鸡用牛刀；不做接口设计的纯业务改动用不上 codebase-design；两者都需要你认可「共享词汇优先」这套 DDD 味的方法论

参考来源

1. Skills Leaderboard — skills.sh — domain-modeling 52.7万（#58）、codebase-design 51.2万（#59）等总榜安装数，2026-08-31 抓取
2. mattpocock/skills git tree API — 全部文件路径与字节数：SKILL.md 3361/6488 字节、附属文件、openai.yaml、.changeset 与 .agents/adr 目录
3. domain-modeling SKILL.md 原文 — frontmatter、负面空间定义、五动作协议、ADR 三重门逐段引用
4. codebase-design SKILL.md 原文 — 八术语表、Avoid 设计、四原则、Rejected framings 逐段引用
5. DESIGN-IT-TWICE.md 原文 — 并行子代理协议与四约束设计
6. CONTEXT-FORMAT.md 原文 — 词汇表格式规范、Avoid 行、单/多上下文仓库结构

[!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 等场景全覆盖。