claude-code-best/docs/superpowers/specs/2026-05-12-review-skill-extract-to-disk-design.md

Review Skill Extract-to-Disk Migration Design

Goal

将 review 和 security-review 从 registerBundledSkill() 内存内嵌方式迁移到 extract-to-disk + 标准 skill scanner 发现 的架构，完全对齐上游 opencode#360 的实现模式。

彻底移除 registerBundledSkill 对 review/security-review 的使用。

Background

当前问题：

• src/costrict/review/skill/builtin.ts 是 2.5MB 的内嵌文件，所有 skill 内容在内存中
• reviewSkills.ts 通过 registerBundledSkill() 注册，绕过了标准 skill 发现流程
• strict:review / strict:security-review 也是 bundled skill 方式，增加了复杂度

PR #360 的方案：

• 生成脚本从 zgsm-ai/costrict-review 远程仓库拉取资源
• 运行时通过 extension.ts 将 skill 提取到磁盘缓存目录（~/.claude/skills/ 或类似目录）
• .version 文件跟踪版本 + locale
• 标准 skill scanner 从磁盘目录发现并加载 skill
• /review、/security-review 命令模板只说 "请使用 Skill 工具加载 X 技能"

Architecture

Build time:
  scripts/generate-review-builtin.ts
    → git clone zgsm-ai/costrict-review
    → 读取 index.json
    → 生成 src/costrict/review/skill/builtin.ts (内嵌所有文件内容)

Runtime:
  Startup → extension.ts:initializeBuiltinSkills(locale)
    → 检查 .version 文件（版本+语言）
    → 如需更新，调用 builtin.ts:extractBundledSkill() 写入磁盘
    → 标准 skill scanner 扫描缓存目录，发现 review / security-review

Commands:
  /review → CommandLocale.get('review') → "请使用 Skill 工具加载 review 技能"
  /security-review → CommandLocale.get('security-review') → "请使用 Skill 工具加载 security-review 技能"

Changes

1. 新增 scripts/generate-review-builtin.ts

生成脚本，参考 PR #360 的同名文件：

• 通过 git ls-remote 获取远程 SHA，与缓存 SHA 对比
• git clone --depth 1 浅克隆 zgsm-ai/costrict-review 仓库
• 读取 index.json，收集所有 skill 及其 locale 路径
• 将 skill 文件内容内嵌为 TypeScript 常量
• 生成 src/costrict/review/skill/builtin.ts，导出：
  • SKILL_FILES: Record<string, Record<string, Record<string, string>>> (locale → skillName → filePath → content)
  • SKILL_METADATA: Record<string, Record<string, { name: string; description: string }>> (locale → skillName → 元数据，从 SKILL.md frontmatter 解析)
  • SKILL_VERSIONS: Record<string, string> (skillName → commit SHA)
  • extractBundledSkill(skillName, targetDir, locale) — 提取到磁盘
  • listBuiltinSkills() — 返回所有 skill 名称
  • getBuiltinSkillVersion(skillName) — 返回版本

2. 重新生成 src/costrict/review/skill/builtin.ts

由脚本生成的产物，从 2.5MB 精简为只包含：

• SKILL_FILES 多 locale 数据
• SKILL_METADATA 元数据
• SKILL_VERSIONS 版本
• extractBundledSkill() 提取函数

不再导出 extractBundledSkill() 以外的运行时函数。

3. 新增 src/costrict/review/extension.ts

运行时初始化逻辑：

• initializeBuiltinSkills(locale: string) — 遍历所有 builtin skill，按需提取到磁盘
• needsUpdate(skillDir, skillName, locale) — 检查 .version 文件（格式：sha:locale）
• writeVersionFile(skillDir, skillName, locale) — 写入版本+语言标记
• getBuiltinSkillsDir() — 返回缓存根目录

4. 修改 src/costrict/review/index.ts

• 移除 agent/builtin.ts 相关导出
• 导出 Extension from ./extension.js
• 导出 SkillBuiltin from ./skill/builtin.js

5. 删除 src/costrict/skills/reviewSkills.ts

移除整个文件，不再需要 registerBundledSkill 注册。

6. 修改 src/skills/bundled/index.ts

• 移除 import { registerReviewSkills } 和调用
• 改为在 skill 初始化阶段调用 Extension.initializeBuiltinSkills(locale)

7. 修改 src/costrict/command/locales/index.ts

保持不变，locale 模板继续用于 /review 和 /security-review 命令。

8. 修改 package.json

• 添加 "build:builtin-review": "bun run scripts/generate-review-builtin.ts" 脚本
• 将 build:builtin 改为包含 build:builtin-review

9. 修改 .gitignore

• 添加 bundled-review/（生成脚本的临时下载目录）
• 保留 src/costrict/review/skill/builtin.ts 在 .gitignore（生成产物）

10. 清理

• 移除 src/costrict/review/agent/builtin.ts（不再有 review agent）
• 移除 REVIEW_AGENTS、AGENT_VERSIONS、PRIMARY_REVIEW_AGENT、SUB_REVIEW_AGENT 的导出和引用
• 移除 builtInAgents.ts 中的 review agent 注册
• 移除 strict:review / strict:security-review 的 bundled skill 注册

Files Summary

Action	File
Create	scripts/generate-review-builtin.ts
Create	src/costrict/review/extension.ts
Generated	src/costrict/review/skill/builtin.ts
Modify	src/costrict/review/index.ts
Delete	src/costrict/skills/reviewSkills.ts
Delete	src/costrict/review/agent/builtin.ts
Modify	src/skills/bundled/index.ts
Modify	package.json
Modify	.gitignore
Modify	Agent 注册（移除 review agent）

Key Differences from Previous Design

Aspect	旧方案 (registerBundledSkill)	新方案 (extract-to-disk)
运行时	内存内嵌 + getPromptForCommand	提取到磁盘 + 标准 scanner
发现方式	registerBundledSkill 注册到数组	skill scanner 扫描目录
版本追踪	无	.version 文件（sha:locale）
strict 变种	单独注册 bundled skill	不需要，走标准流程
extension.ts	删除	新增（提取逻辑）