用途：把已在用 nuqs 的代码库从 pre-v2.5 模式迁移到 v2.5–v2.8 写法。当用户要求“升级 nuqs”或“迁移到 nuqs 2.x”、评审中发现遗留模式、package.json 中 nuqs 版本从 <2.5 升到 >=2.5，或刚安装 nuqs 技能需对齐现有代码时触发。它是 nuqs 技能（规定正确写法）的自动化配套，负责把旧代码改写为正确模式。
工作流按顺序运行四个脚本：scan.sh <repo-root> 用 ripgrep 扫描 .ts/.tsx/.js/.jsx 中的五类模式并输出 scan.json；report.sh 生成按 codemod 分组的 markdown 表，需向用户逐字展示并取得明确确认；apply.sh [--filter <codemod-id>] 执行 scripts/transforms/ 下的 jscodeshift 转换；verify.sh 运行 tsc --noEmit 和 npm run lint（或 config.json 中的等价命令）。失败时用 git restore 回退被改文件。只想扫描可停在第二步。
五个 codemod：throttle-ms 将 withOptions({ throttleMs: N }) 或 setX(v, { throttleMs: N }) 改为 withOptions({ limitUrlUpdates: throttle(N) }) 并加入 throttle 导入；manual-debounce 将围绕 useQueryState 的 useState 镜像加 useEffect/setTimeout 防抖改为 withOptions({ limitUrlUpdates: debounce(N) })，删除镜像状态与 effect；unchecked-json-cast 处理无校验器的 parseAsJson<T>() 或 parseAsJson((v) => v as T)，插入 TODO 类型守卫，若检测到 Zod 则用 parseAsJson(SchemaName.parse)；react-router-unversioned 将 nuqs/adapters/react-router 改为带版本路径 v6；parser-builder-type 将 ParserBuilder<T> 改为 SingleParserBuilder<T>。
限制与护栏：该技能有写入风险，仅修改源文件。工作树不干净时 apply.sh 中止（可先 git stash，或读 gotchas.md 后传 --allow-dirty）；scan.json 超过 60 分钟或针对不同 git HEAD 时中止；PreToolUse 钩子阻止绕过编排器直接调用 node scripts/transforms/*.js；verify.sh 在 TS 或 lint 失败时自动回退。首次运行需在 config.json 填 lint/typecheck 命令与默认 min_node_version。其余边界与失败模式见 references/workflow.md 与 gotchas.md。