@netpilot/skills 0.3.2 → 0.4.0

package/skills/wayfinder/SKILL.md

@@ -1,81 +1,188 @@
 ---
 name: wayfinder
-description: 当用户有一个规模较大但边界模糊的产品、技术或工作流想法，不知道从哪里开始、先验证什么或如何形成路线时使用。它通过探索、研究和风险排序收敛方向；已有明确规格的任务不使用。
+description: 为超过单个 agent 会话且仍处于 fog of war 的大型工作建立 decision map，逐票解决决策直到路线清楚。
+disable-model-invocation: true
 ---
 
 # Wayfinder
 
-把模糊愿景转成一条可验证、可调整的路线。重点不是一次设计完整终局，而是找到最短的可信学习路径。
+Wayfinding 的目标是找到通往 **Destination** 的路，不是冲向 Destination。命名 Destination 是建图的第一项动作，因为它会塑造每一张 ticket。Destination 可能是交给后续流程迭代的明确 spec、规划前尚待锁定的 decision，或在当前 effort 原地完成的 migration。Map 不限定领域：工程、课程内容或其他超过单会话且仍在 fog of war 中的工作都可以使用。
 
-## 阶段一：建立地图
+地图由 decision tickets 组成：每票解决一个问题，产物是 decision，而不是 build slice。Destination 是 spec 时，路线清楚后默认交给 `$to-spec`；Destination 本身是 decision 或 Notes 明确允许原地 migration 时，按该 Destination 的完成条件结束，不机械转成 spec。
 
-先检查现有资料，然后回答：
+## 动作门禁
 
-- 想改变谁的什么现状，为什么现在值得做？
-- 可观察的成功结果是什么？
-- 哪些内容明确不在当前范围？
-- 已有哪些代码、数据、流程、约束和可复用资产？
-- 哪些未知项一旦判断错误，会使整个方向失效？
+用户显式调用且仓库、tracker、map 或 destination 唯一时，可以自动：
 
-必要时调用 `grilling` 逐题访谈；术语混乱时调用 `domain-modeling`。
+- 创建 map 与 child tickets；
+- 添加标签、blocking 和 sub-issue；
+- 指派 ticket 作为 claim；
+- 写 resolution comment；
+- 关闭已解决或确定超出范围的 ticket；
+- 更新 map；
+- 在明确 context 中沉淀 decision 形成的稳定领域语言或 ADR；
+- 对明确的 prototype ticket 授权 `$prototype` 创建本地 throwaway branch、实现并 commit artifact，以及写回该 ticket；这不授权写入正式代码；
+- 为 research ticket 创建隔离本地 branch/worktree 并 commit artifact。
 
-调用子 skill 时必须传递用户的权限约束、当前范围、已知事实、唯一待回答问题和预期返回格式。“只读”“仅规划”“不创建文件”或“禁止外部写入”等约束自动继承，子 skill 不得放宽。默认一次只推进一个信息价值最高的访谈、研究或原型；子 skill 只回答被分配的问题，完成后把控制权交回 `wayfinder`，由这里整合路线，避免递归扩大任务。
+目标不清时，先只读加载现状，展示计划创建或改变的对象，再询问。
 
-## 阶段二：探索路径
+永不自动 push、创建 PR、merge、deploy 或发布。研究结果必须同时写入 tracker resolution，不能假设本地 commit 对远程协作者可见。
 
-提出 2 至 4 条真正不同的候选路径。每条都说明：
+先按 `triage` 的 [项目 tracker 配置](../triage/references/project-config.md) 发现目标；具体操作见 [GitHub](../triage/references/issue-tracker-github.md)、[GitLab](../triage/references/issue-tracker-gitlab.md) 与 [Local Markdown](../triage/references/issue-tracker-local.md) 参考。
 
-- 核心假设；
-- 最小用户价值；
-- 主要依赖和约束；
-- 最大失败模式；
-- 最便宜的验证方式；
-- 成功后下一步与失败后的退路。
+## 默认只规划，不实施
 
-需要外部事实时调用 `research`，需要运行证据时调用 `prototype`。不要用更多文档替代本应进行的验证。
+默认只做决策。想直接实施通常说明已经到达地图边缘，应 handoff 给主流程。
 
-## 阶段三：选择第一段路
+只有 map 的 Notes 明确声明某类执行属于该 effort，才允许 task ticket 执行必要动作。即使如此，task 也必须为了解除一个 decision blocker，而不是提前交付 destination。
 
-按“信息价值、用户价值、风险降低、实施成本、可逆性”排序。推荐一条路径，同时保留至少一个被否定方案及原因，避免把唯一提案误当成唯一可能。
+## 以名称引用
 
-将路线拆成阶段，而不是伪精确的长期任务表：
+所有 map 和 ticket 在面向人的叙述中都以标题引用。标识符和 URL 放在标题链接内，不用一串裸编号代替可读名称。
 
-1. **探索**：解决会改变方向的未知项。
-2. **成形**：确认最小端到端价值和领域边界。
-3. **交付**：形成规格、垂直任务与验证门禁。
-4. **扩展**：仅在证据支持时增加范围和自动化。
+## 地图
 
-推荐路线的第一阶段必须是一张可检查的实验卡，至少包含：要支持的决策、可证伪假设、成功与失败门槛、时间或成本上限，以及结果出现后“继续、换路、停止”三个出口。
+Map 是一个标记为 `wayfinder:map` 的 tracker item，也是 canonical artifact。远程 tracker 使用 parent/child issue；本地 fallback 使用一份 map 文件和每票一个文件。
 
-## 默认产物
+Map 是索引，不重复保存 ticket 的完整答案。每个 decision 只在其 ticket 的 resolution 中存在；map 只写一句 gist 并链接。
 
-在回答中或用户指定的本地 Markdown 文件中形成：
+Map body 是每个 session 只加载一次的低分辨率视图。Open tickets 不列在 body 中，而是通过 child-ticket query 获取。
 
 ```markdown
-# 路线图
-## 愿景与成功信号
-## 当前资产与约束
-## 关键未知项
-## 候选路径与取舍
-## 推荐路径
-## 分阶段验证
-## 停止条件与回退方案
-## 下一步
+## Destination
+一到两行说明地图结束时应得到什么。
+
+## Notes
+领域、每个 session 应调用的 skills、常驻约束和权限。
+
+## Decisions so far
+- [已关闭 ticket 标题](link) — 一行 decision gist
+
+## Not yet specified
+仍在 scope 内，但尚无法精确表述为问题的 fog。
+
+## Out of scope
+明确位于 destination 之外的内容。
+```
+
+远程 tracker 不可用时，使用：
+
+```text
+.scratch/<effort>/map.md
+.scratch/<effort>/issues/<NN>-<slug>.md
+```
+
+保持与远程相同的 parent、state、blocking 和 resolution 语义。
+
+## 票据（Tickets）
+
+每票是 map 的 child issue，大小不超过一个新鲜 agent session：
+
+```markdown
+## Question
+本 ticket 要解决的 decision 或 investigation。
 ```
 
-默认不创建远程 issue、项目看板或其他外部资源。只有用户明确授权并指定目标系统后才执行外部写入。
+每票必须带一个 `wayfinder:<type>` label：
+
+- **research**：AFK。当 decision 等待当前工作目录之外的一手知识时使用，读取并返回带来源的事实；普通 repo exploration 不建立 research ticket。
+- **prototype**：HITL。制作低成本 artifact，让人对具体形态或行为作出判断。
+- **grilling**：HITL。调用 `$grilling` 与 `$domain-modeling`，一次一个问题；这是不确定类型时的默认选择。
+- **task**：HITL 或 AFK。完成一个必须先发生、但本身没有 decision 的动作，以解除后续阻塞。Resolution 要记录后续 tickets 依赖的事实，例如 credential location、URL、row count 或完成步骤。
+
+HITL ticket 必须让真人表达自己的判断；agent 不得代替用户回答访谈问题。
+
+解决 ticket 时产生的 prototype、research report 或其他 assets 只从 issue 链接，不把完整 artifact 粘贴进 ticket body。
+
+## Claim、Blocking 与 Frontier
+
+开始工作前先 claim ticket。远程 tracker 通过 assignee 表示 claim；本地 tracker 记录 claim 字段。并发 session 必须跳过已 claim ticket。
+
+优先使用 native blocking；不支持时使用正文关系。
+
+- ticket 的所有 blockers 都关闭后，它才 unblocked；
+- frontier 是所有 open、unblocked、unclaimed child tickets；
+- 没指定 ticket 时，从 frontier 顺序中取第一项。
+
+## 战争迷雾（Fog of war）
+
+地图故意不完整。能看见某个区域迟早需要处理，但现在还无法准确说出问题时，把它写进 **Not yet specified**。
+
+判断标准不是“现在能否回答”，而是“现在能否把问题精确说出来”：
+
+- 能精确表达问题：建 ticket，即使它当前 blocked；
+- 不能精确表达问题：留在 fog；
+- 已决定：进入 Decisions so far；
+- 已有 live ticket：不再重复；
+- 超过 destination：进入 Out of scope。
+
+一个 fog patch 之后可能生成多个 tickets，也可能不生成任何 ticket。
+
+## 超出范围
+
+Out of scope 是经过确认的 scope boundary，不是尚未看清的 fog，永不自动 graduate。
+
+如果已建 ticket 后来证明位于 destination 之外：
+
+1. 关闭该 ticket；
+2. 在 map 的 Out of scope 写一行理由并链接；
+3. 不把它写进 Decisions so far。
+
+只有 destination 被重新定义时，才将相关内容作为新 effort 重新考虑。
+
+## 调用模式一：Chart the map
+
+用户以大型模糊想法调用：
+
+1. **Name the destination**
+   调用 `$grilling` 和 `$domain-modeling`，明确 map 最终要找到什么。它们返回 destination、scope 和统一术语。
+
+2. **Breadth-first map the frontier**
+   再次访谈，但横向扫描整个空间，寻找当前可精确表达的 decisions 与仍在 fog 中的区域。不要过早深入单一分支。
+
+3. **检查是否真的需要 map**
+   如果没有 fog，且全部工作可在一个 session 中解释清楚，停止建图，告诉用户应进入 `$to-spec` 或 `$implement`。
+
+4. **Create the map**
+   填写 Destination、Notes、空的 Decisions so far、Not yet specified 和 Out of scope。
+
+5. **Create then wire tickets**
+   先创建所有当前可定义的 child tickets，拿到真实标识符后，第二 pass 再建立 blocking。不能在创建前猜 id。
+
+6. **Fire research tickets**
+   research tickets 可以并行：
+   - 为每票创建隔离 worktree/本地 branch；
+   - 调用 `$research` 写带引用的 Markdown artifact；
+   - commit artifact；
+   - 在 ticket 中留下指向 branch 与 artifact 的 context pointer；
+   - 将完整结论或足以独立理解的摘要与引用写入 resolution comment；
+   - 关闭 research ticket并更新 map。
+   不得自动 push branch。
+
+7. **Stop**
+   Charting session 不手工解决 grilling、prototype 或 task ticket。
 
-## 完成标准
+## 调用模式二：Work through the map
 
-- 愿景已转成可观察的目标和明确非目标。
-- 最大未知项有研究、原型或访谈方式，而不是被当成事实。
-- 第一阶段足够小，可以产生决策证据。
-- 当前阶段允许的读取、本地写入、外部写入和需再次授权的动作已经明确。
-- 用户知道下一步进入 `research`、`prototype`、`domain-modeling`、`codebase-design` 或 `to-spec` 中的哪一个；关键假设未验证前不进入代码库结构设计。
+用户提供 map URL、编号或本地路径。ticket 参数可选。
 
-## 反模式
+1. 加载 map 的低分辨率视图，不一次读取所有 ticket body。
+2. 用户指定 ticket 时使用它；否则选择第一个 frontier ticket。
+3. 在工作前 claim。
+4. 按 type 解决，并调用 map `Notes` 中点名的 skills；未指定且不确定时默认使用 `$grilling` + `$domain-modeling`：
+   - research → `$research`；
+   - prototype → `$prototype`；
+   - grilling → `$grilling` + `$domain-modeling`；
+   - task → 完成解除 decision blocker 所需的最小动作。
+5. 需要时再 zoom：按需读取相关 open/closed ticket 全文。
+6. 记录 resolution：
+   - 写 resolution comment；
+   - 关闭 ticket；
+   - 在 Decisions so far 追加标题链接与一行 gist。
+7. 更新地图：
+   - create then wire 新 ticket；
+   - 把已变得可精确表达的 fog 转为 ticket，并从 Not yet specified 删除；
+   - 把越过 destination 的 ticket 关闭并放入 Out of scope；
+   - 更新或关闭被该 decision 推翻的 tickets。
 
-- 不要把头脑风暴清单冒充路线。
-- 不要在关键假设未验证前设计完整平台。
-- 不要用抽象愿景替代成功信号。
-- 不要未经授权把本地规划同步到外部系统。
+除并行 research tickets 外，一个 session 最多解决一个 decision ticket。其他 session 可能同时修改 tracker，每次写入前重新读取相关状态。

package/skills/wayfinder/agents/openai.yaml

@@ -1,6 +1,6 @@
 interface:
   display_name: "Wayfinder"
-  short_description: "把模糊的大型想法逐步收敛为可执行、可验证的项目路线"
-  default_prompt: "请使用 $wayfinder 将这个模糊想法收敛成阶段清楚、风险可控的执行路线。"
+  short_description: "为大型模糊工作建立 decision map，并逐票消除 fog of war"
+  default_prompt: "请使用 $wayfinder 为这个大型模糊工作建立或推进 decision map。"
 policy:
-  allow_implicit_invocation: true
+  allow_implicit_invocation: false

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

@@ -1,83 +1,125 @@
 ---
 name: writing-great-skills
-description: 当用户要创建、改写、本地化、拆分、合并或评估一个供 Codex 与 Claude Code 使用的 skill 时使用。它设计清晰触发边界、渐进式说明、宿主 metadata 和真实场景测试；普通文档写作不使用。
+description: 创建和编辑高质量 skills 的词汇与原则，核心目标是让 agent 的执行过程可预测。
+disable-model-invocation: true
 ---
 
 # Writing Great Skills
 
-高质量 skill 不是知识文章，而是一组在正确场景自动触发、能稳定约束行动并具有可验证完成条件的工作说明。
+Skill 的作用，是从 stochastic system 中约束出足够的 determinism。根本美德是 **Predictability**：每次采用相同的过程，而不是每次产生相同的输出。下面所有杠杆都服务于它。
 
-## 1. 定义行为契约
+正文中的**粗体术语**均在 [glossary.md](references/glossary.md) 中有完整定义。第一次使用某个术语判断设计时，读取对应定义，不靠近义词猜测。
 
-先收集 3 至 5 个应触发请求和 2 至 3 个不应触发请求，明确：
+## 调用方式（Invocation）
 
-- skill 解决的重复问题；
-- 使用前提和允许的写入范围；
-- 必须遵循的步骤与可调整部分；
-- 完成证据；
-- 容易出现的失败模式。
+有两种调用方式，它们支付不同成本：
 
-如果两个 skill 的触发条件和主要产物高度重叠，优先合并或建立明确的“入口 + 内部引擎”关系，不创建同义别名。
+- **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，但不要把它写成模型触发词清单。
 
-## 2. 设计名称与描述
+只有当 agent 必须自行到达某项能力，或另一个 skill 必须调用它时，才选择 Model-Invoked。如果它只应由人手动启动，让它保持 User-Invoked。
 
-- 目录名和 `name` 使用小写英文 kebab-case，简短表达能力。
-- `description` 同时说明做什么、何时使用和关键的不使用边界，因为它决定模型是否能正确触发。
-- 面向中文用户时，正文、描述、`short_description` 和 `default_prompt` 使用中文；`display_name` 使用由 canonical name 派生的英文可读标题，代码、路径、命令和标准技术标识保持英文。
-- 去除个人名字、组织暗语和只有原作者才理解的语境。
+User-Invoked skills 多到用户难以记住时，用一个 **Router Skill** 降低 Cognitive Load。Router 只说明每个入口及其适用时机；它不能替用户启动另一个 User-Invoked skill，应给出精确命令让用户显式选择。
 
-## 3. 用官方脚手架创建
+## 编写 Description
 
-新 skill 优先使用当前宿主提供的 skill 初始化脚本，生成标准 `SKILL.md` 与 `agents/openai.yaml`。不要手工复制一个包含残留内容的旧目录。
+Model-Invoked skill 的 **Description** 同时完成两件事：说明它是什么，并列出应该触发它的真实 **Branches**。每个词都会增加 Context Load，因此 description 比正文更需要裁剪：
 
-`SKILL.md` frontmatter 至少包含：
+- 把 skill 的 **Leading Word** 放在前面，让模型尽早进入正确概念区域。
+- 每个 branch 只保留一个触发条件。仅仅换同义词重复同一 branch 属于 **Duplication**；“用 TDD 构建功能”和“用户要求 test-first”若指同一路径，就不应写两遍。
+- 删除正文已经承担的身份说明。Description 只保留触发分支，以及必要的“当另一 skill 需要……”到达条款。
+- 写出相邻 skill 的关键不适用边界，但不要把整份路由表塞进 description。
 
-```yaml
----
-name: example-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 偿还成本。
 
-Codex 的 `agents/openai.yaml` 应包含与 canonical name 一一对应的英文 `display_name`、25 至 64 字符的中文 `short_description`，以及显式提到对应 skill（本 skill 为 `$writing-great-skills`）的中文 `default_prompt`。例如 `code-review` 显示为 `Code Review`，不要另造中文名称。跨宿主共用一份正文时保持可组合调用，并用正文门禁控制动作；只有先建立可验证的宿主专用生成层后，才能为某个宿主单独禁用隐式调用。
+## 上游本地化
 
-## 4. 编写最小充分说明
+本地化不是摘要竞赛。处理已有优秀上游 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。
 
-- 使用命令式、可观察的指令。
-- 解释会影响判断的“为什么”，不解释常识。
-- 能由 agent 根据上下文决定的细节不要硬编码。
-- 大段参考资料放入 `references/`，确定性重复操作放入 `scripts/`，输出用模板或静态文件放入 `assets/`。
-- 引用只深入一层，并清楚说明何时读取资源。
-- skill 调用其他 skill 时，写明触发条件和返回关系，避免循环调用。
+采用 **Conservation First（保留优先）**：默认认为上游的限定词、判断规则、失败边界、例子和刻意重复都可能承担行为约束。逐句翻译时特别保留 `where possible`、`each claim`、`before`/`after`、`only` 等会改变适用范围、时机或证据强度的词。
 
-跨宿主兼容时以通用 Agent Skills 结构为核心，把 Codex 专用 metadata 放在 `agents/`，把插件级差异放在各宿主 manifest；不要在正文复制两套流程。
+只有满足以下至少一项，才合并、删除或替换上游内容：
 
-## 5. 测试与迭代
+- 属于个人化角色、作者口吻或不存在的命令；
+- 与真实宿主、平台 API 或本地权限边界冲突，并有一手资料或可运行证据；
+- 与同一权威位置完全重复，删除后所有谓词、例子作用和 completion criterion 仍有唯一去向；
+- 独立前向测试确认它是 No-Op，删除后没有触发、执行、停止或失败边界回退。
 
-1. 运行结构验证器，检查 frontmatter、名称、描述和资源引用。
-2. 用真实请求进行前向测试：观察 skill 是否触发、是否遵循门禁、是否产出预期证据。
-3. 用反例测试误触发和职责重叠。
-4. 对高风险指令做压力测试，例如用户要求跳过验证、越权写入或把推断当事实。
-5. 依据失败修改最小必要指令，再重复测试；不要为了单个例子堆叠大量例外。
+上游例子是规则的一部分：诊断例子、反例和 branch 选择例子不得只剩抽象总结。需要适配例子时，替换个人语境或失效工具，但保留它原来帮助 agent 区分的情况。
 
-## 上游改编
+AI 提出的“优化”只有在能说明解决了什么真实问题，并通过场景或结构验证时才优先于上游；更整齐、更短或更长都不是改写依据。对是否可删存在疑问时，保留。
 
-可以吸收上游方法，但应重新表达并适配本地安全规则、工具能力和语言。复制或实质改编受许可证约束的内容时，在仓库级 `THIRD_PARTY_NOTICES.md` 保留必要版权与许可证声明；不需要为每个 skill 建立复杂来源注册表。
+## 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。
 
-- 名称唯一，触发描述能区分相邻 skill。
-- 正文包含可执行工作流、完成标准和反模式。
-- metadata 与正文一致，内部引用能解析。
-- 结构验证、正向场景、反向场景和至少一个压力场景有真实结果。
-- 上游改编满足许可证要求且没有残留个人化符号。
+## 失败模式（Failure Modes）
 
-## 反模式
+用这些模式诊断 skill：
 
-- 不要把长篇教程直接包装成 skill。
-- 不要创建职责相同、名称不同的入口。
-- 不要只翻译词句而保留不适合本地环境的权限假设。
-- 不要在没有运行验证时声称 skill 可用。
-- 不要把所有知识塞进 `SKILL.md`，造成每次触发都加载无关上下文。
+- **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 +1,6 @@
 interface:
   display_name: "Writing Great Skills"
-  short_description: "设计、编写、测试并持续迭代高质量、可触发且可靠的技能"
-  default_prompt: "请使用 $writing-great-skills 创建或改进一个 skill，并用真实场景验证其触发和行为。"
+  short_description: "用可预测性、信息层级和裁剪原则创建或改写高质量 skills"
+  default_prompt: "请使用 $writing-great-skills 创建或改写这个 skill，并验证其调用、过程与权限边界。"
 policy:
-  allow_implicit_invocation: true
+  allow_implicit_invocation: false