Skill Sync Plus

中文说明

Skill Sync Plus is a local-first manager, sync tool, and quality auditor for Codex skills. It helps you keep your installed or authored skills in your own Git repository, sync them across computers, manage them from a Web UI or CLI, and spot weak skill metadata before agents rely on it.

Codex / Agent skills are just local files — they don't sync across machines. Edit a skill on your work laptop, and it won't show up on your home machine. Modify both sides, and merging by hand risks overwriting the wrong version. Over time, skills also accumulate silently: you forget which ones you actually use, and have no real basis for deciding what to delete.

Skill Sync solves this by turning your own Git repository into the source of truth. You choose which skills to track; the tool syncs them across machines and surfaces version conflicts so you can compare and decide what to keep.

It also runs a lightweight local service that scans Codex session traces to record when each skill was last used by an agent — giving you real usage data to guide cleanup.

Everything is local-first: no hosted backend, no central server. Your skills only travel through your own Git remote.

Features

• Sync selected Codex and Agents skills across computers with your own Git repository.
• Web UI for choosing tracked skills, reviewing local/repo state, resolving conflicts, and applying remote updates.
• Auto-sync watcher that commits and pushes edits to tracked local skills.
• Last-used monitoring from local Codex session traces so stale skills are easier to find and delete.
• Codex Archive session management, including preview, Trash, restore, and unarchive.
• Skill audit CLI for checking metadata clarity, workflow structure, missing referenced files, and optimization opportunities.
• Local-first storage: no hosted service, no central backend, and machine-specific config/cache stay out of Git.

Future

• Claude-to-Claude skill sync.
• Claude and Codex skill sync/migration.
• Skill quality checks and optimization suggestions, such as description clarity, length, discoverability, and structure.

Usage

Prerequisites:

• Node.js >=20
• Git
• macOS for the native directory picker
• A local folder or Git clone to use as the sync repository

Web UI

Run without installing:

npx @nameczz/skill-sync serve

Or install the CLI globally:

npm install -g @nameczz/skill-sync
skill-sync serve

If skill-sync is not found after a global install, your npm global binary directory is not on PATH. Check the prefix:

npm config get prefix

Then add <prefix>/bin to your shell PATH. For example, if the prefix is ~/.npm-global:

echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Already-open terminals need source ~/.zshrc or a restart before they can see the new command.

Open http://127.0.0.1:3017.

On first launch:

1. Choose the Git sync repository directory.
2. Initialize the manager.
3. Add local-only skills to sync.
4. Let auto-sync watch managed skills, or use manual actions when you want explicit control.

The Web UI is the primary control surface for tracking skills, applying repo changes, and reviewing local state.

When local and repo versions diverge, open the compare dialog and choose which version to keep.

CLI

Use the CLI for headless or agent-driven workflows. skill-sync serve starts the local API server, Web UI, auto-sync watcher, and usage scanner.

Initialize once with an explicit sync repository path:

skill-sync init --sync-repo /path/to/skills-sync

Then keep the watcher running:

skill-sync serve

Common commands:

skill-sync status
skill-sync status --json
skill-sync audit
skill-sync audit ~/.codex/skills --min-score 60
skill-sync audit ~/.codex/skills --json
skill-sync pull
skill-sync sync <skill-id>
skill-sync update-local <skill-id>
skill-sync stop-syncing <skill-id>
skill-sync serve --port 4100

Agents can edit tracked skills under ~/.codex/skills or ~/.agents/skills. Skill Sync detects local changes, copies them into the sync repo, commits, and pushes.

If a conflict appears, do not overwrite silently. Resolve it through the Web UI or an explicit CLI/API action.

Skill Audit

Run a local quality scan before syncing or publishing a skill:

skill-sync audit ~/.codex/skills

The audit checks:

• required name and description frontmatter
• description length and discoverability
• clear Markdown title and workflow guidance
• thin or oversized SKILL.md files
• missing files referenced from scripts/, templates/, assets/, examples/, or references/
• whether the skill has reusable supporting material

Example output:

Skill audit: /Users/me/.codex/skills
Skills: 2 | Average score: 78 | Pass: 1 | Warn: 0 | Fail: 1

PASS research-pack - 100/100
  No issues found.

FAIL thin - 22/100
  [error] missing_frontmatter: SKILL.md is missing YAML frontmatter.
    Fix: Add a frontmatter block with name and description.

See the full demo report in docs/demo/skill-audit.md.

Run from Source

yarn install
npm run dev -- serve

Sync Model

The sync repository stores shared state:

skills/                 # tracked skill folders
metadata/skills.json    # tracked skill metadata
metadata/usage-events.jsonl
.gitignore

Your machine keeps local-only state outside Git:

~/.skill-sync/config.json
~/.skill-sync/cache/

At a high level:

flowchart LR
  Codex["~/.codex/skills"] --> Manager["Skill Sync"]
  Agents["~/.agents/skills"] --> Manager
  Manager --> Repo["Git sync repo"]
  Repo --> GitHub["Your Git remote"]
  Manager --> Archive["~/.codex/archived_sessions"]
  Manager --> Cache["Local config/cache"]

Loading

Typical Workflows

Add a local skill to sync

1. Open the Skills page.
2. Find a Local only skill.
3. Click Add to sync.
4. The app copies it into the sync repo, updates metadata, commits, and pushes.

Use another machine

1. Clone or choose the same sync repository.
2. Initialize Skill Sync with that repo path.
3. Click Pull.
4. Apply repo changes to install missing local copies.

Resolve a conflict

1. Open the compare dialog for the skill.
2. Review the repo, Codex, and Agents versions.
3. Accept the version you want to keep.
4. The app updates metadata, commits, and pushes the resolution.

Codex Archive

Codex App can archive sessions into ~/.codex/archived_sessions. Skill Sync exposes those sessions in the web UI so you can:

• Search archived sessions.
• Preview metadata without loading the full file by default.
• Move an archived session to Trash.
• Restore from Trash.
• Unarchive a session back into Codex sessions.

Documentation

Local docs site:

npm run docs:dev
npm run docs:build

Useful docs:

• Getting Started
• Sync Model
• API Reference

Development

Run checks:

npm run typecheck
npm test
npm run build

Run with isolated test paths:

SKILL_SYNC_REPO=/tmp/skill-sync-repo \
SKILL_SYNC_CODEX_SKILLS_DIR=/tmp/skill-sync-codex \
SKILL_SYNC_AGENTS_SKILLS_DIR=/tmp/skill-sync-agents \
SKILL_SYNC_CONFIG_DIR=/tmp/skill-sync-config \
SKILL_SYNC_CACHE_DIR=/tmp/skill-sync-cache \
npm run dev -- serve

Legacy CSM_* environment variables and ~/.codex-skill-manager config are still read for compatibility.

Publishing

The npm package is published by .github/workflows/publish-npm.yml using npm Trusted Publishing, so no long-lived npm publish token is needed after the package exists on npm.

1. Rename or create the GitHub repository that matches package.json's repository.url.
2. Publish @nameczz/skill-sync@0.1.0 once manually if the package does not exist yet:

   npm login
   npm publish --access=public

3. On npmjs.com, open the @nameczz/skill-sync package settings and add a Trusted Publisher:
   • Provider: GitHub Actions
   • Organization/user: nameczz
   • Repository: skill-sync
   • Workflow filename: publish-npm.yml
   • Allowed action: npm publish
4. Publish future versions with a GitHub Release, or run the Publish npm workflow manually with dry-run set to false.

You can also configure the trusted publisher from the CLI after the first publish:

npm trust github @nameczz/skill-sync --repo nameczz/skill-sync --file publish-npm.yml --allow-publish

The workflow installs dependencies, runs typecheck, tests, build, npm pack --dry-run, then publishes with OIDC-backed npm provenance.

Project Structure

skill-sync/
├── src/                # CLI, sync, git, archive, usage scanner, server
├── web/                # local management UI
├── tests/              # Vitest coverage
├── docs/               # docs and README screenshots
├── .github/            # CI workflows and GitHub metadata
└── README.md

Contributing

Issues and pull requests are welcome. No special template is required; a clear description, reproduction steps for bugs, and screenshots or logs when relevant are enough.

Before opening a PR, please run:

npm run typecheck
npm test
npm run build

See CONTRIBUTING.md, CODE_OF_CONDUCT.md, and SECURITY.md for project expectations.

License

MIT. See LICENSE.