Codex Essentials Plugin Pipeline
Keep each distributable plugin self-contained and keep the generated marketplace
catalog consistent with validated package manifests. This skill is repository
maintenance guidance; the skill itself under .agents/skills/ is not a plugin.
Use when
- Creating or changing
plugins/<plugin-id>/or any declared plugin component. - Editing a plugin manifest, skill, agent metadata, hook, app, MCP resource, README, changelog, or marketplace registration.
- Changing the schemas, templates, validators, generators, manifest guard, or release checks that enforce this contract.
Do not use for unrelated repository work or documentation-only changes with no plugin-contract impact. Applying this skill never authorizes a commit, tag, push, publication, PR, merge, or other remote mutation.
Current model
plugins/<plugin-id>/.codex-plugin/plugin.jsonis the authored source of truth for that plugin's identity, version, interface, and components.SKILL.md,agents/openai.yaml,README.md,CHANGELOG.md, hooks, apps, MCP files, and assets are package-owned and are validated, not regenerated..agents/plugins/marketplace.jsonis generated from validated manifests; do not edit it by hand.schemas/,templates/,scripts/, andlib/are repository tooling, not installed-plugin dependencies.
There is no current lib/source.json model. Do not restore it or prescribe the
historical scaffold:plugin, sync:*, or validate:all commands.
Workflow
- Read
AGENTS.mdandplugins/AGENTS.md; classify the change and inspect the complete affected package boundary. - For a new package, start
.codex-plugin/plugin.jsonfromtemplates/codex-plugin-plugin.json. For an existing package, edit its manifest and author-owned resources directly. - Keep every referenced file, executable, asset, symlink target, and runtime
path inside the owning plugin. Do not depend on
lib/, another plugin, or repository-only tooling at install time. - Follow the pipeline protocol for checks.
Any non-document change under
plugins/<plugin-id>/requires updating that package's README and CHANGELOG and runningnpm run documentation:gate -- --base <base> --head <head>. Usenpm run marketplace:buildafter manifest/catalog changes,npm run marketplace:checkfor a read-only consistency check, andnpm run validate:release-workflowafter changing Release Please component configuration or workflow output capture. - Use
npm run checkfor changes to repository tooling, schemas, templates, hooks, validators, generators, release behavior, or tests. - Before an authorized release, validate the normalized Release Please plan
with
npm run validate:release-set -- --plan <release-plan.json> [--archives]and review the exact tag, package boundary, archive, checksum, and changelog invariants.
Boundaries
- Never hand-edit generated marketplace output or commit credentials.
- Stage named paths only. Never stage, commit, tag, push, publish, create a PR, or merge without explicit authorization.
- Validation is evidence of repository state, not permission for remote action.