# 两个没有一行代码的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 实时抓取）： | 排名 | Skill | 来源 | 累计安装 | |---|---|---|---| | 38 | grilling | mattpocock/skills | 57.8万 | | 58 | **domain-modeling** | mattpocock/skills | **52.7万** | | 59 | **codebase-design** | mattpocock/skills | **51.2万** | | 60 | diagnosing-bugs | mattpocock/skills | 50.4万 | 两个主角正好卡在榜单的「中腰部第一梯队」：比不过 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）。 ## 二、评测对比表 | Skill | 功能完整度(25%) | 设计质量(25%) | 实战效果(20%) | 上手难度(15%) | 社区活跃(15%) | 加权总分 | |---|---|---|---|---|---|---| | codebase-design | 4.5 | 5 | 4 | 3.5 | 5 | **4.5** | | domain-modeling | 4 | 5 | 4 | 4 | 5 | **4.4** | | （参照）wayfinder | 5 | 5 | 4 | 3 | 5 | 4.5 | | （参照）wizard | 4 | 5 | 4 | 4 | 4.5 | 4.3 | 注：后两行为上一轮已拆解样本，供横向对照。安装命令均为： ```bash # 方式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 埋了三个触发器 ```yaml 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_` 行： ```md **Customer**: A person or organization that places orders. _Avoid_: Client, buyer, account ``` 强制列出同义替换词，等于给模型装了一个「禁用词表」——下次它想写 client 时会意识到该写 Customer。其二，ADR 不是想写就写，三条件全满足才许建：**难以逆转、缺上下文会令人费解、真实权衡的产物**，缺一即跳过。这是用可判定条件管住了 agent 最爱犯的「文档过载」病。 ## 四、逐段拆 codebase-design：一个 Skill 就是一套术语表 ### 4.1 description 即定位：这 Skill 的本体是词汇 ```yaml 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 同名章节）是一个完整的多代理编排协议： ```mermaid 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 放回仓库看：三层架构中的词汇层 ```mermaid 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](https://www.skills.sh) — domain-modeling 52.7万（#58）、codebase-design 51.2万（#59）等总榜安装数，2026-08-31 抓取 2. [mattpocock/skills git tree API](https://api.github.com/repos/mattpocock/skills/git/trees/main?recursive=1) — 全部文件路径与字节数：SKILL.md 3361/6488 字节、附属文件、openai.yaml、.changeset 与 .agents/adr 目录 3. [domain-modeling SKILL.md 原文](https://raw.githubusercontent.com/mattpocock/skills/main/skills/engineering/domain-modeling/SKILL.md) — frontmatter、负面空间定义、五动作协议、ADR 三重门逐段引用 4. [codebase-design SKILL.md 原文](https://raw.githubusercontent.com/mattpocock/skills/main/skills/engineering/codebase-design/SKILL.md) — 八术语表、_Avoid_ 设计、四原则、Rejected framings 逐段引用 5. [DESIGN-IT-TWICE.md 原文](https://raw.githubusercontent.com/mattpocock/skills/main/skills/engineering/codebase-design/DESIGN-IT-TWICE.md) — 并行子代理协议与四约束设计 6. [CONTEXT-FORMAT.md 原文](https://raw.githubusercontent.com/mattpocock/skills/main/skills/engineering/domain-modeling/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 等场景全覆盖。