@namewta/speculo 1.0.24 → 2.0.1

package/template/skills/retrospective/SKILL.md

@@ -1,43 +0,0 @@
----
-name: retrospective
-description: Analyze a development session or Speculo usage feedback when asked for a retrospective; return evidence, root causes, and improvement proposals to the caller, without executing fixes or remote operations.
-metadata: {"speculo-id": "retrospective", "speculo-kind": "skill", "speculo-legacy-name": "Speculo Retro"}
----
-
-# Retrospective
-
-## 输入
-
-- 当前会话、开发活动及调用方明确关联的 change/commands/workflows。
-- `commands/<command>/*.md` 报告、active change 状态、archive 和 `INDEX.md` 声明的知识 store。
-- 可选已有 issues，用于语义去重。
-
-## 流程
-
-1. 按本次 scope 和来源 ID 定位相关证据，再读取 [ friction-taxonomy.md ](references/friction-taxonomy.md)；穷尽当前范围内的已定位摩擦，不全量读取 archive/知识库。完成标准：每项都有来源路径或对话节点。
-2. 按 bug、friction、missing-capability、doc-gap、ergonomics 归类，合并同一根因。完成标准：每项只属于一个根因簇，合并关系可追溯。
-3. 按下方修复方向分类，再评估影响与频率，过滤一次性噪声；低信号项标为丢弃或仅记教训。完成标准：每项都有优先级和处置理由。
-4. 读取 [ issue-drafting-sop.md ](references/issue-drafting-sop.md)，生成 issue-ready 提案并与已有 issue 去重。完成标准：标题、证据、问题、建议、验收、影响资产和去重结论齐全。
-
-## 输出
-
-- 按优先级排序的 `file-issue | lesson-only | discard | duplicate | insufficient-evidence | no-findings` 结果，不强行制造 Issue。
-- 合并/丢弃说明和调用方执行 `gh` 所需字段。
-
-本 skill 不写文件、不调用外部 API；调用方 command/Work 负责持久化、授权和后续路由。
-
-## 修复方向：先减少未来重复指令
-
-每个根因簇保留原 issue type，同时选择一个 remediation_axis；这不是新的远程标签或状态机。
-
-| remediation_axis | 首选提案与验收 |
-|---|---|
-| code-defect | 最小复现/回归测试与局部修复，证明目标症状红→绿 |
-| deterministic-check-gap | lint、validator、pre-commit 或 CI 中可判定断言，至少一个通过与一个拒绝样本 |
-| context-pointer | 修正触发、owner、失效路径或条件引用；验证应触发与近邻不触发 |
-| judgment-rule | 仅保留不能由机械检查替代的真实判断、权衡与边界，注明反例 |
-| environment-discovery | 修复命令/工具/配置的可发现性或环境反馈，避免文档缓存简单可查询事实 |
-
-检查缺口优先提到测试/工具，不再把同一禁令复制到多个 Work。没有因果证据时标为假设并给验证方法；删除指令的提案必须附运行对照方案，不把“模型应该会”当作删除证据。
-
-只提出建议，不直接改 AGENTS/全局提示词、永久知识或项目代码，不创建远程 Issue；调用方的报告、确认与目标仓库边界保持。

package/template/skills/retrospective/references/issue-drafting-sop.md

@@ -1,69 +0,0 @@
-# Issue Drafting SOP
-
-把通过过滤的改进提案规范化成 issue-ready 结构、对照已存在 issue 去重、生成交给调用方 / `gh` 的交接字段。
-
-## 提案字段（issue-ready）
-
-每条提案产出以下结构化字段，调用方据此写报告并据此调 `gh`：
-
-```jsonc
-{
-  "title":        "string, 见标题规范",
-  "type":         "bug | friction | missing-capability | doc-gap | ergonomics",
-  "priority":     "critical | high | medium | low",
-  "area":         "string|null, 例 commands / workflows / skills / cli / contract",
-  "body":         "string, 见正文结构",
-  "remediation_axis": "code-defect | deterministic-check-gap | context-pointer | judgment-rule | environment-discovery",
-  "regression":   {"positive": "通过样本与可观察结果", "negative": "拒绝/停止样本与不应出现的副作用"},
-  "affected":     ["相对路径，例 speculo/commands/archive-and-consolidate.md"],
-  "evidence":     ["证据出处，例当前会话节点或具体工件及段落"],
-  "disposition":  "file-issue | lesson-only | discard | duplicate",
-  "dup_of":       "number|null, 疑似重复的已存在 issue 编号"
-}
-```
-
-## 标题规范
-
-- 用祈使句描述「要改成什么」，不是「哪里坏了」：`命名` 区分度差 ❌ → `enhancement: 提升 command description 在系统提示里的区分度` ✅
-- 前缀对齐类型：`bug:` / `enhancement:` / `docs:` / `feature:`
-- 单行、可独立读懂、不超过约 70 字，含受影响的 asset 名。
-
-## 分类与标签
-
-只返回语义类型、优先级与领域；标签名称、存在性、创建权限和映射由调用方决定，不要求每个仓库都具备某套标签。不确定改进方向时记录设计缺口，不自行增加远程标签。
-
-## 正文结构
-
-每条 issue body 用固定小节，占位符填实，禁止空话：
-
-```markdown
-## 问题
-[一句话说清痛点 / 不符合预期的行为。]
-
-## 证据
-[引用具体出处：对话节点、`<Path>{roots.state}/...</Path>` 产物路径、`.status.json` 字段、文档段落。可附最小复现。]
-
-## 根因
-[判断是 asset 设计 / 持久化契约 / 文档 / 工具问题，指明根因而非表象。]
-
-## 建议改动
-[改哪个 asset、怎么改。给相对路径与具体方向，不要泛泛而谈。]
-
-## 验收标准
-[可验证的完成判据、通过/拒绝样本、回归命令与未验证项。机械问题写确定性检查，不以新增提示词代替测试。]
-
-## 受影响资产
-[列出相关相对路径。]
-```
-
-## 去重
-
-起草后、交给调用方提交前，对每条做去重判定：
-
-1. 提取标题与根因的关键词。
-2. 由调用方用 `gh issue list --repo <owner/repo> --search "<关键词>" --state all --limit 20` 检索；Skill 自身不执行远程检索。
-3. 命中语义重复：把 `disposition` 设为 `duplicate` 并在 `dup_of` 记录已存在编号，默认不重复提；仅当用户明确要求才补提。
-
-## 交接契约
-
-本 skill 只返回结构化提案清单与丢弃/合并说明，**不写文件、不调用 `gh`、不创建 issue**。command 或 Work 选择自己的报告路径、标签和授权方式；无发现与证据不足同样是有效分析结果。

package/template/skills/source-code-zip/SKILL.md

@@ -1,54 +0,0 @@
----
-name: source-code-zip
-description: Create a requested source ZIP using the bundled Node script and its ignore rules; do not install dependencies.
----
-
-# Source Code ZIP
-
-先确认 node 可用，只有 node 不存在时才回退 nodejs。使用 scripts/zip_source_code.js；无第三方依赖，不安装 npm/Python/zip 工具。
-
-## 标准工作流
-
-1. 确认用户提供的是目录路径，不是单个文件；路径含空格时必须加引号。
-2. 先确认 `node --version` 能正常执行。
-3. 默认先运行一次 `--dry-run`；目录较大、规则刚修改或可能包含敏感信息时，同时添加 `--verbose`。
-4. 检查预览结果，确认 `.env`、YAML、依赖目录、构建产物、归档文件和密钥没有被纳入。
-5. 正式创建 ZIP。
-6. 报告 ZIP 的绝对路径、纳入文件数、输入总大小和生成结果。
-7. 除非用户明确理解风险并提出要求，不得使用 `--no-default-ignore`。
-
-推荐预览：
-
-```bash
-node scripts/zip_source_code.js "/path/to/project" --dry-run
-```
-
-查看每个项目被排除的原因：
-
-```bash
-node scripts/zip_source_code.js "/path/to/project" \
-  --dry-run \
-  --verbose
-```
-
-正式创建：
-
-```bash
-node scripts/zip_source_code.js "/path/to/project"
-```
-
-默认输出在源目录旁边：
-
-```text
-<目录名>.code.zip
-```
-
-例如：
-
-```text
-源目录：/work/my-app
-输出：  /work/my-app.code.zip
-```
-
-
-需要自定义过滤、额外文件、输出位置、覆盖、压缩或排障时读取 [参数与行为参考](references/cli-reference.md)。执行前核对目标目录和忽略策略，交付 ZIP 路径、清单/统计及未打包项。

package/template/skills/upstream-fork-sync/SKILL.md

@@ -1,82 +0,0 @@
----
-name: upstream-fork-sync
-description: Assess a requested fork/upstream checkpoint and produce reproducible diff, conflict, and customization-risk evidence.
-metadata: {"speculo-id": "upstream-fork-sync", "speculo-kind": "skill"}
----
-
-# Upstream Fork Sync
-
-以**检查点**为主导词。每个仓库始终分开记录：本次观测到的 upstream tip、可选本地 mirror tip，以及已经由产品分支历史证明完成集成的 upstream checkpoint。Fetch 或 mirror 变化不能推进集成 checkpoint。
-
-## 1. 解析上下文
-
-1. 从当前目录向上寻找并读取 `<Path>{roots.state}/workspace.json</Path>`，验证 `path_base` 和所有 roots，再读取 `<Path>{roots.config}</Path>`；无法唯一确定项目根时停止。
-2. 读取项目 `AGENTS.md` 及其作用域内规则。项目存在工程规范时读取适用入口。
-3. 将本 Skill 的唯一持久化根解析为 `<Path>{roots.state}/skills/upstream-fork-sync/</Path>`。独立运行只写该根；不得创建 workflow change 或 command 报告。
-4. 读取 [Repository contract](references/repository-contract.md)，确定仓库、refs、网络刷新和副作用边界。
-
-完成标准：项目根、Skill state 根、目标仓库集合和本次是否允许 fetch 都只有一个解释。
-
-## 2. 建立稳定配置
-
-读取 `<Path>{roots.state}/skills/upstream-fork-sync/repository-map.json</Path>`。不存在时，只读发现 Git 仓库、remotes、默认产品分支和 upstream tracking refs，按 [Repository contract](references/repository-contract.md) 创建 schema v1 配置；无法从 Git 事实唯一判断的字段一次性询问用户。配置已存在时验证，不静默改写。
-
-读取 `<Path>{roots.state}/skills/upstream-fork-sync/customization-map.md</Path>`。不存在时创建最小稳定清单，记录 fork 必须长期保留的产品不变量和审查热点；无法从项目文档或代码证明的业务约束标记为待确认。该文件不接收运行 SHA、dirty paths、冲突或本次结论。
-
-完成标准：每个 repository id 唯一，所有项目路径和 refs 可解析，稳定配置与动态运行事实分离。
-
-## 3. 创建评估 change
-
-读取 [State schema](references/state-schema.md) 和 [Report contract](references/report-contract.md)，从用户主题生成小写 ASCII kebab-case topic，然后运行：
-
-```bash
-node <Path>{roots.skills}/upstream-fork-sync/scripts/upstream-sync.mjs</Path> assess \
-  --root . \
-  --state-root <Path>{roots.state}/skills/upstream-fork-sync</Path> \
-  --repository-map <Path>{roots.state}/skills/upstream-fork-sync/repository-map.json</Path> \
-  --topic <topic>
-```
-
-- 默认离线使用本地 refs；只有用户明确要求刷新网络 refs 时添加 `--fetch`。
-- 只需预览完整冻结快照时添加 `--dry-run`，此分支不写 state 或 change。
-- 正常运行创建 `<Path>{roots.state}/skills/upstream-fork-sync/{date}-{topic}[-NN]/</Path>`，已有目录永不覆盖。
-
-完成标准：脚本退出 0，change 的 state 与两份报告完整发布，根 `state.json` 只在 change 发布成功后更新。
-
-## 4. 深化风险结论
-
-逐仓库检查报告中的 Git 确认冲突、自动合并重叠和定制风险路径。对每条高风险路径使用报告冻结的 SHA 执行精确 `git diff <base>..<target> -- <path>`，再与 `customization-map.md` 的稳定不变量映射。
-
-只把路径级证据支持的语义结论补入本 change 的报告。保持 Git 冲突、自动合并重叠、定制合同风险和 dirty-worktree 重叠为四个类别；零文本冲突不得表述为集成安全。
-
-完成标准：所有冲突和定制热点都有结论或明确未验证项，报告中的命令可以从冻结 SHA 复现。
-
-## 5. 返回后续选择
-
-返回 change 路径、仓库 checkpoint、观测 upstream SHA、风险摘要和未验证项。列出适合继续处理的已安装 Work，但不自动创建 workflow change、不调用 Work、不 merge、不 commit、不 push；后续路线由用户选择。
-
-完成标准：本次 Skill 在评估 change 完整后停止，用户能用冻结产物自行选择下一 Work。
-
-## 6. 记录外部集成
-
-只有其他 Work 已完成集成且用户要求更新 checkpoint 时进入此分支。读取目标 change state，并运行：
-
-```bash
-node <Path>{roots.skills}/upstream-fork-sync/scripts/upstream-sync.mjs</Path> record-integration \
-  --root . \
-  --state-root <Path>{roots.state}/skills/upstream-fork-sync</Path> \
-  --repository-map <Path>{roots.state}/skills/upstream-fork-sync/repository-map.json</Path> \
-  --change <change> \
-  --repository <repository-id> \
-  --merge-commit <full-sha> \
-  --upstream-sha <full-sha> \
-  --verification '<command>: exit 0'
-```
-
-该入口只在 merge commit 可从产品 ref 到达、目标 upstream SHA 是其精确非第一父节点且匹配 change 冻结目标时更新状态；它不执行集成。
-
-完成标准：change state 和根 checkpoint 都已原子重读，实际 Git 历史与记录一致。
-
-## 停止条件
-
-目标 ref 缺失、保存的 checkpoint 不在产品历史、checkpoint 不在当前 upstream 历史、存在多个 merge-base、配置越界或状态 schema 非法时，停止且不移动 refs、不发布部分 change、不推进 checkpoint。返回准确 repository id、路径、refs 与 SHAs。

package/template/skills/upstream-fork-sync/references/report-contract.md

@@ -1,40 +0,0 @@
-# Report Contract
-
-## Output
-
-每次成功 assessment 创建：
-
-```text
-<Path>{roots.state}/skills/upstream-fork-sync/{change}/state.json</Path>
-<Path>{roots.state}/skills/upstream-fork-sync/{change}/diff-report.md</Path>
-<Path>{roots.state}/skills/upstream-fork-sync/{change}/conflict-report.md</Path>
-```
-
-首份无编号，冲突时从 `-01` 选择最小未占用编号。整个 change 先在同一 state 根暂存，再原子 rename；不得覆盖或留下半成品目录。
-
-## Diff report
-
-每个仓库包含：
-
-- checkpoint 来源、已集成 upstream SHA、观测 upstream SHA、product SHA、merge-base、mirror SHA 和 freshness；
-- `integrated_upstream_sha..observed_upstream_sha` 的有序提交；
-- 完整 name-status 与 numstat 文件清单；
-- product 自 checkpoint 后也修改的路径；
-- repository map 风险 glob 命中的路径；
-- 使用冻结 SHA 的复现命令；
-- commit/file/conflict/risk 计数和当前 disposition。
-
-Agent 使用 customization map 和路径级 diff 增补语义结论；报告不内嵌无界完整 patch。
-
-## Conflict report
-
-使用 `git merge-tree --write-tree --messages <product-sha> <upstream-sha>`，不修改 index、worktree 或 refs。该命令可能在对象数据库留下不可达 tree objects。
-
-始终分开：
-
-1. Git confirmed conflicts；
-2. Automatically mergeable overlaps；
-3. Customization contract risks；
-4. Dirty worktree overlaps。
-
-始终生成 conflict report。零文本冲突明确写为零，并注明 merge-tree 无法证明编译、运行时、API、数据迁移、权限或业务行为安全。

package/template/skills/upstream-fork-sync/references/repository-contract.md

@@ -1,54 +0,0 @@
-# Repository Contract
-
-## Repository map
-
-`<Path>{roots.state}/skills/upstream-fork-sync/repository-map.json</Path>` 是稳定、项目专属的 Git ref 配置：
-
-```json
-{
-  "schema_version": 1,
-  "repositories": [
-    {
-      "id": "app",
-      "path": ".",
-      "product_ref": "refs/heads/main",
-      "origin_ref": "refs/remotes/origin/main",
-      "origin_remote": "origin",
-      "upstream_ref": "refs/remotes/upstream/main",
-      "upstream_remote": "upstream",
-      "mirror_ref": null,
-      "baseline_ref": null,
-      "risk_paths": ["src/auth/**", "package.json"]
-    }
-  ]
-}
-```
-
-- `id` 使用唯一小写 kebab-case。
-- `path` 是项目根 POSIX 相对 Git worktree 路径，`.` 表示项目根；不得绝对、包含 `..` 或指向符号链接目录。
-- `product_ref` 与 `upstream_ref` 必填且使用完整 `refs/...`。
-- `origin_ref`、`origin_remote`、`mirror_ref`、`baseline_ref` 可以为 `null`；配置 remote 时对应 ref 必须存在。
-- `risk_paths` 是项目确认的 glob；它补充稳定 customization map，不取代 Agent 的语义复核。
-
-## Ref invariants
-
-- Product ref 包含二次开发；mirror 只表示本地上游镜像。
-- 配置 baseline 时，它必须同时是 product 与 observed upstream 的祖先；配置 mirror 时，它必须是 observed upstream 的祖先。任一关系不成立时停止评估。
-- Fetch 只更新 remote-tracking refs。Skill 不自动 stash、reset、clean、rebase、force-update、删除、commit、merge、push、tag 或更新 submodule pointer。
-- Dirty worktree 不影响基于 commit 的评估，但必须独立报告。
-- `--fetch` 逐仓库刷新配置的 upstream remote，并在配置时刷新 origin remote；失败仓库使用现存 refs 且标记 `stale`，不得称为最新。
-
-## Checkpoint discovery
-
-没有有效保存 checkpoint 时：
-
-1. 若配置 baseline，从 baseline 到 product ref 的 first-parent merges 逆序检查；否则检查 product ref 的 first-parent merges。
-2. 选择最新一个其非第一父节点属于当前 upstream 历史的 merge。
-3. 记录该 upstream 父节点及 merge commit。
-4. 没有合格 merge 时，仅在 product/upstream 有唯一 merge-base 时使用它，且 merge commit 为 `null`。
-
-Mirror tip 不能推导已集成 checkpoint；cherry-pick patch equivalence 也不能推进 graph checkpoint。
-
-## Stable customization map
-
-`<Path>{roots.state}/skills/upstream-fork-sync/customization-map.md</Path>` 只保存长期 fork 不变量、领域约束和审查热点。当前 SHAs、fetch 结果、changed files、conflicts、dirty paths 和一次运行结论属于 change 报告。

package/template/skills/upstream-fork-sync/references/state-schema.md

@@ -1,55 +0,0 @@
-# State Schema
-
-## Root state
-
-`<Path>{roots.state}/skills/upstream-fork-sync/state.json</Path>` 使用 schema v1：
-
-```json
-{
-  "schema_version": 1,
-  "updated_at": "RFC-3339 timestamp",
-  "current_change": "YYYY-MM-DD-ascii-kebab-topic",
-  "repositories": {
-    "app": {
-      "integrated_upstream_sha": "full SHA",
-      "main_merge_sha": "full SHA or null",
-      "observed_upstream_sha": "full SHA"
-    }
-  }
-}
-```
-
-根 state 只是当前同步索引。它不保存 ref 配置、run history、dirty paths、文件清单、conflicts、fetch details 或 verification logs。
-
-## Change state
-
-每个 `<Path>{roots.state}/skills/upstream-fork-sync/{change}/state.json</Path>` 包含：
-
-```json
-{
-  "schema_version": 1,
-  "created_at": "RFC-3339 timestamp",
-  "repository_map_sha256": "sha256",
-  "repositories": {
-    "app": {
-      "product_sha": "full SHA",
-      "upstream_sha": "full SHA",
-      "integrated_upstream_sha": "full SHA",
-      "main_merge_sha": null,
-      "recorded_at": null,
-      "verification": []
-    }
-  }
-}
-```
-
-只列出存在 upstream delta 的仓库。`record-integration` 填写 `main_merge_sha`、`recorded_at` 和 verification，并推进根 checkpoint；assessment、fetch、mirror observation 和报告生成都不能推进 `integrated_upstream_sha`。
-
-## Update rules
-
-- 发布 change 的全部文件后才替换根 state。
-- 未知 schema、额外字段、非法 repository id 和 SHA 类型全部拒绝。
-- 保存 checkpoint 必须仍在 product 与 upstream 历史中。
-- `record-integration` 要求精确匹配 change 的冻结 upstream target。
-- 旧 change 的冻结 target 不得回退或分叉当前根 checkpoint。
-- 状态写入使用同目录临时文件、fsync 和 rename；失败不得伪装为成功。

package/template/skills/writing-for-agents/GLOSSARY.md

@@ -1,201 +0,0 @@
-# 术语表 — 构建优秀技能
-
-关于什么造就优秀技能的领域模型。技能的存在是为了从随机系统中驯服确定性；根本美德是 **Predictability**（可预测性），以下每个术语都是调节它的一根杠杆。这是 [`writing-for-agents`](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

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

@@ -1,22 +0,0 @@
----
-name: writing-for-agents
-description: Review or author agent instructions, Skills, AGENTS, commands and workflow contracts when explicitly requested.
-disable-model-invocation: true
-metadata: {"speculo-id": "writing-for-agents", "speculo-kind": "skill", "speculo-invocation": "user-only"}
----
-
-# Writing for Agents
-
-对明确要求的文档编写/重构使用本能力；不因仓库存在指令文件而自动审计。先读 [保真合同](references/document-contract.md)，确定真实源、调用方、owner、输出与恢复边界。
-
-1. 从当前任务入口追踪相关调用和生成器，列出现存能力、数量、工具、权限、验证及失败语义。不要默认整读仓库。
-2. 明确触发分支和近邻职责；入口保留每次必读步骤，只有分支规则、示例、flags 与模板下沉。需要审查结构与冗余时读 [编写原则](references/authoring-principles.md)，术语按需查 [GLOSSARY](GLOSSARY.md)。
-3. 按单一规则 owner 合并重复；删除无效/过期内容，保留不可丢失的证据、研究、许可与必要元数据。新增或改变的行为单列。
-4. 修订调用方与生成器，测试正常、近邻不触发、缺失输入、失败与恢复；语法通过不代表实际宿主行为。
-5. 交付实际差异、全源字符统计、验证和未验证项。没有实际用量证据不声称 token 或额度节省。
-
-## 宿主适配
-
-Claude 的显式调用使用 disable-model-invocation；Codex 使用 agents/openai.yaml 中 policy.allow_implicit_invocation=false。metadata 仅描述策略，不授予权限。Speculo 的分发路径不等于宿主原生发现目录，安装/启用需由对应宿主方式完成；不要复制到系统或插件缓存。
-
-AGENTS 放项目独有事实与作用域约束，工具可检验的规则交机械检查；CLAUDE 需要加载同层手册时使用 @AGENTS.md，保护用户现有内容。

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

@@ -1,2 +0,0 @@
-policy:
-  allow_implicit_invocation: false