SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillssubtree-publish

subtree-publish

General & other

View repository

Updated 10-15 20:10

About this skill

Subtree Publish

Push a specified subdirectory in the monorepo to an independent GitHub repository via git subtree push .

Files are stored only once (in the monorepo), and synced to the independent repository with a single command.

Prerequisites

  • The current working directory is the monorepo root
  • The subdirectory is located at <prefix>/<name>/
  • The above dependencies (git subtree, gh, jq) are installed

Dependencies

System dependencies

Dependency Purpose Installation method
git (including subtree) Subdirectory splitting and pushing macOS: preinstalled
gh GitHub CLI, creating repositories and authentication macOS: brew install gh
jq JSON configuration parsing macOS: brew install jq

Usage

1. Automatic detection and push (recommended)

After the user completes a git commit, if this commit involves a subproject in the manifest:

bash scripts/subtree-push.sh --auto

The script checks the files involved in the most recent commit, and if a subdirectory in the manifest is matched, it automatically pushes to the corresponding independent repository.

Trigger timing: When the user says "the commit is done", "help me push to the independent repository", or "sync the subtree", first check whether any subproject in the manifest has been modified.

2. Register a new subproject for the first time

When the user says "register a subtree" or "add a new independent repository release":

Step 1: Confirm the subdirectory exists

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

Step 2: Pre-check — check README.md

Before performing any remote operations, you must first check whether README.md：

ls <prefix>/<name>/README.md
  • If it does not exist: you must first create README.md before continuing with the subsequent steps. Do not skip. When creating, refer to the references/readme-template.md template.
  • If it already exists: skip creation and continue to the next step.

README.md is the human-facing display page of the independent GitHub repository, not a skill runtime file. When creating or rewriting it, you must comply with the following:

  • Explain the outcome on the first screen: the title, first paragraph, and quote must let visitors know within 30 seconds "who this skill helps, in what scenarios, and what it produces". Do not start with frontmatter, directory structure, or internal implementation.
  • Open with a real question: put a real user question and how AI intervenes in the first half, prioritizing showing "how to use it" rather than listing features.
  • Installation path is executable: it must include the three steps of downloading from GitHub Releases, extracting to the skill directory, and enabling the environment; if dependencies such as Python/CLI/API Key are required, the installation or configuration commands must be written nearby.
  • Outputs are predictable: use a list to explain which files, reports, tables, annotations, retrieval results, or action checklists will be produced; avoid writing only vague phrases such as "improve efficiency" or "intelligent analysis".
  • Boundaries and responsibilities are clear: it must separately explain suitable and unsuitable scenarios. Legal, patent, trademark, and compliance skills must clearly state boundaries such as "does not replace formal legal advice/agent judgment/guarantees of successful registration".
  • Credibility is supported: Complex or heavily promoted skills should explain the methodology framework, coverage scope, key files, evaluation/examples/scripts and other quality support, but do not write the README as complete technical documentation.
  • License consistency: The license type in the README must be consistent with the SKILL.md frontmatter and LICENSE.txt ; for CC BY-NC type skills, prompt the commercial licensing contact to be based on LICENSE.txt .
  • External referral closing: The bottom should explain the upstream project or skill collection to which this repository belongs, and recommend related projects, the main repository, or author contact information. Do not write internal maintenance mechanisms such as "all modifications are made in the monorepo" or "synced via git subtree" for end users.

If you need to unify author information, QR codes, main repository links, or related project recommendations, first read config/readme-profile.json; this file is a local personalized configuration and is not committed by default. When there is no local configuration, refer to config/readme-profile.example.json for the field structure, and generate the README using generic placeholders.

Before writing, choose a profile based on complexity:

  • minimal: Simple tool-type skill. Keep "Typical scenarios / What it can produce / Installation method / Usage boundaries / License / Author / Related projects".
  • standard: Most public skills. On top of minimal, add "Who it is suitable for / Current coverage scope / Common usage".
  • showcase: Heavily promoted, complex legal, or high-risk skills. On top of standard, add "What problem the project solves / Core design / Example output / Quality support / Key files".

Before publishing, review the README with the following checklist:

  1. Can the target users, core scenarios, and output results be directly determined from the first screen?
  2. Are there real user question examples, rather than only a feature list?
  3. Are the installation steps sufficient for external users to start trying it out?
  4. Are suitable/unsuitable cases stated, and do high-risk scenarios have disclaimers?
  5. Are the license, author, and related projects consistent with the current skill metadata?
  6. Have template placeholders, internal maintenance tone, and overly long directory trees been removed?

Step 3: Create an independent GitHub repository(if first-time setup is needed)

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

Step 4: Add remote

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

Step 5: First push

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

Step 6: Register in the manifest

Add the subproject information to config/subtree-skills.json, and update the manifest table above.

Step 7: Create the first Release

After the first push, run the script to create a GitHub Release:

bash scripts/create-release.sh <name>

3. Manually push a single subproject

bash scripts/subtree-push.sh <name> [--setup] [--dry-run]
  • --setup: Create the GitHub repository and add the remote at the same time
  • --dry-run: Only show the operations to be performed, without actually pushing

Remote naming rules

The remote name for independent repositories is uniformly <name>-standalone。

Release creation rules

After each subtree push, automatically check whether a GitHub Release needs to be created.

Trigger conditions

  1. Read <prefix>/<name>/SKILL.md in version field to get the current version number
  2. Via gh release list --repo <org>/<repo-name> --limit 1 check the tag of the latest Release
  3. If the current version number corresponds to v<version> tag does not yet exist, create a Release
  4. If a Release with the same version already exists, skip

Execution steps

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

The script automatically performs: read version number → check existing Release → extract CHANGELOG → package (excluding README.md and .DS_Store) → create Release.

Release Notes source

  • Prioritize extraction from <prefix>/<name>/CHANGELOG.md of the changelog for the corresponding version
  • If CHANGELOG.md does not exist or has no corresponding version, use the default text:"发布 v<version>"

Archive contents

After extracting the archive, you get the <name>/ folder (e.g., code2patent/)，users can directly place it into .claude/skills/ to use it.

Exclusion rules (create-release.sh in zip -r the -x parameter):

Exclusion pattern Reason
*.DS_Store macOS system file
README.md For standalone repository browsers; not a skill runtime file
archive/、archive/** Historical review/processing records containing real user data
output/、output/** Runtime output artifacts
**/__pycache__、**/__pycache__/* Python compilation cache
**/*.pyc、**/*.log Python compilation cache, logs
**/*.tmp、**/*.bak Temporary/backup files
**/.env、**/.env.* Environment variable files (contain key risk)
DECISIONS.md Local decision records and work logs containing internal details, not for external release
TASKS.md Local task list; not a skill runtime file
config/*.json Local personalized configuration; only retain *.example.json

The completeness of the exclusion rules is guaranteed by comparing .gitignore in **/archive/*、**/output/*、**/__pycache__/、**/DECISIONS.md、**/TASKS.md and other rules. The script does not actively read .gitignorebut instead uses explicit -x patterns to cover common scenarios. When new exclusion requirements are added, update the table here accordingly.

Version jumps

Supports non-consecutive version numbers (e.g., 1.2.0 → 1.2.2, skipping 1.2.1). Each time, a Release is created only for the currently pushed version; Releases for intermediate versions will not be retroactively created.

Notes

  • Do not directly modify files in the standalone repository; all modifications should be made in the monorepo
  • git subtree push may be slower on large repositories; this is normal
  • Files in the standalone repository are located in the root directory (not in a nested subdirectory)
  • Git subtree only pushes committed files, controlled by the monorepo root directory .gitignore Control
  • If the monorepo uses a symlink to make .claude/skills/<name> point to skills/<name>(e.g., legal-skills), when manually committing changes to the skill itself, git add .claude/skills/<name>/... will report "pathspec is in a symbolic link"; use the real physical path git add skills/<name>/... instead. The push and packaging scripts of this skill already uniformly use the skills/ prefix internally and are not affected by this symlink.

Configuration file

config/subtree-skills.json

The actual configuration file is located at config/subtree-skills.json, used for --auto pattern detection and repository name mapping. To create a new configuration, refer to config/subtree-skills.example.json。

field descriptions:

  • prefix: subdirectory prefix (relative to the monorepo root directory)
  • org: GitHub organization/username
  • skills: subproject array
    • name: subdirectory name (required)
    • repo: standalone repository name (optional, defaults to <name>.skill）
    • version: version number in the current SKILL.md (optional, used to check whether a new Release needs to be published)
    • last_release: latest published Release tag (optional, e.g., v1.0.0）
    • last_updated: most recent subtree push or Release update time (optional, format YYYY-MM-DDTHH:MM:SS）

config/readme-profile.json (optional)

Local README personalization configuration. Used to uniformly generate the author entry, QR code, upstream project referral, and related project recommendations for standalone repository READMEs. This file usually contains personal or project-specific information and should be kept locally; the release package and version repository only keep config/readme-profile.example.json。

Read priority:

  1. Environment variables (temporary override)
  2. config/readme-profile.json(local fixed configuration)
  3. config/readme-profile.example.json(field structure example)
  4. references/readme-template.md generic placeholders in

Common environment variables:

  • 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

Recommended fields:

  • upstream: Upstream project or skill collection information
  • author: Author display name, contact information, QR code image URL
  • contact_messages: Default, legal business, and tool contact copy
  • related_projects: Pool of related projects that can be recommended
  • skill_overrides: Customize recommended projects, contact copy, or profile by skill name

Release rules:

  • Do not write the real readme-profile.json into the public release package
  • scripts/create-release.sh will exclude non-example config/*.json, keeping *.example.json

Default repository name rule

The standalone repository name by default appends after the subdirectory name .skill suffix. For example:

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

Users can, in config/subtree-skills.json , explicitly specify a different repository name through the repo field, but if not specified, it automatically uses <name>.skill。

script

scripts/subtree-push.sh

Automates the subtree push process, supporting --auto change detection and repository name mapping.

scripts/create-release.sh

Automates the GitHub Release creation process. Usage:bash scripts/create-release.sh <name> [--dry-run]

The script automatically completes: reads the SKILL.md version number → checks for an existing Release → extracts CHANGELOG as Release Notes → packages (excluding README.md and .DS_Store, yielding after extraction the <name>/ folder) → creates the Release and attaches the compressed package.