From Prompts to Plugins

Claude Code and Codex are coding agents: they can inspect a repository, edit files, run commands, and use other tools to complete a task. They work out of the box, but they become much more useful when they do not have to rediscover how your project works or be coached through the same procedure every time.

Both agents provide three layers for making guidance reusable:

1. Put durable, always-on context in the repository instruction file.
2. Put repeatable, on-demand procedures in skills.
3. Package related skills, tools, hooks, and integrations as plugins.

The key is knowing which layer a piece of guidance belongs in.

Repeated prompting is a workflow trying to be born.

If you keep correcting an agent in the same way, pasting the same checklist, or asking it to run the same sequence of tools, the answer is probably not a better prompt. The answer is to promote that behavior into something reusable.

Claude Code and Codex use different filenames, invocation syntax, and plugin manifests, but the architecture is essentially the same. The concepts transfer cleanly. The packaging does not always transfer byte-for-byte.

The Reuse Ladder

The easiest way to decide where new agent behavior belongs is to ask how often it should apply and how much machinery it needs.

The critical distinction is scope:

• If the agent should know it every time, it is an instruction.
• If the agent should do it only for a particular kind of task, it is a skill.
• If a group of workflows needs installation, shared tooling, or governance, it is a plugin.

Most agent setups get bloated because they skip this question. Every useful thought gets dumped into the always-on file, which consumes context and makes the truly important rules harder to follow.

Level 1: CLAUDE.md and AGENTS.md

CLAUDE.md and AGENTS.md are repository memory. They give the agent the context it would otherwise waste time and tokens rediscovering:

• how to build and test the project
• architectural boundaries
• naming and formatting conventions
• files that should not be edited
• what evidence counts as “done”
• how you want changes reviewed and handed off

Claude Code loads project instructions from CLAUDE.md. Codex uses AGENTS.md. Both support layered instructions, so a repository can define broad rules at the root and narrower rules closer to a package or service.

Both tools also currently provide an /init command that can draft a starting instruction file from the repository. The generated file is a first pass. Review it, remove facts the agent can easily discover, and add the conventions it cannot infer from code alone.

The best instructions are concrete and testable. “Write good code” is decorative. “Run npm run lint, npm run type-check, and the relevant tests before declaring the change complete” changes behavior.

Here is the kind of instruction I want every coding session to inherit:

## Burden of proof

Assume the implementation may still be wrong until evidence proves otherwise.

Identify the strongest realistic failure mode, verify it with a command, test,
trace, screenshot, or direct inspection, and include that evidence in the final
handoff.

That belongs in CLAUDE.md or AGENTS.md because it is not a one-off procedure. It is a standing expectation for how work gets completed.

One Shared File for Claude Code and Codex

If your team uses both tools, keep AGENTS.md as the shared source and make CLAUDE.md import it:

@AGENTS.md

## Claude Code-specific notes

- Put any Claude-only guidance here.

Claude Code's documentation explicitly supports importing AGENTS.md this way. Codex reads the original AGENTS.md, so the shared rules only need to be maintained once.

Do not force every workflow into this file. When a section becomes a long sequence of steps rather than a durable fact, it is ready to move up the ladder.

Level 2: Skills

A skill is repeated prompting, on demand.

Both Claude Code and Codex use SKILL.md as the entry point for a reusable workflow. Both can select a skill when the request matches its description, and both let you invoke one explicitly. The main differences are discovery location and invocation syntax:

Claude Code skills and Codex skills both follow the Agent Skills format. That makes the core workflow highly portable even though each product discovers repository skills in a different directory.

Here is a minimal skill that works as a useful starting point in either system:

---
name: pr-review
description: Use when reviewing a pull request before merge. Identify realistic failure modes and return an evidence-backed review.
---

Assume the change may still be wrong until evidence proves otherwise.

1. Inspect the diff and the surrounding implementation.
2. Identify the three strongest realistic failure modes.
3. Verify each with a test, command, trace, screenshot, or direct inspection.
4. Separate confirmed defects from unverified risks.
5. Return findings first, followed by the verification receipt.

The Description Is the Interface

The description is not metadata you fill in at the end. It is how the agent decides whether the skill applies.

A useful description says:

• when to use the skill
• when not to use it, if the boundary is easy to confuse
• what input it expects
• what result it produces

“Helps with reviews” is too vague. “Use when reviewing a pull request before merge; identify realistic failure modes and return an evidence-backed review” gives the agent a real selection boundary.

The body should define the process, evidence, failure behavior, and output shape. Supporting templates, examples, references, and scripts can live beside SKILL.md and load only when the skill needs them.

That context behavior is the real advantage over stuffing everything into CLAUDE.md or AGENTS.md: the skill's full instructions are loaded for the relevant task, not every task.

When to Create a Skill

Create a skill when you notice one of these patterns:

• you paste the same prompt or checklist more than twice
• you repeatedly correct the same skipped step
• quality depends on a specific order of operations
• the agent needs a defined stop condition
• the output needs a stable format
• a workflow needs examples, templates, or helper scripts

Keep the first version small. A focused skill is easier to trigger, test, and improve than a giant “do engineering correctly” skill.

Level 3: Plugins

A skill becomes a plugin when the reusable practice needs packaging.

That usually happens when:

1. One workflow turns into a family of related workflows.
2. The workflows share scripts, templates, hooks, or policy.
3. They need MCP servers or connected services.
4. Other people need to install and update them as one unit.
5. A team needs versioning, approval, or a curated marketplace.

What a Plugin Looks Like

The reusable parts live at the plugin root. Only the manifest directory differs between Claude Code and Codex.

claude-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   ├── pr-review/
│   │   └── SKILL.md
│   └── release-notes/
│       └── SKILL.md
├── agents/
├── hooks/
├── scripts/
└── .mcp.json

codex-plugin/
├── .codex-plugin/
│   └── plugin.json
├── skills/
│   ├── pr-review/
│   │   └── SKILL.md
│   └── release-notes/
│       └── SKILL.md
├── hooks/
├── assets/
├── scripts/
├── .app.json
└── .mcp.json

Imagine a PR review skill. It starts as instructions for inspecting a diff. Then it grows:

• one skill reviews correctness
• another checks test coverage
• another looks for silent failures
• a hook runs deterministic validation
• a script gathers the diff and CI state
• an MCP server or CLI integration reads GitHub checks
• a command coordinates the whole review

At that point you are no longer sharing a prompt. You are distributing a toolkit.

Claude Code and Codex both call that installable unit a plugin, and both can bundle skills, hooks, and MCP-backed tools. Their plugin formats are not interchangeable:

• Claude Code uses the .claude-plugin/plugin.json format and can package skills, agents, hooks, MCP servers, LSP servers, monitors, and executables.
• Codex uses the .codex-plugin/plugin.json format and can package skills, hooks, MCP servers, apps/connectors, and presentation assets.

The clean portability boundary is the skill. Keep the reusable reasoning and workflow in SKILL.md; wrap it in a thin Claude or Codex plugin package when you need product-specific distribution or tools.

What Should I Build?

Use this decision test:

Put it in CLAUDE.md or AGENTS.md when…

• it should affect most work in the repository
• it is a fact, convention, command, or standing constraint
• forgetting it would make almost any task worse

Make it a skill when…

• it applies to one recognizable class of task
• it has multiple steps or a defined output
• it benefits from templates, examples, references, or scripts

Make it a plugin when…

• several skills belong together
• installation or updates need to be managed
• the workflow brings tools, hooks, MCP, connectors, or other dependencies
• you want to distribute a stable capability across a team

If you are unsure, start one level lower. Put the smallest useful rule in the instruction file or the smallest useful workflow in a skill. Let real repetition prove that you need more machinery.

Turn Corrections Into Infrastructure

The easiest way to improve an agent setup is to talk about it with the agent while the failure is still fresh.

At the end of a session, ask:

Which corrections from this work should persist? Sort them into always-on repository instructions, on-demand skills, and plugin ideas. Do not add anything that is already enforced by code, tests, linting, or CI.

Then review the result together:

• Promote durable facts into CLAUDE.md or AGENTS.md.
• Extract repeated procedures into focused skills.
• Package a plugin only when shared infrastructure or distribution justifies it.
• Turn mechanical requirements into deterministic tests, hooks, or CI instead of relying on prose.

That is the whole reuse ladder. You do not need a grand agent framework. You need a habit of noticing repetition and giving each kind of repetition the right home.