Matt 在 README 里把目标说得很清楚这些 skill 是小的、可改的、可组合的实践用来修复 coding agent 在真实工程里的常见失败而不是像 GSD、BMAD、Spec-Kit 那样接管整个流程。README.md#L12-L18这个判断决定了仓库的组织方式。它不追求一个大 workflow engine而是把工程中的稳定失败拆成小 skill需求没对齐就 grilling项目语言太啰嗦就沉淀 domain model代码跑不通就建立反馈环架构变成泥球就重新设计模块边界。README.md#L42-L140公开交付面最新版本的公开交付面不等于skills/目录里的所有文件。Claude plugin 只暴露engineering和productivity中的一部分 skillask-matt、grill-with-docs、triage、tdd、diagnosing-bugs、domain-modeling、codebase-design、writing-great-skills等。plugin.json#L3-L20这说明仓库里有两层边界。第一层是文件系统边界所有 skill 都放在skills/下面。第二层是产品边界只有 plugin 清单里的 skill 被当作稳定入口交付。这个边界很重要。in-progress、personal、misc、deprecated里的内容可以帮助理解 Matt 怎么工作但不能直接当成主流程的一部分。它们更像工作台、个人脚本和历史沉积。目录分组engineering是工程主干。它放的是 Matt 每天写代码时会用到的能力初始化仓库约定、澄清需求、建立 domain model、做 prototype、写 PRD、拆 issue、triage、TDD、debug、架构审查、合并冲突处理。这里的 skill 能连成开发流程。productivity是通用工作习惯。grill-me、grilling、handoff、teach、writing-great-skills不一定绑定代码仓库。它们处理的是对话压测、交接、教学和 skill 写作方法。misc是低频工具。比如 git guardrail、pre-commit setup、课程 exercise scaffold、迁移到shoehorn。这些 skill 证明了 skill 可以封装很具体的重复动作但它们不是 Matt 方法论的主干。personal是个人工作流。它服务 Matt 自己的文章编辑和 Obsidian 笔记。它们不属于工程交付链路但很值得看因为这里能看到 Matt 如何把“写文章”和“管理知识”也做成有状态的工作流。in-progress是实验区。decision-mapping、review、writing-beats、writing-fragments、writing-shape都还没有进入公开主叙事。它们说明 Matt 仍在把新的工作法试探性地 skill 化。deprecated是历史层。它保留被替换的 skill帮助理解演化。这些旁支 skill 不应该被忽略只是不适合放进“工程开发流程”那篇里。teach是一个完整的学习工作区它要求建立MISSION.md、RESOURCES.md、learning-records/、lessons/、assets/和NOTES.md把教学拆成使命、资源、课程、学习记录和复习材料。SKILL.md#L8-L20 这和工程流程里的 PRD、issue、ADR 很像都是先规定状态放在哪里再让 Agent 在状态之间推进。edit-article则展示了写作类 skill 的另一种形态它先要求按标题拆章节再检查信息依赖顺序确认结构后逐节改写。SKILL.md#L7-L15 这个 skill 很短但它抓住了文章编辑的关键失败Agent 容易直接润色句子却不先判断段落和章节是否按依赖关系展开。调用方式才是真正的分类轴目录只是使用场景分组。真正决定 skill 性质的是调用方式。README 把 skill 分成user-invoked和model-invoked前者只能由用户主动输入通常承担编排后者可以由模型在任务匹配时自动触发通常承载可复用纪律。一个 user-invoked skill 可以调用 model-invoked skill但不能调用另一个 user-invoked skill。README.md#L142-L144writing-great-skills把这个规则解释得更彻底。model-invoked skill 保留description换来模型可发现性同时每轮付出 context loaduser-invoked skill 通过disable-model-invocation: true从模型视野里消失换来零 context load但把记忆成本交给人。SKILL.md#L11-L20这也是为什么新版新增了ask-matt这种 router。user-invoked skill 多了以后用户不可能记住每个入口。router 不让系统自动接管流程只降低用户选择 skill 的 cognitive load。仓库的核心设计Matt 的设计不是“把每个任务都做成一个 prompt”。它更像一个 agent 行为控制系统。每个 skill 解决一个稳定失败grilling解决需求没压实。domain-modeling解决项目语言漂移。tdd解决 Agent 写完才发现行为不对。diagnosing-bugs解决看几行代码就猜补丁。codebase-design解决模块边界浅、接口不稳定。handoff解决会话断裂后下一轮无法接续。这些 skill 之间不是代码调用关系而是 artifact 接力。grill-with-docs可能更新CONTEXT.md和 ADRto-prd生成 PRDto-issues生成 issuetriage决定 issue 当前状态tdd和diagnosing-bugs产出测试、代码和复现证据improve-codebase-architecture产出临时 HTML report再把长期语言或决策回写到CONTEXT.md或 ADR。writing-great-skills作为设计例子writing-great-skills不是工程开发流程的一环而是这个仓库对自身设计方法的说明。它的第一句话已经把目标钉住skill 存在的目的是从随机系统里压出确定性。这里的确定性不是每次输出相同而是每次走同一种可靠过程。SKILL.md#L7-L9这个 skill 本身采用 user-invoked。它的description是给人看的不承担模型自动触发。这个选择符合它的用途它不是每次写代码都要自动出现的纪律而是人在创建或审查 skill 时主动打开的参考。它的正文不是步骤而是一套 reference。Matt 没有写“第一步、第二步、第三步写 skill”而是定义一组判断工具调用方式、description、信息层级、拆分粒度、修剪、leading words、failure modes。真正的流程要由写 skill 的人用这些工具判断。这点很关键。不是所有 skill 都必须写成执行步骤。writing-great-skills说明 skill 可以是全步骤例如tdd要求 Agent 一轮一轮红绿推进。全参考例如writing-great-skills给 Agent 或人一套判断词汇。步骤加语义参考例如triage先定义 issue 的状态语义再规定如何把 issue 推进到某个状态。这里的“状态机”不是执行步骤而是判断结果的语义集合。needs-info、ready-for-agent、wontfix这些词回答的是“这张 issue 现在是什么状态、应该交给谁”不是“Agent 第一步、第二步做什么”。执行流程回答的是另一件事Agent 如何读 issue、查代码、验证 claim、追问信息、最后贴 brief 或改 label。把两者拆开才能避免把“读 issue”“验证复现”这类动作误当成状态。这个 skill 展示了什么写法第一个设计点是 invocation。一个 skill 是否允许模型自动发现不是格式细节而是成本选择。model-invoked 花 context loaduser-invoked 花 cognitive load当 user-invoked 太多时需要 router skill 缓解记忆成本。SKILL.md#L15-L20第二个设计点是 description。model-invoked 的 description 不应该写成简介而要写成触发器。一个 branch 一个触发不要把同义词当成多个分支堆进去。SKILL.md#L22-L28第三个设计点是 information hierarchy。Agent 立即要执行的 step 应该留在SKILL.md定义、规则和分支性材料可以作为 reference不是每条路径都要看的 reference 应该通过 context pointer 放到外部文件。SKILL.md#L30-L44第四个设计点是 split。拆 skill 只有两种值得付费的理由按 invocation 拆让某个 leading word 独立触发按 sequence 拆隐藏后续步骤避免 Agent 提前完成当前步骤。SKILL.md#L46-L51第五个设计点是 pruning。每个意义只能有一个 single source of truth每行都要通过 relevance 检查每句都要通过 no-op test。它反对“越详细越安全”的直觉因为冗余会增加维护成本也会错误放大某个含义在模型注意力里的权重。SKILL.md#L53-L59第六个设计点是 leading word。一个好的 skill 不靠长篇解释压住行为而是找到模型预训练里已经有的紧凑概念用这个词稳定触发一片行为区域。SKILL.md#L61-L72为什么GLOSSARY.md要拆出去writing-great-skills的GLOSSARY.md不是附录而是这套设计的示范。SKILL.md只保留写作时最常用的判断完整术语定义放进 disclosed reference。这样顶层 skill 保持短读者需要精确定义时再进入术语表。术语表也让这个仓库获得一套自己的 domain model。Model-Invoked、User-Invoked、Context Load、Cognitive Load、Router Skill、Information Hierarchy、Completion Criterion、Premature Completion不是随意解释的词而是后续设计和审查 skill 时可复用的判断工具。GLOSSARY.md#L15-L103这就是一个自反例子Matt 不只写了很多 skill还把“怎样写 skill”本身也沉淀成 skill并把这套语言外置成 reference。它同时展示了 progressive disclosure、domain model 和 single source of truth。GLOSSARY.md具体提供了什么GLOSSARY.md不是把正文里的词再解释一遍而是把 skill 设计中的几个压力拆成可命名的杠杆。第一组概念处理“谁来触发”。Model-Invoked、User-Invoked、Description、Context Pointer、Context Load、Cognitive Load、Router Skill共同回答一个问题一个 skill 应该让模型自己发现还是让人主动调用。这个选择不是偏好问题而是成本交换。模型能发现就要长期支付 context load人来调用就要长期支付 cognitive load。router skill 的出现是因为 user-invoked 多了以后人也会记不住。GLOSSARY.md#L19-L57第二组概念处理“内容放在哪里”。Information Hierarchy可以理解成信息优先级Agent 立刻要执行的步骤放在SKILL.md顶层只在某些情况才需要的解释放到外部 reference。Co-location可以理解成同一件事放在一起一个概念的定义、规则和例外不要散在文件各处否则 Agent 读到一半会漏掉相关约束。Branch是不同调用分支Progressive Disclosure是按需展开材料。Reference是 skill 自己的参考材料可以在SKILL.md里也可以被拆到同目录的附属文件里External Reference是 skill 外部的普通资料比如项目文档、ADR、README它不是 skill 的一部分只是被 skill 指向后读取。它们共同回答一个问题哪些内容必须留在当前上下文哪些内容应该藏到 pointer 后面。Matt 不是为了短而短而是为了让 Agent 在正确时刻看见正确材料。GLOSSARY.md#L59-L99第三组概念处理“Agent 为什么会提前收工”。Steps是 Agent 要执行的动作Completion Criterion是当前动作怎样才算完成Post-Completion Steps是后面还没轮到的动作Legwork是当前动作内部需要自己完成的调查、阅读和验证。Premature Completion描述的失败是Agent 看见后续步骤后会急着宣布当前步骤完成。解决办法不是一味增加说明而是先把当前步骤的完成标准变清楚如果完成标准天然模糊再把后续步骤藏到真正的上下文边界之后。GLOSSARY.md#L101-L127第四组概念处理“skill 怎么变烂”。Single Source of Truth是同一个意思只放在一个权威位置避免规则分叉Relevance是每一行都还服务当前 skillDuplication是同一个含义被写了多份Sediment是旧规则、旧例子、旧 workaround 像沉积层一样留在文件里Sprawl是内容即使都有效顶层也已经摊得太大No-Op是一行文字看似相关却完全不改变模型行为。它们共同提供了一套删减标准重复会制造多个事实源旧内容会沉积过长会稀释注意力无效指令会浪费上下文。这里最有价值的是No-Op因为它提醒我们不能改变行为的行就不该留在 skill 里。GLOSSARY.md#L145-L194这几组词连起来GLOSSARY.md就不只是术语表而是一张设计诊断图。写一个 skill 时可以顺着它问触发权交给谁内容放在哪一层完成线是否清楚后续步骤是否诱导抢跑哪些行是重复、沉积或 no-op。读者掌握这张图就不必只模仿 Matt 的具体 skill而能自己判断一个新 skill 为什么应该这样写。当前设计的代价这套仓库的优点是小、可改、可组合。代价是用户仍要知道当前处在哪个阶段。README 的 Reference 虽然列出了 user-invoked 和 model-invoked但如果没有ask-matt新用户仍会在grill-with-docs、prototype、to-prd、to-issues、triage之间犹豫。另一个代价是版本演化会改变分析结论。旧版里的diagnose已经变成diagnosing-bugswrite-a-skill被writing-great-skills取代zoom-out和caveman已从当前主线消失。分析这类仓库时不能只读目录快照必须先确认 plugin 清单、README 和当前分支。最终判断是这个仓库的设计价值不在于 skill 数量而在于它把 Agent 开发中的隐性工程动作显式化。每个 skill 至少要回答什么时候触发、拦住什么失败、读写什么状态、完成线在哪里、哪些内容应该留在当前上下文哪些应该延迟披露。writing-great-skills是这套判断的元 skill。