| name | magpie-setup-shared-config-sync |
| family | setup |
| mode | Meta |
| description | Commit + push the user's shared Claude config to the
`~/.claude-config` private dotfile-style sync repo. Inspects
for uncommitted local edits and unpushed commits, drafts a
commit message, and after explicit approval commits and
pushes. Runs `git pull --rebase` first if the local checkout
is behind, so a push never overwrites concurrent work from
another machine. Bootstraps the repo when it is missing:
clones the default private remote if it exists, or creates a
new private remote + scaffolds the minimal layout if it does
not. Never force-pushes; never rewrites already-pushed
history; never creates a public remote; never modifies files
outside `~/.claude-config/` (except the confirmed fresh-host
symlink wiring into `~/.claude/`).
|
| when_to_use | Invoke when the user says "sync my Claude config", "push my
~/.claude-config", "commit shared Claude config", or after
modifying a file in `~/.claude-config/` (scripts, CLAUDE.md,
commands, sync.sh). Also invoke on a fresh host with no
`~/.claude-config/` yet ("set up my shared config", "bootstrap
my claude-config repo") — the skill clones the default remote
or creates it. Also appropriate after
`setup-isolated-setup-update` surfaces drift on a script the
user keeps in `~/.claude-config/` and wants propagated to
other machines.
|
| capability | ["capability:intake","capability:platform"] |
| license | Apache-2.0 |
setup-shared-config-sync
This skill propagates local edits in ~/.claude-config/ to the
sync repo's remote, so other machines can pull them. It is the
counterpart to the periodic git pull --rebase --autostash that
the framework's example sync.sh runs on a timer — that direction
pulls upstream into the local clone; this skill pushes local
modifications upstream.
Adopter overrides
Before running the default behaviour documented
below, this skill consults
.apache-magpie-local/setup-shared-config-sync.md (personal, gitignored) and .apache-magpie-overrides/setup-shared-config-sync.md (committed, project-wide)
in the adopter repo if it exists, and applies any
agent-readable overrides it finds. See
docs/setup/agentic-overrides.md
for the contract — what overrides may contain, hard
rules, the reconciliation flow on framework upgrade,
upstreaming guidance.
Hard rule: agents NEVER modify the snapshot under
<adopter-repo>/.apache-magpie/. Local modifications
go in the override file. Framework changes go via PR
to apache/magpie.
Snapshot drift
Also at the top of every run, this skill compares the
gitignored .apache-magpie.local.lock (per-machine
fetch) against the committed .apache-magpie.lock
(the project pin). On mismatch the skill surfaces the
gap and proposes
/magpie-setup upgrade.
The proposal is non-blocking — the user may defer if
they want to run with the local snapshot for now. See
docs/setup/install-recipes.md § Subsequent runs and drift detection
for the full flow.
Drift severity:
- method or URL differ → ✗ full re-install needed.
- ref differs (project bumped tag, or
git-branch
local is behind upstream tip) → ⚠ sync needed.
svn-zip SHA-512 mismatches the committed
anchor → ✗ security-flagged; investigate before
upgrading.
Hardcoded path
The sync repo lives at ~/.claude-config/. This is the convention
documented in
→ Syncing user-scope config across machines.
Adopters who maintain a sync repo at a different path will need to
fork this skill — the path is intentionally not parameterised
because the doc specifies one canonical location and forking the
skill is cleaner than per-invocation path-passing.
