@namewta/speculo 0.1.21 → 0.2.1

package/template/vendor/matt-pocock/in-progress/writing-shape/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: writing-shape
+description: "写作，利用阶段——将原始素材塑造成一篇文章，逐段推进。"
+disable-model-invocation: true
+---
+
+<what-to-do>
+
+用户已经传递（或将传递）一个包含原始素材的 markdown 文件。将其视为输入素材堆——从整齐的碎片列表到无结构的散文堆再到转录稿，任何格式都可以。格式不重要。在做任何其他事之前从头到尾读完它。
+
+然后运行一个塑造会话，产出一篇独立的文章文档。这是**利用**阶段：探索已完成，素材堆已固定——承诺一个结构并挖掘素材堆来填充它。不要编辑原始素材文件——它对本技能是只读的。
+
+如果用户没有说明将文章保存到哪里，询问一次并记住路径。
+
+</what-to-do>
+
+<supporting-info>
+
+## 循环
+
+1. **读取素材堆。** 完整读取输入文件。形成对其内容的感觉。
+2. **确定前置条件。** 与用户确认读者走进来时知道什么——从一开始就已经**落地**的概念。其他所有概念必须由某个模块落地后，后续模块才能使用。参见[落地](#grounding)。
+3. **起草 2-3 个候选开头。** 每个开头应暗示文章的不同论点或角度。全部展示。迫使用户选择一个或组合一个混合体。选定的开头定义了文章其余部分必须完成的任务。
+4. **逐段推进。** 开头落地后，问"鉴于这个开头，读者接下来需要听到什么？"从素材堆中取材来回答。下一个模块只能依赖已落地的概念，并在落地时落地新的概念。争论下一个模块应采取的形式——段落、列表、表格、标注、引用、代码块。每种格式选择都应经过深思熟虑且有理有据。
+5. **边写边追加到文章文件。** 不要批量处理。在达成一致后立即写入每个段落或模块，以便用户看到文章正在成形。
+6. **循环步骤 4 直到文章完成。** 用户决定何时完成。
+
+## 落地
+
+每个**概念**必须在一个模块依赖它之前被**落地**：读者要么走进来时就知道它，要么在之前的模块中遇到它。一个试图使用未落地概念的模块会使读者迷失。单元是概念，而非表达它的词语——即使没有行话出现，一个模块也可能依赖读者尚未掌握的想法。当一个概念有一个名称——一个**术语**——落地它意味着同时传达想法和术语。
+
+概念通过两种方式之一被落地：
+
+- **前置**——在开头之前就已落地。读者自带。在开始时固定。
+- **引入**——某个模块建立它，从那时起，它对文章其余部分都是落地的。
+
+维护一个已落地概念的运行列表。当你问"读者接下来需要听到什么？"时，下一个动作所需的未落地概念本身就是答案：先落地它——在这里或之前的模块中——否则你无法做这个动作。这是比[从素材堆中取材](#pulling-from-the-pile)高一个层次的差距命名：那里是素材堆缺少材料；这里是文章缺少基础。
+
+重要的杠杆是：你让什么成为前置条件，以及你让什么在文章内部落地。前置条件要求太多会排斥读者；在内部落地太多则会导致开头淹没在定义中。在确定前置条件时与用户解决这个问题。
+
+## 对话感
+
+这是反向的追问会话。在构思阶段，问题是"你实际上观察到了什么？"这里的问题是"这篇文章实际上在论证什么，读者需要以什么顺序听到它？"回击。拒绝让薄弱的过渡溜过去。如果一个段落不值得存在，砍掉它。
+
+持续使用的具体招数：
+
+- "这个段落为读者做了什么前一个段落没做的事？"
+- "如果我删掉这个，什么会断裂？"
+- "这是散文，还是应该是列表？为什么是散文？"
+- "这句话在做两件事——拆分它或选择一件。"
+- "开头承诺了 X。我们已经漂移到了 Y。要么重新串联它，要么改变开头。"
+
+## 从素材堆中取材
+
+将原始素材视为采石场，而不是脚本。提取一个碎片，重新加工以适配周围段落，然后放置它。一个碎片可以被拆分到多个段落中，与另一个合并，或被改写。素材堆的工作是被开采；文章的工作是读起来像一个统一的声音。
+
+如果素材堆缺少文章需要的某些内容，明确说出差距："我们需要一个示例，素材堆里没有——现在给我一个，否则我们砍掉这一节。"
+
+## 应该实际进行的格式辩论
+
+在选择如何渲染一个模块时，与用户大声权衡以下取舍，而不是默默决定：
+
+- **散文 vs. 列表。** 散文承载论证；列表承载并列项。如果项目不是真正并列的，散文更好。如果是并列的，列表扫描更快。
+- **内联 vs. 标注。** 提示、警告和旁注放入标注（`> [!TIP]`、`> [!NOTE]`）——但仅当它们确实会干扰内联的主论证时。否则保持内联。
+- **表格 vs. 重复结构。** 如果相同结构重复 3 次以上且具有相同字段，用表格。否则用加粗引导词的散文。
+- **引用 vs. 改写。** 当原始措辞本身是重点时引用。当只有想法重要时改写。
+- **代码块 vs. 内联代码。** 多行、可运行或有说明性的 → 代码块。单个标记或标识符 → 内联。
+
+## 写作节奏
+
+每个模块达成一致后立即追加到文章文件。在每次写入之前从磁盘重新读取文件——用户可能在两次交互之间编辑了。永远不要盲目覆盖。如果用户想重写某个段落，在原位置编辑该特定段落；其余内容保持不变。
+
+## 范围之外
+
+- 挖掘素材堆中没有的新碎片（按"从素材堆中取材"的方式处理差距）。
+- 编辑原始素材文件。
+- 发布、为特定平台格式化、或添加用户未要求的 frontmatter。
+
+</supporting-info>

package/template/vendor/matt-pocock/productivity/README.md

@@ -0,0 +1,18 @@
+# 生产力
+
+通用工作流工具，不限于编码。
+
+## 用户调用
+
+只能由用户输入来访问（`disable-model-invocation: true`）。
+
+- **[grill-me](./grill-me/SKILL.md)** — 接受关于计划或设计的 relentless 访谈，直到决策树的每个分支都被解决。
+- **[handoff](./handoff/SKILL.md)** — 将当前对话压缩为交接文档，以便另一个 agent 可以继续工作。
+- **[teach](./teach/SKILL.md)** — 在多个会话中向用户教授新 skill 或概念，使用当前目录作为有状态的教学工作区。
+- **[writing-great-skills](./writing-great-skills/SKILL.md)** — 编写和编辑 skill 的参考：使 skill 可预测的词汇和原则。
+
+## 模型调用
+
+模型或用户均可访问（丰富的触发措辞使模型能够使用它们）。
+
+- **[grilling](./grilling/SKILL.md)** — relentlessly 访谈用户关于计划或设计，直到决策树的每个分支都被解决。

package/template/vendor/matt-pocock/productivity/grill-me/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: grill-me
+description: 一场无情的面试，用于打磨方案或设计。
+disable-model-invocation: true
+---
+
+运行一次 `/grilling` 会话。

package/template/vendor/matt-pocock/productivity/grilling/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: grilling
+description: 无情地盘问用户关于方案或设计的方方面面。当用户想在动手前对方案进行压力测试，或使用了任何 'grill' 触发短语时使用。
+---
+
+请对我进行无情的面试，深入探讨该方案的每一个方面，直到我们达成共识。沿设计树的每个分支逐步推进，逐个解决决策之间的依赖关系。每个问题都给出你的推荐答案。
+
+一次只问一个问题，等待我对每个问题给出反馈后再继续。一次问多个问题会让人困惑。
+
+如果某个*事实*可以通过探索代码库找到，请自行查找，不要来问我。但*决策*由我来做 —— 将每个决策提交给我并等待我的回答。
+
+在我确认我们已达成共识之前，不要执行该方案。

package/template/vendor/matt-pocock/productivity/handoff/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: handoff
+description: 将当前对话压缩为一份交接文档，供另一个 agent 接手继续工作。
+argument-hint: "下一个会话将用于什么？"
+disable-model-invocation: true
+---
+
+编写一份交接文档，总结当前对话，使新的 agent 可以继续此工作。保存到用户操作系统的临时目录 —— 而非当前工作区。
+
+在文档中包含一个"建议 skills"部分，列出建议 agent 调用的 skills。
+
+不要重复已被其他产物（规范、方案、ADR、issue、commit、diff）覆盖的内容，改用路径或 URL 引用它们。
+
+清除任何敏感信息，如 API 密钥、密码或个人身份信息。
+
+如果用户传入了参数，将其视为对下一个会话重点内容的描述，并据此定制文档。

package/template/vendor/matt-pocock/productivity/teach/GLOSSARY-FORMAT.md

@@ -0,0 +1,35 @@
+# GLOSSARY.md 格式
+
+`GLOSSARY.md` 是该教学工作区的规范语言。所有讲解、练习和学习记录都应遵守其术语。构建它本身就是学习的一部分：将一个概念压缩成精确的定义，是用户理解它的证据。
+
+## 结构
+
+```md
+# {主题} 术语表
+
+{对该术语表所涵盖主题的一两句话描述。}
+
+## Terms
+
+**Hypertrophy**：
+由反复训练过程中的机械张力和代谢压力驱动的肌肉增长。
+_Avoid_: Bulking, getting big
+
+**Progressive overload**：
+随着时间系统地增加对肌肉的需求 — 通过负荷、训练量或强度。
+_Avoid_: Pushing harder, levelling up
+
+**RPE (Rate of Perceived Exertion)**：
+对一组训练有多吃力的 1–10 分自评，10 表示力竭，8 表示还有两次重复的余力。
+_Avoid_: Effort score, intensity rating
+```
+
+## 规则
+
+- **仅在用户理解术语后添加。** 术语表是压缩知识的记录，不是用户可以阅读来学习的字典。如果用户刚接触一个概念，等到他们能正确使用它再将其提升到此。
+- **要有主见。** 当存在多个表示同一概念的词时，选择最好的那个，将其余列为应避免的别名。这就是语言压缩的方式。
+- **定义保持精炼。** 一到两句话。定义术语是什么，而不是它做什么或如何做。
+- **在定义中使用术语表自身的术语。** 一旦一个术语被收录在术语表中，在任何地方都优先使用它 — 包括在其他定义中。这就是后续理解复杂术语变得更容易的原因。
+- **当自然形成聚类时，用子标题分组**（例如 `## Anatomy`、`## Programming`）。当术语内在一致时，扁平列表也可以。
+- **明确标记歧义。** 如果一个术语在更广泛的领域中被宽松使用，注明本工作区的选择："在本工作区中，'set' 始终表示正式组 — 热身组单独跟踪。"
+- **随着理解深入而修订。** 用户在第一周写的定义到第六周可能是错的。就地更新；不要留下过时的条目。

package/template/vendor/matt-pocock/productivity/teach/LEARNING-RECORD-FORMAT.md

@@ -0,0 +1,46 @@
+# 学习记录格式
+
+学习记录存放在 `./learning-records/` 中，使用顺序编号：`0001-slug.md`、`0002-slug.md` 等。延迟创建目录 — 仅在第一条记录被写入时才创建。
+
+它们是教学领域的 ADR：捕获非显而易见的经验、关键洞察以及将会指导未来会话的既有知识声明。它们用于计算最近发展区。
+
+## 模板
+
+```md
+# {对学到或确立的内容的简短标题}
+
+{1-3 句话：学到了什么（或确立了哪些既有知识），以及为什么它对未来会话重要。}
+```
+
+这就是全部格式。一条学习记录可以就是一个段落。其价值在于记录_这个_知识现在已知，以及_为什么_它会改变接下来教什么 — 而不是填满各个部分。
+
+## 可选部分
+
+仅当它们真正增加价值时才包含这些。大多数记录不需要它们。
+
+- **Status** 前置元数据（`active | superseded by LR-NNNN`）— 当早期的理解后来被发现是错误的并被替换时有用。
+- **Evidence** — 用户如何展示了理解（回答了一个问题、完成了一个练习、引用了先前经验）。当声明可能被重新审视时有用。
+- **Implications** — 这为未来会话解锁了什么或排除了什么。当不显而易见时值得记录。
+
+## 编号
+
+扫描 `./learning-records/` 中的最高现有编号，然后加 1。
+
+## 何时编写学习记录
+
+当以下任一为真时编写：
+
+1. **用户展示了对某个非平凡事物的真正理解** — 不仅仅是接触，而是有证据表明他们可以正确使用该概念。这为接下来教什么设定了新底线。
+2. **用户披露了既有知识** — "我已经知道 X。"记录下来，这样未来的会话不会重复教它。同时记录所声称的_深度_。
+3. **一个误解被纠正了** — 用户之前相信了错误的东西，现在明白了为什么。这些是高价值的：它们预测了相关主题未来的绊脚石。
+4. **使命因学习而转变** — 用户发现他们关心的东西与之前想的不同。交叉链接到 [[MISSION.md]] 并更新它。
+
+### 什么不算
+
+- 仅仅覆盖过的材料。覆盖不等于学习。等有证据再说。
+- 任何已简明地作为术语定义捕获在 [[GLOSSARY.md]] 中的内容。不要重复。
+- 逐次会话的活动日志。学习记录不是日志 — 它们是决策级别的洞察。
+
+## 取代
+
+当后来的记录与之前的记录矛盾时（用户的理解深化了或被纠正了），将旧记录标记为 `Status: superseded by LR-NNNN`，而非删除它。理解如何演变的历史本身就是有用的信号。

package/template/vendor/matt-pocock/productivity/teach/MISSION-FORMAT.md

@@ -0,0 +1,31 @@
+# MISSION.md 格式
+
+`MISSION.md` 位于工作区根目录。它捕获用户学习该主题的_原因_。每个教学决策 — 接下来教什么、呈现哪些资源、设计哪些练习 — 都应追溯到此文档。
+
+## 模板
+
+```md
+# Mission: {Topic}
+
+## Why
+{1-3 句话。用户正在追求的具体的、真实世界中的目标。当拥有这项技能时，他们的生活或工作中会发生什么改变？避免抽象的表述如"理解 X" — 追问底层的成果。}
+
+## Success looks like
+- {用户将能够做到的一件具体的、可观察的事情}
+- {另一件具体的事情}
+- {……}
+
+## Constraints
+- {时间、预算、既有承诺、学习偏好，任何限制方法的边界条件}
+
+## Out of scope
+- {用户明确不想现在追求的相邻主题 — 保护最近发展区}
+```
+
+## 规则
+
+- **每个工作区一个使命。** 如果用户想学习两个不相关的东西，那就是两个工作区。
+- **具体优于抽象。** "十月份之前跑完半程马拉松"优于"变得更健康"。"给我的团队交付一个 Rust CLI 工具"优于"学习 Rust"。
+- **对模糊性进行追问。** 如果用户无法说清为什么，在写任何东西之前和他们面谈。一个糟糕的使命比没有使命更糟。
+- **当现实改变时修订。** 使命会改变。当用户的目标移动时，更新此文件 — 不要让一个过时的使命引导未来的会话。
+- **保持简短。** 如果 `MISSION.md` 超过一屏，它已经不再是罗盘，而是变成了计划。

package/template/vendor/matt-pocock/productivity/teach/RESOURCES-FORMAT.md

@@ -0,0 +1,32 @@
+# RESOURCES.md 格式
+
+`RESOURCES.md` 是该主题的精选可信来源集合。讲解中的知识应从此处提取，而非从参数化猜测中获取。智慧来自此处列出的社区。
+
+## 结构
+
+```md
+# {主题} 资源
+
+## Knowledge
+
+- [书籍：_The Science and Practice of Strength Training_ — Zatsiorsky & Kraemer](https://example.com)
+  关于编排与适应的基础文本。适用：任何与周期化、恢复、强度区间相关的内容。
+- [文章："How Much Should I Train?" — Greg Nuckols (Stronger By Science)](https://example.com)
+  关于训练量参考点的循证综述。适用：每周每个肌群的组数目标。
+
+## Wisdom (Communities)
+
+- [r/weightroom](https://reddit.com/r/weightroom)
+  高信号 subreddit，严格管控伪科学。适用：训练方案评价、平台期排除。
+- 本地：周二在 {健身房名称} 的力量课程
+  适用：举重的实时指导反馈。
+```
+
+## 规则
+
+- **仅高信任度来源。** 偏好一手来源、公认专家、同行评审工作和具有强管控的社区。如果某个资源是伪装成教育的营销内容，排除它。
+- **为每个条目注释。** 一个裸链接在三个月后毫无用处。添加一行：它涵盖什么以及何时使用它。
+- **按 Knowledge / Wisdom 分组。** 对应 [SKILL.md](./SKILL.md) 中的理念。一个资源只出现在一个组中是没问题的。
+- **明确标记缺口。** 如果使命所需的某个领域没有好的资源，写一个 `## Gaps` 部分列出缺失的内容。这将驱动未来的搜索。
+- **无情地修剪。** 一个被证明是错的、肤浅的或偏离使命的资源应该被移除，而不是被埋没。五个精选来源比三十个平庸的要好。
+- **记录社区偏好。** 如果用户选择不加入社区，在此注明，这样未来的会话不会不断建议它们。

package/template/vendor/matt-pocock/productivity/teach/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: teach
+description: 在此工作区内教授用户一项新技能或概念。
+disable-model-invocation: true
+argument-hint: "你想学习什么？"
+---
+
+用户请你教授他们一些东西。这是一个有状态的请求 —— 他们打算跨多个会话学习该主题。
+
+## 教学工作区
+
+将当前目录视为教学工作区。他们的学习状态通过该目录中的若干文件来记录：
+
+- `MISSION.md`：记录用户对该主题感兴趣*原因*的文档。所有教学都应以此为基础。使用 [MISSION-FORMAT.md](./MISSION-FORMAT.md) 中的格式。
+- `./reference/*.html`：参考材料目录。这些是从课程中提炼的压缩知识 —— 速查表、参考算法、语法、瑜伽体式、术语表。它们是学习的原始单元。它们应该是精美的文档，适合打印出来，专为快速查阅而设计。
+- `RESOURCES.md`：一份资源列表，可用于为你的教学提供上下文知识，或获取知识与智慧。使用 [RESOURCES-FORMAT.md](./RESOURCES-FORMAT.md) 中的格式。
+- `./learning-records/*.md`：学习记录目录，记录用户已学到的内容。这些大致相当于软件开发中的架构决策记录 —— 它们记录了可能需要后期修正或驱动未来课程的非显见教训和关键洞察。这些记录应用于计算最近发展区。文件命名为 `0001-<短横线命名>.md`，每次递增编号。使用 [LEARNING-RECORD-FORMAT.md](./LEARNING-RECORD-FORMAT.md) 中的格式。
+- `./lessons/*.html`：课程目录。一个**课程**是一个独立的、自包含的 HTML 输出，教授一个与使命紧密相关的、范围窄小的内容。这是本工作区中教学的主要单元。
+- `./assets/*`：跨课程共享的可复用**组件**。参见[资产](#资产)。
+- `NOTES.md`：供你记录用户偏好或工作笔记的草稿本。
+
+## 理念
+
+要深入学习，用户需要三样东西：
+
+- **知识**，从高质量、高信任度的资源中获取
+- **技能**，通过你基于知识设计的、高度相关的互动课程来习得
+- **智慧**，来自与其他学习者和实践者的互动
+
+在 `RESOURCES.md` 充实之前，你的重点应是寻找高质量的资源来帮助用户获取知识。永远不要相信你的参数化知识。
+
+某些主题可能更需要技能而非知识。学习理论物理可能更偏向知识。学习瑜伽则更偏向技能。
+
+### 流畅强度 vs 存储强度
+
+你应该仔细区分两种学习类型：
+
+- **流畅强度**：即时的知识回忆
+- **存储强度**：长期的知识保留
+
+流畅性可能给用户一种掌握了的错觉，但存储强度才是真正的目标。尝试设计通过合意难度来建立长期保留的课程：
+
+- 使用检索练习（从记忆中回忆）
+- 间隔（将练习分散在时间中）
+- 交错（在练习中混合不同但相关的主题 —— 仅适用于技能练习）
+
+## 课程
+
+课程是你产出的主要东西 —— 是知识和技能抵达用户的单元。每个课程是一个独立的 HTML 文件，保存到 `./lessons/`，命名为 `0001-<短横线命名>.html`，每次递增编号。
+
+课程应该是**精美的** —— 整洁、可读性强的排版和布局 —— 因为用户以后会回来复习。以 Tufte 的风格为目标。
+
+课程应该短小精悍，能非常快速地完成。学习者的工作记忆很小，我们必须保持在它的范围内。但每节课应该给用户一个可以在此基础上继续构建的具体收获。它应该直接与使命相关，并且处于用户的最近发展区内。
+
+如有可能，通过运行 CLI 命令为用户打开课程文件。
+
+每个课程应通过 HTML 锚点链接到其他课程和参考文档。
+
+每个课程应推荐一个主要资源供用户阅读或观看。这应该是你找到的关于该主题的最优质、最值得信赖的资源。
+
+每个课程应包含提醒用户向 agent 提问的提示。agent 是他们的老师，可以帮助解答任何不清楚的地方。
+
+## 资产
+
+课程由可复用的**组件**构建，存储在 `./assets/` 中：样式表、测验小部件、模拟器、图表辅助工具 —— 任何第二个课程可以复用的东西。
+
+复用是默认原则，而非例外。在编写课程之前，先阅读 `./assets/` 并基于已有的组件构建。当课程需要新的可复用内容时，将其编写为 `./assets/` 中的组件并链接它 —— 永远不要将未来课程会重复的代码内联。
+
+共享样式表是每个工作区获得的第一个组件：每个课程都链接它，使课程看起来像一个统一的课程体系，而非一堆零散的单品。随着工作区的成长，组件库也应随之成长。
+
+## 使命
+
+每个课程都应与使命相关联 —— 即用户对该主题感兴趣的原因。
+
+如果用户对使命不明确，或 `MISSION.md` 未填写，你的首要任务应该是询问用户为什么想学这个。
+
+未能理解使命将意味着知识获取没有扎根于现实世界目标。课程会感觉过于抽象。你将无法判断用户下一步应该做什么。
+
+随着用户技能和知识的增长，使命可能会改变。这是正常的 —— 务必更新 `MISSION.md` 并添加一条学习记录来记录这一变化。在更改使命前请与用户确认。
+
+## 最近发展区
+
+每节课，用户应始终感觉他们被"恰到好处"地挑战。
+
+用户可能会指定他们想学的确切内容。如果没有，通过以下方式找出他们的最近发展区：
+
+- 阅读他们的 `learning-records`
+- 根据他们的使命找出正确的教授内容
+- 教授处于其最近发展区内的最相关内容
+
+## 知识
+
+课程应围绕用户将学习的技能来设计。课程中的知识应仅限于习得该技能所需的内容。你先教授知识，然后让用户通过互动反馈循环来练习技能。
+
+知识应首先从可信资源中收集。使用 `RESOURCES.md` 来跟踪它们。课程应遍布引用 —— 即支持任何主张的外部资源链接。这增加了课程的可信度。
+
+对知识获取来说，难度是敌人。它会消耗你理解所需的工作记忆。
+
+## 技能
+
+如果说知识的核心是获取，那么技能的核心就是持久性和灵活性。让知识扎根。
+
+对技能获取来说，难度是工具。努力检索才是建立存储强度的方式。技能应通过互动课程来教授。你有以下几种工具可供使用：
+
+- 互动课程，使用测验和轻量级浏览器内任务
+- 引导用户完成一系列现实世界操作步骤的课程（例如，瑜伽体式）
+
+每种方式都应基于**反馈循环**，让用户获得对其表现的反馈。这个反馈循环应尽可能紧密，即时提供反馈 —— 最好是自动化的。
+
+对于测验，每个答案应恰好包含相同数量的单词（如可能，也包含相同数量的字符）。不要通过格式给用户任何关于答案的线索。
+
+## 获取智慧
+
+智慧来自真正的现实世界互动 —— 在学习环境之外检验你的技能。
+
+当用户提出一个看似需要智慧的问题时，你的默认姿态应是尝试回答 —— 但最终要委托给一个**社区**。
+
+社区是用户可以在现实世界中检验其技能的场所（线上或线下）。这可能是一个论坛、一个 subreddit、一个线下课程（预算允许的话）或一个本地兴趣小组。
+
+你应尝试找到用户可加入的高声望社区。如果用户表示不想加入社区，请尊重这一意愿。
+
+## 参考文档
+
+在创建课程的同时，你也应创建参考文档。课程可以引用这些文档 —— 它们有助于跟踪跨课程有用的知识原始单元。
+
+课程很少会被重新翻阅 —— 参考文档才会。它们应该是课程的压缩精华，采用专为快速查阅设计的格式。
+
+某些学习主题天然适合参考：
+
+- 编程的语法和代码片段
+- 流程的算法和流程图
+- 瑜伽的体式和序列
+- 健身的练习和训练计划
+- 任何有自己术语体系的主题的术语表
+
+特别是术语表，是必不可少的参考。一旦创建，每节课都应遵循它。
+
+## `NOTES.md`
+
+用户有时会表达他们希望如何被教授，或你应注意的事项。这是记录这些偏好的地方，以便你在设计课程或与用户协作时可以回头参考。

package/template/vendor/matt-pocock/productivity/writing-great-skills/GLOSSARY.md

@@ -0,0 +1,201 @@
+# 术语表 — 构建优秀技能
+
+关于什么造就优秀技能的领域模型。技能的存在是为了从随机系统中驯服确定性；根本美德是 **Predictability**（可预测性），以下每个术语都是调节它的一根杠杆。这是 [`writing-great-skills`](SKILL.md) 的公开参考。
+
+术语按轴分组：**Invocation**（调用，技能如何被触达）、**Information Hierarchy**（信息层级，其内容如何排列）、**Steering**（引导，Agent 的运行时行为如何被塑造）和 **Pruning**（修剪，如何保持精炼）。每个**失败模式**都紧邻治愈它的杠杆，标记为 _失败模式_。
+
+任何定义中的**粗体术语**本身也在本术语表中定义；通过其标题找到它们。
+
+## Predictability
+
+技能使 Agent 在每次运行时以相同的*方式*行为的程度 — 相同的过程，而不是相同的输出（一个头脑风暴技能应该*可预测地*发散；其 token 不同，但行为不变）。每个其他术语所服务的根本美德 — 成本和可维护性是它的症状，而非对手。
+
+_避免使用：_ consistency, reliability, robustness, output-determinism
+
+## Invocation
+
+技能如何被触达 — 以及你为选择付出的两种负载。
+
+### Model-Invoked
+
+一种保留其 **description** 字段的技能，使 Agent 能够看到并自主触发它 — 而人类仍然可以输入其名称，因此模型调用总是_包含_用户触达。不存在仅模型的状态：描述只会_增加_ Agent 发现能力，从不会移除人类的。这种可发现性的代价是每轮持续付出的**上下文负载**。可被其他技能触达，因为使其对 Agent 可发现的描述也使其可被调用。一个内容全是 **reference** 的模型调用技能也是共享参考的一个归宿：另一个技能可以调用它，因此多个技能需要的参考集中存放。仅当 Agent 必须自行触发技能时才选择模型调用；如果它从不自动触发，删除描述就不用付出上下文负载。
+
+_避免使用：_ ability, tool, capability
+
+### User-Invoked
+
+一种**描述**被剥离的技能 — 对 Agent 不可见，只能由人类输入其名称来触达（用户_独有_，而**模型调用**是用户_和 Agent_）。以 Agent 可发现性换取零**上下文负载**。因为没有描述，除人类之外没有任何东西可以触达它：没有其他技能可以触发它。
+
+_避免使用：_ procedure, workflow, command
+
+### Description
+
+技能的机器可读触发器，以及**模型调用**技能被迫始终保持加载的一个**上下文指针**。它的存在本身就_是_调用轴：保留它，技能就是模型调用的（且可被其他技能触达）；删除它，技能就是**用户调用的**，只有人类能触达。模型调用技能的**上下文负载**的来源。
+
+_避免使用：_ frontmatter, summary
+
+### Context Pointer
+
+Agent 上下文中持有的一个引用，命名一些上下文外的材料并编码了触达它的条件。**描述**是顶层上下文指针（上下文窗口 → 技能）；指向已披露文件的指针是同一对象向下一级。它的_措辞_决定了 Agent 何时触达 — 以及_有多可靠_ — 而非目标。一个措辞薄弱的指针后面跟着一个必须触达的目标就是一个方差 bug：先修正措辞，只有在改进失败时才内联材料。
+
+_避免使用：_ link, reference, import
+
+### Context Load
+
+**模型调用**技能强加在 Agent 上下文窗口上的成本 — 其始终加载的**描述**，消耗 token 和注意力。**用户调用**技能通过没有描述所避免的东西，也是拆分成更多模型调用技能的刹车。
+
+_避免使用：_ token cost, context bloat
+
+### Cognitive Load
+
+**用户调用**技能强加在人类身上的成本 — 他们必须记住的内容：哪些技能存在以及何时使用每个（人类就是索引）。**模型调用**通过 Agent 可发现性所移除的东西，也是拆分成更多用户调用技能的刹车。不是一个要最小化的成本：它是人类代理权的代价，是一些技能保持用户调用的原因。在人类判断重要的地方花费它；在它不重要的地方移除它。
+
+_避免使用：_ human index, burden, overhead
+
+### Router Skill
+
+一个**用户调用**技能，其工作是指向你的其他用户调用技能 — 命名每个技能以及何时使用它 — 这样人类只需记住一个技能，而不是很多。它只能提示，永远不能触发它们：用户调用技能没有**描述**，所以除人类之外没有任何东西可以触达它们。当用户调用技能增多时，对**认知负载**的治愈方案。
+
+_避免使用：_ dispatcher, menu, registry, index, router procedure
+
+### Granularity
+
+你拆分技能的细度。更细的拆分消耗两种负载之一：更多的**模型调用**技能消耗**上下文负载**（更多描述挤占窗口，竞争注意力）；更多的**用户调用**技能消耗**认知负载**（更多需要人类记住并触达的东西）。两个切割指导拆分。按**调用方式**切割，在你有独特的**引导词**来触发它时拆分一个模型调用技能 — 一个你在提示中实际使用的触发词。按**序列**切割，当一个步骤的**后续步骤**需要被隐藏时拆分一段**步骤**，因为在自身上下文中隔离它清除了后面的内容。警惕反向操作：合并序列会将每个步骤的后续步骤暴露给后续内容，诱发过早完成。
+
+_避免使用：_ chunking, modularity
+
+## Information Hierarchy
+
+技能的内容如何排列，以及每部分内容处于阶梯的哪一级。
+
+### Information Hierarchy
+
+技能的内容按 Agent 对它的即时需求程度排列 — 一条单一的阶梯，由两个切割产生：在文件中还是指针后面，以及是步骤还是参考。阶梯的各级：
+
+- **Steps（步骤）** — 在文件中，主要层级
+- **Reference（参考）**，在文件中 — 次要层级
+- **Reference（参考）**，已披露的 — 在**上下文指针**后面
+
+一个没有**步骤**的技能只使用底下两个层级 — 通常是一个合理的扁平同级组合（例如检查清单的每条规则都在同一层级），这是一个好的安排，不是坏味道。层级独立于调用方式：一个技能可以是模型调用或用户调用的，无论它是全步骤、全参考或两者都有。当技能有步骤时，应该披露的文件内参考会淹没它们，并使遵循它们变成掷硬币 — 这是方差杠杆，而不仅仅是可读性的杠杆。保持阶梯顶部清晰；把你能够推下去的都推下去。
+
+_避免使用：_ structure, organization, layout
+
+### Steps
+
+Agent 执行的有序动作 — 当技能有步骤时，是其内容的主要层级，也是它值得放在 SKILL.md 中的部分。不是每个技能都有步骤：一个技能可以是全步骤（`tdd`）、全**参考**（一个检查清单），或两者都有，与调用方式无关。每个步骤结束于一个**完成标准**，清晰或模糊。
+
+_避免使用：_ workflow, instructions, choreography
+
+### Reference
+
+Agent 按需参考的材料 — 定义、事实、参数、示例、条件指令。当技能有**步骤**时，它是次要的；当技能没有步骤时，它是全部内容；或者它完全存在于任何技能之外 — 参见**外部参考**。通过**上下文指针**触达，是**渐进式披露**的首选候选。
+
+_避免使用：_ supporting material, docs, background
+
+### External Reference
+
+存在于技能系统之外的**参考** — 一个普通文件，没有**描述**，没有**步骤**，不可调用 — 任何技能都可以指向它。是不需要自己触发的共享参考的归宿，也是两个**用户调用**技能可以使用的唯一共享归宿，因为它们都没有描述，所以彼此不能调用对方。
+
+_避免使用：_ doc, resource, knowledge base
+
+### Progressive Disclosure
+
+将**参考**沿阶梯向下移动 — 移出 SKILL.md，放到**上下文指针**后面 — 使顶部保持清晰。主要不是 token 优化；它是**信息层级**如何被保护的。由**分支**授权：只披露某些分支需要的材料，内联每条路径都需要的材料，如果指针对于必须触达的材料触发不可靠，则改进其措辞，只有在改进失败时才将其拉回内联。
+
+_避免使用：_ lazy loading, chunking
+
+### Co-location
+
+将 Agent 需要一次性使用的材料放在一个地方 — 一个概念的定义、规则和注意事项放在单个标题下，而不是分散在文件中 — 这样读取一部分会将其邻居一并带入。是**信息层级**的文件内伴侣：层级排列了每部分内容_有多深_；共置决定了它在那里_和什么放在一起_。没有公式来确定一批**参考**的正确格式；检验标准是技能应该读起来像为 Agent 编写的文档，而组合在一起的材料读起来有这种效果，分散的材料则没有。与**重复**不同：重复是将一个含义在两地重复，而分散是将单一含义碎裂到多处以避免重复。
+
+_避免使用：_ grouping, clustering, cohesion
+
+### Sprawl
+
+_失败模式。_ 一个简单过长的技能 — SKILL.md 中行数太多 — 无论这些行是否过时或重复。即使是一个全活跃、全独特的技能也可能蔓延。它消耗可读性（Agent 在行动前必须翻阅更多，注意力在多余内容上稀释）、可维护性（每一行额外内容都是多一个需要保持**相关性**的行）和 token。治愈方案是**信息层级**：将**参考**推到**上下文指针**后面，并按**分支**或序列拆分，这样每条路径只携带它需要的。与**沉淀**不同（长度来自过时内容的积累）和**重复**不同（长度来自重复的含义）— 蔓延就是长度本身，不论其原因。
+
+_避免使用：_ bloat, length, size, verbosity
+
+## Steering
+
+塑造 Agent 运行时行为朝向**可预测性**的杠杆。
+
+### Branch
+
+技能可以被调用的不同方式 — 技能处理的一种情况 — 因此不同的运行通过它走不同的路径。一个有很多步骤的技能可能携带多个分支；一个线性的技能没有分支。
+
+_避免使用：_ path, case, fork
+
+### Leading Word
+
+一个紧凑的概念 — 也称为 _Leitwort_ — 已经存在于模型的预训练中，Agent 在运行技能时用它来思考。它通过调用模型已经持有的先验知识，以最少的 token 编码一个行为原则（例如 _lesson_、_最近发展区_、_战争迷雾_、_曳光弹_）。作为一个 token 重复，从不是作为一个句子，它在整个技能中累积一个分布式定义，并锚定一整块行为区域。如果你清楚地定义它，自己造一个也可以，但一个编造的词不招募任何先验知识 — 你付出的定义 token 是一个预训练词免费提供的。优先找到现有的词。
+
+引导词在两个方面服务于**可预测性**。在正文中它锚定**执行** — Agent 每次该概念出现时都采用相同的行为，在扁平参考内部它将注意力聚焦到一类要寻找的东西上，每次运行都招募正确的检查。在**描述**中它锚定**调用** — 且不仅在技能内部：当同一个词存在于你的提示、你的文档和你的代码库中时，Agent 将该共享语言与技能关联起来，并更可靠地触发它。用你真正在想要该技能时使用的引导词来措辞一个描述。
+
+_避免使用：_ keyword, term, motif
+
+### Completion Criterion
+
+告诉 Agent 一个工作单元已完成的条件 — 它用来判断的目标。两个属性使其成为杠杆而不仅仅是一个质量。其**清晰度**（Agent 能否区分完成与未完成？）抵抗**过早完成** — 一个模糊的界限（"理解已达成"）让 Agent 声明完成并滑到下一步；这个轴需要_步骤_才能咬合，因为过早完成是步骤之间的失败。其**要求度**（它要求多少）设定**背后的工作量** — "每个修改过的模型都被考虑"强制了彻底的工作，而"产出一个变更列表"则不会 — 而这个轴是_不_与步骤绑定的：它也可以约束一批扁平参考，这就是没有步骤的技能如何仍然承载一个穷尽性标准（"每条规则都被应用"）。最强的标准既是可检查的又是穷尽的。
+
+_避免使用：_ done condition, exit condition, stopping rule
+
+### Legwork
+
+Agent 在单一步骤内幕后的工作 — 读取文件、探索代码库、进行变更、挖掘它需要的东西而不是推卸给用户。它存在于步骤结构之下：从不写作自己的步骤，潜伏在措辞中，由 Agent 而非技能控制。是**后续步骤**跨步骤拉力的步骤内对应物。由一个**引导词**（_全面_、_彻底_）或要求工作是穷尽的**完成标准**来提升 — 包括应用于扁平参考的要求轴，这正是驱动一个扁平参考技能覆盖其所有层级的原因。当该要求缺失或**过早完成**将步骤截断时变得薄弱。
+
+_避免使用：_ scope, effort, diligence, coverage
+
+### Post-Completion Steps
+
+当前步骤之后的**步骤**。可见时，它将 Agent 向前拉入**过早完成** — 看到得越多，拉力越强；防御方法是通过将步骤序列一分为二来隐藏它们。
+
+_避免使用：_ horizon, fog of war, lookahead
+
+### Premature Completion
+
+_失败模式。_ 在当前步骤真正完成之前结束它，因为 Agent 的注意力滑向了"完成"而非工作本身。是一个步骤间失败：它需要**步骤**才能发生 — 一个没有步骤的技能提前退出不是过早完成，而是未满足要求下的薄弱的**背后工作量**。两股力量之间的拉锯战：可见的**后续步骤**（向前的拉力）和**完成标准**的清晰度（抵抗力 — 一个清晰、可检查的界限能抵抗；一个模糊的界限则会失守）。模糊性是必要条件：一个清晰的界限无论后面还有多少步骤可见都能抵抗拉力，所以一个从不匆忙的步骤无需防御。两个杠杆控制一个需要防御的步骤，但按顺序使用：**先改进界限** — 它是局部的且成本低。只有当标准是不可约的模糊_且_你确实观察到匆忙时才**隐藏后续步骤** — 而隐藏只跨真实的上下文边界才有效（用户调用的交接或子 Agent 分发；内联的模型调用会将后续步骤留在上下文中，什么也清除不掉）。是薄弱背后工作的一个原因，但与之不同：即使步骤运行到完全完成，背后工作也可能薄弱。
+
+_避免使用：_ premature closure, the rush, rushing, shortcutting
+
+### Negation
+
+_失败模式。_ 通过禁止来引导 — 告诉 Agent _不要_ 做什么 — 这将被禁止的行为拖入上下文，使其_更_可用，而非更少。_不要想大象_，大象就是一切；_绝不写冗长的注释_，冗长就是 Agent 刚刚读到的模式。否定是一个弱修饰语，被强烈激活的概念碾压，因此禁令半读作做某事的指令。其**引导词**就是_大象_：任何禁令唤入框架的东西。治愈方案：提示**正面** — 描述目标行为（"写单行注释"）使被禁止的行为永远不被说出。仅当你无法正面表述的行为需要一个硬护栏时，禁令才有存在价值；即使如此，也要搭配正面目标，使注意力落在要做什么上。
+
+_避免使用：_ ironic rebound, don't-prompting, the pink elephant
+
+## Pruning
+
+保持技能精炼 — 每种疗法与其治愈的失败配对。
+
+### Single Source of Truth
+
+每个含义恰好在唯一的一个权威位置上存在的期望状态，这样对技能行为的变更就是对一处地方的变更。**重复**是对它的违反。
+
+_避免使用：_ home, canonical location
+
+### Duplication
+
+_失败模式。_ 同一含义被赋予了多于一个**单一事实来源**。它消耗可维护性（变更一处，你必须变更其他地方）、消耗 token，并夸大了显著性 — 重复一个含义将它在阶梯上的权重抬升到超过其真实排名。是一个**引导词**的意外反面，引导词通过重复一个 token 来有意提升注意力，从不重复含义。
+
+_避免使用：_ repetition, redundancy
+
+### Relevance
+
+一行内容是否仍然承载技能所做的事情 — 决定保留什么的镜头。一行内容失去相关性，要么是因为它从不承载任务（仅仅是说明，或一个应该被披露的**分支**），要么是因为它变得过时：随着它所描述的行为或世界的变化而飘离。更短的技能更容易保持相关，因为每一行检查成本更低。与**空指令**不同：相关性询问一行是否承载任务，而不是它是否改变行为。
+
+_避免使用：_ load-bearing, staleness, freshness
+
+### Sediment
+
+_失败模式。_ 旧内容层层堆积在技能中永不清理，因为添加感觉安全而移除感觉有风险 — 于是过时和不相关的行积累，你必须穿过它们才能找到仍然活跃的内容。任何没有修剪纪律的技能的默认命运；**相关性**的缓慢侵蚀，与**重复**的重复含义相对。
+
+_避免使用：_ accretion, bloat, cruft, rot
+
+### No-Op
+
+_失败模式。_ 一条不改变任何东西的指令，因为模型默认已经做了 — 你付出负载告诉 Agent 它本来就会做的事。检验标准：一行是否改变行为与默认相比？一行可以是完全**相关**的但仍然是一个空指令。那些使**引导词**免费的相同先验知识使空指令毫无价值。
+
+引导词是一种_技术_；No-Op 是对一行的_裁决_ — 它们有交集。一个太弱而无法击败默认的引导词是空指令（_be thorough_ 当 Agent 已经相当彻底时），修复方案是一个通过裁决的更强的词（_relentless_），而不是不同的技术。因此 No-Op 检验 — 它改变行为与默认相比了吗？— 也是你评估一个引导词是否赢得其重复度的方式。这是模型相对的，而非读者相对的：两个对一行是否为空指令有分歧的人，对默认有分歧，通过运行技能来解决，而非通过辩论。
+
+_避免使用：_ redundant instruction, restating the obvious, belaboring