How to Share Agent Skills Across a Team

Published September 12, 2026 · by the AQ team

To share agent skills across a team, commit project skills into the repository (Claude Code reads .claude/skills, Codex and Cursor read .agents/skills), keep personal skills in a dotfiles repo synced to each machine, and add a distribution layer (a central skills repo with a bootstrap script, or a sync tool like skillshare) only when you have several tools or several machines to keep aligned. The repo path needs no extra tooling: a committed skill rides along with every clone, gets reviewed like code, and updates for everyone on the next pull. Everything else here handles the two cases git alone does not cover: skills that belong to a person rather than a project, and teams running more than one agent CLI against the same library.

What a skill actually is

A skill is a folder containing a SKILL.md file: YAML frontmatter with a name and a description, then a markdown body of instructions, optionally alongside scripts, reference documents, and templates. The agent reads only the name and description up front and loads the full instructions when a task matches, which is why skills scale where giant instruction files do not: fifty skills cost almost nothing in context until one is used.

The format started in the Claude ecosystem and has effectively become the cross-tool standard: as of September 2026 the same SKILL.md shape is documented by Claude Code, Codex, and Cursor, and picked up by a long tail of other agents. That convergence is what makes team-wide sharing tractable at all. The file format is portable; the discovery locations are not, and that gap is where every sync strategy below earns its keep.

Where each CLI looks, as of September 2026

Three details worth knowing beyond the table. Claude Code's discovery walks upward: it loads project skills from the start directory and every parent up to the repository root, and skills in subdirectories load once the agent works on files there, which is exactly what a monorepo wants. Codex ships system skills (a planning skill, a skill-creator) in a .system folder inside its home directory, and skills are invoked explicitly by mention or chosen automatically from their descriptions. Cursor supports the .agents/skills convention alongside its own .cursor/skills and now recommends skills over always-on rules, since a skill loads only when a task matches. The locations have already shifted this year, so re-check the vendor docs when a skill silently fails to load.

Pattern 1: commit project skills to the repository

If a skill encodes knowledge about a codebase (how to run the test suite, how deploys work, what a migration needs), it belongs in that repository. Committed skills get code review, blame, and history; a new teammate gets them with git clone; an update lands for everyone on the next pull; and the skill is versioned with the code it describes, so a checkout from March carries the instructions that were true in March.

The multi-tool tax is real but small at this layer. Claude Code wants .claude/skills, Codex and Cursor read .agents/skills. Teams handle it the same way they handle AGENTS.md and CLAUDE.md drift: pick one directory as canonical and make the other a symlink, or add a tiny CI check that fails when the two trees diverge. A relative symlink from .claude/skills to .agents/skills is committable and works on macOS and Linux; Windows checkouts need git's symlink support enabled, which is why some teams prefer the CI-check approach instead.

Pattern 2: a dotfiles repo for personal skills

Skills that describe how you personally work (your commit message conventions, your debugging ritual, your writing style) do not belong in any one repository. The established answer is the one that has managed shell configs for decades: a dotfiles repo, linked into place on each machine. Plain git plus symlinks works; chezmoi adds templating, encrypted secrets, and one-command bootstrap on a fresh machine, and it was among the most-named tools when Hacker News asked "How do you manage skills files?" in September 2026. The pattern from that thread: skills live in the dotfiles repo and get symlinked into ~/.claude/skills and the equivalents for other tools, so an edit in one place shows up everywhere.

# One personal skills library, linked into each tool's discovery path
mkdir -p ~/dotfiles/skills/commit-style
ln -s ~/dotfiles/skills ~/.claude/skills
ln -s ~/dotfiles/skills ~/.cursor/skills
ln -s ~/dotfiles/skills ~/.codex/skills

The limits are the usual dotfiles limits: it distributes your skills to your machines, and says nothing about your teammates.

Pattern 3: a central skills repo with a bootstrap script

For organization-wide skills that span many repositories (security review steps, incident runbooks, house API conventions), teams in that same Hacker News thread described a sturdier setup: one internal skills repository, a bootstrap script that copies or links company-managed skills into each developer's personal skills directory, and startup hooks in the agent CLIs that refresh them on launch. One commenter runs a scheduled agent job over the skills repo that checks whether skill content has drifted from the docs it summarizes and opens PRs when it has.

The strength here is an explicit contract: the skills repo is the source of truth, the bootstrap is the distribution mechanism, and updating a skill is a reviewed PR. The cost is owning a small piece of infrastructure, including the failure mode where half the team has not re-run the bootstrap in a month.

Pattern 4: a dedicated sync tool

The tooling gap between patterns 2 and 3 is being filled by purpose-built sync tools, the most visible being skillshare (open source, runkids/skillshare on GitHub). As of September 2026 it keeps one source-of-truth library in ~/.config/skillshare/skills and symlinks it into Claude Code, Codex, Cursor, and dozens of other tools (NTFS junctions on Windows, with a copy mode where links will not do). It installs skills from any git host, supports a per-repo .skillshare directory committed with the code, and ships an audit command that scans a skill before it reaches your agent. That last part matters: skills can carry executable scripts, and installing one from the internet runs someone else's code with your agent's permissions.

A sync tool is the right call when the matrix gets big: several CLIs, several machines, a team library plus personal libraries. It is one more moving part, so adopt it when symlinks stop scaling, not before.

Keeping shared skills trustworthy

Whatever the distribution mechanism, the teams that get lasting value out of shared skills treat them like code. Review changes in PRs, since a bad skill misleads every agent run that loads it. Assign an owner per skill, because unowned skills rot: the drift-checking agent job above is the automated version of an owner. Keep skills small and specific, so the description matches tasks precisely. And audit anything imported from outside before it lands in a discovery path, exactly as you would a dependency. The ecosystem is still moving fast (OpenAI's original public skills catalog for Codex was deprecated in favor of a plugins repository within months), so a quarterly pass to delete skills that no longer earn their descriptions is not bureaucracy, it is hygiene.

Where AQ fits

AQ is the multiplayer coding harness where engineering teams run AI coding agents like Claude Code and Codex together: shared live terminals, a code editor, and app previews, in your own cloud. AQ does not add another skills mechanism, and that is the point: agents on AQ are the real CLIs (Claude Code, Codex, Cursor Agent, Kimi, Grok, or plain shells) running in persistent tmux sessions on your team's VM, so they discover skills exactly the way this guide describes. Every workspace is an isolated git worktree of your repository with dependencies installed automatically, which means pattern 1 becomes self-enforcing: skills committed to the repo are present in every workspace, for every teammate, with no bootstrap script and no per-laptop drift, because the worktree is the distribution mechanism.

The team layer helps with the softer half of the problem: getting people to actually use the library. Teammates open the same workspace and watch the same live session, so when someone's agent picks up the deploy skill and runs it correctly, that is visible rather than folklore; sessions survive a closed laptop and resume from any device, so a long skill-driven run does not die with someone's Wi-Fi. Each engineer signs into the CLIs with their own Claude or OpenAI account (AQ never marks up model usage). The Free plan is a personal sandbox AQ creates for you with nothing to install; the Team plan is $50 per user per month early access (standard $200, billed monthly) on VMs you connect from your own cloud or a dedicated AQ-managed VM. If your skills strategy is "commit them and pull," AQ is the version where the pulling, the machines, and the sessions are already handled: see rolling out coding agents to your team and team workflows for coding agents for the wider playbook.