--- title: "Skills & Plugins" type: concept tags: [skills, plugins, marketplace, customization, distribution, hooks] created: 2026-06-10 updated: 2026-06-10 confidence: high sources: ["raw/llms_txt_doc-agent-skills.md", "raw/llms_txt_doc-plugins.md", "raw/llms_txt_doc-build-plugins.md", "raw/github_doc-docs-skills-md.md"] --- # 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](https://agentskills.io). **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."@"] 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: ```md --- 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): | Scope | Location | | --- | --- | | `REPO` | `$CWD/.agents/skills`, parent folders, and `$REPO_ROOT/.agents/skills` | | `USER` | `$HOME/.agents/skills` | | `ADMIN` | `/etc/codex/skills` | | `SYSTEM` | bundled with Codex (skill-creator, plan) | **Manage**: install curated skills with `$skill-installer` (e.g. `$skill-installer linear`); disable without deleting via `~/.codex/config.toml` (restart after): ```toml [[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 ([[concepts/enterprise-admin]]), Gmail, Google Drive, Slack, Sites. Installing doesn't change your approval settings ([[concepts/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: ```toml [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.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: ```bash 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** ([[concepts/mcp-integration]]): `mcpServers` points at `.mcp.json` (direct or wrapped `mcp_servers` map); users tune policy under `plugins..mcp_servers.`. **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 [[concepts/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 - [[concepts/mcp-integration]], [[concepts/automations]], [[concepts/configuration]], [[concepts/agents-md]], [[concepts/enterprise-admin]] ## Sources Official docs (high confidence): agent skills, plugins, and build-plugins pages; open-source repo `docs/skills.md` (pointer only).