A Simple Way to Manage Agent Skills Across AI Tools

If you use more than one AI coding tool, you may have run into the same small annoyance I did. A skill you create for one tool can be just as useful in another, but each tool expects it in a different place. Copying a skill is easy enough. Keeping every copy updated is where it becomes repetitive.

I first learned about agent skills through Claude Code, where Anthropic helped popularize the concept. I started creating small, reusable instructions for recurring tasks such as code reviews, commit messages, and pull request descriptions.

I did not stay with one tool, though. When I hit my Claude Code usage limit, I sometimes switched to Cursor because it was cheaper for my workflow. These days, I pair Cursor with Codex, which I mainly use for code reviews and validating implementation plans.

Working across these tools made me realize that their skill systems are based on the same underlying concept. A code-review skill should follow the same process whether I open Claude Code, Cursor, Codex, or another compatible agent. I did not want to maintain separate copies of the same instructions just because I changed tools.

That led me to keep all my custom skills in one Git repository and point each compatible AI tool to the same collection. In this post, I’ll show how I use Git and symbolic links to manage those skills in one place while still making them available across Claude Code, Cursor, and Codex.

What Agent Skills Are

Agent Skills is an open standard for packaging instructions and resources that AI agents can discover and use when needed. Each skill is a folder with a required SKILL.md file containing metadata and instructions. It can also include scripts, reference files, templates, and other supporting resources.

In this post, an agent is an AI assistant such as Codex, Cursor, or Claude Code. Because these tools support the same underlying format, a well-structured skill can often move between them without changing its core instructions.

I think of a skill as a reusable playbook. My generate-commit-message skill explains how I want commit messages written. My review-code-changes skill provides a repeatable checklist for reviewing code. The skill does not retrain the AI. It gives the agent the right instructions when that task comes up.

When I Use Agent Skills

I create a skill when:

• Repeat the same task across different projects.
• Want the agent to follow a specific process or writing style.
• Need consistent results from more than one AI tool.
• Have useful commands, examples, or checks that I do not want to explain in every prompt.

For a one-off question, a normal prompt is usually enough. If an instruction should apply to every task in one project, I put it in the project’s main agent instructions instead. Skills work better for focused workflows that the agent only needs at the right time.

Why I Manage Them Manually

Some readers may already use a tool such as the skills CLI. It can install skills for different agents and use symbolic links to keep them connected to a canonical copy. For many workflows, that is enough.

This guide focuses on setting up the same underlying idea manually, without relying on a package or CLI. I wanted to understand where each tool looks for skills, keep the files in my own Git repository, and control the symbolic links myself. Once you understand that setup, you can decide whether to keep managing it directly or let a tool handle it for you.

One Folder as the Source of Truth

In my case, the full path is:

/Users/ricardoescaran/.agents/skills

Using ~ makes the same location easier to describe across machines:

~/.agents/
└── skills/
    ├── cherry-pick-to-develop/
    │   └── SKILL.md
    ├── generate-commit-message/
    │   └── SKILL.md
    ├── generate-pr-description/
    │   └── SKILL.md
    ├── review-code-changes/
    │   └── SKILL.md
    └── sanity-check-code-changes/
        └── SKILL.md

Keeping the Skills in Git

I clone the repository into my normal workspace instead of cloning it directly into the hidden ~/.agents path. My repository looks like this:

~/Documents/Workspace/Personal/my-agent/
└── .agents/
    └── skills/
        └── <skill-name>/
            └── SKILL.md

I cloned the repository into my workspace with:

git clone <skills-repository-url> \
  ~/Documents/Workspace/Personal/my-agent

I then link the repository’s .agents folder to my user folder:

ln -s \
  ~/Documents/Workspace/Personal/my-agent/.agents \
  ~/.agents

After that, ~/.agents points to the .agents folder in my repository:

~/.agents -> ~/Documents/Workspace/Personal/my-agent/.agents

Running ls -alh from my user folder confirms that .agents is a symbolic link to the .agents directory inside my project repository:

Following that link into ~/.agents/skills shows the custom skills from the repository:

The ~/.agents path must not already exist before creating the link. If I already have that folder, I move or back up its skills first.

After that, updating every compatible agent is a normal Git pull inside the repository:

git -C ~/Documents/Workspace/Personal/my-agent pull

There is no need to copy an updated SKILL.md into several locations.

Using the Same Skills in Different Agents

Codex

Codex reads my custom skills from the shared folder and lists them together with its built-in skills.

Cursor

Cursor discovers the same user-level skills. Its list can also contain Cursor-specific skills, but my custom workflows still come from the same source.

Claude Code

Claude Code reads user skills from ~/.claude/skills, so I point that path to the same shared folder:

mkdir -p ~/.claude
ln -s ~/.agents/skills ~/.claude/skills

This creates another link without copying the skills:

~/.claude/skills -> ~/.agents/skills -> project repository

After restarting Claude Code, the /skills command shows the same five custom skills:

If ~/.claude/skills already exists, I back it up before creating the link. I leave the rest of ~/.claude untouched because it contains Claude’s other settings and local data.

Support for skill locations can vary between AI tools. When a tool does not read ~/.agents/skills directly, I point its supported skills directory back to this folder with a symbolic link. I check the tool’s documentation first, because its expected path may be different.

Why This Works for Me

• One source of truth: I edit each skill once.
• Portable setup: Git keeps the skills available across machines.
• Consistent workflows: Code reviews, commits, and PR descriptions follow the same instructions in every compatible agent.
• No platform lock-in: My custom workflows are not tied to one AI harness.

Final Thoughts

AI coding tools will keep changing, but I want my workflows to remain portable. Git stores the real files, while the ~/.agents link gives compatible tools a common place to find them. I can switch tools without rebuilding the same set of skills each time.