wikis / Codex / wiki / concepts / skills-plugins.md view as markdown

Skills & Plugins

Definition

Skills are the authoring format for reusable workflows: a directory with a SKILL.md (instructions + metadata) plus optional scripts, references, and assets, built on the open agent skills standard. Plugins are the installable distribution unit: they bundle one or more skills, app integrations, MCP servers, and lifecycle hooks into a package others can install. Design the workflow as a skill; package it as a plugin when you want to share it. Skills work in the CLI, IDE extension, and Codex app.

How It Works

Codex discovers skills by scanning .agents/skills folders across repo, user, admin, and system scopes, and holds only each skill's name, description, and path in context — the full SKILL.md loads on demand when a skill is invoked explicitly ($skill-name, /skills) or matched implicitly against the task description. Plugins wrap skills for distribution: a .codex-plugin/plugin.json manifest names the package and points to its skills plus optional MCP servers, apps, and lifecycle hooks; marketplaces (JSON catalogs read from the official directory, repo, and user locations) tell Codex where to fetch plugins, and installs land versioned under ~/.codex/plugins/cache/ with enabled state tracked in ~/.codex/config.toml. Plugin hooks stay untrusted until the user reviews and trusts them.

Key Parameters

• SKILL.md frontmatter — name, description (front-load trigger words; drives implicit matching).
• agents/openai.yaml — allow_implicit_invocation: false (default true), app UI metadata, tool dependencies.
• [[skills.config]] with path + enabled = false — disable a skill without deleting it.
• Skill scopes — $CWD/.agents/skills up to $REPO_ROOT/.agents/skills, $HOME/.agents/skills, /etc/codex/skills, bundled SYSTEM skills.
• .codex-plugin/plugin.json — name (kebab-case identifier and namespace), version, description, "skills": "./skills/"; optional mcpServers, apps, hooks pointers.
• [plugins."<name>@<marketplace>"] enabled = false — keep-but-disable an installed plugin.
• codex plugin marketplace add|list|upgrade|remove — marketplace management (--ref, --sparse).
• Marketplace entry fields — name, source (local path / url / git-subdir), policy.installation, policy.authentication, category.
• plugin_sharing = false in requirements.toml — admin kill switch for workspace sharing.

How skills work

Skills use progressive disclosure: Codex starts with only each skill's name, description, and path, and loads the full SKILL.md only when it decides to use the skill. The initial skills list is capped at roughly 2% of the model's context window (8,000 characters when unknown); with many skills installed, descriptions get shortened first, then skills get omitted with a warning. So front-load trigger words in description.

Two activation paths:

1. Explicit: run /skills or type $ to mention a skill (e.g. $skill-name); in the app, @ also reaches plugin skills.
2. Implicit: Codex matches your task against skill descriptions. Disable per-skill with allow_implicit_invocation: false in agents/openai.yaml (default true).

Create: use the built-in $skill-creator (asks what the skill does, when it triggers, instruction-only vs scripts — instruction-only is the default), or hand-write:

---
name: skill-name
description: Explain exactly when this skill should and should not trigger.
---

Skill instructions for Codex to follow.

Codex detects skill changes automatically; restart if an update doesn't appear.

Locations (Codex scans .agents/skills from CWD up to the repo root; symlinked folders are followed; same-name skills aren't merged — both appear):

Manage: install curated skills with $skill-installer (e.g. $skill-installer linear); disable without deleting via ~/.codex/config.toml (restart after):

[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

Optional agents/openai.yaml adds app UI metadata (display_name, icons, brand_color, default_prompt), invocation policy, and tool dependencies (e.g. an MCP server with transport: "streamable_http"). Best practices: one job per skill, prefer instructions over scripts unless you need determinism or external tooling, write imperative steps with explicit inputs/outputs. The open-source repo's docs/skills.md just points to the official docs page.

How plugins work

Browse and install via Plugins in the app (categories: Curated by OpenAI, Shared with you, Created by you) or /plugins in the CLI (grouped by marketplace; Space toggles an installed plugin). Examples: Codex Security (enterprise admin), Gmail, Google Drive, Slack, Sites. Installing doesn't change your approval settings (sandboxing approvals); bundled apps may prompt for ChatGPT sign-in, and external services keep their own privacy policies. Uninstall from the plugin browser (bundled apps stay until managed in ChatGPT), or keep-but-disable:

[plugins."gmail@openai-curated"]
enabled = false

Building plugins

Fastest path: the built-in @plugin-creator skill scaffolds the required .codex-plugin/plugin.json manifest and a local marketplace entry. Manual minimum: a folder with .codex-plugin/plugin.json (name in kebab-case — it's the identifier and component namespace — plus version, description, "skills": "./skills/") and a skill at skills/<skill-name>/SKILL.md. Only plugin.json belongs in .codex-plugin/; keep skills/, hooks/, assets/, .mcp.json, .app.json at the plugin root. Richer manifests add author, homepage, repository, license, keywords, component pointers (mcpServers, apps, hooks), and an interface block (displayName, descriptions, category, capabilities, legal URLs, defaultPrompt, brand assets). Manifest paths must start with ./ and stay inside the plugin root.

Marketplaces are JSON catalogs of plugins. Codex reads: the curated official directory, $REPO_ROOT/.agents/plugins/marketplace.json, a legacy-compatible $REPO_ROOT/.claude-plugin/marketplace.json, and ~/.agents/plugins/marketplace.json. Each entry needs name, source (local path relative to the marketplace root, "url" for a repo-root Git plugin, or "git-subdir" with url/path/ref), policy.installation (AVAILABLE, INSTALLED_BY_DEFAULT, NOT_AVAILABLE), policy.authentication (on install vs first use), and category. Unresolvable entries are skipped, not fatal. Installs land in ~/.codex/plugins/cache/$MARKETPLACE_NAME/$PLUGIN_NAME/$VERSION/ (local for local plugins); enabled state is stored in ~/.codex/config.toml.

CLI marketplace management:

codex plugin marketplace add owner/repo
codex plugin marketplace add owner/repo --ref main
codex plugin marketplace add https://github.com/example/plugins.git --sparse .agents/plugins
codex plugin marketplace add ./local-marketplace-root
codex plugin marketplace list
codex plugin marketplace upgrade
codex plugin marketplace remove marketplace-name

Bundled MCP servers (mcp integration): mcpServers points at .mcp.json (direct or wrapped mcp_servers map); users tune policy under plugins.<plugin>.mcp_servers.<server>. Lifecycle hooks: default file hooks/hooks.json (or manifest hooks entry: path, array, or inline). Hook commands get PLUGIN_ROOT and PLUGIN_DATA env vars (plus CLAUDE_PLUGIN_ROOT/CLAUDE_PLUGIN_DATA for compatibility). Plugin hooks are not trusted on install — Codex skips them until the user reviews and trusts the hook definition.

Workspace sharing: from the app, Created by you → Share invites workspace members/groups or copies a link; shared plugins stay inside the workspace boundary. Admins can disable sharing with plugin_sharing = false in requirements.toml. Publishing to the official Plugin Directory is "coming soon."

When To Use

Local skill folder: iterating on one repo or personal workflow. Plugin: cross-team distribution, bundling app/MCP config, lifecycle hooks, or a stable versioned package. Skills also power automations ($skill-name in automation prompts).

Risks & Pitfalls

• Oversized skill sets silently truncate descriptions and drop skills from the initial list.
• Same-name skills in different locations both appear — confusing in selectors.
• source.path is relative to the marketplace root, not .agents/plugins/ — the most common manual-marketplace mistake.
• After editing a local plugin, update the directory the marketplace points to and restart Codex.

Related Concepts

• mcp integration, automations, configuration, agents md, enterprise admin

Sources

Official docs (high confidence): agent skills, plugins, and build-plugins pages; open-source repo docs/skills.md (pointer only).