Keep catalogs in sync

In Getting started, Dana synced each change right after she made it, and nobody else was editing. Now Dana and Sam both change acme-skills every day, some changes in the desktop app and some by hand in the clone, and sometimes they change the same line. This guide explains when each change reaches the Git host, and how to merge when two changes collide.

What a desktop save does

When Dana edits a skill in the desktop app and saves it, the change reaches the Git host at once, so she has nothing left to sync. On a catalog with the default direct sync policy, each save runs these steps:

1. Pulls the catalog, so the change starts from the host's latest version.
2. Applies your change and checks the catalog.
3. Commits the files of the item you saved, with a message that starts with [skillcatalog] .
4. Pushes the commit.
5. Delivers every profile.

When you edit an existing skill, the save asks you to describe the change, and the commit message becomes [skillcatalog] Update skill "<slug>": <your description>.

A save commits only the item you saved, so files you edited by hand in the clone stay uncommitted until you sync. The save tells you how many files are waiting:

Saved. Other changes in this catalog are still waiting for Sync: 1 file.

If one of the waiting files belongs to the item you are saving, the save stops and changes nothing, because it cannot publish your save without also publishing that hand edit. Sync first, then save again.

On a review-branch catalog, a save becomes a proposal instead of a commit on the catalog's branch.

Publish hand edits with skc sync

Dana adds a check to skills/review-security/SKILL.md in her clone. When she runs skc sync in a terminal without --message, it lists each catalog's changed files and asks for a commit message, one catalog at a time:

skc sync

Catalog Acme Skills (acme-skills) [direct]
  modified: skills/review-security/SKILL.md
Commit message for Acme Skills (acme-skills) (empty to abort): Read secrets from the vault
Synced 1 catalog (2 commits pulled, 1 commit pushed, 1 delivery).
...

• SkillCatalog committed the change as [skillcatalog] Read secrets from the vault.
• It pulled the two commits Sam had pushed, then pushed Dana's commit and delivered every profile.
• An empty message cancels the whole run, and nothing is synced.

--message gives every catalog that has changes the same message. A script, a CI job, or an AI agent's shell has no terminal to answer the question, so there skc sync refuses to commit anything until you pass --message.

skc sync commits the catalog's own files, such as catalog.yaml and the files under skills/, stacks/, and bundles/. Anything else you add to the repository, commit with Git.

Sync from the desktop app

In the desktop app, Dana syncs from the Sync Center. On its Review tab, she replaces the suggested Change summary, Updated 1 file, with a message her teammates can read, then chooses Sync.

The app also checks your catalogs when its window comes to the front, at most once a minute. When a catalog has new commits on the Git host and no local changes, the app pulls it and delivers. It never commits, merges, or pushes on its own, so your edits wait until you sync. To check at once, choose Refresh at the top of the window or press Cmd+R.

When a push is rejected or a pull conflicts

Sam and Dana changed the same line of the checklist, and Sam synced first. Dana's sync commits her change, then stops before it pushes, because Git cannot merge the two versions of the line:

skc sync --message "Tests must fail without the change"

Error: sync-all-failed
Every requested catalog-sync attempt failed.

Catalog results:
- Acme Skills (acme-skills): diverged (Conflicts detected: 1 file could not be merged automatically: skills/review-checklist/SKILL.md.)
Hint: Inspect the per-catalog results, repair the failing catalog state, then rerun `skc sync`.

Dana's commit stays in her clone, and nothing was pushed. She merges Sam's change with Git, in the clone:

cd ~/.skillcatalog/catalogs/acme-skills
git pull --no-rebase

Auto-merging skills/review-checklist/SKILL.md
CONFLICT (content): Merge conflict in skills/review-checklist/SKILL.md
Automatic merge failed; fix conflicts and then commit the result.

Git writes both versions of the line into the file, between <<<<<<< and >>>>>>> lines. Dana keeps the text she wants and deletes the three marker lines. SkillCatalog refuses to commit a SKILL.md that still has markers, but its check can miss some, so she searches the clone for leftover markers before she syncs. When the search prints nothing, the sync commits the merge and pushes it:

git grep -n '^<<<<<<<'
skc sync --message "Merge checklist changes"

In the desktop app, the Sync Center's Results tab lists the files that conflict. Merge them in a terminal as above, then sync again.

The Git host can also refuse a push, for example when main accepts changes only through pull requests. The sync then stops with the host's reason, and your commit stays in your clone:

Error: sync-all-failed
Every requested catalog-sync attempt failed.

Catalog results:
- Acme Skills (acme-skills): push failed (The Git host refused the push: Changes to main must go through a pull request. (pre-receive hook declined).)
...

In the desktop app, the Sync Center shows the host's reason under Show exact catalog and delivery records. When the host requires review, switch the catalog to review branches and sync again. That sync sends the refused commit to the host as a proposal.

Check pending changes

Before she syncs, Dana checks what her next sync would commit. skc catalog changes lists the changed files in each clone:

skc catalog changes

1 pending catalog change.
- Acme Skills (acme-skills): modified skills/review-security/SKILL.md

The command lists files, not commits, so a commit whose push failed does not appear. In the desktop app, the sync button's tooltip counts the same files, as in Open Sync Center: 1 file to sync.

Sync or update?

Sam can bring catalog changes to his tools with either skc sync or skc update. They differ in how much they touch:

skc deliver neither pulls, commits, nor pushes. It delivers every profile again from the clones you already have.