Subtree Publish

Subtree Publish

将 monorepo 中指定子目录通过 git subtree push 推送到独立 GitHub 仓库。

文件只存一份（在 monorepo 中），一条命令同步到独立仓库。

前置条件

• 当前工作目录是 monorepo 根目录
• 子目录位于 <prefix>/<name>/
• 已安装上述依赖（git subtree、gh、jq）

依赖

系统依赖

使用方式

1. 自动检测并推送（推荐）

当用户完成一次 git commit 后，如果本次提交涉及清单中的子项目：

bash scripts/subtree-push.sh --auto

脚本会检查最近一次 commit 涉及的文件，如果命中清单中的子目录，自动推送到对应独立仓库。

触发时机： 用户说"提交完了"、"帮我推到独立仓库"、"同步 subtree"时，先检查是否有清单中的子项目被修改。

2. 首次注册新子项目

当用户说"注册 subtree"、"新增独立仓库发布"时：

Step 1: 确认子目录存在

ls <prefix>/<name>/SKILL.md

Step 2: 前置校验 — 检查 README.md

在执行任何远程操作之前，必须先检查子目录中是否已存在 README.md：

ls <prefix>/<name>/README.md

• 如果不存在：必须先创建 README.md，才能继续后续步骤。不得跳过。创建时参照 references/readme-template.md 模板。
• 如果已存在：跳过创建，继续下一步。

README.md 是独立 GitHub 仓库的人类展示页，不是 skill runtime 文件。创建或重写时必须遵守：

• 首屏讲清结果：标题、首段和引用句必须让访客在 30 秒内知道“这个 skill 帮谁，在什么场景下，产出什么”。不要先讲 frontmatter、目录结构或内部实现。
• 真实提问开场：在前半部分放一个真实用户提问和 AI 介入方式，优先展示“怎么用”，而不是罗列功能。
• 安装路径可执行：必须包含 GitHub Releases 下载、解压到 skill 目录、启用环境这三步；如需 Python/CLI/API Key 等依赖，必须就近写出安装或配置命令。
• 产物可预期：用清单说明会产出哪些文件、报告、表格、批注、检索结果或行动清单；避免只写“提高效率”“智能分析”等空泛词。
• 边界与责任清楚：必须分别说明适合与不适合的场景。法律、专利、商标、合规类 skill 必须写明“不替代正式法律意见/代理判断/注册成功承诺”等边界。
• 可信度有支撑：复杂或重点推广 skill 应说明方法框架、覆盖范围、关键文件、评测/示例/脚本等质量支撑，但不要把 README 写成完整技术文档。
• 许可证一致：README 的许可证类型必须与 SKILL.md frontmatter 和 LICENSE.txt 保持一致；CC BY-NC 类 skill 应提示商用授权联系方式以 LICENSE.txt 为准。
• 外部导流收尾：底部应说明本仓库所属的上游项目或技能集合，并推荐相关项目、主仓库或作者联系方式。不要把“所有修改在 monorepo 中进行”“通过 git subtree 同步”这类内部维护机制写给最终用户。

如需统一作者信息、二维码、主仓库链接或相关项目推荐，先读取 config/readme-profile.json；该文件为本地个性化配置，默认不提交。没有本地配置时，参考 config/readme-profile.example.json 的字段结构，并用通用占位符生成 README。

写作前按复杂度选择 profile：

• minimal：简单工具型 skill。保留“典型场景 / 能产出什么 / 安装方式 / 使用边界 / 许可证 / 作者 / 关联项目”。
• standard：大多数公开 skill。在 minimal 基础上增加“适合谁用 / 当前覆盖范围 / 常见用法”。
• showcase：重点推广、复杂法律或高风险 skill。在 standard 基础上增加“项目解决什么问题 / 核心设计 / 示例输出 / 质量支撑 / 关键文件”。

发布前用以下检查清单复核 README：

1. 首屏是否能直接判断目标用户、核心场景和输出结果？ 2. 是否有真实用户提问示例，而不是只有功能列表？ 3. 安装步骤是否足以让外部用户开始试用？ 4. 是否写明适合/不适合，且高风险场景有免责声明？ 5. 许可证、作者、关联项目是否与当前 skill 元数据一致？ 6. 是否删除了模板占位符、内部维护口吻和过长目录树？

Step 3: 创建独立 GitHub 仓库（如果需要首次设置）

gh repo create <org>/<repo-name> --public --description "<描述>"

Step 4: 添加 remote

git remote add <name>-standalone https://github.com/<org>/<repo-name>.git

Step 5: 首次推送

git subtree push --prefix=<prefix>/<name> <name>-standalone main

Step 6: 注册到清单

将子项目信息加入 config/subtree-skills.json，并更新上面的清单表格。

Step 7: 创建首个 Release

首次推送后，运行脚本创建 GitHub Release：

bash scripts/create-release.sh <name>

3. 手动推送单个子项目

bash scripts/subtree-push.sh <name> [--setup] [--dry-run]

• --setup: 同时创建 GitHub 仓库和添加 remote
• --dry-run: 只显示将要执行的操作，不实际推送

Remote 命名规则

独立仓库的 remote 名称统一为 <name>-standalone。

Release 创建规则

每次 subtree push 后，自动检查是否需要创建 GitHub Release。

触发条件

1. 读取 <prefix>/<name>/SKILL.md 中的 version 字段，获取当前版本号 2. 通过 gh release list --repo <org>/<repo-name> --limit 1 检查最新 Release 的 tag 3. 如果当前版本号对应的 v<version> tag 尚不存在，则创建 Release 4. 如果已存在相同版本的 Release，跳过

执行步骤

bash scripts/create-release.sh <name> [--dry-run]

脚本会自动完成：读取版本号 → 检查已有 Release → 提取 CHANGELOG → 打包（排除 README.md 和 .DS_Store）→ 创建 Release。

Release Notes 来源

• 优先从 <prefix>/<name>/CHANGELOG.md 提取对应版本的变更记录
• 如果 CHANGELOG.md 不存在或无对应版本，使用默认文本："发布 v<version>"

压缩包内容

压缩包解压后得到 <name>/ 文件夹（如 code2patent/），用户直接放入 .claude/skills/ 即可使用。

排除规则（create-release.sh 中 zip -r 的 -x 参数）：

排除规则的完整性通过比对 .gitignore 中 **/archive/*、**/output/*、**/__pycache__/、**/DECISIONS.md、**/TASKS.md 等规则保证。脚本不主动读 .gitignore，而是用显式 -x 模式覆盖常见场景。新增排除需求时同步更新此处表格。

版本跃迁

支持非连续版本号（如 1.2.0 → 1.2.2，跳过 1.2.1）。每次只为当前推送的版本创建 Release，不会补建中间版本的 Release。

注意事项

• 不要在独立仓库中直接修改文件，所有修改都应在 monorepo 中进行
• git subtree push 在大仓库上可能较慢，这是正常的
• 独立仓库中的文件位于根目录（不是嵌套的子目录）
• Git subtree 只推送已 commit 的文件，受 monorepo 根目录 .gitignore 控制
• 若 monorepo 用 symlink 让 .claude/skills/<name> 指向 skills/<name>（如 legal-skills），手动提交 skill 自身改动时 git add .claude/skills/<name>/... 会报“pathspec 位于符号链接中”；改用真实物理路径 git add skills/<name>/... 即可。本 skill 的推送和打包脚本内部已统一使用 skills/ 前缀，不受此 symlink 影响。

配置文件

config/subtree-skills.json

实际配置文件位于 config/subtree-skills.json，用于 --auto 模式检测和仓库名映射。如需新建配置，可参考 config/subtree-skills.example.json。

字段说明：

• prefix: 子目录前缀（相对于 monorepo 根目录）
• org: GitHub 组织/用户名
• skills: 子项目数组
• name: 子目录名称（必填）
• repo: 独立仓库名（可选，默认为 <name>.skill）
• version: 当前 SKILL.md 中的版本号（可选，用于核查是否需要发布新 Release）
• last_release: 最新已发布的 Release tag（可选，如 v1.0.0）
• last_updated: 最近一次 subtree push 或 Release 更新时间（可选，格式 YYYY-MM-DDTHH:MM:SS）

config/readme-profile.json（可选）

本地 README 个性化配置。用于统一生成独立仓库 README 的作者入口、二维码、上游项目导流和相关项目推荐。该文件通常包含个人或项目特定信息，应保留在本地；发布包和版本库只保留 config/readme-profile.example.json。

读取优先级：

1. 环境变量（临时覆盖） 2. config/readme-profile.json（本地固定配置） 3. config/readme-profile.example.json（字段结构示例） 4. references/readme-template.md 中的通用占位符

常用环境变量：

• SUBTREE_README_UPSTREAM_NAME
• SUBTREE_README_UPSTREAM_URL
• SUBTREE_README_AUTHOR_DISPLAY
• SUBTREE_README_WECHAT_ID
• SUBTREE_README_QR_IMAGE_URL
• SUBTREE_README_CONTACT_DEFAULT
• SUBTREE_README_CONTACT_LEGAL
• SUBTREE_README_CONTACT_TOOL

推荐字段：

• upstream: 上游项目或技能集合信息
• author: 作者展示名、联系方式、二维码图片 URL
• contact_messages: 默认、法律业务类、工具类联系文案
• related_projects: 可推荐的相关项目池
• skill_overrides: 按 skill 名定制推荐项目、联系文案或 profile

发布规则：

• 不要把真实的 readme-profile.json 写入公开发布包
• scripts/create-release.sh 会排除非 example 的 config/*.json，保留 *.example.json

仓库名默认规则

独立仓库名默认在子目录名后追加 .skill 后缀。例如：

• opc-legal-counsel → opc-legal-counsel.skill
• code2patent → code2patent.skill

用户可以在 config/subtree-skills.json 中通过 repo 字段显式指定不同的仓库名，但如果不指定则自动使用 <name>.skill。

脚本

scripts/subtree-push.sh

自动化 subtree 推送流程，支持 --auto 变更检测和仓庝名映射。

scripts/create-release.sh

自动化 GitHub Release 创建流程。用法：bash scripts/create-release.sh <name> [--dry-run]

脚本自动完成：读取 SKILL.md 版本号 → 检查已有 Release → 提取 CHANGELOG 作为 Release Notes → 打包（排除 README.md 和 .DS_Store，解压后得到 <name>/ 文件夹）→ 创建 Release 并附上压缩包。

Changelog

All notable changes to this skill will be documented in this file.

[v1.7.1] - 2026-06-04

修复

• 修复 create-release.sh 不读 .gitignore 的设计缺陷。zip -r 之前只排除 .DS_Store、README.md、config/*.json，未处理 .gitignore 中被全局排除的目录（archive/、output/、__pycache__/）和文件类型（*.pyc、*.log、*.tmp、*.bak、.env*）。
• 触发场景：contract-copilot v1.5.2 release 包含 242 个 archive/ 历史合同审核条目、60 个 __pycache__/ 条目、55 个 .pyc 编译缓存。
• 影响范围：archive/output/__pycache__ 等运行时产物可能被打包进独立仓库 release zip，潜在泄露用户数据（如合同审核历史）或污染 skill 安装目录。
• 修复后排除规则完整覆盖 .gitignore 中常见运行时产物类型。

文档完善

• 更新 TASKS.md 和 DECISIONS.md（本地）记录脚本设计缺陷。
• 更新 SKILL.md "压缩包内容" 章节，文档化完整排除规则。
• 排查其他 skill 历史 release：code2patent v1.5.3 / md2word v1.0.1 / de-ai-polish v1.0.0 / opc-legal-counsel v0.2.5 / contract-copilot v1.4.50 / v1.5.1 均无此问题。

[v1.7.0] - 2026-04-23

新增

• 新增 config/readme-profile.example.json，用于定义独立仓库 README 的作者入口、二维码、上游项目导流和相关项目推荐字段
• 支持通过本地 config/readme-profile.json 或 SUBTREE_README_* 环境变量提供 README 个性化信息

改进

• README 模板改为从 profile 配置读取作者展示名、联系文案、二维码图片、上游项目和相关项目推荐
• Release 打包排除非 example 的 config/*.json，避免本地个性化配置进入公开发布包，同时保留 *.example.json

文档完善

• 更新 SKILL.md、TASKS.md 与 DECISIONS.md，说明 README profile 的读取优先级、字段结构和发布规则

[v1.6.0] - 2026-04-22

改进

• 强化独立仓库 README 写作要求：从栏目模板升级为首屏价值、真实提问、安装依赖、产物预期、边界责任、可信度支撑和许可证一致性的质量验收标准
• 更新 references/readme-template.md，增加依赖/API Key 就近说明、CC BY-NC 商用授权提示和发布前检查清单
• 明确已注册独立仓库 README 应按 skill 复杂度选择 minimal / standard / showcase profile，而不是机械套用固定长模板
• 调整“关联项目”规范：README 应面向最终用户推荐上游项目、相关 skill 或作者入口，不再输出 monorepo/subtree 内部同步说明
• README 模板保持通用占位符，不硬编码特定作者二维码或特定项目推广文案

文档完善

• 更新 TASKS.md 与 DECISIONS.md，记录 README 规范升级的背景、理由和影响范围

[v1.5.0] - 2026-04-19

新增

• README 模板升级为“固定骨架 + 可选叙事模块”的结构，支持 minimal / standard / showcase 三种复杂度 profile
• README 写作原则：结果优先、示例优先、边界清晰、安装简单
• 首次注册流程新增 README 创建规则，要求根据 skill 复杂度选择合适展开层级

修改

• references/readme-template.md 从轻量固定模板改为面向独立 GitHub 仓库的人类展示模板
• SKILL.md 中明确 README.md 是独立仓库展示页，不属于 skill runtime 文件

[v1.4.0] - 2026-04-19

新增

• Release 创建规则：每次 subtree push 后自动检查 SKILL.md 版本号，如无对应 tag 则创建 GitHub Release
• Release 附加 zip 压缩包（排除 README.md 和 .DS_Store），用户下载后可直接放入 .claude/skills/ 使用
• README.md 是面向独立仓库浏览者的展示文件，不属于 skill 运行所需，不纳入压缩包
• 新增 scripts/create-release.sh 脚本，自动化 Release 创建流程
• Release Notes 优先从 CHANGELOG.md 提取，无则使用默认文本
• 首次注册流程新增 Step 7：创建首个 Release
• 仓库名默认规则：独立仓库名默认为 <name>.skill

修改

• 配置文件引用改为指向实际文件和 example 文件，移除内联 JSON 示例
• 版本跃迁说明：支持非连续版本号（如 1.2.0 → 1.2.2），只为当前推送的版本创建 Release

[v1.3.0] - 2026-04-19

新增

• 首次注册流程新增 Step 2 前置校验：推送前必须检查子目录是否存在 README.md，不存在则必须先创建

修复

• 修正首次注册流程中 Step 编号重复的问题（原文有两个 Step 3 和重复的 gh repo create 命令）

[v1.2.0] - 2026-04-19

修改

• 配置文件从 TXT 格式迁移到 JSON 格式（config/subtree-skills.json）
• 支持子目录名与 GitHub 仓库名的映射（如 opc-legal-counsel → opc-legal-counsel.skill）
• 脚本从 JSON 配置中读取 org 和 prefix，不再硬编码
• SKILL.md 措辞通用化，去除 legal-skills 特定引用

[v1.1.0] - 2026-04-19

新增

• --auto 模式：自动检测最近 commit 涉及的子项目并推送
• config/subtree-skills.txt 注册清单

修改

• SKILL.md 中添加已注册子项目清单表格

[v1.0.0] - 2026-04-19

新增

• 初始版本：支持单子项目推送（--setup、--dry-run）
• 自动创建 GitHub 仓库
• 自动添加 git remote

<skill-name>

<一句话说明：这个 skill 帮谁、在什么场景下、产出什么。>

<一句话价值主张：让访客在 30 秒内知道为什么值得安装。>

<!-- README.md 面向独立 GitHub 仓库的人类访客，不是 skill runtime 文件。 Release zip / 安装包中仍应排除 README.md，避免污染实际 skill 目录。

个性化信息来源：

• 优先读取 config/readme-profile.json（本地配置，不提交）
• 可用 SUBTREE_README_* 环境变量临时覆盖
• 公开发布只保留 config/readme-profile.example.json 作为字段示例

写作原则：

• outcome first：首屏先讲结果，不先讲 YAML/frontmatter/目录结构
• example first：前半部分给真实用户提问和 AI 介入方式
• install executable：安装步骤必须能照做；有依赖就就近写命令
• boundary clear：适合/不适合分开写，高风险场景必须写清免责声明
• trust supported：复杂 skill 补方法框架、覆盖范围、质量支撑和关键文件
• metadata consistent：许可证、作者、项目链接必须与 SKILL.md / LICENSE.txt 一致

复杂度 profile：

• minimal：保留“典型场景 / 能产出什么 / 安装方式 / 使用边界 / 许可证 / 作者 / 关联项目”
• standard：再加“适合谁用 / 当前覆盖范围 / 常见用法”
• showcase：再加“项目解决什么问题 / 核心设计 / 示例输出 / 关键文件 / 质量支撑”

-->

适合谁用

• <目标用户 1>
• <目标用户 2>
• <目标用户 3>

典型场景

<用一个真实、短小的例子说明什么时候会用到这个 skill。不要写成完整工作流，只要让读者一眼看懂“原来可以这样用”。>

用户：<用户会怎么提出需求>
AI：<这个 skill 会如何介入，并产出什么>

它能产出什么

• <产出物 1>
• <产出物 2>
• <产出物 3>

安装方式

1. 打开本仓库的 GitHub Releases。 2. 下载最新版本的 skill 压缩包。 3. 解压后将 <skill-name>/ 文件夹放入你的 skill 目录。 4. 在支持 SKILL.md 的 Agent / Claude 环境中启用该 skill。

<!-- 如果需要依赖，必须就近补充，例如： 5. 安装依赖：pip install -r scripts/requirements.txt 6. 配置 API Key：复制 scripts/.env.example 为 scripts/.env 并填入密钥 -->

<!-- 不要在 README 中写“通过 git subtree 同步”“所有修改在 monorepo 中进行”等内部维护机制。README 面向最终用户，应把这里留给安装、使用和项目导流。 -->

可以怎么用

你可以直接向 Agent 提出类似问题：

• “<示例问题 1>”
• “<示例问题 2>”
• “<示例问题 3>”

使用边界

这个 skill 适合：

• <适合场景 1>
• <适合场景 2>
• <适合场景 3>

这个 skill 不适合：

• <不适合场景 1>
• <不适合场景 2>
• <不适合场景 3>

<!-- 以下为 standard / showcase profile 可选模块。简单 skill 可以删除。 -->

这个项目解决什么问题

<可选。用于复杂或重点推广的 skill。讲真实痛点，不要先讲文件结构。>

当前覆盖范围

• <覆盖范围 1>
• <覆盖范围 2>
• <覆盖范围 3>

核心设计

1. <设计原则 A>

<说明这个设计原则为什么存在，它如何影响输出质量。>

2. <设计原则 B>

<说明这个设计原则为什么存在，它如何影响使用体验。>

3. <设计原则 C>

<说明这个设计原则为什么存在，它如何控制边界或风险。>

示例输出

<可选。放一个短示例即可，不要把完整长文档粘进 README。重点展示“使用后会得到什么”。>

<简短示例输出>

Before / After

不用这个 skill：

• <原来需要手工做什么>
• <容易遗漏什么>

使用这个 skill：

• <现在能自动完成什么>
• <输出如何更稳定、更结构化>

项目结构

<skill-name>/
├── SKILL.md
├── CHANGELOG.md
├── LICENSE.txt
├── references/
├── assets/
├── examples/
├── evals/
└── scripts/

关键文件

• SKILL.md：正式 skill 入口，供 Agent 判断何时加载和如何执行
• CHANGELOG.md：版本变更记录
• LICENSE.txt：许可证文本
• references/：领域资料、流程规则或补充说明
• examples/：公开示例或示范输入输出
• evals/：评测样本或回归检查
• scripts/：辅助脚本

质量支撑

• <评测或回归方式 1>
• <示例或样稿 2>
• <脚本或人工检查 3>

许可证

本作品采用 <许可证类型> 许可证。

<!-- CC BY-NC 类 skill 如需提示商用授权，写： 如需商用授权，请以 LICENSE.txt 中的联系方式为准。 -->

作者

<从 config/readme-profile.json 的 author.display 读取；如未配置，再从 SKILL.md frontmatter 的 author 字段提取>

<!-- 如 config/readme-profile.json 或环境变量配置了作者咨询入口，可加入二维码或联系方式，例如：

<contact_messages.default / contact_messages.legal / contact_messages.tool 中匹配当前 skill 的联系文案>

<div align="center"> <img src="<author.qr_image_url>" width="200" alt="微信二维码"/> <p><em>微信：<author.wechat_id></em></p> </div> -->

关联项目

本仓库是 <upstream.name> 的子项目。<upstream.description>

相关项目：

• <related_projects 中的相关项目 A>：<一句话说明>
• <related_projects 中的相关项目 B>：<一句话说明>
• <related_projects 中的相关项目 C>：<一句话说明>

发布前检查

• [ ] 首屏说明了目标用户、核心场景和输出结果
• [ ] 前半部分有真实提问示例
• [ ] 安装步骤可执行，依赖/API Key 说明就近出现
• [ ] 适合/不适合场景分开写清楚
• [ ] 法律、专利、商标、合规类 skill 写明不替代正式专业意见
• [ ] 许可证、作者、关联项目与当前 skill 元数据一致
• [ ] 关联项目面向最终用户导流，不暴露 monorepo/subtree 等内部维护机制
• [ ] 删除模板占位符、内部维护口吻和过长目录树