Privatize Fork
legdonkey/privatize-fork
Privatize forks open-source com regras, rastreamento seguro e manutenção sustentável
Ver no GitHubSkill Claude Code que privatiza forks de projetos open-source de forma estruturada e segura. Configura rastreamento upstream apenas leitura com proteção contra push acidental, estabelece isolamento em diretório private/ com registro de mudanças, e gera documentação de manutenção e convenções de versionamento para forks privados de longo prazo.
Instalação
npx convez-ai legdonkey/privatize-fork1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Equipes que customizam projetos open-source e precisam acompanhar atualizações upstream
- Privatizar forks com isolamento de mudanças e prevenção de push acidental para repositório original
- Gerar documentação e convenções de versionamento para manutenção sustentável de forks privados
Veredito

Skill bem estruturado que resolve um problema real de equipes que mantêm forks privados: padronização de workflow, prevenção de erros operacionais e documentação automática. A abordagem de escanear riscos antes de agir, combinada com scripts imutáveis para passos críticos e isolamento explícito de mudanças, é robusta e pragmática.
README
A tradução para o português deste README ainda está na fila.
privatize-fork
一个跨 Claude Code 与 Codex 的 skill:把 clone 下来的开源项目 fork 一次性私有化。
配好 upstream 只读跟踪 + 禁推、建立 private/ 维护规范与改动台账、由 skill 自己内联完成 upstream 初始化与文档翻译、写好 CLAUDE.md / AGENTS.md 指针——让一个私有 fork 能长期跟踪上游稳定版,同时把私有定制干净隔离、可维护。
内置了从实战中提炼的方法论:先勘察 → 私有隔离 → 本地定型 → 最后一次性发布。
解决什么问题
团队基于开源项目做私有定制,真正的难点不是「改代码」,而是缺一套能长期维护的私有规范——于是每次升级 upstream 都像拆弹:
- 远端约定:
origin(自己的 fork)和upstream(原作者)怎么分工?upstream 能不能推? - 分支约定:私有开发、合并 upstream 各走什么分支?能不能 rebase / force-push?
- 私有版本号:私有 release 怎么编号,才能既对应 upstream 基线、又不和官方 tag 撞车?
- 升级与回滚:升级到 upstream 哪个版本、怎么判断动了哪些文件、出问题怎么退回?
规范缺位,就会反复踩这些坑:
- 私有改动和 upstream 文件混在一起,升级时冲突地狱;
- 误把私有改动推到了原作者仓库(upstream);
- 基建还没定型就打 tag + push,结果反复
force-push移动已发布 tag; .gitignore的通配规则悄悄挡掉了你新建的文件,或误删了上游「故意跟踪」的特殊文件。
这个 skill 一次性把这套规范立起来:生成 private/README.md 维护规范(远端 / 分支 / 私有版本号 / upstream 同步判断 / 升级流程 / 回滚预案 / 发布前检查),配套 private/ 隔离目录与改动台账——让私有 fork 能被团队长期、可控地维护,而不只是「躲过几个坑」。
核心特性
| 特性 | 说明 |
|---|---|
| 只读勘察暗礁 | 动手前先扫一遍 .gitignore 通配误伤、故意跟踪的文件、官方版本号位置、本地状态文件、upstream 最新 tag——把项目的坑全摸清再动手。 |
| 引导问答一次问全 | upstream 地址、私有 tag 格式、remote 协议、是否启用翻译模块、高冲突文件清单,能从勘察推断的给默认值。 |
| upstream 只读跟踪 + 禁推 | 从 git 层面把 upstream 的 push 设成 DISABLED,杜绝误把私有改动推到原作者仓库。这一步即 init,幂等可重跑。 |
| 关键步骤固化为自检脚本 | 勘察、配远端禁推、判断待翻清单这三处「确定性强、又最怕模型凭印象跳步」的环节,抽成了幂等/只读的小脚本(scripts/)——尤其禁推闸会自检 push = DISABLED 是否真生效,不对就报错退出,不再单靠模型自觉;判断与翻译等需要灵活性的部分仍交给模型。 |
| 私有内容尽量隔离 | 新增定制集中进 private/,不往 upstream 目录塞新文件;确需直接改的上游文件登记入账、定好冲突策略,升级时有据可查。 |
| 维护规范自动生成 | private/README.md 含升级流程、私有 tag 约定、版本号位置、验证命令。 |
| 改动台账 | private/CHANGES-REGISTRY.md 登记每一处私有定制,可追溯、可审计。 |
| 跨 CC / Codex 一键安装 | SKILL.md 是 开放标准,一个 install.sh 同时软链进 ~/.claude/skills/ 和 ~/.codex/skills/,两边通用、随 git pull 更新。 |
| 可选文档翻译(内联 + 增量更新) | skill 自己内联翻译 upstream 官方文档到 private/translations/,无需装命令。亮点是增量更新——每份译文记着译自哪个 upstream 版本,重跑 skill 时只重译源文件真正变动过的、补翻缺失的,已是最新的直接跳过;CC(Task)与 Codex(subagent)等有并行子任务能力的 agent 并行翻译,仅在确无并行能力时才顺序进行。 |
| 指针段跨平台 | 按团队 agent 把「私有维护规范」指针写进 CLAUDE.md(CC)和/或 AGENTS.md(Codex),去重不重复追加。 |
| 本地状态文件 skip-worktree | .idea/、.vscode/、.obsidian/workspace.json 等上游跟踪、每台机器不同的文件,逐个征得同意后让本机忽略其变化。 |
| 幂等可重入 | 可重复执行,已存在的文件一律不覆盖、只补缺失;重跑 skill = 重配 upstream + 增量刷新翻译,这就是后续维护要做的全部。 |
| 本地就绪,发布交给你 | skill 只做到「本地就绪」,不替你 push、不替你打 tag,确认无误后一次性发布。 |
安装与使用
安装
三种方式任选其一。装完重启 CC / Codex 即可;skill 不会自动调用,需你手动触发。
① Claude Code —— 插件市场(CC 地道做法,可版本化、可更新)
/plugin marketplace add legdonkey/privatize-fork
/plugin install privatize-fork@legdonkey
之后用 /plugin marketplace update 拉取更新。注意:插件方式的 skill 触发名带命名空间,为 /privatize-fork:privatize-fork(软链/skills 目录方式则是干净的 /privatize-fork)。
② Codex —— 内置 skill-installer(Codex 地道做法)
在 Codex 里调用内置 skill-installer($skill-installer),传入 GitHub 路径,它会 clone 进 ~/.codex/skills/:
legdonkey/privatize-fork/skills/privatize-fork
③ 一键装两边 —— install.sh(同时软链进 CC 与 Codex,最省事)
install.sh 自动检测本机装了 ~/.claude 还是 ~/.codex,把 skill 软链进对应 skills 目录(幂等、可重跑、已装则跳过、不覆盖同名目录;软链可随 git pull 原地更新)。
# 本地(首选,clone 后可先 review 再装):
git clone https://github.com/legdonkey/privatize-fork
cd privatize-fork && ./install.sh # 加 --copy 用复制代替软链
# 远程便捷:
curl -fsSL https://raw.githubusercontent.com/legdonkey/privatize-fork/main/install.sh | bash
不会自动调用:CC 靠 frontmatter
disable-model-invocation: true,Codex 靠agents/openai.yaml的allow_implicit_invocation: false——两边都只能由你手动触发。私有化是有副作用的操作,刻意设计成「人点头才跑」。
开始使用
- clone 你的私有 fork 到本地(
origin指向你的 fork); - 在该项目目录里打开 CC 或 Codex(Codex 建议先
/plan),手动触发:
/privatize-fork
skill 会带你走完整个流程,最后把私有化基建留在本地就绪状态——不替你 push、不替你打 tag,发布留给你确认无误后手动做。后续维护(重配 upstream、刷新翻译)只需重跑这个 skill。
兼容性
SKILL.md 是 agentskills.io 开放标准,同一份文件 CC / Codex / Gemini CLI / Cursor 等 30+ 工具通用。两边差异都已抹平:
| Claude Code | Codex | |
|---|---|---|
| skills 目录 | ~/.claude/skills/ | ~/.codex/skills/ |
| 禁自动调用 | disable-model-invocation: true(frontmatter) | agents/openai.yaml → allow_implicit_invocation: false |
| 选项弹窗 | AskUserQuestion | request_user_input(需先 /plan 才弹窗) |
| 并行子任务 | Task | subagent |
| 指令文件(指针段) | CLAUDE.md | AGENTS.md |
Codex 用户提示:引导问答要弹出图形化选项,需先
/plan进入 Plan 模式;否则 Codex 会静默用默认值。
实现方式与注意事项
它会做什么(8 个阶段)
| 阶段 | 动作 |
|---|---|
| 0 | 前置检查 + 重入守卫(已初始化则进增量模式,只补缺失、绝不覆盖) |
| 1 | 勘察(只读,跑 recon.sh):远端协议、.gitignore 暗礁、版本号位置、本地状态文件、upstream tag |
| 2 | 引导问答:upstream 地址、私有 tag 格式、协议、是否启用翻译、团队用哪个 agent、高冲突文件清单 |
| 3 | 配 git 远端(即 init,跑 setup-remote.sh):upstream 只读跟踪 + push = DISABLED + 自检 |
| 4 | 建 private/:维护规范 README.md + 改动台账 CHANGES-REGISTRY.md |
| 5 | 翻译(若启用):translate-plan.sh 判增量清单 → skill 内联翻译变动文档 |
| 6 | 写指针段:CLAUDE.md(CC)和/或 AGENTS.md(Codex) |
| 7 | 本地状态文件按需 skip-worktree(逐个征得同意) |
| 8 | 收尾:汇总产物,给出发布命令但不自动执行 |
四条铁律(注意事项)
- 私有内容尽量隔离:新增私有文件只进
private/(指针段除外);不得不直接改 upstream 文件时,登记到改动台账并定好升级冲突策略。 - 动手前先读
.gitignore:上游忽略规则会误伤你将生成的文件,也会暴露它「故意跟踪」的特殊文件。 - 重入安全(幂等):可重复执行,已存在的文件一律不覆盖,只补缺失。
- 本地定型后再发布:skill 只做到「本地就绪」,push 和打 tag 留给你确认无误后手动做。
仓库结构
.claude-plugin/ # CC 插件市场清单(/plugin 安装用)
├── marketplace.json # 市集:列出本仓库这个 plugin
└── plugin.json # 插件清单:privatize-fork
skills/privatize-fork/ # skill 本体(CC/Codex 共用,软链/插件都指它)
├── SKILL.md # 入口,唯一被识别的文件
├── agents/openai.yaml # Codex 专属元数据(禁自动调用;CC 忽略)
├── scripts/ # 关键步骤固化的自检脚本(幂等/只读 + 自检)
│ ├── setup-remote.sh # 阶段3:配 upstream + 禁推闸 + 自检
│ ├── recon.sh # 阶段1:只读勘察,结构化输出
│ └── translate-plan.sh # 阶段5:判断待翻清单(增量比对)
└── references/ # 按需读取的模板/流程,skill 运行时用
├── maintenance-readme.template.md # → private/README.md(维护规范)
├── changes-registry.template.md # → private/CHANGES-REGISTRY.md(改动台账)
├── translate-docs.md # 翻译流程(skill 内联执行)
└── translations-conventions.template.md # → private/translations/CONVENTIONS.md(翻译模块)
install.sh # 一键装两边:软链进 CC + Codex 的 skills 目录
assets/ # README 配图(outline 矢量,引用用)
├── banner.svg / features.svg # → README 引用的产物(文字已转路径)
└── src/ # 可编辑源 + build-svg.sh(改图后重生成产物)
README.md # 本文件(给人看的门面,不影响 skill 运行)
方法论内核
这个 skill 的价值不在「自动化」,而在顺序:先勘察(把项目的暗礁全摸清)→ 再设计(私有内容尽量隔离,必改上游的登记入账)→ 本地定型 → 最后一次性发布。把顺序走对,就能少走绝大部分弯路。