Skills Sync

Skills are markdown files that agents auto-inject as context when their compatibility filters match. Codemux's skills sync mirrors them across every device you sign into. Skills are stored server-side — the same model your personal settings already use — so any signed-in account is sync-ready immediately, including GitHub OAuth (SSO) accounts that never set a password.

Skills are consumed through the default Agent Chat GUI. The Skills settings section is hidden if you switch to the classic terminal-first interface.

What Counts As A Skill

Codemux watches six user-level directories on every device:

• ~/.codemux/skills/ — Codemux-native skills
• ~/.claude/skills/ — Claude Code skills (also picked up natively by claude)
• ~/.codex/skills/ — Codex skills
• ~/.agents/skills/ — Codex's newer shared agent-skills root
• ~/.opencode/skills/ — OpenCode skills
• ~/.config/opencode/skills/ — OpenCode's XDG config root

Each skill is a folder with a SKILL.md (or skill.md) plus optional support files. The folder name is the skill ID; the SKILL.md frontmatter declares compatibility (which providers, which workspaces) and the body is the system-prompt fragment that gets injected.

Project-level skills are also discovered from .codemux/skills/, .claude/skills/, .codex/skills/, .agents/skills/, and .opencode/skills/ under the project root. They work in Agent Chat but stay local to that repository.

Setting Up Sync

There's nothing to set up. If you're signed in, sync is on — for both email/password and GitHub OAuth accounts. There's no sync password, no encryption key, and no per-device setup step.

Changed in a recent build: skills sync used to be end-to-end encrypted, which forced GitHub OAuth users to invent a separate "sync password" before they could sync at all. That requirement is gone — OAuth/SSO accounts now sync with no password prompt.

How It Works (User-Level)

• Storage: the skill name + content are stored server-side as plaintext columns, protected by encryption-at-rest at the database layer — the same posture as your synced settings. There's no client-held key.
• Account: a signed-in session (email/password or GitHub OAuth) is all that's needed. The Better Auth account stays cross-product compatible with Vexis at the login layer.
• Sync triggers:
  • File watcher pushes ~1.5s after you save a skill.
  • Periodic 5-minute pulse when the window is visible.
  • On any sign-in.
  • Manual "Sync now" button in Settings.
• Conflict resolution: last-write-wins by updated_at. If you edit the same skill on two devices simultaneously, the newer timestamp wins.
• Upgrading from the encrypted model: the first sync after upgrade quietly rewrites your previously-encrypted skills to plaintext in place — no duplicate rows, no data loss. Your local skill files stay the source of truth throughout.

The Sync Status Panel

Open Settings → Account → Sync to see:

• Sync ready — the status row (also reads Syncing… or Sync error), or a sign-in hint when you're signed out.
• Last sync — relative time ("3 minutes ago").
• Sync now — manual trigger.
• Export skills locally — write all current skills to a JSON file for backup.
• Import skills from backup — restore from an export.

There's no "Forgot password / reset sync" step anymore — there's no device key to lose.

What Doesn't Sync

• Project-scoped skills. They are discovered and usable today, but intentionally do not sync to other devices.
• Anything outside the recognized user and project roots. Aliased or symlinked roots are canonicalized so one skill is not listed twice.
• Skills you've explicitly disabled. The disable state is local-only.

Privacy

• On the server: skill names and contents are server-readable, protected by encryption-at-rest plus access control — not zero-knowledge. This matches the posture of essentially every settings/notes sync product. Don't paste secrets into skill files expecting a vault.
• In transit: HTTPS to api.codemux.org (override with CODEMUX_API_URL for self-hosting).
• On disk: plaintext in your skills directories (so the providers can read them).
• Cross-product compatibility: your Better Auth account roams across Codemux and Vexis. The shared codemux-api-* login-derivation protocol is pinned in CI for both clients.

Related

• Agent Chat — where skills are consumed at chat time
• Authentication — account setup and password derivation
• Settings — the Sync, Skills, and Account sections