sync-global-rules

sync-global-rules

Sync the Agent rule system from the GitHub repository nangongwentian-fe/Awesome-GlobalRule to the global configuration directories of the two local AI tools.

Sync mapping

Repository source	Claude Code target	Codex target
AGENTS.md	~/.claude/CLAUDE.md	~/.codex/AGENTS.md
docs/agent-rules/* (11 files)	~/.claude/docs/agent-rules/	~/.codex/docs/agent-rules/

Status tracking

The last sync information is saved in ~/.claude/.sync_state.json, including the synced commit SHA. This way, each check only needs to compare the SHA, without downloading all the content.

Workflow

Scenario 1: Check whether there are updates (recommended to run first)

bash ~/.claude/skills/sync-global-rules/scripts/check_updates.sh

Output interpretation:

• Exit code 0 + output starts with updates-available: → there is a new version, perform sync
• Exit code 1 + output starts with up-to-date: → already up to date, no action needed
• Exit code 2 + output ERROR: → environment issue (gh not installed or not logged in)

Scenario 2: Perform a full sync

When there are updates (or when the user explicitly requests a sync):

bash ~/.claude/skills/sync-global-rules/scripts/sync.sh

The script will automatically:

1. Check the remote SHA against the locally recorded SHA
2. In ~/.claude/backups/<timestamp>/ automatically back up existing files
3. Download all files and write them to the two target directories
4. Update ~/.claude/.sync_state.json

Scenario 3: Force sync (even if the SHA is the same)

bash ~/.claude/skills/sync-global-rules/scripts/sync.sh --force

Scenario 4: Preview mode (do not write files)

bash ~/.claude/skills/sync-global-rules/scripts/sync.sh --dry-run

Standard execution order

When the user triggers this skill, execute in the following order:

1. Run check_updates.sh
2. Interpret the output:
   • There are updates → tell the user "New version found:", and ask whether to sync (or sync directly, depending on the user's instruction)
   • Already up to date → tell the user "Currently up to date (SHA: <short_sha>, last sync: )", and end
   • Error → tell the user the specific error and give repair suggestions
3. When there are updates, run sync.sh
4. Report the sync result (SHA, backup path, number of files)

Prerequisites

• gh CLI is installed and logged in (gh auth status）
• python3 is available
• For ~/.claude/ and ~/.codex/ have write permission

Notes

• Syncing will overwrite existing rule files, but an automatic backup is made before every sync(saved in ~/.claude/backups/）
• The backup only saves the main rule files (CLAUDE.md and AGENTS.md), files in the docs directory are not backed up (they can be restored from GitHub)
• If the user has local personalized modifications (such as language preferences, etc.), they need to be manually appended after syncing