skmx

Keep one GitHub repository of agent skills and global instructions in sync across Linux and macOS devices.

skmx keeps a canonical checkout at ~/.skmx/repo and links each supported agent to it. An edit made through Claude, Codex, or an Agents-compatible tool therefore changes the same file. A background interval job commits those changes, integrates remote work with Git's three-way merge, and pushes the result.

Install and set up

Use it directly:

npx @hjgr/skmx setup

Or install the skmx command globally:

npm install -g @hjgr/skmx
skmx setup

Setup asks for a GitHub repository and a sync interval. It uses the git and gh already installed and authenticated on your machine; skmx has no OAuth flow and never stores a GitHub token. Run gh auth login first if needed.

Because interval jobs have no interactive terminal, the Git credential method chosen by gh must also work unattended—for example, an HTTPS credential helper or an SSH key that does not need a prompt.

For an unattended setup, give every answer as a flag:

skmx setup --repo your-name/agent-library --branch main --interval 15

The interval can be a whole number that divides evenly into 60, such as 5, 10, 15, 20, 30, or 60 minutes. This keeps Linux cron and macOS launchd behavior equivalent. V1 deliberately uses interval sync only—there is no file watcher or long-running daemon.

Repository layout

The source repository must contain at least one valid skill:

skills/
  writing/
    SKILL.md
    references/
AGENTS.md         # optional
CLAUDE.md         # optional

Each skill directory is linked into:

• ~/.claude/skills/<name>
• ~/.agents/skills/<name>
• ~/.codex/skills/<name>

Global files live at the repository root and are linked to their matching agent locations. AGENTS.md goes to ~/.agents/AGENTS.md and ~/.codex/AGENTS.md. CLAUDE.md goes to ~/.claude/CLAUDE.md; when it is absent, Claude shares the root AGENTS.md instead.

Setup inspects every destination before changing any of them. A missing path is safe, and identical content can be adopted. This includes existing symlinks from a previous checkout: setup resolves and fingerprints them, then atomically repoints identical links into its canonical checkout without deleting the previous source. Unrelated links are ignored. If any desired destination is broken or contains different content, setup stops, lists every collision, and leaves all targets untouched. Move or reconcile those paths yourself, then rerun setup.

Commands

skmx setup       # connect the repo, create links, and enable interval sync
skmx sync        # sync immediately
skmx logs        # show configuration and recent structured runs
skmx uninstall   # remove the interval job and links owned by skmx

uninstall always preserves ~/.skmx/repo, ~/.skmx/runs.jsonl, and the rest of the local state. It prints their paths so you can inspect or remove them deliberately.

What happens during sync

One lock protects the entire lifecycle:

1. Validate all managed skills and YAML frontmatter.
2. Commit changes under skills/ and to root AGENTS.md or CLAUDE.md in the app-owned checkout.
3. Fetch and merge the configured remote branch with normal Git three-way behavior.
4. Validate the merged tree, restore missing owned links, and push.

Non-overlapping changes from multiple devices converge automatically. If the same lines overlap, the merge is aborted so agents never see conflict markers, nothing is pushed from that device, and skmx logs gives the exact recovery command:

cd ~/.skmx/repo
git merge origin/main
# resolve the files, then:
git add -A && git commit
skmx sync

The previous prototype's union merge rule is removed. skmx never guesses how to combine contradictory prose or duplicate YAML keys.

Local state and scheduling

Configuration and logs live under ~/.skmx/:

~/.skmx/
  config.json
  repo/
  runs.jsonl
  scheduler.log

Linux uses the user's crontab. macOS uses ~/Library/LaunchAgents/com.skmx.sync.plist. Both invoke the same hidden coordinator used by skmx sync; scheduled runs do not depend on an interactive shell.

For isolated testing, SKMX_HOME moves the state directory and SKMX_AGENT_HOME moves the projected agent home. Setup records those values and the current Node path in the background job. Run skmx setup again after upgrading skmx or moving your Node installation so the registered job uses the new tool.

Development

Node 24 is required. Bun is not.

npm install
npm run check
npm run dev -- --help
npm pack

The integration tests use temporary local Git repositories and do not need network access or GitHub credentials.