Guides

How to organize AI agent skills

AI agent skills help teams reuse proven workflows, get more reliable agent output, and spend less time learning every tool from scratch.

Updated May 29, 2026

AI agent skills are gaining traction because they make recurring work easier to repeat. They also help agents produce more predictable results and reduce the time it takes to work with a new tool or workflow. A good skill can turn product knowledge, team habits, or setup steps into something the agent can reuse.

The organization problem starts when skills are added independently. One teammate asks an agent to create a workflow skill. Another adds a similar skill in a different repo or local agent folder. Someone updates one copy and the others stay unchanged. Because most of this happens through agent interaction, the library can grow outside the team's view.

“Lately I’ve been working across several AI tools at once: Cursor, Codex, and Claude Code. A new pain appears fast: the same skill gets copied into different folders, and then I have to track which version lives where. At first it feels minor. Later the whole workflow is out of sync.”

A workable setup keeps the library readable and keeps three things clear: who owns a skill, where the canonical version lives, and which projects or agents should use it.

Start with one source of truth

Keep one canonical library of skills in Git. Edit that library directly. Treat every agent-specific folder as a view or distribution target.

This is the core idea behind tools such as dot-agents, one-skills-manager, and Skill Desktop. They all solve the same operational problem: one library, multiple agent directories.

If you maintain separate copies in ~/.claude/skills, ~/.codex/skills, ~/.cursor/skills, and repository-level folders, drift becomes the default. The same workflow slowly turns into several slightly different workflows. The agent still sees instructions, but the team loses track of which version is current.

A source-of-truth setup gives skills the same basic discipline as code. There is one place to review changes, one place to update shared behavior, and one place to check why a skill exists.

Separate personal, team, and project-local skills

Skill organization works best when scope is explicit.

“Does anyone have experience organizing skills for a team across different repos? Some people need .claude/, others need .cursor/, and others need .codex/. How do you keep order in that tool zoo?”

• Personal skills: research helpers, writing workflows, and utility skills you use in every project.
• Team skills: workflows your whole team shares, such as release notes, PR triage, or incident review.
• Project-local skills: instructions tied to one repository, one stack, or one product domain.

Claude Code already distinguishes between personal, project, and plugin skill locations in its skills documentation. GitHub Copilot also supports both project-level and personal skill directories in its agent skills docs. That scope model is worth adopting even if your tooling mix is broader than one product.

The practical reason is access control. A personal research skill can live on your machine. A team release-note skill belongs in a shared repo. A project-local deployment skill belongs close to the repo it depends on.

Use one portable skill format

The most practical source format today is the SKILL.md directory pattern. Claude Code documents it directly, and GitHub Copilot supports the same structure for project and personal skills.

Claude Code also notes that its skills follow the Agent Skills open standard, which makes it a sensible source format for cross-tool setups.

A basic skill can stay very small:

pr-review/
|-- SKILL.md
|-- checklist.md
`-- examples/
    `-- good-review.md

Use SKILL.md for the task definition, routing metadata, expected workflow, and important constraints. Put longer examples, checklists, scripts, and references into nearby files. This keeps the main skill readable and gives the agent more context only when it needs it.

Different tools may read directories in slightly different ways. One source format can still feed several agents with a light adapter layer.

Add ownership metadata

Every shared skill should have an owner.

At minimum, track:

owner: platform
scope: team
status: active
install_targets:
  - claude-code
  - copilot
  - codex
review_required: true
last_reviewed: 2026-05-29

This metadata can live in SKILL.md frontmatter, a registry file, or a small catalog page. The exact format matters less than the operating habit.

Ownership becomes important when a skill changes agent behavior, runs scripts, prepares release notes, reviews code, touches production workflows, or depends on internal product knowledge. Skills are part of the agent configuration surface, so they need the same basic hygiene as other shared operational assets.

Keep rules and memory separate from skills

Skills are one layer of agent configuration. Memory files and rules are another.

Claude Code uses CLAUDE.md and path-specific rules for persistent instructions. GitHub Copilot can place skills in .github/skills, .claude/skills, or .agents/skills. These layers should stay distinct.

A useful rule of thumb:

• Put reusable task workflows in skills.
• Put persistent project guidance in memory or rule files.
• Put machine-specific or private overrides in local config that stays local.

For example, a release-note workflow belongs in a skill. Repository architecture guidance belongs in project rules. Private API tokens, local paths, and machine-specific environment setup belong in local config.

This separation keeps your skill library smaller and easier to share.

Treat third-party skills like code

Skills can contain instructions, scripts, references, and tool usage patterns. That makes them useful, and it also makes review important.

Before installing a third-party skill, preview the contents. Check the SKILL.md, supporting files, scripts, and any requested tool behavior. For team-wide use, pin versions and record the source.

A safe install flow looks like this:

discover -> preview -> review -> pin -> install -> test -> share

This is especially important for skills that run shell commands, touch files, call external services, or process private data.

For production teams, third-party skills should go through a short review before they enter the shared library. The review can be lightweight, but it should exist.

Choose a sync pattern that matches your team

There are three practical ways to organize the distribution layer.

1. Git repo plus symlinks

This is the most direct setup. Keep a shared skill repo, then symlink the relevant directories into the places each agent expects. This is also the model highlighted by tools such as dot-agents and one-skills-manager.

It works especially well for solo developers and small teams that want transparent files and plain Git history.

Example:

agent-skills/
|-- shared/
|   |-- commit-message/
|   |-- pr-review/
|   `-- research/
|-- project/
|   |-- billing-service/
|   `-- website/
`-- README.md

Then link selected folders into agent directories such as:

~/.claude/skills/
~/.codex/skills/
~/.cursor/skills/
~/.copilot/skills/

2. Central library plus sync command

A sync tool gives you one managed home directory and pushes skills into the agent-specific directories when needed. The benefit is convenience: fewer manual links, cleaner setup on a new machine, and easier multi-tool support.

Examples include one-skills-manager, which stores skills once and recreates symlinks for Claude Code, Cursor, Windsurf, and Codex, and Skill Desktop, which presents the same idea as a cross-agent library.

This pattern is useful when you use several agents on the same machine and want a repeatable setup across laptops or team members.

3. Packaged distribution

Some teams need versioned distribution instead of direct filesystem sync. In that case, plugins or published repositories are a better fit than ad hoc copying.

Claude Code supports plugin-based skill packaging, and GitHub Copilot supports GitHub-hosted skill installation, including gh skill workflows.

Packaged distribution is especially useful when you want pinned versions, explicit updates, and clear ownership. It also helps larger teams separate draft skills from approved skills.

A practical folder layout

A simple layout is enough for most teams:

agent-skills/
|-- shared/
|   |-- commit-message/
|   |-- pr-review/
|   `-- research/
|-- project/
|   |-- billing-service/
|   `-- website/
|-- adapters/
|   |-- claude/
|   |-- copilot/
|   `-- codex/
|-- registry.yaml
`-- README.md

The important part is the contract:

• shared/ contains canonical reusable skills.
• project/ contains repository-specific skills.
• adapters/ contains the small amount of tool-specific glue.
• registry.yaml tracks scope, owner, status, and install targets.

Adapters can stay very small. They may contain symlink scripts, install commands, generated paths, or tool-specific transformations. The canonical skill still lives in one place.

Keep drift visible

Good organization is also about change control.

• Version your skill library in Git.
• Review shared skill changes like code changes.
• Add owners for team and project-local skills.
• Pin packaged skills when stability matters.
• Audit agent-specific directories regularly if local overrides are allowed.
• Add test prompts for critical skills.

A preview step before installation helps, and a source review helps even more. The same discipline should apply to every tool in the stack.

For important skills, add a small test fixture. A PR review skill can include a sample diff and expected review format. A release-note skill can include sample commits and expected output. A debugging skill can include common failure cases.

This turns skills from loose prompts into reusable operational assets.

Discover first, then organize

Organization works better when the library contains skills your team actually uses. The discovery layer matters too.

The Skillscout Chrome extension helps with that step by surfacing relevant skills while you browse tools, docs, and SaaS products. That makes it easier to decide which skills belong in your shared library and which ones should stay project-local.

Discovery is only the first step. The shared library still needs curation. A skill belongs in the shared library when it has repeat usage, a clear owner, stable behavior, and value for more than one person or project.