@netpilot/skills 0.6.0 → 0.8.0

package/skills/prototype/references/ui.md

@@ -1,57 +1,64 @@
 # UI Prototype
 
-在一个 route 上生成数个结构上显著不同的 UI variants，通过浮动底部 switcher 切换。用户可以选择一个方案，或组合不同方案的优点，其余最终丢弃。
+在一个 route 上生成 **数个结构上显著不同的 UI variants**，并通过浮动底栏切换。用户在 browser 中逐个比较，选定一个方案或组合各方案的优点，然后丢弃其余方案。
 
-若问题是 logic/state，改用 `logic.md`。
+如果问题是 logic/state 而不是外观，说明选错了分支，改用 [logic.md](logic.md)。
 
-## 适用情形
+## 何时适合这种形态
 
 - “这个 page 应该长什么样？”
-- “实现 dashboard 前先看几个方案。”
-- “尝试 settings screen 的不同 layout。”
+- “实现 dashboard 前，我想先看几个方案。”
+- “尝试 settings screen 的另一种 layout。”
+- 任何本来会让用户花一天在脑中比较三份模糊 mockup 的情形。
 
-## 两种形态
+## 两种形态——强烈优先 A
 
-强烈优先 A。Variant 与真实 header、sidebar、data 和 density 相邻时，才容易判断。
+当 UI prototype **紧贴应用其余部分**——真实 header、真实 sidebar、真实 data、真实 density——时，会更容易判断。孤立的 throwaway route 是一个 vacuum：每个 variant 单独看起来都不错。只要存在合理的已有页面可以承载 variants，就默认使用 A；只有 prototype 确实没有附近的归宿时才使用 B。
 
 ### A：调整已有页面
 
-Route 已存在。通过 `?variant=` 在同一 route 切换 render subtree；保留原 data fetching、params 和 auth。
+Route 已经存在。通过 `?variant=` URL search param 在 **同一个 route** 上切换 variants。现有 data fetching、params 和 auth 全部保留，只替换 render。除非有具体理由，否则选择 A。
 
-即使新内容尚无独立 page，只要它自然属于已有 dashboard、settings 或 flow，也仍使用 A，把 variants mount 到 host page。
+即使新内容还没有自己的 page，只要它自然属于某个已有页面——dashboard 的新 section、settings screen 的新 card，或现有 flow 的新 step——仍属于 A。把 variants mount 到 host page 内。
 
 ### B：全新页面
 
-只有完全没有合理 host page 的全新顶层 surface 或 flow 才使用。
+只有要验证的内容确实没有任何已有页面可容纳时才使用，例如完全新的 top-level surface，或无法合理嵌入别处的 flow。
 
-按项目 routing convention 创建明确标记 prototype 的 throwaway route，例如 `/prototype/<name>`，同样使用 `?variant=`。不要自创新的顶层目录结构。
+按项目已有 routing convention 创建 **throwaway route**，不要发明新的顶层结构。名称必须明显表明它是 prototype，例如 path 或 filename 包含 `prototype`。仍使用相同的 `?variant=` pattern。
 
-进入 B 前再次确认：它真的无法嵌入任何现有 page 吗？
+选择 B 前再核对一次：它真的无法嵌入已有页面吗？空 route 会隐藏 design problems，而有真实内容的页面会把它们暴露出来。
+
+两种形态共用完全相同的浮动底栏。
 
 ## 流程
 
-### 1. 写明问题并确定数量
+### 1. 写明问题并选择 N
 
-默认 **3 variants**，最多 5 个。超过 5 个往往不再是 radically different，而只是噪声。
+默认 **3 variants**。超过 5 个后，它们通常不再 radically different，而只是噪声，因此上限为 5。
 
-在 prototype 位置写一行：
+在 prototype 所在位置或文件顶部 comment 写下一行 plan：
 
 > 在现有 `/settings` route 上提供 3 个 settings page variants，通过 `?variant=` 切换。
 
+无论用户在线可以提出异议，还是暂时 AFK，这行 plan 都能供之后核对。
+
 ### 2. 生成结构上显著不同的 variants
 
-每个 variant 必须符合：
+起草每个 variant，并逐一满足：
 
-- page purpose 与可用 data；
-- 项目已有 component library / styling system；
+- page purpose 与它可以访问的 data；
+- 项目既有 component library / styling system，例如 TailwindCSS、shadcn、MUI 或 plain CSS；
 - 清楚的 exported component name，例如 `VariantA`、`VariantB`、`VariantC`。
 
-Variants 必须在 layout、information hierarchy 或 primary affordance 上不同，而不只是颜色、copy 或 card 间距不同。若两个方案太像，明确要求其中一个不用 card grid 并重新设计。
+Variants 必须 **结构不同**：layout、information hierarchy 或 primary affordance 不同，而不只是 colours。三个只有轻微差别的 card grid 不是 UI prototype，只是 wallpaper。两个 draft 太相似时，明确要求其中一个“不要使用 card grid”并重新设计。
 
 ### 3. 连接切换逻辑
 
+在 route 上创建单一 switcher component：
+
 ```tsx
-// pseudo-code：按项目 framework 调整
+// pseudo-code——按项目 framework 调整
 const variant = searchParams.get("variant") ?? "A";
 
 return (
@@ -67,42 +74,43 @@ return (
 );
 ```
 
-Sub-shape A：所有现有 data fetching 保留在 switcher 上方，只替换 render subtree。
-Sub-shape B：throwaway route mount 同一个 switcher。
+形态 A：所有现有 data fetching 留在 switcher 上方，只替换各 variant 的 rendered subtree。
+
+形态 B：`/prototype/<name>` 下的 throwaway route mount 同一个 switcher。
 
 ### 4. 浮动 switcher
 
-底部中央固定一个小 bar：
+在屏幕底部中央固定一个小 bar，包含三部分：
 
-- 左箭头：切换前一 variant，首尾循环；
-- label：显示当前 key 与名称，例如 `B — Sidebar layout`；
-- 右箭头：切换后一 variant，首尾循环。
+- **左箭头**：切换到前一个 variant，并首尾循环；
+- **Variant label**：显示当前 variant key；如果 variant export 了名称，也一起显示，例如 `B — Sidebar layout`；
+- **右箭头**：向后切换，并首尾循环。
 
 行为：
 
-- 使用项目 router 更新 URL search param，使 variant 可分享、reload 后稳定；
-- `←` 与 `→` 键切换；
-- focus 位于 `input`、`textarea` 或 `[contenteditable]` 时不截获方向键；
-- 视觉上明显独立于被评估页面；
-- 通过 `NODE_ENV !== "production"` 或等价条件确保 production build 隐藏；
-- switcher 只实现一次，放在项目合理的 shared UI 位置。
+- 点击箭头时用项目 framework 的 router 更新 URL search param，例如 Next 的 `router.replace` 或 React Router 的 `navigate`，使 variant 可分享并在 reload 后保持稳定；
+- `←` 与 `→` 键也可切换；focus 位于 `<input>`、`<textarea>` 或 `[contenteditable]` 时不得截获方向键；
+- switcher 必须在视觉上明显独立于被评估页面，例如高对比 pill 加轻微 shadow，使人清楚它不属于设计本身；
+- 在 production builds 中隐藏：使用 `process.env.NODE_ENV !== "production"` 或等价检查，避免一次意外 merge 把底栏交付给用户。
+
+Switcher 只实现一次，放在项目既有 shared UI 位置，让两种形态复用。
 
 ### 5. 交给用户比较
 
-给出完整 URL 与 variant keys。用户可能会提出“B 的 header 加 C 的 sidebar”，这种组合反馈正是 prototype 要发现的答案。
+给出完整 URL 与 `?variant=` keys。用户可以在方便时逐个比较。最有价值的反馈通常是“我想要 B 的 header 和 C 的 sidebar”——这才是他们真正想要的设计。
 
 ### 6. 捕获结论并清理
 
-选定方案后记录 winner 与原因：
+Variant 胜出后，先捕获答案——哪个 variant 以及为什么——再按主 [SKILL](../SKILL.md) 的方式捕获 prototype。只有另行授权 `$implement` 后，才能把 winner 写入正式代码；其余内容进入 throwaway branch，而不是 main：
+
+- **形态 A**：把 winner 作为现有 page 的正式实现输入；获得 `$implement` 授权后吸收 winner，并从 main 移除 losing variants 与 switcher。
+- **形态 B**：把 winner 作为真实 route 的正式实现输入；获得 `$implement` 授权后吸收 winner，并从 main 移除 throwaway route 与 switcher。
 
-- Sub-shape A：把 winner 作为现有 page 的实现输入；只有另行授权 `$implement` 后才写入正式代码，并从主分支移除 losing variants 与 switcher。
-- Sub-shape B：把 winner 作为真实 route 的实现输入；只有另行授权 `$implement` 后才写入正式代码，并从主分支移除 throwaway route 与 switcher。
-- 完整 variants 作为 primary source 留在已授权的 throwaway branch，而不是主分支。
+完整 variants 是 primary source，因此保留在 throwaway branch，而不是丢进垃圾箱；variant components 与 switcher 如果留在 main，会很快 rot，并让下一位读者困惑。
 
 ## 反模式
 
-- Variants 只改变颜色或 copy。
-- 共享过多 layout 代码，使各方案无法真正不同。
-- 把 prototype 连接到真实 mutation；需要 mutation 时使用 stub。
-- 把 prototype variant 直接提升为生产实现；正式吸收时必须补生产级错误处理与测试。
-- 把 losing variants 或 switcher 留在主分支腐化。
+- **Variants 只改变 colour 或 copy。** 那只是 tweak，不是 prototype；真正的 variants 对结构持不同意见。
+- **Variants 共享过多代码。** 共用 `<Header>` 没问题，共用 `<Layout>` 会破坏目的；每个 variant 都必须能丢掉现有 layout。
+- **把 variants 接到真实 mutations。** 只读 prototype 没问题；需要 mutation 时指向 stub。问题是“它应该长什么样”，不是“backend 是否工作”。
+- **把 prototype 直接提升为 production。** Variant code 是在 prototype 约束下写的，没有测试，错误处理也最少。获得 `$implement` 授权后，仍须按生产标准重新实现、补齐 error handling 和 tests。

package/skills/to-questionnaire/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: to-questionnaire
+description: 当一项决定依赖另一位知识持有者提供用户自己无法回答的事实或判断，需要生成可异步填写或会议共填的 Markdown questionnaire 时使用。
+disable-model-invocation: true
+---
+
+# To Questionnaire
+
+把用户无法独自回答的事情变成一份 **questionnaire**：一份交给某一个人异步填写，或在会议中共同填写的 Markdown 文档。Recipient 掌握用户缺少的知识；questionnaire 把这些知识提取出来。
+
+**Grill the send, not the subject.** 只访谈用户能够回答的 _send_：发给谁，以及需要拿回什么。文档中的问题再瞄准 recipient 已知与用户所需之间的 **gap**。
+
+1. **发给谁？** 在一次 exchange 中询问 recipient 的角色、专业知识，以及与用户的关系。这决定 questionnaire 的语气和需要携带多少 context。完成条件：已经知道 recipient 是谁，以及对方掌握什么用户不知道的知识。
+
+2. **需要拿回什么？** 在一次 exchange 中询问用户无法独自解决、必须由这个人提供的具体 decisions 或 facts。完成条件：已经得到一份具体清单，说明用户在收到回答后必须能够做什么或决定什么。
+
+3. **编写 questionnaire。** 针对步骤 1–2 确定的 gap 起草问题，严格采用下方 Document Structure。写入当前目录的 `to-questionnaire-<slug>.md`，slug 来自主题，并报告最终路径。目标路径已存在时，选择唯一的新 suffix 或 slug；不得覆盖已有文件。完成条件：文件已经存在，并且步骤 2 中用户点名的每一项都由一个问题覆盖。
+
+## Document Structure
+
+把文档框定为 **discovery questionnaire**：用户缺少 context，recipient 掌握它。按 most-important-first 排列问题——async 意味着可能只有一次回答机会。问题多于少量时，再按主题用 `##` headings 分组。使用下面的模板。
+
+<questionnaire-template>
+
+# <Questionnaire title>
+
+**Purpose:** 为什么需要这份 questionnaire，以及哪个 decision 取决于它。
+
+**From:** <the user> — **To:** <the recipient> — **How your answers will be used:** <answers 会进入哪里>
+
+## Context
+
+用一个 paragraph 帮助没有参与用户思考过程的 recipient 定位。提供足以高质量回答的 context，但不要写成一页背景资料。
+
+## How to answer
+
+写明 deadline 与大致 effort。Partial answers 和 “I don't know” 都有价值；对不确定的内容显式标记，而不是跳过。
+
+## <Theme heading>
+
+每个 theme 一个 `##` section，下面按 most-important-first 排列问题。每个问题只包含一个 idea，不能 compound；紧接一个 answer stub。只有问题可能被误解或招致敷衍回答时，才添加一行 _Why this matters_。
+
+<question-example>
+
+### 系统在首次发布时预计要承受多大负载？
+
+_Why this matters: 这决定现在就为 burst traffic 预留容量，还是推迟该投入。_
+
+>
+
+</question-example>
+
+## Anything else?
+
+用一个 closing catch-all 收尾：还有什么我们没有问、但应该知道的事情？
+
+</questionnaire-template>

package/skills/to-questionnaire/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "To Questionnaire"
+  short_description: "为掌握关键信息的人生成可异步填写的结构化问卷并覆盖全部决策缺口"
+  default_prompt: "请使用 $to-questionnaire 询问问卷的收件人与信息缺口，并生成可异步填写的 Markdown。"
+policy:
+  allow_implicit_invocation: false

package/skills/triage/SKILL.md

@@ -112,7 +112,7 @@ state labels 冲突时停止写入，先请求维护者决定。
 
 请求仍缺关键决定时调用 `$grilling`；术语、状态或不变量需要沉淀时同时调用 `$domain-modeling`。
 
-一次一个问题。已确认内容写入 triage notes，后续 session 不重问。
+每一轮询问当前全部已解锁的 frontier；本轮尚未解决的依赖留到下一轮。已确认内容写入 triage notes，后续 session 不重问。
 
 ### 应用结果
 

package/skills/wait-what/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: wait-what
+description: 当用户表示上一条消息没有听懂、没有讲清楚，或显式要求 wait-what 时，用缺失上下文和项目术语重新讲述上一条消息。
+disable-model-invocation: true
+---
+
+等等——上一条没有讲清楚。重新讲一遍：补一点上下文；使用当前沟通语言的短句和单义技术词，英语时采用 ASD-STE100 Simplified Technical English；优先使用 `CONTEXT.md` 的 canonical terms，不存在时使用已经确认的项目词汇，不杜撰文档内容。

package/skills/wait-what/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Wait What"
+  short_description: "用当前语言和项目术语重新讲清上一条没有讲明白的消息"
+  default_prompt: "请使用 $wait-what 补足必要上下文，并用更简明的当前语言重述上一条消息。"
+policy:
+  allow_implicit_invocation: false

package/skills/wayfinder/SKILL.md

@@ -87,7 +87,7 @@ Map body 是每个 session 只加载一次的低分辨率视图。Open tickets
 
 - **research**：AFK。当 decision 等待当前工作目录之外的一手知识时使用，读取并返回带来源的事实；普通 repo exploration 不建立 research ticket。
 - **prototype**：HITL。制作低成本 artifact，让人对具体形态或行为作出判断。
-- **grilling**：HITL。调用 `$grilling` 与 `$domain-modeling`，一次一个问题；这是不确定类型时的默认选择。
+- **grilling**：HITL。调用 `$grilling` 与 `$domain-modeling`，以 rounds 询问当前 ticket 内 design tree 的全部 frontier；这是不确定类型时的默认选择。
 - **task**：HITL 或 AFK。完成一个必须先发生、但本身没有 decision 的动作，以解除后续阻塞。Resolution 要记录后续 tickets 依赖的事实，例如 credential location、URL、row count 或完成步骤。
 
 HITL ticket 必须让真人表达自己的判断；agent 不得代替用户回答访谈问题。

package/skills/writing-for-agents/SKILL-MECHANICS.md

@@ -0,0 +1,62 @@
+# Skill Mechanics
+
+这是 [`writing-for-agents`](SKILL.md) 的 skill-specific branch：当 agent-consumed document 是 skill 时，frontmatter、Invocation 选择与 Router Skills 会带来额外机制。其余写作规则都以 `SKILL.md` 的通用 reference 为唯一来源。
+
+## Invocation
+
+Skill 有两种选择，用两种负载互换：
+
+- **model-invoked** skill 保留面向模型的 `description`，因此 agent 可以自主触发它，其他 skills 也能到达它。用户仍然可以显式输入名称：model invocation 始终 _包含_ user reach；description 只增加 agent discovery，从不移除人的入口。Description 是 skill 顶层的 Context Pointer，被迫始终加载；它用永久 Context Load 换取 discoverability。全是 Reference 的 model-invoked skill 还可以成为共享 Reference 的唯一归属：多个 skills 都能调用它，所以共同材料只保存一份。Claude source 省略 `disable-model-invocation`；Codex metadata 显式设置 `policy.allow_implicit_invocation: true`；description 按 `SKILL.md` 的 pointer rules 写入真实 trigger branches。
+- **user-invoked** skill 把 description 从模型可见集合中移除：只有人显式输入名称才能启动，其他 skills 也不能调用。它不支付常驻 Context Load，却支付 Cognitive Load——人是必须记住它存在的 index。Claude source 设置 `disable-model-invocation: true`；Codex metadata 设置 `policy.allow_implicit_invocation: false`；description 变成人类可读的一行摘要，移除模型 trigger list。
+
+只有 agent 必须自行到达该 skill，或另一个 skill 必须调用它时，才选择 model invocation。如果永远只应由人手动启动，就保持 user-invoked，不支付 Context Load。
+
+两个 user-invoked skills 共同需要的 Reference 不能住在其中任何一个：没有模型可见 description，二者都无法调用对方。把它移到 skill system 之外的普通文件，作为任何 skill 都能指向的 External Reference。
+
+Invocation classification 只决定如何到达 skill，不授予文件、Git、tracker 或远程写入权限；动作授权必须由该 skill 的正文和当前用户请求另行确定。
+
+## 按 Invocation 拆分
+
+Sequence cut 在 `SKILL.md`；Invocation cut 是 skill 特有的切法。只有出现一个应该独立触发的 Leading Word——而且用户 prompts 中真实使用这个词——或另一个 skill 必须到达该能力时，才拆成 model-invoked skill。新的 description 会永久支付 Context Load，因此 independent reach 必须值得这笔成本。
+
+## Router Skills
+
+当 user-invoked skills 多到人难以记住时，累积的 Cognitive Load 由 **Router Skill** 处理：只需记住一个入口，Router 点名其他入口以及何时选择每一个。
+
+Router 只能提示，不能替用户启动 user-invoked skill。User-invoked skill 对模型没有可达的 description，因此只有人能到达它。Router 应给出 canonical 名称和精确显式调用形式，把选择权交还用户；显式调用 Router 本身也不自动授权下游动作。
+
+## 上游本地化
+
+本地化成熟上游 skill 时使用 **Conservation First（保留优先）**。它不是拒绝 Pruning，而是改变举证责任：在证明某段内容属于允许适配、真正 Duplication，或经场景验证的 No-Op 之前，先保留其限定词、判断规则、Failure Modes、例子作用和在 Information Hierarchy 中的位置。
+
+按下面顺序处理：
+
+1. 锁定来源版本，完整读取 `SKILL.md`、references、scripts、assets 与 metadata。完成条件是候选的全部运行时文件都有唯一、可复核的来源。
+2. 保留 Steps 顺序、Leading Words、Completion Criteria 的原位置、例子作用和 Progressive Disclosure 关系。完成条件是每个上游行为约束在本地都有唯一去向。
+3. 只做有证据的适配：去除个人角色与作者口吻、删除不存在的 setup 或命令、翻译普通说明、映射真实宿主路径与工具、加入必要权限门禁，以及修复有一手资料或可运行证据支持的矛盾。
+4. 保持上游方法自身的形状：短 orchestration skill 仍然短，reference-only skill 不被改成主动 workflow，不强加统一章节。
+5. 上游 skill 被移除但附件仍有独立方法价值时，把附件迁移到职责最接近的 canonical skill，并更新 Context Pointer。完成条件是有价值的 Reference 可达，同时没有同职责双入口。
+
+特别保留 `where possible`、`each claim`、`before` / `after`、`only` 等会改变适用范围、时机或证据强度的词。对是否可删存在疑问时，保留。
+
+上游例子是规则的一部分：诊断例子、反例和 branch 选择例子不能只剩抽象总结。需要适配个人语境或失效工具时，替换表面内容，但保留例子原本帮助 agent 区分的相邻情况。例如，一个用于区分 Logic 与 UI prototype 的具体问题，不能被概括成“根据情况选择分支”。
+
+只有满足以下至少一项，才能合并、删除或替换上游内容：
+
+- 属于个人角色、作者口吻或不存在的命令；
+- 与真实宿主、平台 API 或本地权限边界冲突，并有一手资料或可运行证据；
+- 与同一权威位置完全 Duplication，删除后所有 predicates、例子作用和 Completion Criterion 仍有唯一去向；
+- 独立前向测试确认它是 No-Op，删除后 trigger、execution、stop 或 failure boundary 没有回退。
+
+AI 提出的“优化”必须说明它解决的真实问题，并通过场景或结构验证；更整齐、更短或更长都不是优先于上游的依据。
+
+## NetPilot 宿主适配
+
+- Skill 目录与 frontmatter `name` 使用唯一的英文 kebab-case；`display_name` 由 canonical name 派生。普通说明、`description`、`short_description` 与 `default_prompt` 默认使用中文，稳定 Leading Words、协议字段、代码、路径和命令保留英文。
+- 每个 skill 提供 `agents/openai.yaml`。`default_prompt` 显式包含 `$<skill-name>`；Claude 与 Codex 的 invocation 分类必须成对一致。
+- 仓库保留双宿主单源；Codex 安装时生成确定性投影，移除 Claude-only frontmatter，但保留 Codex metadata 行为。
+- 大段条件性 Reference 放在 `references/`，确定性重复操作放在 `scripts/`，供产物使用而非加载进 context 的模板放在 `assets/`。Context Pointer 只深入一层，并明确说明何时读取。
+- 普通过程标题使用中文；具有行为锚定作用的 Leading Word、领域词、协议字段、label 与代码术语保留英文，并在首次出现时解释。
+- 不统一追加“完成标准”或“反模式”。真实 Steps 在原位置保留 Completion Criterion；上游方法本身有诊断价值时才保留 Failure Modes。
+- Git、issue tracker、外部消息或其他可见写入可以成为 skill 能力，但正文必须说明明确目标、用户授权、完成证据与 Failure Boundary。Push、PR、merge、deploy 和 publish 不从相邻动作或 Invocation classification 隐式获得授权。
+- 去除个人角色、作者口吻、私有暗语和不存在的命令；实质改编受许可约束的内容，只在仓库级 `THIRD_PARTY_NOTICES.md` 保存必要声明。

package/skills/writing-for-agents/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: writing-for-agents
+description: 为 agent 编写文档。当创建或编辑 skills、修改 AGENTS.md 或 CLAUDE.md，或维护由 Context Pointer 到达的 agent 文档时使用；纯面向人的普通文档不使用。
+---
+
+# Writing for Agents
+
+这是为 agent 编写任何文档的 reference：skills、`AGENTS.md` / `CLAUDE.md`，以及由 Context Pointer 到达的文档。包装形式不同，写作方法相同：相同的杠杆让 agent 每次采用相同的 _process_，而不是每次产生相同的输出，从而获得 **Predictability**。
+
+当正在编写的文档是 skill 时，必须读取 [SKILL-MECHANICS.md](SKILL-MECHANICS.md)，了解 frontmatter、Invocation 选择与 Router Skills。
+
+## Context Pointers
+
+**Context Pointer** 是保留在 agent context 中的一条 reference：它命名 context 之外的材料，同时编码到达该材料的条件。Skill 的 description 是 Context Pointer；`AGENTS.md` 中点名另一份文档的一行也是同一种对象。决定 agent 何时、以及多可靠地到达材料的是 pointer 的 _措辞_，不是目标文件本身。必须读取的材料如果藏在措辞薄弱的 pointer 后面，就是 variance bug：先 sharpen pointer；只有 sharpen 仍失败时才把材料 inline。
+
+一个 pointer 同时完成两件事：说明材料是什么，并列出应该触发它的 **branches**。Branch 是文档处理的一种独立情形，因此不同 runs 会经过不同路径。始终加载的 pointer 中，每个词都会在每一轮支付成本，所以它比正文更需要 Pruning：
+
+- **Front-load the Leading Word**：pointer 正是在这里完成触发。
+- **One trigger per branch**：仅仅用同义词重命名同一个 branch，等于把同一 branch 写了两次；collapse 它们，只保留真正不同的 branches。
+- **Cut identity the body already carries**：删除正文已经承担的身份说明。
+
+## 两种负载
+
+每增加一份文档或 pointer，都会花费下面两种预算之一：
+
+- **Context Load**：始终加载的材料占用 agent context window 的成本。`AGENTS.md` 中的一行、skill description，以及每轮都位于 context 中的内容，无论是否触发都消耗 tokens 与 attention。
+- **Cognitive Load**：由人承担的成本——记住有哪些文档，以及何时使用每一份。人是 index。它不是应该机械最小化的成本，而是 human agency 的代价；在人类判断重要时支付，在不重要时移除。
+
+只通过 pointer 到达的材料可以避开正文的 Context Load，但要支付 pointer 自身一行的成本；完全没有 pointer 的材料则完全依赖 Cognitive Load。
+
+## Information Hierarchy
+
+文档由两种内容自由组合：
+
+- **Steps**：agent 按顺序执行的动作；
+- **Reference**：按需查阅的定义、规则和事实。
+
+文档可以全是 Steps（recipe）、全是 Reference（review rules 或本 skill），也可以二者兼有。核心判断是把每项内容放在 **Information Hierarchy** 的哪一级；这个阶梯按 agent 多快需要材料排序：
+
+1. **In-file Step**：主要层，agent 按顺序执行的动作。
+2. **In-file Reference**：按需查阅。它可以是合法的 flat peer-set，例如 review 的每条规则都在同一层；这不是结构缺陷。
+3. **Disclosed Reference**：移到独立文件中，由 Context Pointer 到达，只在 pointer 触发时加载。它可以是同一目录的 sibling file，也可以是任何文档都能指向的 External Reference。
+
+下推得太少会让顶部膨胀；下推得太多会藏起 agent 真正需要的材料。这股张力就是全部判断。
+
+**Progressive Disclosure** 是沿阶梯向下移动：把内容从主文件移到 pointer 后面，使顶部保持可辨认。它首先保护 Information Hierarchy，而不只是节省 tokens。Branching 是最清楚的 disclosure test：每个 branch 都需要的内容 inline；只有部分 branches 到达的内容放到 pointer 后面。文档存在 Steps 时，本应 disclosed 的 Reference 会埋住 Steps，使 agent 是否关注它近似 coin-flip；这是 variance lever，不只是可读性问题。
+
+**Co-location** 是同一文件内的配套判断：阶梯决定内容放多深，Co-location 决定到达该层后哪些内容彼此相邻。把一个概念的定义、规则和 caveats 放在同一标题下，而不是散落各处，使 agent 读到一部分时也同时获得它的邻居。测试方式是：文档应像专门写给 agent 的 documentation；相关材料集中时通常如此。Co-location 不同于 Duplication：Duplication 重复同一 meaning，散落则把一个 meaning 的不同部分拆到多处。
+
+**Sprawl** 是这里的 Failure Mode：即使每一行仍然有效且唯一，文档也可能只是太长。过量内容会稀释 attention，每增加一行也多一行需要持续保持 Relevant。处理方式是 Information Hierarchy：把 Reference disclosed 到 pointer 后面，并按 branch 或 sequence 拆分，使每条路径只携带它所需的内容。
+
+## Steps 与 Completion Criteria
+
+每个 Step 都结束于 **Completion Criterion**：告诉 agent 这项工作何时完成的条件。两个属性让它成为行为杠杆：
+
+- **Clarity**：agent 能否区分 done 与 not-done？模糊边界（例如“已经形成理解”）会邀请 **Premature Completion**：当前 Step 尚未真正完成，attention 已滑向 _being done_。仍然可见的后续 Steps——**Post-Completion Steps**——提供向前的拉力，Criterion 的 Clarity 提供阻力。按顺序防守：**先 sharpen bound**，因为它局部且便宜；只有边界不可避免地模糊，且真实运行已经观察到 rush，才通过 sequence split 隐藏后续 Steps。隐藏只有跨越真实 context boundary 才生效，例如 handoff 或 subagent dispatch；inline 调用仍让后续 Steps 留在 context 中，什么也没有清除。
+- **Demand**：Criterion 要求多少工作。“每个修改过的 model 都已核对”会驱动比“生成改动列表”更充分的工作。Demand 驱动 **Legwork**——agent 在工作单元内部完成的挖掘；它潜伏在措辞里，不应另写成机械步骤。Demand 也不依赖 Steps：“每条规则都已应用”同样能约束一份 flat Reference，因此全 Reference 文档仍然可以拥有穷尽门槛。
+
+最强的 Completion Criteria 同时可检查且穷尽。
+
+## 何时拆分
+
+把一份文档拆成两份会花费两种负载之一，因此只在切分确实值得时进行：
+
+- **按 Sequence 拆分**：当 Post-Completion Steps 诱使 agent rush 当前 Step 时切分。把后续内容移出视野，可以驱动当前任务内更多 Legwork。反方向也要小心：合并 sequences 会让每个 Step 看到更多后续 Steps，从而邀请 Premature Completion。
+- **按 Invocation 拆分**：这是 skill 特有的切法；读取 [SKILL-MECHANICS.md](SKILL-MECHANICS.md)。
+
+## Leading Words
+
+**Leading Word** 是模型预训练中已经存在、agent 运行文档时用来思考的紧凑概念，例如 _lesson_、_fog of war_、_tracer bullets_。它以 token 重复，而不是以句子重复；由此积累分布式定义，并用最少 tokens 调用已有 behavioural priors，锚定一整片行为。自造词只要定义清楚也能工作，但它没有预训练 priors：已有词免费提供的东西，自造词要用定义 tokens 偿还，因此先寻找已有词。
+
+Leading Word 有两次锚定作用：
+
+- 在正文中锚定 _execution_：agent 每次看到它都到达相同类型的行为；在 flat Reference 中，它把 attention 聚焦到要寻找的一类对象。
+- 在 pointer 中锚定 _invocation_：当同一个词也存在于 prompts、docs 与 codebase 中时，agent 会把共享语言连接到相应材料，并更可靠地到达它。
+
+主动寻找可以用 Leading Words refactor 的表达：三处都展开的三元组、用整句含糊指向一个想法的 pointer，都应该 collapse 为一个 token。
+
+- “快速、确定、低开销” → _tight_，形成 _tight feedback loop_。
+- “一个你相信的循环” → _red_：模糊门禁变为二元可观察状态——loop 能在 bug 上变 _red_，或不能。
+
+收益有两次：tokens 更少，同时为 agent 的思考提供更锋利的挂钩。默认假设每份文档都携带着可由 Leading Words 退役的复述，并主动寻找它们。
+
+**Negation** 是这个杠杆旁边的 Failure Mode：通过禁止来 steering，会把被禁止的行为拖进 context，反而提高它的可用性。_Don't think of an elephant_，此时 context 中只剩 elephant；negation 是弱 modifier，可能被刚刚强烈激活的概念压过，使禁令被半读成行动提示。Prompt the **positive**：直接描述目标行为，例如“comments 保持单行”，让被禁止对象不进入 frame。只有无法用正向目标表达的硬 guardrail 才值得保留 prohibition；即使如此，也要配对写出正向目标，使 attention 落到应该做什么。
+
+## Pruning
+
+- 让每个 meaning 只有一个 **Single Source of Truth**：一个权威位置，使行为变化只需修改一处。**Duplication** 是同一 meaning 出现在多处；它增加维护与 tokens，并把该 meaning 在 Information Hierarchy 中的 prominence 抬得高于真实层级。它是 Leading Word 的意外反面：Leading Word 有意重复一个 token，从不重复完整 meaning。
+- **environment** 也是 source of truth：`package.json` scripts、config files、目录布局与 `--help` 输出都可以被 agent 直接查看。文档复述这些内容就是 **cache**，只有 lookup 本身昂贵时才值得支付 load。Cache agent 无法通过查看得到的内容：未写下的约定、选择背后的原因、config 不会承认的 gotcha。把一文件或一命令即可得到的事实留在 environment 中，那里不会因复制而 stale。
+- 逐行检查 **Relevance**：这行是否仍直接影响文档所做的事？一行可能从未与任务相关，例如纯 exposition 或本应 disclosed 的 branch；也可能随着行为或世界变化而 stale。更短的文档更容易保持 Relevant。没有 Pruning discipline 时，默认结局是 **Sediment**：旧层因为添加令人安心、删除令人不安而不断沉积，直到维护者必须向下取芯才能找到仍然有效的内容。
+- 逐句寻找 **No-Op**：模型默认已经会遵守的指令，只支付 load 却没有改变行为。测试问题是“相对默认值，它是否改变了行为？”这是 model-relative，而不是 reader-relative；两个人对 No-Op 有分歧，实质是在争论模型默认值，应通过运行文档解决，而不是辩论。句子失败时删除整句，不要靠删几个词保留它。Leading Word 也接受同一测试：如果 _be thorough_ 无法超过模型本来就有的“有点 thorough”，它就是 No-Op；修复方式是更有力的词，例如 _relentless_，而不是另造技巧。

package/skills/writing-for-agents/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Writing For Agents"
+  short_description: "编写或维护供 Agent 使用的 Skills、项目规则与指针文档"
+  default_prompt: "请使用 $writing-for-agents 创建或改写这份 Agent 文档，并核对触发、信息层级与行为约束。"
+policy:
+  allow_implicit_invocation: true

package/skills/writing-great-skills/SKILL.md

@@ -1,125 +0,0 @@
----
-name: writing-great-skills
-description: 创建和编辑高质量 skills 的词汇与原则，核心目标是让 agent 的执行过程可预测。
-disable-model-invocation: true
----
-
-# Writing Great Skills
-
-Skill 的作用，是从 stochastic system 中约束出足够的 determinism。根本美德是 **Predictability**：每次采用相同的过程，而不是每次产生相同的输出。下面所有杠杆都服务于它。
-
-正文中的**粗体术语**均在 [glossary.md](references/glossary.md) 中有完整定义。第一次使用某个术语判断设计时，读取对应定义，不靠近义词猜测。
-
-## 调用方式（Invocation）
-
-有两种调用方式，它们支付不同成本：
-
-- **Model-Invoked** skill 对模型暴露一条 **Description**，因此 agent 可以自主选择它，其他 skills 也可以到达它，用户仍然可以显式输入名称。它在每轮支付 **Context Load**。机制：`SKILL.md` 省略 disable-model-invocation 字段，`agents/openai.yaml` 设置 `policy.allow_implicit_invocation: true`，并编写包含真实触发分支的模型侧 description。
-- **User-Invoked** skill 只由用户显式输入名称启动；模型和其他 skills 都不能启动它。它没有常驻 Context Load，但把“有哪些入口、何时使用”变成用户承担的 **Cognitive Load**。机制：`SKILL.md` 设置 disable-model-invocation 为 true，`agents/openai.yaml` 设置 `policy.allow_implicit_invocation: false`；仍保留一行面向用户和目录展示的 description，但不要把它写成模型触发词清单。
-
-只有当 agent 必须自行到达某项能力，或另一个 skill 必须调用它时，才选择 Model-Invoked。如果它只应由人手动启动，让它保持 User-Invoked。
-
-User-Invoked skills 多到用户难以记住时，用一个 **Router Skill** 降低 Cognitive Load。Router 只说明每个入口及其适用时机；它不能替用户启动另一个 User-Invoked skill，应给出精确命令让用户显式选择。
-
-## 编写 Description
-
-Model-Invoked skill 的 **Description** 同时完成两件事：说明它是什么，并列出应该触发它的真实 **Branches**。每个词都会增加 Context Load，因此 description 比正文更需要裁剪：
-
-- 把 skill 的 **Leading Word** 放在前面，让模型尽早进入正确概念区域。
-- 每个 branch 只保留一个触发条件。仅仅换同义词重复同一 branch 属于 **Duplication**；“用 TDD 构建功能”和“用户要求 test-first”若指同一路径，就不应写两遍。
-- 删除正文已经承担的身份说明。Description 只保留触发分支，以及必要的“当另一 skill 需要……”到达条款。
-- 写出相邻 skill 的关键不适用边界，但不要把整份路由表塞进 description。
-
-User-Invoked skill 的 description 是面向人的一句摘要，不承担模型触发任务。
-
-## 信息层级（Information Hierarchy）
-
-Skill 由两类内容构成：**Steps** 与 **Reference**。二者可以任意组合：全是步骤、全是参考资料，或同时存在。关键是每项内容在 **Information Hierarchy** 中应处于哪一层：
-
-1. **In-skill Step**：`SKILL.md` 中按顺序执行的动作，是主要层。每个真正的 step 都在原位置结束于 **Completion Criterion**，让 agent 能判断该步是否完成。标准应可检查，并在重要处穷尽，例如“每个修改过的 model 都已核对”，而不是“生成改动列表”；它属于步骤边界，不是每个 skill 都要追加的统一尾部章节。
-2. **In-skill Reference**：`SKILL.md` 中按需查阅的定义、规则与事实。它可以是合法的扁平同级集合；全是 reference 的 skill 并不是结构缺陷。
-3. **Disclosed / External Reference**：从 `SKILL.md` 移到独立文件、只在 **Context Pointer** 触发时加载的资料。它可以是 skill 内的 `references/*.md`，也可以是 skill 系统之外由多个 skills 指向的普通文件。
-
-高要求的 Completion Criterion 会驱动充分 **Legwork**。这一点既适用于 steps，也适用于 flat reference：“应用每条规则”同样可以约束全 reference skill 的覆盖度。
-
-顶部保留过多内容会造成 **Sprawl**；向下推得太多会藏起每条 branch 都需要的材料。**Progressive Disclosure** 就是在这股张力中把 reference 下移：每条 branch 都需要的内容内联，只有部分 branch 需要的内容放到清楚命名的文件后面。Context Pointer 的措辞，而不是目标文件本身，决定 agent 何时、是否可靠地读取它。
-
-Information Hierarchy 决定材料放多深，**Co-location** 决定放在同一层的哪些材料应相邻。一个概念的定义、规则和 caveats 应聚在同一标题下，让 agent 读到一部分时同时获得其邻居。
-
-## 何时拆分
-
-**Granularity** 是 skills 被切分得多细。每次切分都会增加 Context Load 或 Cognitive Load，因此只有切分带来明确收益时才做。两种有效切法：
-
-- **By Invocation**：某项能力拥有独立 Leading Word，应该自主触发，或必须被另一 skill 调用时，把它拆成 Model-Invoked skill。新增的常驻 description 必须值得它支付的 Context Load。
-- **By Sequence**：当前 step 后面可见的 **Post-Completion Steps** 让 agent 急于向前、产生 Premature Completion 时，把后续步骤隐藏到真实上下文边界之后。先尝试把当前 step 的 Completion Criterion 写清；只有标准不可避免地模糊、且真实测试观察到抢跑时才切分。
-
-仅仅把后续内容写在同一文件的另一个标题下不会形成上下文边界。有效边界来自用户显式交接或独立 subagent dispatch。
-
-## 修剪（Pruning）
-
-让每个 meaning 只有一个 **Single Source of Truth**，这样行为变化只需修改一处。
-
-逐行检查 **Relevance**：它现在是否仍直接影响 skill 的行为？再逐句进行 **No-Op** 测试：与模型默认行为相比，这句话是否真的改变执行？一句失败时删除整句，不要靠换词保留没有行为价值的 prose。
-
-主动寻找 **Sediment**、**Duplication** 与 Sprawl。添加通常让人感觉安全，删除让人感觉冒险，因此没有裁剪纪律的 skill 会自然积累失效层。
-
-## Leading Words（引导词）
-
-**Leading Word** 是模型预训练中已经存在、运行 skill 时会用来思考的紧凑概念，例如 _lesson_、_Zone of Proximal Development_、_fog of war_、_tracer bullets_。它用很少 tokens 调用已有 priors，并在 skill 各处形成分布式定义。
-
-Leading Word 对 Predictability 有两次作用：
-
-- 在正文中锚定 execution：每次出现都把 agent 拉回同一种行为；
-- 在 description 中锚定 invocation：当用户 prompts、项目 docs 与代码也使用同一词时，agent 更可靠地把请求连到 skill。
-
-寻找可被 Leading Word 折叠的重复表达。三个位置都写一遍的三元组、用整句含糊指向一个概念的 description，通常都可以 collapse：
-
-- “快速、确定、低开销”可折叠为 _tight_，形成 tight feedback loop；
-- “一个你相信的循环”可折叠为 _red_，把模糊门禁变成二元可观察状态：loop 能在 bug 上变 red，或不能。
-
-优先使用已有词。自造词没有预训练 priors，需要用额外定义 tokens 偿还成本。
-
-## 上游本地化
-
-本地化不是摘要竞赛。处理已有优秀上游 skill 时：
-
-1. 锁定来源版本，完整读取 `SKILL.md`、references、scripts 与 metadata。
-2. 保留步骤顺序、Leading Words、Completion Criterion 的原位置、示例作用和 Progressive Disclosure 关系。
-3. 只做有证据的适配：去个人化、删除不存在的命令、翻译普通说明、映射真实宿主路径与工具、加入必要权限边界、修复可证实矛盾。
-4. 不强加统一章节，不把短 orchestration skill 扩成第二套方法，不把 reference-first skill 改成主动工作流。
-5. 上游 skill 被移除但附件仍有独立方法价值时，把它迁移到职责最接近的现有 skill，并更新 Context Pointer。
-
-采用 **Conservation First（保留优先）**：默认认为上游的限定词、判断规则、失败边界、例子和刻意重复都可能承担行为约束。逐句翻译时特别保留 `where possible`、`each claim`、`before`/`after`、`only` 等会改变适用范围、时机或证据强度的词。
-
-只有满足以下至少一项，才合并、删除或替换上游内容：
-
-- 属于个人化角色、作者口吻或不存在的命令；
-- 与真实宿主、平台 API 或本地权限边界冲突，并有一手资料或可运行证据；
-- 与同一权威位置完全重复，删除后所有谓词、例子作用和 completion criterion 仍有唯一去向；
-- 独立前向测试确认它是 No-Op，删除后没有触发、执行、停止或失败边界回退。
-
-上游例子是规则的一部分：诊断例子、反例和 branch 选择例子不得只剩抽象总结。需要适配例子时，替换个人语境或失效工具，但保留它原来帮助 agent 区分的情况。
-
-AI 提出的“优化”只有在能说明解决了什么真实问题，并通过场景或结构验证时才优先于上游；更整齐、更短或更长都不是改写依据。对是否可删存在疑问时，保留。
-
-## NetPilot 宿主适配
-
-- 目录名与 frontmatter `name` 使用唯一的英文 kebab-case；`display_name` 从 canonical name 派生。中文用户可见的 description、`short_description`、`default_prompt` 和正文使用中文，代码、路径、命令与标准术语保留英文。
-- 每个 skill 提供 `agents/openai.yaml`。`default_prompt` 必须显式包含对应的 `$<skill-name>`；Claude Code 的调用形式由 README 说明，不在正文复制三套工作流。
-- 大段 reference 放在 `references/`，确定性重复操作放在 `scripts/`，静态模板和可复用产物放在 `assets/`。Context Pointer 只深入一层，并清楚说明何时读取。
-- 创建或修改前收集正向、反向和压力场景。完成后运行结构校验、真实触发测试和权限门禁测试；根据观察到的失败修改最小必要内容。
-- Git、issue tracker、外部消息和其他可见写入可以成为 skill 能力，但必须有明确目标与用户授权，并在正文说明触发条件、完成证据与失败边界。Invocation classification 不等于动作权限。
-- 去除个人角色、作者口吻、私有暗语和不存在的命令。实质改编受许可约束的内容时，在仓库级 `THIRD_PARTY_NOTICES.md` 保留必要法律声明。
-- 普通过程标题和说明使用中文；稳定 Leading Words、领域术语、协议字段、label、代码和路径保留英文，并在首次出现时解释。
-- 不强制统一“完成标准”或“反模式”。上游或该方法自身需要时保留，否则用真实步骤内的 Completion Criterion 和 Failure Modes。
-
-## 失败模式（Failure Modes）
-
-用这些模式诊断 skill：
-
-- **Premature Completion**：step 在真正完成前结束。先 sharpen Completion Criterion；只有标准无法更清楚且测试确实观察到抢跑时，才隐藏 Post-Completion Steps。
-- **Duplication**：同一 meaning 有多个来源，增加维护和 tokens，并把它在层级中的权重抬得过高。
-- **Sediment**：旧内容因为只加不删而沉积。
-- **Sprawl**：即使每行仍有效且唯一，`SKILL.md` 也可能长到削弱注意与可维护性。用 Information Hierarchy、branches 和 sequence cuts 处理。
-- **No-Op**：模型默认就会做的指令。弱 Leading Word 也可能是 No-Op；换成足以改变行为的词，或删除。
-- **Negation**：用禁止语激活了被禁止行为。优先描述正向目标；只有无法正向表达的硬 guardrail 才保留禁止，并同时说明应采取的替代行为。

package/skills/writing-great-skills/agents/openai.yaml

@@ -1,6 +0,0 @@
-interface:
-  display_name: "Writing Great Skills"
-  short_description: "用可预测性、信息层级和裁剪原则创建或改写高质量 skills"
-  default_prompt: "请使用 $writing-great-skills 创建或改写这个 skill，并验证其调用、过程与权限边界。"
-policy:
-  allow_implicit_invocation: false