Menu
Explains how to use Unity to keep Agent Skills synchronized across coding agents.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Inspects the working tree, groups changes into atomic commits, stages explicit paths, generates conventional commit messages (succinct or detailed), and commits. In a populated chat, prefer staging only session-related files. Use when the user wants to commit, asks to commit, or needs a commit message.
Bumps package semver, commits release changes with conventional commits, tags the release, and publishes to npm. Use when cutting a release, running npm publish, bumping package.json version, or shipping a new npm package version.
Resolves Git merge conflicts safely by inspecting markers, choosing or combining changes, validating the result, and completing merge, rebase, or cherry-pick. Use when git reports conflicts, conflict markers appear in files, or the user asks to fix merge/rebase conflicts.
Based on SOC occupation classification
| name | unity-skill |
| description | Explains how to use Unity to keep Agent Skills synchronized across coding agents. |
Unity keeps Agent Skills in one source-of-truth directory and mirrors them into the skill folders used by coding agents such as Codex, Orion, Claude Code, Cursor, OpenCode, etc.
npm install -g @nicolasakf/unity
unity --help
One-off without a global install:
npx @nicolasakf/unity sync
Unity has two source directories:
| Scope | Source of truth |
|---|---|
| User | ~/.agents/skills |
| Project | <repo>/.agents/skills |
Unity uses these as the source of truth for the skills. You or your agent can edit the skills in the source directory or in the agent mirror directory. Unity will guarantee that all linked directories (targets) are kept in sync at each scope level.
Initialize user-level Unity:
unity init
init also creates a user-level unity-skill from this README and pushes it to enabled user targets, so coding agents can learn how Unity works.
On first init in an interactive terminal, Unity prompts for two things:
unity watch; press Enter on an empty line when you are finished, or press Escape to stop adding paths.Coding agents or scripts cannot use interactive prompts. Run init without prompts like this:
unity init --non-interactive [--targets codex,orion] [--projects /abs/path/to/repo]
If the targets and/or projects were not specified by the user in their prompt, ask them. At least one target must be enabled. Projects are optional.
Equivalent environment variables (UNITY_INIT_TARGETS, UNITY_INIT_PROJECTS; set UNITY_INIT_NON_INTERACTIVE=1 to force non-interactive even in a tty) are documented under configuration.
Import existing skills from an agent directory:
unity import --from claude --scope user
unity import --from .cursor/skills --scope project
Pull new skills from all enabled agent directories into Unity:
unity pull --scope all
Push Unity skills out to enabled agent directories:
unity push --scope all
unity sync is kept as an alias for the push direction.
Preview a push without writing target directories or state:
unity push --scope all --dry-run
Register projects for the global watcher:
unity projects add ~/path/to/repo
unity projects list
Run one global background watcher for user scope and all registered projects:
unity watch --pull
Unity keeps a single watcher registration at ~/.agents/watch.json. Starting unity watch again replaces any already-running Unity watcher, so changing flags is as simple as running the new command:
unity watch --scope project --pull
Check the registered watcher:
unity watch-status
For a one-off watcher in the current repository only:
unity watch --scope project --pull
Keep the watcher attached to the current terminal:
unity watch --pull --foreground
| Agent | User target | Project target |
|---|---|---|
| Codex | ~/.agents/skills | .agents/skills |
| Orion | ~/.agents/skills | .agents/skills |
| Claude Code | ~/.claude/skills | .claude/skills |
| Augment | ~/.augment/skills | .augment/skills |
| Cursor | ~/.cursor/skills | .cursor/skills |
| Devin | ~/.config/devin/skills | .devin/skills |
| Factory | ~/.factory/skills | .factory/skills |
| Goose | ~/.config/goose/skills | .goose/skills |
| OpenClaw | ~/.openclaw/skills | .agents/skills |
| OpenCode | ~/.config/opencode/skills | .opencode/skills |
| OpenHands | ~/.openhands/skills | .openhands/skills |
| Qwen Code | ~/.qwen/skills | .qwen/skills |
| Windsurf | ~/.codeium/windsurf/skills | .windsurf/skills |
Codex, Orion, and project OpenClaw use the Unity source directory directly: .agents/skills and ~/.agents/skills.
Unity mirrors by copying directories, not by creating symlinks.
Unity's push direction writes from .agents/skills into enabled agent targets. Codex, Orion, and project OpenClaw already read that source path, so Unity skips those targets as copy destinations. The pull direction imports new skills from targets into .agents/skills; it skips source skills that already exist unless you use the explicit import workflow to handle a specific target.
Unity tracks every file it writes in .agents/state.json or ~/.agents/state.json. On future syncs it only overwrites or removes files when the target still matches Unity's manifest.
If a target skill exists but Unity did not create it, sync skips it and reports a warning. Use --force to overwrite:
unity sync --force
When a source skill is removed, Unity removes the previously managed target copy. If that target copy was edited outside Unity, removal is skipped unless --force is used.
Unity also creates a per-scope lock file while mutating files so two unity sync or unity watch processes cannot update the same scope at the same time.
List targets:
unity targets list
Disable Claude sync without deleting mirrored files:
unity targets disable claude --scope all
Disable Claude sync and delete only Unity-managed Claude skills:
unity targets disable claude --scope all --prune
Add a custom target:
unity targets add my-agent \
--user-path ~/.my-agent/skills \
--project-path .my-agent/skills
unity watch defaults to a global watcher. It watches the user source plus every project registered in ~/.agents/config.json.
unity projects add .
unity projects remove .
unity projects list
unity watch --pull
The watcher also watches the user config file, so unity projects add <path> can add a project to an already-running global watcher.
Use --scope user, --scope project, or --scope all when you want an old-style scoped watcher for one shell session instead of the global registry.
unity status
unity status --verbose
unity doctor
unity doctor --fix
doctor validates source skills and prints the resolved paths for every configured target.
doctor --fix creates missing Unity source/config directories and enabled target directories.
Some existing agent skills have a folder name that does not match the name: field in SKILL.md. Unity keeps source validation strict, but import can repair copied skills without changing the original agent directory:
unity import --from cursor --scope user --fix-names
For a skill in ~/.cursor/skills/create-skill-local with name: create-skill, this imports the skill into ~/.agents/skills/create-skill-local and rewrites the copied SKILL.md to name: create-skill-local.
Preview imports first with:
unity import --from cursor --scope user --fix-names --dry-run