Skip to content

xinetzone/SpecWeave / .agents/skills/skill-target-root-switch-replan

skill-target-root-switch-replan

Verified

当用户把已批准的 Skill 方案目标根从 ~/.qoder/skills 改成 .agents/skills 或其他目录时,重新在新根跨根查重、重读该根 frontmatter 与登记约定、按四项契约差异重算字段与门禁口径、显式列出被作废的已批准条目、核对旧根未被写入,并在新根重跑格式、链接与质量门。用户说「要写入 .agents/skills/」「迁入 .agents/skills」「改到主权区」「目标目录换成」「不要写用户级目录」「方案批了但目录变了」「哪些已批准条目作废」时必须使用此技能;不用于首次跨根分诊(用 skill-recommendation-disk-triage)、已有 Skill 的位置迁移(用 user-skill-sovereign-migration)或从零设计内容(用 skill-creator)。

Skill 目标根切换重规划

方案已经提出、甚至已经批准,用户突然用一句话把目标根改到别处(典型是「要写入 .agents/skills/」或「迁入 .agents/skills」)。这不是在同一个计划里替换一个路径字符串,而是授权范围发生了变化:新根有不同的查重面、frontmatter 契约、登记面和验收门。把旧方案的内容原样搬到新路径,会把旧根的假设一起带过去。

本技能把这次改道变成一次零写入的重规划:先在新根重新取证,再给出路径、字段、文件清单与门禁命令的差异,确认后才落盘。

Why

三种失败最贵,且都不会当场报错:

  1. 只换路径不查新根:旧根查重为空,不代表新根没有权威副本。照搬路径会在新根制造第二份真相,后续修改只落在其中一份。
  2. 旧根已经被写过,却当作没发生:可能留下空壳目录、半套文件或指向别处的联接。新根再写一份,就从「一份权威」变成「两份实体 + 一个悬空入口」。
  3. 继承旧根的验收结论:旧根跑过门禁不等于新根通过;新根的 frontmatter 字段、相对引用层级、登记面都不同,旧结论会掩盖真实断链和掉分。

为什么把换根当作授权变更而不是路径替换? 用户批准的是「在某个根创建某个 Skill」。根变了,审批对象的边界、可写范围、后续登记责任都变了。把新根当成旧根的别名,等于在未经确认的新范围里写入。重规划的成本是一次读盘和一张差异表,误写的成本是清理两处实体并重新证明哪一份是权威。

为什么旧根取证必须显式做? 空目录、联接和半套副本在 ls 里看起来都像「不存在」或「有个目录」。只有分别检查存在性、联接类型和内容清单,才能判断是需要清理、需要保留,还是确实从未写入。

1. 适用边界

场景使用本技能交给谁
方案已提出或已批准,写入前用户改目标根是—
换根后需要重读新根约定并重跑门禁是—
旧根可能已留下空壳、副本或联接是(取证与处置建议)删除实体需单独授权
首次收到推荐,判断 create/update/补登记否skill-recommendation-disk-triage
已有 Skill 从用户级正式迁入主权区否user-skill-sovereign-migration
从零设计 Skill 内容否skill-creator
共享工作树 rebase 中的写入安全否shared-worktree-rebase-write-guard

判定口诀:还没写 → 重规划;已经写完 → 迁移;还没判 → 分诊。

2. 重规划六步(R1–R6,全部只读)

R1 冻结写入并复述 delta

停止任何 Write、Edit、mkdir、cp。用一句话复述变化:

旧根:<old-root>/<skill-name>
新根:<new-root>/<skill-name>
状态:尚未写入 / 旧根已有 N 个文件 / 旧根是联接

不静默继承旧方案的目录结构、frontmatter 字段和验收命令。

R2 解析新根身份

新根形态典型路径约束
用户级~/.qoder/skills/<name>跨项目可见,通常只要求 name 与 description
兼容用户级~/.agents/skills/<name>先确认是否与当前产品目录重叠
仓库主权区<repo>/.agents/skills/<name>需原生 frontmatter、登记面、仓库门禁
其他项目根用户显式给出的绝对路径只按该项目的实际约定,不套用 SpecWeave 规则

先确认仓库边界,再谈路径:

git rev-parse --show-toplevel
git rev-parse --show-superproject-working-tree

为什么不能用相对路径猜新根? .agents/skills/ 是相对当前工作目录的写法。在子目录、子模块或另一个 worktree 里执行时,它会指向完全不同的位置。新根必须解析成绝对路径并回显给用户。

R3 在新根跨根查重

至少检查四个位置,名称一律用目录名与 frontmatter name 双重匹配:

for root in "$HOME/.qoder/skills" "$HOME/.agents/skills" "<repo>/.agents/skills"; do
  test -e "$root/<name>" && echo "EXISTS: $root/<name>"
  test -L "$root/<name>" && echo "LINK:   $root/<name>"
done

在仓库内再查受追踪登记面与 TOML 镜像:

git grep -n "<name>" -- .
ls -d .meta/toml/.agents/skills/<name> 2>/dev/null || echo "NO_TOML"

任一同名命中即停止写入,转入现状阅读与 update/补登记判断;不得用改名绕过。

R4 重读新根约定

不要凭记忆套字段。读取新根的索引与两三个同类 Skill 的 frontmatter,列出字段差异:

字段用户级常见主权区常见说明
name / description必需必需目录名必须与 name 一致
version可选推荐原生轨质量门按推荐字段计分
argument-hint可选推荐有参数时填写
user-invocable可选推荐—
paths可选推荐指向该 Skill 自身目录
source可选推荐溯源用自由文本,不是文件路径
title可选推荐人类可读标题
x-toml-ref不适用有 TOML 镜像时才写层级按文件实际位置推算

四项契约级差异必须逐项重算,结论写进 R6 方案;只换路径字符串会同时踩错键位与门禁口径:

契约面用户级根仓库主权区权威出处
frontmatter 键层级version 只能写 metadata.version;顶层只认 name、description、license、allowed-tools、metadata、compatibilityversion、argument-hint、user-invocable、paths 必须在顶层;缩进到 metadata 会被质量门行首锚点漏读并静默 −5qoder-user-skill-authoring、repo-native-skill-frontmatter-contract
quick_validate 期望退出码期望 0,非 0 即真失败需修期望 1(报 Unexpected key(s)),属尺子差异;为凑 0 而删字段会掉分,把 version 挪进 metadata 会掉更多repo-native-skill-frontmatter-contract
登记面义务无;落盘即可用四处:README 表行与分类计数、capability-registry/02-skills 表行与计数、CHANGELOG 版本条目、.meta/toml 镜像native-skill-surface-registration
可见性机制独立目录,或指向权威副本的联接该目录即唯一权威副本;用户级入口是事后联接,不是第二份内容native-skill-surface-registration、skill-junction-durability-guard

为什么不能在两个根之间复制同一份 SKILL.md? 两把尺子对 version 层级的要求互斥:用户级把顶层 version 判为 unexpected key,主权区对 metadata.version 静默扣分。同一份文件无法同时拿两边满分,先按所在根选尺子,再定键位。

同时记录新根的登记面与门禁位置:

git status --short -- .agents/skills/README.md .agents/skills/CHANGELOG.md \
  .agents/capability-registry/02-skills.md

若这些文件正被其他会话修改,登记必须延后,不能把他人改动卷进来。

R5 核对旧根从未写入

分别检查存在性、联接类型和内容,不要只看 ls:

test -e "<old-root>/<name>" && echo OLD_EXISTS || echo OLD_NOT_FOUND
test -L "<old-root>/<name>" && echo OLD_IS_LINK || echo OLD_NOT_LINK
find "<old-root>/<name>" -mindepth 1 -maxdepth 2 2>/dev/null | head -20

按结果分类处置:

旧根状态含义动作
不存在从未写入直接在新根创建,报告旧根未触碰
空目录可能创建过目录但未落文件报告;经授权后只用 rmdir 清理
完整或半套副本曾写入实体内容先比对文件清单与哈希,报告哪份是权威;删除需单独授权
联接可能指向新根或其他位置先读 LinkType/Target,不得直接复制或删除

为什么删除旧根不是重规划的默认步骤? 目录里可能有用户或其他会话的产物。重规划只负责证明旧根状态并给出处置建议;删除是不可逆动作,必须有独立授权,且优先用可失败的空目录删除而不是递归强删。

R6 输出修订方案等待确认

方案至少包含:

项目内容
新目标路径绝对路径
旧根状态不存在 / 空壳 / 副本 / 联接,附命令证据
同名校验四根 + git grep + TOML 结果
frontmatter保留、新增、删除的字段,及 x-toml-ref 是否有真实目标
文件清单SKILL.md、references、scripts、evals 各写什么
验收命令新根质量门与链接门的实际命令
作废条目旧方案中被新根作废的已批准项,及各自的替代
延后事项登记面、TOML、联接,以及延后原因

作废清单:换根会作废旧方案里已批准、但只对其中一个根成立的条目。逐条给出「作废 / 替代」,不要静默沿用——把旧根已批准的头字段直接写进新根,是换根事故里最常见的一种。

旧方案条目改到主权区后改到用户级后
已拟好的 frontmatter 段作废:version 等提回顶层,补 paths、title、source作废:version 收进 metadata,删掉顶层扩展键
已拟定的验收命令作废:改跑 check-skill-quality.py --score --threshold 100 与 check-links.py --check-frontmatter-paths作废:改跑 quick_validate.py(期望退出 0)与链接门
「落地即完成」的交付口径作废:四处登记与 TOML 镜像转为待办作废:无需登记,但须说明与主权区权威副本的关系
「目标目录要创建」作废:改为事后联接,不是第二份副本作废:该目录本身就是唯一交付物

等待用户确认后再进入写入阶段。批准范围外的扩展回到 R6 补充。

3. 写入规则

  • 只在一个根创建,不做双写兜底。
  • 不用 cp -r 把旧方案目录搬过来;没有源目录时直接写新内容。
  • 不用联接掩盖位置错误;联接是登记阶段的收尾手段,不是创建手段。
  • 目标目录已存在时停止,先读现状,转 update 或冲突裁决。
  • 新根是仓库主权区时,先写内容与资源,不碰正在被并发修改的登记面。

4. 新根验收

按新根实际能力选择门禁,不要拿旧根结论替代:

# 仓库主权区示例,路径按实际仓库探测
python .agents/scripts/check-skill-quality.py \
  --path .agents/skills/<name> --score --threshold 100
python .agents/scripts/check-links.py \
  --path .agents/skills/<name> --check-frontmatter-paths

无仓库门禁时,至少完成等价直接校验:

  1. 解析 YAML frontmatter,确认 name 与目录名一致、description 非空。
  2. 正文引用的每个相对路径真实存在。
  3. 全文无绝对路径链接、无盘符绝对路径、无临时目录引用。
  4. 文件为 UTF-8 无 BOM,无 __pycache__、*.pyc 等运行残留。
  5. 有脚本时实跑一次帮助或只读模式,记录退出码。

为什么门禁必须在最终根上跑? 用户级根通常没有仓库的质量门与链接门;在旧根跑过的分数不能证明新根的引用层级和登记字段成立。换根后重跑,才是对新交付物的验收。

5. 登记延后规则

新根是共享仓库且登记面有并发改动时:

  • 只交付 Skill 内容与验证结果。
  • 明确写「四处登记与 TOML 镜像延后」,并列出被并发修改的文件。
  • 不在 frontmatter 写指向尚不存在 TOML 的 x-toml-ref,避免制造断链。
  • 等并发会话提交后,重新读取计数,再走 native-skill-surface-registration。

6. 报告模板

旧根:<path> — 不存在 / 空壳 / 副本 / 联接(附证据)
新根:<path> — 新建 N 个文件
同名校验:四根 0 命中;git grep 0 命中;TOML 无镜像
frontmatter:新增 <字段>;未写 x-toml-ref(TOML 待建)
作废条目:<旧方案中被新根作废的字段 / 命令 / 口径,及替代>
质量门:<分数> / <通过项数>
链接门:<断链数>
未做:登记面(并发修改中)、TOML、联接、提交、推送

7. Gotchas

  1. ls 返回空不等于从未写入:空目录、联接和权限失败都可能表现相似,必须分别测试存在性与联接类型。
  2. 相对新根会跑偏:.agents/skills/ 相对 cwd 解析;在子目录或子模块里执行会写到别处,先解析绝对路径。
  3. 质量门 95 分常是 description 缺触发场景:补齐「当用户…」或「when…」措辞即可到 100,不要为此重写正文。
  4. x-toml-ref 层级按文件位置数:.agents/skills/<name>/SKILL.md 到仓库根是三级;照抄根目录模板会多算或少算一层。
  5. 没有 TOML 时写 x-toml-ref 会制造断链:链接门开启 frontmatter 校验后会直接报错,登记延后就先省略。
  6. 双写不是保险:两个根各留实体,必然产生两份真相;最终应是一个权威副本,必要时再加联接。
  7. 不要把 source 当路径字段:它是溯源自由文本;写成仓库相对路径会被链接门当成失效引用。
  8. 并发登记面不能顺手改:README、CHANGELOG、registry 可能已暂存他人改动,延后并在报告中写明。
  9. 旧根清理优先 rmdir:非空目录是实体副本信号,先报告;递归强删会销毁未知产物。
  10. metadata.version 在主权区不报错但掉分:它是合法 YAML,quick_validate 也接受,只有质量门的行首锚点读不到,代价是静默 −5;反向把顶层 version 带进用户级则会让 quick_validate 退出 1。
  11. quick_validate 在主权区退出 1 不是待修缺陷:不要让退出码变成换根后的返工任务;在同根取一个已满分的原生 Skill 跑同一命令即可证明是尺子差异。

8. 安全检查清单(逐项确认)

  • 已冻结写入并复述旧根到新根的 delta
  • 新根已解析为绝对路径,仓库根与 submodule 状态已确认
  • 四根查重与 git grep 完成,同名命中时未覆盖
  • 新根 frontmatter 与登记约定已从磁盘原文读取,非凭记忆
  • 四项契约差异已按新根重算,作废条目已逐条列出并给出替代
  • 旧根存在性、联接类型与内容清单已取证并分类
  • 修订方案已输出并取得确认,批准前零写入
  • 只在单一根创建,无双写、无 cp -r、无联接掩盖
  • 新根质量门与链接门已实跑,结果与退出码已记录
  • 引用资源真实存在,无绝对链接与运行残留
  • 并发登记面未被触碰,延后事项已写明
  • 未提交、未推送,旧根删除有独立授权

参考

reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 466kUpdated Claude CodeCodexVerifiedInstall
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 466kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 319kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 319kUpdated Claude CodeCodexVerifiedInstall