Share Codex skills with your team: repo skills, review, versioning and plugins

Pick the sharing route

Route	Location	Reaches	Best for
Repository skills	<repo>/.agents/skills/	Everyone working in that repo, plus Codex cloud tasks	Codebase-specific workflows
Machine-wide skills	/etc/codex/skills/	Every user on a machine, container or CI image	Shared dev boxes, automation
Team skills repository	Cloned and symlinked into ~/.agents/skills/	Whoever sets it up	Small teams, personal workflows everyone wants
Plugin in a marketplace	Installed with /plugins or codex plugin add	Anyone who adds the marketplace	Many repositories, skills with MCP servers

Most teams use the first route for almost everything and add a plugin once a skill is wanted outside its original repository.

Repository skills

Commit skills next to the code they describe:

repo/
├── AGENTS.md
├── .agents/
│   └── skills/
│       ├── release/
│       │   ├── SKILL.md
│       │   └── scripts/bump_version.sh
│       └── db-migration/
│           ├── SKILL.md
│           └── references/locking.md
└── services/
    └── billing/
        └── .agents/
            └── skills/
                └── billing-webhooks/
                    └── SKILL.md

Codex scans .agents/skills from the working directory up to the repository root. Skills at the root are available everywhere in the repository; billing-webhooks is available only when someone starts Codex inside services/billing. That keeps a large monorepo’s catalog small for people who never touch billing.

Two properties make repository skills a good default. They are versioned with the code, so a skill that documents the deploy process changes in the same pull request as the deploy process. And they travel: repository skills are available in Codex cloud tasks, while personal skills from someone’s laptop are not synced to cloud environments.

The default sandbox also protects them. In workspace-write mode, a .agents directory inside a writable root is read-only, as are .git and .codex. Codex cannot quietly rewrite your team’s skills during a task; it has to ask.

Review skills like code

A skill changes how an agent behaves for everyone on the team, so treat edits to it as behavior changes.

Route reviews. Add an owner in CODEOWNERS:

/.agents/skills/            @your-org/dev-experience
/services/billing/.agents/  @your-org/billing

The codeowners-setup skill helps with routing and branch protection.

Review checklist for a skill PR:

1. Does the description say what the skill does and when to use it, with words people actually type?
2. Does it overlap an existing skill? If so, is there a “Not for …” boundary in both?
3. Are the commands real, and do they pass when run?
4. Does anything belong in AGENTS.md instead (rules for every task) or vice versa?
5. If there is a scripts/ folder: what does each script read, write and send over the network?
6. Should implicit invocation be off (allow_implicit_invocation: false) because the skill has side effects?

Validate in CI. A short check catches broken frontmatter before it reaches anyone:

#!/usr/bin/env bash
# scripts/check-skills.sh - fail if any skill's name does not match its folder
set -euo pipefail
status=0
for f in $(find . -path '*/.agents/skills/*/SKILL.md' -not -path './node_modules/*'); do
  dir=$(basename "$(dirname "$f")")
  head -1 "$f" | grep -qx -- '---' || { echo "$f: frontmatter must start on line 1"; status=1; }
  name=$(sed -n 's/^name:[[:space:]]*//p' "$f" | head -1 | tr -d "\"'")
  [ "$name" = "$dir" ] || { echo "$f: name '$name' does not match folder '$dir'"; status=1; }
  grep -q '^description:' "$f" || { echo "$f: missing description"; status=1; }
done
exit $status

The Agent Skills project’s reference validator, skills-ref validate <dir>, performs the full specification check if you want more than this.

Versioning

For repository skills, git history is the version. When a change matters to users of the skill, say so in the commit message and, for larger teams, in a short changelog section at the bottom of SKILL.md or in the PR description.

If you need an explicit version, the spec’s metadata field takes string values:

metadata:
  version: "2.1"
  owner: dev-experience

Plugins carry a real version in their manifest, and Git-backed marketplace entries can pin a ref or sha, so plugin users get a deliberate upgrade instead of whatever is on the default branch.

Machine-wide skills with /etc/codex/skills

Codex reads /etc/codex/skills as an admin scope available to every user on the machine. OpenAI suggests it for SDK scripts, automation and default admin skills. It fits shared development servers, devcontainers and CI images:

# Dockerfile for a CI image that runs codex exec
COPY ci-skills/ /etc/codex/skills/

Keep this set small and stable. It applies to everyone, and the people affected may not know where the skill came from.

A team skills repository

For skills that are about how people work rather than one codebase (commit style, review habits, incident notes), a shared repository works well:

git clone [email protected]:your-org/codex-skills.git ~/src/codex-skills
for d in ~/src/codex-skills/skills/*/; do
  ln -sfn "$d" ~/.agents/skills/"$(basename "$d")"
done

Codex follows the symlinks, and git pull updates everyone who set it up. If you install skills from this site for the whole team, pin the list in a script so new joiners get the same set:

curl -fsSL https://codexskills.dev/install.sh | sh -s -- systematic-debugging code-review git-commit-hygiene pull-request-writing

Plugins for many repositories

When the same skill is needed in twenty repositories, copying it into each is a maintenance problem. Package it as a plugin, list it in a marketplace (for example .agents/plugins/marketplace.json in a dedicated repository), and have people add that marketplace once:

codex plugin marketplace add your-org/codex-plugins

A repository can switch a marketplace plugin on for everyone working in it through its .codex/config.toml, which Codex loads for trusted projects:

[plugins."release-tools@your-org-plugins"]
enabled = true

In a ChatGPT workspace, admins can also publish a plugin to selected roles. Plugins work in Codex CLI and the ChatGPT desktop app, not in the IDE extension, so check where your team actually works before choosing this route.

Names, conflicts and opting out

Codex does not merge skills with the same name: a repository review skill and a personal review skill both show up. Prefix team skills when collisions are likely (acme-review), or keep names specific (api-review, ui-review).

Anyone can opt out of a shared skill on their machine without touching the repository:

# ~/.codex/config.toml
[[skills.config]]
path = "/Users/you/work/repo/.agents/skills/release/SKILL.md"
enabled = false

A rollout that works

1. Write a lean root AGENTS.md first; skills build on it. The agents-md-authoring skill helps.
2. Add two or three skills for the workflows people complain about most. Measure whether they trigger.
3. Add ownership, the CI check and the review checklist.
4. Package a plugin only when a second repository asks for the same skill.

The codex-team-rollout skill walks Codex through this plan for your organization, and the Codex Power User collection gathers the related configuration skills.