sync-to-hub
Promote project-side `.claude/` improvements (skills, agents, hooks, rules) into the sam-cc-setup plugin in the hub repo. Sync is project -> hub, ADDITIVE ONLY. Each new or changed file is offered with a 3-way prompt (sync now / defer / never) so trial-only experiments do not pollute the curated hub. Use after a session in which you used or refined a tool worth keeping across future projects. NOT for mid-session use, uncommitted project work, or deleting anything from the hub (edit the hub directly for that).
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- sync-to-hub
- description
- Promote project-side `.claude/` improvements (skills, agents, hooks, rules) into the sam-cc-setup plugin in the hub repo. Sync is project -> hub, ADDITIVE ONLY. Each new or changed file is offered with a 3-way prompt (sync now / defer / never) so trial-only experiments do not pollute the curated hub. Use after a session in which you used or refined a tool worth keeping across future projects. NOT for mid-session use, uncommitted project work, or deleting anything from the hub (edit the hub directly for that).
- disable-model-invocation
- true
02 资源文件 1
- 脚本sync.sh692 B
03 SKILL.md 正文
/sync-to-hub
Promote .claude/ work from a project repo into the sam-cc-setup plugin inside the hub repo, at <hub>/cultivation/marketplace/sam-cc-setup/.
Prerequisite: the hub repo must be cloned locally. Its location comes from
SAM_CC_HUB_REPO(default$HOME/Desktop/loam). It is not present on every box;sync.shexits 1 with a hint if missing.
Direction
Project -> hub. ADDITIVE ONLY.
The hub is the curated master set you bootstrap new projects from (via claude plugin install sam-cc-setup@seed-skills, or the Copier template for full renders). For generic assets in a template-rendered project, the template's own template-sync promote into seed/ is the native path; it requires .copier-answers.yml or template-manifest.json, so in a repo without those this skill is the only promote path. A project may be a subset of the hub, or extend the hub with experiments. This skill promotes useful project-side experiments INTO the hub; it never deletes from the hub based on what a project lacks.
Iron law
NO HUB MUTATION WITHOUT PER-FILE USER APPROVAL
Each new or changed file is presented to you with a 3-way prompt:
y/yes/sync- sync this file to hub now- empty /
d/defer- skip this run; ask again after the threshold (default) n/never- skip permanently (until state cleared manually)
Default = defer. Pressing Enter on every prompt syncs nothing. Sync is opt-in.
State persistence
Decisions are recorded in <hub>/.sync-state (gitignored, per-hub-clone). Each /sync-to-hub invocation increments a session counter. Three decision types:
- Defer: the file is silently skipped (no prompt) until session count reaches the recorded
ask_again_atvalue. Defer threshold defaults to 4 sessions; override via envSAM_CC_DEFER_SESSIONS=N(3-6 is the recommended range). - Never: the file is silently skipped on every future run. To re-enable, edit
.sync-stateand remove thenever:<path>line. - Synced: records when the file was last promoted to hub.
State file format (flat KV, no jq dependency):
session=12
defer:skills/foo/SKILL.md:16
never:skills/bar/SKILL.md
synced:skills/baz/SKILL.md:8
To reset all state: rm <hub>/.sync-state.
Invocation
/sync-to-hub
Optionally override the hub location via env var SAM_CC_HUB_REPO=/path/to/hub.
Workflow
- Resolve
SAM_CC_HUB_REPO(default$HOME/Desktop/loam). Verify it exists and is a git repo. - Verify the project's
.claude/has no uncommitted changes. If dirty, refuse - commit or stash first. - Verify the hub's working tree is clean. If dirty, warn and ask to continue.
- Compute the additive diff (
rsync --dry-run -a --itemize-changes ...). Hub-only files are ignored. Standard exclusions:audit.log,settings.local.json,*.local.*. - Print summary:
X new files, Y changed files. - For each ADDED file: prompt
Add <file> to hub? [y/d/n]. Default defer. - For each CHANGED file: prompt
Update <file> in hub? [y/d/n]. Default defer. - If nothing approved: exit 0 with
"Nothing approved - exiting.". - Apply approved files via
rsync --files-from=<approved>. - Show the resulting
git statusin the hub. - Prompt
Commit synced files? [Y/n]. Default Y. - On Y: commit with message
sync: from <project> on <YYYY-MM-DD>, then a separate default-NO prompt asks before pushing (pushes are outward-facing). - On push failure: report the error and instruct a manual
cd <hub> && git pull --rebase && git push.
Record why the change traveled
After a sync batch promotes anything, add one line to the hub's cultivation/marketplace/UPGRADING.md.
State WHAT changed and WHY it traveled: a model change, a paper, a blog post, an incident.
Link the source when one exists.
The hub's provenance rule (top of that file) is the authority; this is a nudge, not a gate.
After a promotion commits, the scan prints a stderr reminder if the batch left UPGRADING.md untouched; it is advisory and never blocks.
Implementation
The deterministic logic lives in sync.sh, bundled next to this SKILL.md. It is a
thin wrapper that execs the canonical scan engine in the hub
(<hub>/bin/agent-sync.sh scan), so the apply path has no LLM in it. Approvals come
from interactive prompts on stdin, so the script can be driven by a human typist OR
by piped stdin (for testing or scripted approval flows).
Direct invocation (recommended):
cd <your-project>
bash <path-to-this-skill>/sync.sh
Scripted invocation:
# Approve all additions, accept default-Y commit/push:
yes y | bash <path-to-this-skill>/sync.sh
# Decline everything:
yes 'n' | bash <path-to-this-skill>/sync.sh
Passing --prune forwards to the engine's prune subcommand instead of scan.
Multi-level dependency chains need one rerun per level
The hub-presence guard withholds a consumer until every dependency in its transitive closure already exists in the hub's committed HEAD, so a chain three levels deep - a hook that sources a helper, which in turn sources a lower-level helper - syncs bottom-up: approve the deepest helper first, let the run commit it, rerun, approve the level above it, and so on. A withheld consumer with a "sync the dependency first, then rerun" message is this flow working, not a bug.
When NOT to use
- During a live debugging session - your
.claude/may have transient experimental tweaks you have not yet decided to keep. Sync at session end, not mid-session. - When you have not yet committed your project work - the dirty-check refuses to sync until the project's
.claude/is committed. - For removing a skill from the hub - this skill cannot delete from the hub. Edit the hub directly and commit there.
Interaction from inside Claude Code
If you invoke /sync-to-hub from a Claude Code session, the recommended flow is:
- Claude opens a Bash tool call:
bash <path-to-this-skill>/sync.sh - The interactive prompts appear in the Bash tool output. Claude relays them to you.
- You answer through Claude's conversation; Claude pipes your answers via stdin.
You may instead run sync.sh directly in a separate terminal - the prompts work natively in any TTY.
04 同仓库更多 Skills
verify-loam
Prove a Loam change in a real rendered project: copier-render this checkout, then drive headless and interactive Claude Code sessions, stubbed Codex runs and copier updates in the render and capture hook, memory, deny-rule, update and check evidence. Use before shipping any seed, hook, settings or copier.yml change.
hypothesis-tree
Persistent hypothesis tree for multi-step, multi-session investigations. Use when a "why does X fail" question branches into sub-hypotheses that must survive across sessions, or when falsifiable claims need tracking with dated, linked evidence. Maintains one markdown file with add, update, review, and prune subcommands, each gated on verifying the cited evidence file exists and supports the claim. NOT for a single-session bug hunt, a one-command question, or general note-taking.
fable-prompting
Which Claude Fable 5.2 guide sections you can act on from a session, and which Claude Code already injects. Use before writing a Fable session prompt or brief.
catchup
Read-only session bootstrap briefing of git state, commits, handoff, tasks and red flags. Use when resuming work, starting a fresh session, or unsure of project state.
writing-for-agents
Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.
wizard
Generate an interactive bash wizard that walks a human through steps only they can perform. Use when provisioning infrastructure, setting up credentials or CI secrets, walking an unfamiliar third-party dashboard, or running a one-off migration or cutover. Don't invoke this for steps the agent can perform itself.