本期是 Skills 生态系列第 2 轮，做单个热门 Skill 的深度拆解。主角是 improve-codebase-architecture——来自 Matt Pocock（Total TypeScript 创始人）的 mattpocock/skills 仓库，在 skills.sh 全时段排行榜上以 747.2K 安装位列第 5，仅次于同仓库的 grill-me（911.2K）和官方 frontend-design（796.7K）。此前已拆解过 grill-me、tdd、agent-browser 等明星 Skill，本期避开它们，选这个“架构审查”类 Skill，原因有二：一是它是整个仓库里文件结构最复杂的一个（SKILL.md 之外还带一份 6.7KB 的 HTML-REPORT.md 输出规范），二是它示范了 Skills 生态里最重要的进阶写法——Skill 组合。本文基于其 GitHub 仓库当前 main 分支的真实文件逐段讲解，读完你可以照着写一个自己的版本。
先看 skills.sh 全时段安装榜的头部格局（数据抓取于 2026-08-28）：
| 排名 | Skill | 来源仓库 | 安装量 |
|---|---|---|---|
| 1 | find-skills | vercel-labs/skills | 3.0M |
| 2 | grill-me | mattpocock/skills | 911.2K |
| 3 | frontend-design | anthropics/skills | 796.7K |
| 4 | grill-with-docs | mattpocock/skills | 775.3K |
| 5 | improve-codebase-architecture | mattpocock/skills | 747.2K |
| 6 | tdd | mattpocock/skills | 722.0K |
| 7 | agent-browser | vercel-labs/agent-browser | 702.8K |
| 8 | setup-matt-pocock-skills | mattpocock/skills | 663.0K |
| 9 | vercel-react-best-practices | vercel-labs/agent-skills | 647.0K |
| 10 | handoff | mattpocock/skills | 628.2K |
榜单前 10 里有 6 席属于同一个仓库——mattpocock/skills 已经不是“一个热门 Skill”，而是一个套件。这个仓库的设计本身值得先讲清楚，因为主角 Skill 的每一处设计都建立在套件架构之上。
mattpocock/skills 的 README 把所有 Skill 按一个轴分类：谁能调用它。
/grill-me 这样的斜杠命令才会启动，职责是编排（orchestrate）。配套一条铁律：user-invoked Skill 可以调用 model-invoked Skill，但永远不调用另一个 user-invoked Skill。这避免了斜杠命令之间互相拉扯形成的调用迷宫。improve-codebase-architecture 的 frontmatter 正是这条铁律的落地：
---
name: improve-codebase-architecture
description: Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
disable-model-invocation: true
---
三个字段三个设计决策：
disable-model-invocation: true——明确禁止模型自动触发。架构审查是一个“重”操作（要跑子代理探索代码库、生成 HTML 文件），绝不该在用户只想改个 bug 时被自动拉起。这是“重 Skill 必须显式触发”的范本。SKILL.md 正文约 6KB，结构是一条清晰的三段流水线。以下逐段讲解（引用均为仓库原文的中文转述或原句）。
正文第一句就定义了目标："Surface architectural friction and propose deepening opportunities — refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability."（浮现架构摩擦点，提出把浅模块变成深模块的重构机会，目标是可测试性和 AI 可导航性。）
紧接着立刻锚定两个外部知识源：
/codebase-design Skill 拿到架构词汇表：module、interface、depth、seam、adapter、leverage、locality，并且要求“在每一条建议里精确使用这些词——不许漂移到 component、service、API、boundary"。CONTEXT.md（领域术语表）和 docs/adr/（架构决策记录），“这个命令不该重新翻案的决策”。这是第一处值得抄的设计：Skill 不自带知识，而是引用另一个 Skill 作为“字典”。词汇表单独放在 model-invoked 的 codebase-design 里，意味着你写代码时模型也会自动用这套词——一份词汇，两处生效。
这一阶段的第一行小标题就是态度："Scope before you scan — YAGNI."（先定范围再扫描——你不需要那用不上的。）逻辑是：加深一个模块的收益在于让未来的修改变容易，所以要给最近频繁变动的代码加权。具体做法：
git log --oneline，找出反复出现的“热点”文件，让这些路径优先吸引注意力；然后派 subagent_type=Explore 的子代理去有机地走读代码（Skill 明确写"不要死板地套启发式”），找四类摩擦：理解一个概念要在多个小模块间跳来跳去的地方；接口复杂度逼近实现的浅模块；为了可测试性抽出纯函数、但真正的 bug 藏在调用方（没有 locality）的地方；以及测试不到或很难从现有接口测到的地方。
点睛之笔是删除测试（deletion test）："Apply the deletion test to anything you suspect is shallow: would deleting it concentrate complexity, or just move it?"（对任何疑似浅模块的东西做删除测试：删掉它是让复杂度集中了，还是只是挪了个地方？“会集中”才是你要的信号。）把 Ousterhout《A Philosophy of Software Design》里的深模块思想压缩成一句模型可执行的判据——这是整个文件里提示词工程的最高光时刻。
第二阶段的第一个决策就很讲究：报告写成自包含 HTML 文件，放到操作系统临时目录。从 $TMPDIR 解析、回退到 /tmp（Windows 是 %TEMP%），文件名带时间戳保证每次运行拿到新文件，然后用 xdg-open/open/start 帮用户打开并告知绝对路径。这样仓库里什么都不落——审查是阅后即焚的，不会污染 git status。
渲染技术栈也写得明确：Tailwind 走 CDN 做布局，Mermaid 走 CDN 画图；但不许全用 Mermaid——“图形状的关系（调用图、依赖、时序）用 Mermaid，想要更编辑部风格的视觉（质量图、剖面图）就手写 div/SVG。混着来，全用 Mermaid 会开始显得千篇一律。”
每个候选机会渲染成一张卡片，字段固定：
Strong / Worth exploring / Speculative 三档徽章报告以"Top recommendation"收尾：你第一个该动哪个、为什么。然后一句硬约束："Do NOT propose interfaces yet."（此刻不许提出具体接口设计。）写完文件后只问用户一句："Which of these would you like to explore?"——先诊断，不开药。这个阶段边界划得极其克制。
还有一个容易被忽略的细节：ADR 冲突处理。如果某个候选和现有 ADR 矛盾，只有当摩擦真实到值得重开决策时才提，并在卡片上用警告框标注（“与 ADR-0007 矛盾——但值得重开，因为……”）。“不要把 ADR 禁止的每一个理论重构都列出来”——这一条防住了 AI 审查工具最常见的毛病：把用户已经决策过的东西当新发现反复端上来。
用户选中一个候选后，Skill 转入 /grilling——套件里那个“拷问”原语（也是 grill-me 的底层引擎，本期不展开）。它会把决策树一枝一枝和你走完：约束、依赖、加深后模块的形状、接缝后面放什么、哪些测试能存活。
同时副作用内联发生：对话中决策定型时，顺手跑 /domain-modeling 维护领域模型——给加深后的模块起了 CONTEXT.md 里没有的名字？当场加进去（文件不存在就惰性创建）；用户以一个“有承重能力的理由”拒绝了候选？主动提议记一条 ADR，原话框架是：“要我把这条记成 ADR 吗？这样未来的架构审查就不会再提它。”——并且明确排除两类不值得记的理由：临时性的（“现在不值得”）和不言自明的。
多数 Skill 只规范“过程”，这个 Skill 额外用一份 6.7KB 的附属文件规范“输出物”——这是它区别于 90% 社区 Skill 的地方。SKILL.md 末尾一句 "See HTML-REPORT.md for the full HTML scaffold, diagram patterns, and styling guidance" 把细节渐进披露出去：主文件保持可读，渲染细节按需加载。
HTML-REPORT.md 里最有含金量的是五种图表模式，明确告诉模型“挑合适的用，混着来”：
classDef 的示例：泄漏边红色、深模块深色；风格规范同样具体到类名："Lean editorial, not corporate-dashboard"（走编辑部风，别做企业仪表盘），标题可选衬线体，text-xs uppercase tracking-wider 做图内模块标签，“它们应该读起来像示意图，而不是 UI"，图表控制在约 320px 高让 before/after 并排不滚动。唯一的脚本是 Tailwind CDN 和 Mermaid ESM 导入——"report 其余部分是静态的：没有应用代码，没有交互”。
最后是术语锁定的二次执行，精确到给出反例句式：必须用 module / interface / implementation / depth / deep / shallow / seam / adapter / leverage / locality；绝不替换为 component / service / unit / API / signature / boundary / layer / wrapper。"Wins"列表的收益必须用词汇表术语表述（"locality: bugs concentrate in one module"），并点名禁用 "easier to maintain"、"cleaner code" 这类不入词汇表的空话。"No hedging, no throat-clearing"——不许含糊，不许清嗓子。
把这个 Skill 的依赖关系画出来，你能看到它其实是套件里的一台“总装机”：
flowchart TD
U["用户输入 /improve-codebase-architecture"] --> P1["阶段1: Explore<br/>git log 找热点 → Explore子代理走读<br/>删除测试筛浅模块"]
P1 --> P2["阶段2: HTML报告<br/>写$TMPDIR + 自动打开<br/>Strong/Worth exploring/Speculative 三档"]
P2 --> Q{"用户选中候选?"}
Q -- 否 --> END["阅后即焚, 仓库零污染"]
Q -- 是 --> P3["阶段3: Grilling循环<br/>决策树逐枝拷问"]
P3 --> DM["/domain-modeling<br/>更新CONTEXT.md + ADR"]
P3 -.设计备选接口.-> CD["/codebase-design<br/>design-it-twice 并行子代理"]
subgraph 词汇层 [model-invoked 可复用纪律]
CD
DM
GR["/grilling 拷问原语"]
end
GR -.被调用.-> P3
CD -.词汇表.-> P1
以下评分基于实读的源文件 + skills.sh 安装数据 + 仓库 README 的自我定位（实战效果项含 README 自述的局限，非独立实测）：
| Skill | 功能完整度(25%) | 设计质量(25%) | 实战效果(20%) | 上手难度(15%) | 社区活跃度(15%) | 加权 |
|---|---|---|---|---|---|---|
| improve-codebase-architecture | ★★★★★ | ★★★★★ | ★★★★ | ★★★★ | ★★★★★ | 4.8 |
| grill-with-docs | ★★★★★ | ★★★★★ | ★★★★★ | ★★★★★ | ★★★★★ | 4.9 |
| codebase-design（词汇Skill） | ★★★★ | ★★★★★ | ★★★★ | ★★★★★ | ★★★★★ | 4.5 |
| diagnosing-bugs | ★★★★ | ★★★★ | ★★★★ | ★★★★ | ★★★★★ | 4.1 |
| triage | ★★★★ | ★★★★ | ★★★★ | ★★★ | ★★★★★ | 4.0 |
| handoff | ★★★★ | ★★★★ | ★★★★ | ★★★★★ | ★★★★★ | 4.2 |
| vercel-react-best-practices | ★★★★ | ★★★★ | ★★★★★ | ★★★★★ | ★★★★★ | 4.5 |
说明：grill-with-docs 得分最高是因为它把拷问、领域建模、ADR 记录三件事焊在一入口里，新手零配置即用；主角 Skill 上手难度略低一档，因为它假设你愿意维护 CONTEXT.md/ADR 这套“领域文档基建”，且 README 坦言它是"a survey, not a rescue"——在真正老旧的代码库上它会找到真候选，但不会替你解开泥球，跟进重构仍然靠人。
# 方式一：Claude Code 官方插件市场（托管、自动更新，只读订阅）
claude plugins install mattpocock-skills
# 或会话内：/plugin install mattpocock-skills
# 方式二：skills.sh 安装器（文件复制进你的仓库，可自由改造）
npx skills@latest add mattpocock/skills
装完后每个仓库跑一次 /setup-matt-pocock-skills（配置 issue 跟踪器、triage 标签、文档存放位置）。注意 README 明确警告：两种方式二选一，都装会得到两份重复 Skill。日常用法：每隔几天对你的代码库跑一次 /improve-codebase-architecture，从 HTML 报告里挑一个候选进入拷问循环。
适用：AI 加速开发导致熵增失控的仓库（README 称之为"We Built A Ball Of Mud"问题的解药）；准备接手老项目前的体检；想系统性引入深模块/接缝词汇的团队；TypeScript/前后端通用工程库。
不适用：期待“一键自动重构”的人——它刻意停在诊断，动不改代码；没有持续维护意愿的一次性脚本仓库（YAGNI 定向逻辑会失去意义）；不愿维护 CONTEXT.md 和 ADR 的团队，词汇联动会退化成普通审查。
disable-model-invocation: true，防模型自作主张。$TMPDIR，阅后即焚。[!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 等场景全覆盖。