Codex Skills and Plugins Guide: Turn Team Workflows into Reusable Capabilities

The same code review checklist gets copied into five repositories. Every PR still needs the same manual reminders: “run the failing tests first”, “check the permission boundary”, “do not forget the changelog.” The problem is not that the prompt is too short. The process has not been productized.

Codex Skills and Plugins are the cleaner way to handle that repetition: move team workflows out of ad hoc prompts and an ever-growing AGENTS.md, then turn them into reusable capabilities. A Skill is the authoring format for a reusable workflow. A Plugin is an installable distribution unit. They sit beside project rules rather than replacing them: persistent rules stay in AGENTS.md; multi-step procedures, examples, scripts, and long references move into Skills; team distribution becomes a Plugin.

A decision table is enough to choose between a Skill, Plugin, MCP, AGENTS.md, or Subagent. From there, you can start with a minimal Skill tree, then decide how to split role-specific plugins, share them with a team, and audit the permission boundary.

1. Repeated Team Workflows: The Prompt Is Not the Problem

Code review, release checks, test procedures, and documentation updates usually have a fixed shape inside a team. You may already paste a prompt into every PR review: “check whether the changelog is missing, whether test coverage dropped, and whether API docs need an update.” The problems show up quickly:

• Maintenance is scattered: when the checklist changes, you have to update five projects’ .github/PULL_REQUEST_TEMPLATE.md files or separate prompt files.
• Execution quality varies: Codex has to understand the process from scratch every time and may miss critical steps such as “run the failing tests first.”
• Role boundaries blur: frontend, QA, security, and documentation checks get stacked into one prompt, so Codex has a harder time choosing the right standard.

Some teams put all of this into AGENTS.md, which creates another problem: the project rules file grows until persistent build commands, directory conventions, and temporary process instructions are mixed together. That goes beyond its job as a durable project-constraint file.

Codex gives you a clearer split: use AGENTS.md for persistent rules, Skills for reusable workflows, and Plugins for distribution. The important part is knowing what belongs in each layer.

2. A Decision Table for Skill, Plugin, MCP, and AGENTS.md

A Skill is an authoring format for reusable workflows, usually a SKILL.md file with optional scripts, references, and assets. A Plugin is an installable Codex distribution unit that can package Skills, app integrations, MCP servers, and assets. MCP is the protocol for connecting external tools and context, such as third-party docs, browser state, Figma, or GitHub. AGENTS.md is for persistent project constraints: build commands, directory conventions, and review expectations. A Subagent is a delegated role for noisy or specialized tasks.

When to choose each option

Content type	Best fit	Typical use	Avoid using it for
Build commands, test script paths, directory conventions	AGENTS.md	”Put all new components under src/components/”, “run tests with npm run test:unit”	Multi-step processes, examples, external tool calls
Multi-step workflows with examples, scripts, or references	Skill	10-step code review, 7-item release checklist, API docs generation flow	A single command or one-line rule
Team distribution and packaging app/MCP configuration	Plugin	A frontend role plugin with 4 review Skills and a Figma connector	A workflow that only lives in one repo and does not need sharing
External tool calls and third-party context	MCP	Fetch Figma specs, access GitHub issues through an API	Pure workflow definition without external data
Noisy or specialized task delegation	Subagent	Hand test diagnosis or log analysis to a dedicated agent	Simple processes the main conversation can handle

When to move something out of AGENTS.md into a Skill

These signals usually mean the process has outgrown a project rules file and should become a Skill:

• The same checklist appears in multiple PRs and is pasted manually each time.
• The process has several steps and needs examples, scripts, or external references.
• The process has a clear trigger, such as “before release” or “during pull request review”, rather than being a permanent constraint.
• Different roles have different standards, so they should not all sit in one file.
• The process needs versioning and change notes instead of being edited directly into project rules each time.

When to upgrade a Skill into a Plugin

A Skill is enough while it is being iterated in one repository or one person’s workflow. Move to a Plugin when you need:

• Cross-team sharing instead of a personal directory or single repo.
• Packaged app integrations such as Figma, GitHub, CI/CD tools, or MCP server configuration.
• Versioning, changelog, and upgrade mechanics instead of copied Skill folders.
• Distribution through the Codex App Plugin Directory to workspace members.
• A stable package rather than an experimental workflow that changes every day.

A practical order is: put repository conventions in AGENTS.md; install an existing Plugin if one fits; otherwise create a Skill; package it as a Plugin when team distribution matters; add MCP only when an external system is needed; use a Subagent when the task is noisy or specialized enough to delegate.

3. A Minimal Useful Skill: Start with Code Review

Minimal Skill tree

A Skill needs at least this:

.agents/skills/code-review/
├── SKILL.md
├── references/
│   └── security-checklist.md
└── scripts/
    └── run-failed-tests.sh

The directory name and the name field in SKILL.md frontmatter must match, using lowercase alphanumeric characters and hyphens.

SKILL.md example: code review Skill

---
name: code-review
description: Use for pull request reviews in frontend projects. Checks changelog, test coverage, security boundary, and API docs. Do not use for backend-only changes or infrastructure PRs.
---

# Code Review Checklist

## Before Starting
1. Run failed tests first: `npm run test:failed`
2. Check if PR has clear description and scope

## Review Steps
1. Changelog: Does `CHANGELOG.md` need update?
2. Test Coverage: Did coverage decrease? Check report in `coverage/`
3. Security: Review changes in `src/auth/`, `src/api/`, and `src/middleware/`
4. API Docs: If API changed, update `docs/api.md`

## Security Boundary Checks
See `references/security-checklist.md` for detailed items.

## Failed Test Runner
Use `scripts/run-failed-tests.sh` to rerun previously failed tests.

Trigger design for description: before and after

Codex uses the description to decide when a Skill should be invoked implicitly. A vague description can trigger too often or not at all:

Before, likely to misfire	After, more reliable
”Code review skill for frontend projects"	"Use for pull request reviews in frontend projects. Checks changelog, test coverage, security boundary, and API docs."
"Help review code"	"Use when reviewing PRs with frontend changes. Do not use for backend-only changes or infrastructure PRs."
"Review checklist"	"Trigger on: PR reviews, code audit requests. Exclude: backend changes, config-only updates.”

Write the description with clear “Use when…” and “Do not use when…” boundaries. Put trigger terms such as pull request, review, and frontend early, because long Skill descriptions may be truncated. If you only want explicit invocation, set allow_implicit_invocation: false.

Skill locations and scope

Location	Scope	Good for	Notes
.agents/skills/ at the repo root	Current repository	Team review, test, and release processes	Commit it to Git for team sharing
$HOME/.agents/skills/	Personal cross-project use	Personal style rules and common command habits	Not automatically synced to the repo
/etc/codex/skills/	Organization level	Organization-wide security or compliance review	Requires admin permission
System bundled	Built in	Skills such as $skill-creator and $skill-installer	Not editable

Skills with the same name are not merged. Priority is usually repo > user > admin > system, but treat the current official docs as the source of truth if that behavior changes.

Progressive disclosure design

Do not put everything into the top-level SKILL.md. Codex uses progressive disclosure in three layers:

1. Metadata: Codex initially sees only name, description, and the file path.
2. Instructions: the full SKILL.md is loaded only after the Skill is selected.
3. Resources: references/, scripts/, and assets/ are loaded only when they are needed.

As a design rule, keep the main SKILL.md under about 500 lines, move long references to separate files, keep deterministic checks such as test runners or coverage scripts under scripts/, put detailed checklists and background docs under references/, and store templates or example screenshots under assets/.

Explicit and implicit invocation

Explicit invocation uses $code-review or the /skills picker. Implicit invocation lets Codex decide from the description whether the Skill fits the current task. To disable implicit invocation, set allow_implicit_invocation: false in agents/openai.yaml.

Implicit invocation works well for high-frequency workflows with clear boundaries, such as a PR review Skill. Explicit invocation is safer for low-frequency work that needs judgment, such as a quarterly security audit. If a Skill includes external scripts or sensitive operations, prefer explicit invocation.

4. Plugin Packaging and Team Distribution: From Local Skill to Team Suite

Minimal Plugin structure

A Plugin is not just a renamed Skill folder. It is an installable package, and it needs at least a .codex-plugin/plugin.json manifest:

.agents/plugins/frontend-review/
├── .codex-plugin/
│   └── plugin.json
├── skills/
│   ├── code-review/
│   │   └── SKILL.md
│   ├── accessibility-check/
│   │   └── SKILL.md
│   └── performance-lint/
│       └── SKILL.md
├── assets/
│   └── templates/
└── README.md

Required plugin.json fields

{
  "name": "frontend-review",
  "version": "1.0.0",
  "description": "Frontend team code review and accessibility check skills",
  "skills": "./skills/",
  "assets": "./assets/",
  "author": "frontend-team",
  "repository": "https://github.com/org/frontend-review-plugin"
}

Optional fields include apps for app integrations such as .app.json for Figma, mcpServers for MCP server configuration such as .mcp.json, and policy for permission and data-sharing policy that remains subject to workspace admin policy.

Marketplace structure for team plugin directories

A Plugin marketplace is a JSON list that points to plugin locations:

.agents/plugins/marketplace.json

{
  "plugins": [
    {
      "source": "local",
      "path": "./frontend-review"
    },
    {
      "source": "github",
      "owner": "openai",
      "repo": "role-specific-plugins",
      "ref": "main",
      "path": "plugins/data-analytics"
    }
  ]
}

Use local for internal plugins that have not been published. Use github for public plugins or packages shared across teams.

Plugin distribution command checklist

CLI commands can change, so keep the official docs as the reference:

# Scaffold a new plugin
codex plugin create frontend-review

# Add a plugin to the marketplace
codex plugin marketplace add owner/repo --ref main --sparse

# List installed plugins
codex plugin marketplace list

# Upgrade a plugin
codex plugin marketplace upgrade frontend-review

# Remove a plugin
codex plugin marketplace remove frontend-review

In the Codex App, Plugin Directory can show Curated by OpenAI, Shared with you, and Created by you. A local plugin can be shared with workspace members or groups. Workspace admins can disable plugin sharing or set managed requirements.

Sharing to a workspace is not the same as public publishing. External app connections and MCP servers still need authorization, and approval settings still apply.

Team marketplace organization

Put a repository-level marketplace at $REPO_ROOT/.agents/plugins/marketplace.json for project-specific plugins. Put organization-level plugins under $HOME/.agents/plugins/marketplace.json or a GitHub organization repository. Keep versioning explicit in the plugin manifest, maintain a README changelog, and validate upgrades in a test environment. Sensitive plugins such as security or compliance checks belong in an organization-level marketplace so they are not installed casually.

Start with a local Skill, iterate until it is stable, and only then package it as a Plugin. Building the Plugin first usually makes the workflow harder to change.

5. Role-Specific Plugin Design: Frontend, QA, and Docs Roles

OpenAI’s role-specific-plugins repository provides templates for Sales, Data Analytics, Product Design, and Financial Markets. Development teams do not need to copy the sales or finance workflow, but the decomposition pattern is useful: start from one role, split it into 3 to 5 small Skills, then package them as a Plugin.

Decomposition frame: role → repeated deliverables → data/tool sources → small Skills → sharing model

Role	Repeated deliverables	Data/tool sources	Skills to split out	Possible apps/MCP	Acceptance check
Frontend engineer	Component review, performance check, accessibility validation	Figma design specs, existing Storybook components	component-audit, accessibility-check, performance-lint, design-system-sync	Figma connector, Storybook MCP	Every new component runs all 4 checks
QA engineer	Coverage report, E2E suite diagnosis, regression checklist	CI/CD test results, historical failures	test-coverage-check, e2e-suite-runner, flaky-test-diagnosis, regression-suite-builder	CI/CD tools such as GitHub Actions or Jenkins	Failing tests run first; coverage does not drop
Technical writer	API docs updates, changelog construction, migration guides	API schema, Git commit history	api-doc-generator, changelog-builder, readme-audit, migration-guide-writer	GitHub API, schema tools	Documentation updates when APIs change
Security engineer	Permission-boundary review, secret checks, dependency security scan	Dependency manifests, secret-storage configuration	auth-boundary-check, secrets-scan, dependency-security	Snyk, Dependabot MCP	Security checklist runs before every release

Example frontend role plugin split

frontend-engineer-plugin/
├── .codex-plugin/
│   └── plugin.json
├── skills/
│   ├── component-audit/
│   │   ├── SKILL.md
│   │   └── references/
│   │       └── component-template.md
│   ├── accessibility-check/
│   │   ├── SKILL.md
│   │   └── scripts/
│   │       └── axe-audit.sh
│   ├── performance-lint/
│   │   ├── SKILL.md
│   │   └── scripts/
│   │       └── lighthouse-check.sh
│   └── design-system-sync/
│       ├── SKILL.md
│       └── references/
│           └── design-tokens.md
├── assets/
│   └── templates/
│       └── component-template.tsx
└── README.md

component-audit checks whether a new component follows team conventions such as naming, directory placement, and props typing. accessibility-check runs an axe-core script. performance-lint checks Core Web Vitals or a Lighthouse threshold. design-system-sync compares the implementation with the Figma design system.

Example QA role plugin split

qa-engineer-plugin/
├── .codex-plugin/
│   └── plugin.json
├── skills/
│   ├── test-coverage-check/
│   │   ├── SKILL.md
│   │   └── scripts/
│   │       └── coverage-threshold-check.sh
│   ├── e2e-suite-runner/
│   │   └── SKILL.md
│   ├── flaky-test-diagnosis/
│   │   ├── SKILL.md
│   │   └── references/
│   │       └── flaky-test-log-analysis.md
│   └── regression-suite-builder/
│       └── SKILL.md
├── .mcp.json
└── README.md

test-coverage-check detects coverage drops and marks uncovered files. e2e-suite-runner runs E2E tests by priority. flaky-test-diagnosis analyzes historical failure logs to identify unstable tests. regression-suite-builder builds a regression checklist from the change surface.

Connector placeholder replacement checklist

Official templates may contain placeholder connector IDs in .app.json. Replace them before installation:

{
  "app_id": "figma-placeholder"
}

Check every placeholder ID in .app.json and replace it with a real app ID available in your workspace. Do not copy connector IDs from another workspace; they may be invalid or unauthorized in yours. Configure OAuth or bearer tokens in MCP server settings for your own environment, not from template examples. After replacement, validate the connector in a test workspace first.

The official role-specific-plugins README notes that these plugin templates are intended to be customized before use, and connector-backed plugins may contain app or connector IDs that need replacement.

6. Security and Maintenance: A Plugin Is Not a Permission Pass

Connector and MCP permission boundaries

Installing a Plugin does not bypass Codex approval settings. External apps and MCP servers still require authorization, and data sharing remains subject to their own policies. Replace placeholder IDs in .app.json, but do not copy connector IDs across workspaces. External apps such as Figma or GitHub require separate authorization; a Plugin packages configuration, not authorization itself. MCP servers can still be enabled, disabled, and governed by tool policy in config.toml. Approval mode still applies; if it is set to “suggest-only”, scripts inside a Plugin will not execute automatically.

Do not treat a Plugin as a permission pass. It packages workflow, configuration, and assets, but the permission boundary remains.

Script source review

The scripts/ directory inside a Skill or Plugin can contain executable files. Third-party Plugins and community marketplaces require review: inspect every executable under scripts, confirm the source is trustworthy, avoid running scripts from unverified repositories, test in a staging environment first, and pin versions with a tag or commit hash instead of always pulling from main.

The same principle that applies to malicious third-party Skills also applies to any executable script and third-party Plugin: review the source, minimize permissions, and validate in a test environment.

Versioning and changelog

Team collaboration needs version management. Put a clear version field in plugin.json, increment it on every update, and maintain a README changelog that records new, changed, and deprecated Skills. Before upgrading, test in a staging environment, run every Skill, confirm scripts still work, and verify connectors are still available. In marketplace entries, pin ref to a tag or commit instead of pulling the latest main every time.

Skill and Plugin count impact

The initial Skill list has a context budget. Official docs describe the initial skills list as taking roughly 2% of the context, or 8,000 characters when the context size is unknown.

In practice, an overly long Skill description may be truncated, so put the core trigger words first. Loading too many Skills can also make it harder for Codex to pick the right one. High-frequency Skills with clear boundaries fit well in a repo or user directory. Low-frequency Skills are better kept in a Plugin that you install only when needed, instead of keeping everything always loaded.

If Codex often triggers the wrong Skill or fails to trigger the right one, inspect the description first. Do not solve that problem by adding more Skills.

7. Comparison with Related Technologies

Comparison with Claude Code Skills

BetterLink has covered the Claude Code Skill mechanism before. The mental model is similar, but the products are different: both use the Agent Skills open format and a SKILL.md file; both use name, description, and optional scripts/, references/, and assets/; both rely on progressive disclosure from metadata to instructions to resources.

The differences matter. Codex uses .agents/skills/; Claude Code uses .claude/skills/. Codex invocation uses $skill-name or /skills; Claude Code uses the /skill command. Codex Plugin distribution has a marketplace, CLI commands, and workspace sharing; Claude Code does not currently have an official Plugin marketplace. Built-in tools also differ: Codex has $skill-creator, $skill-installer, and @plugin-creator, while Claude Code has its own commands.

If you have written Claude Code Skills before, you can reuse the mental model. Do not copy the path or invocation syntax blindly; follow each product’s official docs.

How MCP fits in

MCP, the Model Context Protocol, connects external tools and context. It does not replace Skills or Plugins. A Skill defines the workflow. MCP connects the outside tool, such as Figma, GitHub, or a CI/CD system. A Plugin can package MCP server configuration, but the MCP server remains governed by config.toml.

Example split: a frontend review Skill defines the process for checking whether a component matches the design system; a Figma MCP server provides access to the design file; a frontend Plugin packages the review Skill and Figma MCP configuration, while Figma OAuth still needs separate authorization.

This section only clarifies the boundary. A separate Codex MCP tools guide can go deeper into implementation.

Conclusion

Codex Skills and Plugins are useful because they move repeated team workflows out of copied prompts and an overloaded AGENTS.md into reusable capabilities. The rule of thumb is simple: use AGENTS.md for persistent rules, a Skill for multi-step workflows, a Plugin for packaging and distribution, and MCP for external systems. Write clear trigger conditions in the description, validate a local Skill first, then package it as a Plugin when distribution is real. Third-party Plugin scripts, connector IDs, and MCP configuration still need review.

Start with one minimal Skill. Turn your team’s code review or test process into SKILL.md, run it a few times, and check whether the trigger behavior is reliable. If your team has frontend, QA, security, or documentation roles, use the OpenAI role-specific-plugins pattern: split each role into 3 to 5 small Skills, then package the role as a Plugin.

Further reading on BetterLink:

• Complete Codex beginner guide
• AGENTS.md project rules
• Codex security boundaries and permission management
• Codex MCP tools in practice
• Claude Code Skill comparison
• MCP protocol basics