Syncing One Skill Across Multiple AI Agents with @heropy/symlink

Agent SkillsClaudeCodexCLINode.js

a month ago

An AI agent skill is a single folder that contains a SKILL.md file.
It is published as an open standard, so many tools use the same format, but the standard only covers the folder structure and the SKILL.md format.
Where to look for skills is up to each tool.

Tool	Project skill path
Claude Code	`.claude/skills/`
Codex	`.agents/skills/`
Gemini CLI	`.agents/skills/`, `.gemini/skills/`
Cursor	`.agents/skills/`, `.cursor/skills/`, `.claude/skills/`

.agents/skills/ is a shared path that doesn't belong to any specific tool, but Claude Code only checks .claude/skills/.
If you use Claude Code together with other AI agents like Codex or Cursor in one project, the same skill has to exist in both paths.

If you simply copy the folder, you end up with two or more copies of the same skill.
Once you edit one of them, the copies drift apart, and it becomes hard to tell or manage which one is the latest.
This is where a symbolic link helps: you keep the original in one place and have the other path point to it.

# What is a symbolic link

A symbolic link is a special file that stores the path of another file or folder.
When you open the link, it follows the stored path and opens the original, so programs treat the link and the original as the same folder without telling them apart.
On macOS and Linux, you create one with the ln -s command.

BASH

1
ln -s ../../.claude/skills/my-skill .agents/skills/my-skill

Make the .agents/skills/my-skill path point to the .claude/skills/my-skill folder

Now, if you edit .agents/skills/my-skill/SKILL.md, .claude/skills/my-skill/SKILL.md changes too.
Both paths point to the same file, so an edit on either side shows up on the other side right away.
Deleting the link leaves the original untouched, but deleting the original leaves the link as a broken link with nothing to point to.

However, linking skill folders by hand comes with a lot to check.

A relative path is resolved from where the link is created, not from where you run the command, so if you leave out ../../ in the command above, you get a broken link.
You have to run one command per skill, and repeat it every time you add a skill.
If some skills have their original in .claude/skills and others in .agents/skills, you also have to check the link direction for each skill.
On Windows, you use the mklink command, and creating a symbolic link requires Developer Mode or administrator privileges.

# Creating links the easy way

@heropy/symlink is a CLI tool that compares the entries in several folders and creates symbolic links on the side where they are missing.
You pass the folders to link as arguments, and you can run it with npx without installing anything.

It works on Node.js 20.19 or later.

BASH

L
L
L
L
L
L

1
2
3
4
5
6
npx @heropy/symlink .claude/skills .agents/skills
## link   .agents/skills/commit-push -> ../../.claude/skills/commit-push
## link   .agents/skills/writing-style -> ../../.claude/skills/writing-style
## link   .claude/skills/react-router -> ../../.agents/skills/react-router
##
## 3 linked

commit-push and writing-style have their originals in .claude/skills, so links were created in .agents/skills, and react-router is the other way around.
No matter what order you write the arguments in, the side that holds the actual folder becomes the original, and the relative path of each link is calculated from the link's location.
So you don't have to worry about which path you added a skill to or how to write the path.

When you add a new skill, run the same command again.
Entries that are already linked are reported as keep and left as they are, and only the new skill gets linked.

BASH

L
L
L
L
L
L
L

1
2
3
4
5
6
7
npx @heropy/symlink .claude/skills .agents/skills
## keep   .agents/skills/heropy-commit-push
## keep   .agents/skills/heropy-writing-style
## link   .agents/skills/lighthouse -> ../../.claude/skills/lighthouse
## keep   .claude/skills/react-router
##
## 1 linked, 3 already fine

Running it again after adding the lighthouse skill

Running it many times gives the same result, so it is safe to add to a postinstall script.
It never deletes an existing file or folder to make room, and for entries you need to decide on yourself, such as when an original with the same name exists on both sides, it skips them and prints the reason.
On Windows, it creates directory junctions, which need no special privileges, so you can use the same command on any operating system.

AI skills were just the reason I built this tool. Any folder that each tool expects at its own fixed path, such as shared settings, prompt collections, or static assets, can be linked the same way.
For options like --dry-run, --list, and --unlink, notes on Windows, the Node.js API, and more, see the GitHub repository.