@netpilot/skills 0.3.2 → 0.4.0

package/skills/writing-great-skills/references/glossary.md

@@ -0,0 +1,279 @@
+# Glossary — Building Great Skills
+
+这是高质量 skill 的 domain model。Skill 试图从 stochastic system 中约束出 determinism；根本美德是 **Predictability**，下面每个术语都是它的杠杆。本文件是 [`writing-great-skills`](../SKILL.md) 的 disclosed reference。
+
+术语按四条轴组织：**Invocation**（如何到达 skill）、**Information Hierarchy**（如何安排内容）、**Steering**（如何塑造运行时行为）与 **Pruning**（如何保持精炼）。每个 failure mode 都放在能够处理它的杠杆附近，并标记为 _Failure mode_。
+
+任何定义中的**粗体术语**也在本 glossary 中定义，可按标题查找。
+
+## Predictability
+
+Skill 让 agent 每次以相同**方式**行动的程度：相同的是过程，不是输出。Brainstorming skill 应该可预测地产生不同想法；tokens 会变化，行为模式不会。Predictability 是其他术语共同服务的根本美德；成本和可维护性是它的结果，不是与它竞争的目标。
+
+_Avoid_：一致性、可靠性、鲁棒性、输出确定性
+
+## Invocation
+
+Skill 如何被到达，以及这个选择支付的两种负载。
+
+### Model-Invoked
+
+向模型暴露 **Description** 的 skill，因此 agent 可以自主启动它，用户也仍可显式输入名称。不存在“只能由模型调用”的状态：模型可见性只增加 agent discovery，不会取消人的入口。
+
+Model-Invoked skill 在每轮支付永久 **Context Load**，换取可发现性。其他 skills 也能到达它；如果其内容全是 **Reference**，它还可以成为多个 skills 共享 reference 的一个家。
+
+机制：`SKILL.md` 省略 `disable-model-invocation`，`agents/openai.yaml` 设置 `policy.allow_implicit_invocation: true`，Description 使用模型侧 trigger phrasing。只有 agent 必须自行到达它时才选此模式；永远只手动触发的 skill 不应支付这笔 Context Load。
+
+_Avoid_：能力、工具、功能
+
+### User-Invoked
+
+只由人显式输入名称启动的 skill。它的 Description 对模型隐藏，因此 agent 与其他 skills 都不能启动它；用户仍可以从目录或 UI 看到一行人类摘要。
+
+User-Invoked skill 用零 **Context Load** 换取 **Cognitive Load**：用户自己是索引，必须记得有哪些入口及何时使用。机制：`SKILL.md` 设置 `disable-model-invocation: true`，`agents/openai.yaml` 设置 `policy.allow_implicit_invocation: false`。
+
+_Avoid_：procedure、workflow、command
+
+### Description
+
+Skill 的机器可读触发器，也是 Model-Invoked skill 唯一被迫始终加载的 **Context Pointer**。在概念上，模型是否能看见 Description 决定 invocation axis；在本项目的双宿主实现中，frontmatter 仍保留人类可读 description，并用两宿主对应 flags 控制模型可见性。
+
+Model-Invoked Description 的存在制造 **Context Load**；User-Invoked description 只是目录和 UI 摘要，不承担模型触发。
+
+_Avoid_：frontmatter、摘要
+
+### Context Pointer
+
+留在 agent context 中的一条指针：它命名 context 外的材料，同时编码何时到达它。Description 是顶层 Context Pointer（context window → skill）；指向 disclosed file 的说明是下一层同类对象。
+
+决定到达时机与可靠性的是 pointer 的措辞，不是目标文件。必需材料藏在弱 pointer 后面属于 variance bug：先强化条件和动词；只有仍不可靠时才把材料拉回 inline。
+
+_Avoid_：链接、引用、import
+
+### Context Load
+
+Model-Invoked skill 对 agent context window 施加的成本：始终加载的 Description 同时消耗 tokens 与注意力。User-Invoked skills 通过让 Description 对模型不可见而避开它；它也是把更多 skills 拆成 model-invoked 时的制动器。
+
+_Avoid_：token cost、context bloat
+
+### Cognitive Load
+
+User-Invoked skill 对人的成本：用户必须记住哪些 skills 存在、何时到达每一个。Model invocation 可以移除这笔成本。
+
+Cognitive Load 不是必须最小化的坏事；它是 human agency 的价格，也是某些 skills 应保持 User-Invoked 的原因。需要人类判断时支付它，不需要时通过 model invocation 或 Router Skill 移除。
+
+_Avoid_：human index、burden、overhead
+
+### Router Skill
+
+一个 User-Invoked skill，负责列出其他 User-Invoked skills 及其适用时机，使用户只需记住一个入口。Router 只能提示，不能启动这些入口：User-Invoked skill 的 Description 对模型不可见，只有人能到达。它是 user-invoked 数量增加后处理 Cognitive Load 的方法。
+
+_Avoid_：dispatcher、menu、registry、index、router procedure
+
+### Granularity
+
+Skill 被划分得多细。更细会支付两种负载之一：更多 Model-Invoked skills 增加 Context Load；更多 User-Invoked skills 增加 Cognitive Load。
+
+两种切分指导粒度：
+
+- 按 **Invocation** 切：出现一个应独立触发、且用户 prompts 中真实使用的 **Leading Word**，或另一 skill 必须到达它；
+- 按 **Sequence** 切：某 step 的 **Post-Completion Steps** 需要被藏起来，因为看见后续会诱发 Premature Completion。
+
+反方向同样危险：合并 sequences 会把每一步后面的内容暴露出来，增加向前抢跑。
+
+_Avoid_：chunking、modularity
+
+## Information Hierarchy
+
+Skill 内容按 agent 多快需要它而排列的单一阶梯，由两次切分得到：文件内或 pointer 之后，以及 step 或 reference。层级为：
+
+- **Steps**：文件内，主要层；
+- **Reference**：文件内，次要层；
+- **Reference**：disclosed，位于 **Context Pointer** 之后。
+
+没有 Steps 的 skill 只使用后两层，常常是合法的 flat peer-set，例如同级的 review rules，并不是气味。Hierarchy 与 invocation 独立：全 steps、全 reference 或混合 skill 都可以是 model- 或 user-invoked。
+
+有 Steps 时，本可 disclosed 的 reference 若留在文件内，会埋住步骤并分散注意，这不只是可读性问题，也是 variance lever。保持阶梯顶部清楚，把能够下移的材料推下去。
+
+_Avoid_：structure、organization、layout
+
+### Steps
+
+Agent 按顺序执行的动作。有 steps 时，它们是 `SKILL.md` 的主要层，也最有资格留在正文。并非每个 skill 都需要 steps：`tdd` 可以几乎全是 steps，review 可以全是 **Reference**，二者与 invocation 无关。
+
+每个 Step 都有 **Completion Criterion**，无论它清楚还是含糊。
+
+_Avoid_：workflow、instructions、choreography
+
+### Reference
+
+Agent 按需查阅的材料：定义、事实、参数、例子和条件性指令。有 Steps 时它位于次要层；没有 Steps 时它可以构成整个 skill；也可以完全存在于 skill 系统外，成为 **External Reference**。
+
+Reference 通过 Context Pointers 到达，是 **Progressive Disclosure** 的主要候选。
+
+_Avoid_：supporting material、docs、background
+
+### External Reference
+
+存在于 skill 系统之外的普通 Reference：没有 Description、没有 Steps、不可被调用，但任何 skill 都可以指向它。它适合承载无需独立触发的共享资料，也是两个 User-Invoked skills 共享 reference 的唯一中立位置，因为它们彼此都不能启动。
+
+Skill 目录内由 `SKILL.md` 指向的 `references/*.md` 属于 disclosed reference；项目根目录中由多个 skills 共同指向的规则或领域文档属于 External Reference。
+
+_Avoid_：doc、resource、knowledge base
+
+### Progressive Disclosure
+
+把 Reference 沿阶梯下移：从 `SKILL.md` 移到 Context Pointer 后，让顶部保持可辨认。它首先保护 Information Hierarchy，而不只是节省 tokens。
+
+**Branching** 为 disclosure 提供判断：只有部分 branches 需要的材料下移；每条路径都需要的材料 inline。必需材料的 pointer 若不可靠，先强化 pointer，只有强化失败才拉回正文。
+
+_Avoid_：lazy loading、chunking
+
+### Co-location
+
+把 agent 同时需要的材料放在一起：概念的定义、规则与 caveats 位于同一标题下，而不是散落文件各处。Information Hierarchy 决定内容放多深；Co-location 决定到达某层后什么应彼此相邻。
+
+Reference 的正确格式没有公式。测试标准是：它应像专门写给 agent 的文档；相关材料集中时通常如此。Co-location 不同于 **Duplication**：Duplication 把同一 meaning 写了两次，散落则把一个 meaning 的不同部分拆到多个位置。
+
+_Avoid_：grouping、clustering、cohesion
+
+### Sprawl
+
+_Failure mode._ `SKILL.md` 只是太长。即使每一行都仍相关且唯一，它也可能 Sprawl。成本包括：agent 在行动前需要穿过更多内容、注意力被稀释；维护者需要持续检查更多行；tokens 增加。
+
+处理方法是 Information Hierarchy：把 Reference 放到 Context Pointers 后，按 Branch 或 Sequence 切分，让每条路径只携带所需内容。Sprawl 不同于 **Sediment**（旧层造成的长度）和 **Duplication**（重复 meaning 造成的长度）；它指长度本身，无论成因。
+
+_Avoid_：bloat、length、size、verbosity
+
+## Steering
+
+把 agent 运行时行为推向 **Predictability** 的杠杆。
+
+### Branch
+
+Skill 被调用后可能采取的一种独立路径，也就是它处理的一类情形。不同 runs 因此经过不同内容。拥有许多 steps 的 skill 可能有许多 branches；完全线性的 skill 可以没有 branch。
+
+Branch 是 disclosure 的自然单位：只服务某个 branch 的 reference 不应让其他 branches 每次都携带。
+
+_Avoid_：path、case、fork
+
+### Leading Word
+
+一个已经存在于模型预训练中的紧凑概念，也可称为 Leitwort；agent 在运行 skill 时用它思考。它用最少 tokens 调用已有 behavioural priors，例如 _lesson_、_Zone of Proximal Development_、_fog of war_、_tracer bullets_。
+
+Leading Word 作为 token 重复，而不是把同一解释句重复。它会在全文形成分布式定义，并锚定一整片行为。自造词在定义清楚时也能工作，但没有预训练 priors，必须用额外 tokens 补定义；优先寻找已有词。
+
+它两次服务 Predictability：
+
+- 在正文中锚定 **execution**：每次出现都让 agent 到达同类行为；在 flat reference 中，它会让注意力聚焦于要寻找的一类对象；
+- 在 **Description** 中锚定 **invocation**：当同一词也存在于 prompts、docs 和 codebase 中，agent 更可靠地把请求连到 skill。
+
+Description 应使用用户真正会说的 Leading Words，而不是维护者自造、用户永远不会输入的标签。
+
+_Avoid_：keyword、term、motif
+
+### Completion Criterion
+
+告诉 agent 一个工作单元何时完成的条件，也就是它进行判断的目标。两个属性使它成为行为杠杆：
+
+- **Clarity**：agent 能否区分 done 与 not done。清楚标准抵抗 **Premature Completion**；含糊标准如“理解已经形成”允许 agent 自行宣布完成。这条轴只有在存在 steps 时才产生跨步骤作用。
+- **Demand**：标准要求多少 **Legwork**。“每个修改过的 model 都已核对”比“生成改动列表”要求更多。这条轴不依赖 steps，也可以约束 flat reference，例如“每条规则都已应用”。
+
+最强标准同时可检查且穷尽。
+
+_Avoid_：done condition、exit condition、stopping rule
+
+### Legwork
+
+Agent 在单个 step 内部完成的工作：阅读文件、探索代码库、执行检查、修改内容、查找证据，而不是把这些工作推给用户。它位于 step 结构之下，不应被机械写成一串独立步骤；具体方法由 agent 根据环境决定。
+
+Legwork 与 **Post-Completion Steps** 的跨步骤拉力相对。强 Leading Word（如 _relentless_）或高 demand Completion Criterion 会增加 Legwork；后者也能让全 reference skill 覆盖所有规则。缺少 demand，或 Premature Completion 提前切断 step，都会让 Legwork 变薄。
+
+_Avoid_：scope、effort、diligence、coverage
+
+### Post-Completion Steps
+
+当前 Step 之后仍可见的 Steps。它们会把 agent 向前拉，引发 **Premature Completion**；看见得越多，拉力通常越强。必要时通过真实 sequence split 把它们隐藏。
+
+仅仅折叠标题或把文字放到同一 prompt 后半段并不会隐藏；有效边界需要新用户调用或独立 subagent context。
+
+_Avoid_：horizon、fog of war、lookahead
+
+### Premature Completion
+
+_Failure mode._ 当前 step 尚未真正完成，agent 的注意力却从工作本身滑向“尽快完成”，于是提前结束。它是 between-steps failure：必须存在 Steps 才会发生。没有 Steps 的 skill 提前停下，属于在未满足 demand 时 Legwork 太薄，而不是 Premature Completion。
+
+这是两股力量的拉扯：可见的 **Post-Completion Steps** 向前拉，**Completion Criterion** 的 clarity 负责抵抗。Fuzziness 是必要条件；标准锋利时，无论看见多少后续都能抵抗，因此从不抢跑的 step 无需额外防御。
+
+按成本顺序使用两个杠杆：
+
+1. 先 sharpen completion bound；这是局部、便宜的修复。
+2. 只有标准不可避免地模糊、且真实运行已经观察到抢跑时，才隐藏后续步骤。隐藏必须跨越真实 context boundary；同一上下文内 inline 调用另一个 model-invoked skill 不会清空后续内容。
+
+Premature Completion 是薄 Legwork 的一种成因，但二者不同：step 即使走到自己声明的完成，也可能因为 demand 太弱而 Legwork 不足。
+
+_Avoid_：premature closure、the rush、rushing、shortcutting
+
+### Negation
+
+_Failure mode._ 通过禁止来 steering：告诉 agent 不要做什么，反而把被禁止行为带入 context 并提高其可用性。Negation 是弱 modifier，刚刚被强烈激活的概念可能压过它，于是禁令被半读成行动提示。
+
+处理方法是 prompt the positive：描述目标行为，让禁止对象不进入 frame。例如用“comments 保持单行并解释非显然取舍”代替只写“不要写冗长 comments”。只有无法用正向目标表达的硬 guardrail 才保留 prohibition；即使如此，也要同时写明应采取的替代行为，让注意力落到正确目标。
+
+它的 Leading Word 是 _elephant_：prohibition 刚刚命名进 frame 的对象。
+
+_Avoid_：ironic rebound、don't-prompting、the pink elephant
+
+## Pruning
+
+保持 skill 精炼；每个 remedy 与它处理的 failure 相邻。
+
+### Single Source of Truth
+
+每个 meaning 只存在于一个 authoritative place 的状态，因此 skill 行为变化只需修改一处。**Duplication** 是对它的破坏。
+
+Single Source of Truth 指 meaning，而不只是文字完全相同。两段不同措辞若约束同一行为，仍可能是两个来源。
+
+_Avoid_：home、canonical location
+
+### Duplication
+
+_Failure mode._ 同一 meaning 拥有多个 Single Sources of Truth。它增加维护成本、消耗 tokens，并通过重复把一个 meaning 在 Information Hierarchy 中的 prominence 抬得高于真实等级。
+
+它是 **Leading Word** 的意外反面：Leading Word 有意重复一个 token 来聚焦行为；Duplication 重复完整 meaning。前者不建立第二套定义，后者会。
+
+_Avoid_：repetition、redundancy
+
+### Relevance
+
+一行内容现在是否仍直接影响 skill 所做的事情。内容可能从未相关，例如纯 exposition 或应 disclosed 的 branch；也可能随行为和世界变化而过期。
+
+更短的 skills 更容易维持 Relevance，因为需要持续检查的行更少。Relevance 不同于 **No-Op**：前者问这行是否与任务有关，后者问它是否真的改变模型行为。一行可以完全相关，却仍是 No-Op。
+
+_Avoid_：load-bearing、staleness、freshness
+
+### Sediment
+
+_Failure mode._ 旧内容像沉积层一样不断堆积：添加让人感觉安全，删除让人感觉危险，于是 stale 和 irrelevant lines 留下来，维护者必须穿过它们才能找到仍然有效的层。
+
+没有 pruning discipline 时，Sediment 是 skill 的默认命运。它是 Relevance 随时间缓慢侵蚀的结果，不同于 Duplication 对同一 meaning 的重复。
+
+_Avoid_：accretion、bloat、cruft、rot
+
+### Conservation First
+
+本地化或迁移成熟上游 skill 时采用的保留优先规则：在证明某段内容属于允许适配、真正重复或经场景验证的 **No-Op** 前，先保留其限定词、判断规则、失败边界、例子作用和在 **Information Hierarchy** 中的位置。
+
+它不是拒绝 **Pruning**，而是改变举证责任。新写 skill 时可以主动裁剪；改编成熟方法时，不能仅凭“更短、更整齐”推断某句无用。删除必须说明该 meaning 的唯一去向，或用前向测试证明行为没有回退。
+
+_Avoid_：verbatim copying、never prune、line-count parity
+
+### No-Op
+
+_Failure mode._ 一条没有改变行为的指令，因为模型默认就会这样做；你支付 load，却没有得到任何 steering。测试方法是：与默认行为相比，这一行是否改变了 agent？一行可以非常 Relevant，却仍是 No-Op。
+
+Leading Word 是 technique，No-Op 是对某行的 verdict，二者可以交叉。一个太弱、无法超过默认值的 Leading Word 也是 No-Op：如果 agent 本来就“有点 thorough”，再写 _be thorough_ 可能没有作用；修复方式是换成足以改变行为的词，如 _relentless_，而不是为了保留句子另造技巧。
+
+No-Op 判断相对于模型默认行为，而不是相对于读者感受。两个人对某行是否 No-Op 有分歧，实质是在争论模型默认值；应通过运行场景测试解决，而不是只靠文字讨论。
+
+_Avoid_：redundant instruction、restating the obvious、belaboring

package/agents/codex/code-reader.toml

@@ -1,11 +0,0 @@
-name = "code-reader"
-description = "快速只读阅读代码库，定位职责、调用链、数据流、配置和相关测试，不承担实现或最终设计决策。"
-model_reasoning_effort = "low"
-sandbox_mode = "read-only"
-developer_instructions = """
-先读取适用的 AGENTS.md 和与任务直接相关的说明，只探索用户指定的问题。
-优先使用快速文本搜索定位入口、符号、调用方、配置和测试，再阅读最小必要上下文。
-区分代码事实、合理推断和仍未知内容；所有关键结论给出可定位的文件或符号证据。
-不要修改文件，不要安装依赖，不要运行会改变项目状态的命令，也不要把探索扩大成全面审查。
-向主 agent 返回简洁的调用链、相关文件、关键事实、未知项和建议下一步。
-"""

package/skills/grill/SKILL.md

@@ -1,54 +0,0 @@
----
-name: grill
-description: 当用户明确要求深入盘问，或路由器判断一项重要计划、产品设计、技术设计或关键决策需要挑战与确认时使用。它是默认不写项目文档的访谈入口，负责整理背景并调用 grilling；需要边访谈边维护 CONTEXT.md 或 ADR 时改用 grill-with-docs，普通小问题或已明确的执行任务不使用。
----
-
-# Grill
-
-`grill` 是用户可直接调用、也可由路由器选择的深入访谈入口。它没有个人化角色设定，核心职责是为 `grilling` 准备上下文并启动访谈，默认只输出确认记录，不修改项目文档。
-
-## 启动前
-
-1. 明确本次要确认的决策对象，以及访谈结束后用户希望得到的产物。
-2. 读取用户提供的计划、规格、设计稿和仓库内直接相关的资料。不要询问文件中已经写明的事实。
-3. 提炼已知事实、当前假设、明显冲突和最高风险未知项。
-4. 调用同一套 skills 中的 `grilling`，把上述上下文作为访谈起点。Codex 使用 `$grilling`；Claude Code 的普通用户级 skill 使用 `/grilling`，插件安装模式使用 `/netpilot-skills:grilling`。
-
-如果任务尚未形成值得深入访谈的决策对象，先返回 `ask` 或 `wayfinder`，不要假装开始审查。
-如果用户明确要求把访谈中确认的术语和重要决策同步写入 `CONTEXT.md` 或 ADR，把控制权转交给 `grill-with-docs`，不要在本 skill 内临时增加写入模式。
-
-## 访谈范围
-
-优先覆盖会造成返工或不可逆影响的内容：
-
-- 用户与问题是否真实、边界是否清楚；
-- 成功指标和明确的非目标；
-- 关键业务规则、数据与权限边界；
-- 技术约束、集成点和失败模式；
-- 方案取舍、替代方案与可逆性；
-- 验收方式、发布策略和剩余风险。
-
-## 结束产物
-
-访谈结束后，输出一份紧凑的确认记录：
-
-- 已确认的事实与决策；
-- 被否定的选项及原因；
-- 仍未解决的问题与负责人；
-- 建议进入的下一 skill，通常是 `to-spec`、`research` 或 `prototype`。
-
-未经用户明确授权，不创建远程 issue、不修改外部系统，也不把访谈结论直接当成已批准规格。
-
-## 完成标准
-
-- 已把决策对象、背景和风险交给 `grilling` 逐题确认。
-- 关键决策有明确答案或被显式标记为未决。
-- 形成可供下一阶段使用的确认记录。
-
-## 反模式
-
-- 不要复制一套独立于 `grilling` 的访谈算法。
-- 不要在普通 `grill` 会话中静默创建或更新项目文档。
-- 不要一次发送十几个问题。
-- 不要只接受含糊回答而不追问影响。
-- 不要用对抗语气；挑战的是假设，不是用户。

package/skills/grill/agents/openai.yaml

@@ -1,6 +0,0 @@
-interface:
-  display_name: "Grill"
-  short_description: "对重要计划、设计与关键决策进行一次一个问题的深入访谈"
-  default_prompt: "请使用 $grill 对当前重要决策进行逐题访谈，并在结束时总结确认结果。"
-policy:
-  allow_implicit_invocation: true