Codex Patterns for Building Agents and Tools

The best Codex workflow often begins as a good conversation and ends as repository infrastructure.

You solve one release-note task with a careful prompt. The next week, you repeat the same instructions. Then another engineer repeats them differently. Soon the team has five private versions of a workflow that should have become a shared asset.

The useful pattern is to promote repeated knowledge into the right layer.

Stage 1: package one task well

Start with a bounded task contract:

Goal:
Create draft release notes for version 2.8.

Context:
Merged pull requests since tag v2.7.0 and the existing release-note style.

Constraints:
Group by user impact. Exclude internal refactors unless they change behavior.
Do not publish or create a release.

Done when:
A reviewable Markdown draft links every included pull request.

Stop if:
The previous tag or target audience is ambiguous.

This is better than a long persona prompt because it exposes the engineering contract: scope, evidence, protected actions, and completion.

If the task is still changing every run, keep it here. Premature automation turns open questions into hidden assumptions.

Stage 2: move project truth into `AGENTS.md`

Stable repository facts should not be recopied into every prompt.

A useful AGENTS.md might include:

## Release notes

- Use npm commands from the repository root.
- The public changelog lives in `docs/releases/`.
- Group entries under Added, Changed, Fixed, and Security.
- Link the pull request and credit external contributors.
- Do not publish releases or modify Git tags.
- Verify with `npm run docs:check`.

OpenAI documents AGENTS.md as durable repository guidance, with more specific files applying closer to the work. Keep the file operational. Repository layout, commands, constraints, and verification belong there. Product history and vague principles usually do not.

Add a rule after repeated friction. A short file built from observed mistakes is more useful than a constitution written before the first run.

Stage 3: turn the method into a skill

Repository guidance explains how the project behaves. A skill explains how to perform a repeatable job.

The release-note skill may contain:

.agents/skills/release-notes/
  SKILL.md
  references/style-guide.md
  scripts/collect-merged-prs.mjs

SKILL.md should define when the skill applies, required inputs, the sequence, classification rules, failure handling, output format, and verification. The script should collect facts deterministically. The model should decide the parts that require language and judgment.

That division matters. Do not ask the model to remember which pull requests merged when Git can answer exactly.

Stage 4: add narrow tools for live systems

If the workflow needs external data or action, give it an intentional tool.

For release notes:

list_merged_pull_requests(repository, since_ref, until_ref)
get_pull_request(repository, number)
create_release_draft(repository, version, markdown)

The first two read evidence. The third creates a draft but cannot publish it. That tool boundary encodes the product’s approval model.

Whether the integration uses MCP or another interface, good tools have constrained inputs, typed outputs, source-system authorization, stable errors, idempotency where appropriate, and audit events. A tool named github_action(payload) with arbitrary JSON simply moves ambiguity into a more dangerous layer.

Stage 5: schedule only the stable loop

After the skill works reliably in ordinary chats, scheduling becomes useful.

A weekly task could collect changes, invoke the skill, run documentation checks, and place a draft in a review queue. It should define what counts as a new release window, where the artifact belongs, what to report when nothing changed, and which failure requires attention.

OpenAI’s current scheduled-task guidance recommends testing the prompt manually first. That is the right maturity gate. A schedule repeats a method; it does not improve one.

For Git repositories, use a worktree when the scheduled task may edit files and should remain isolated from unfinished local work. Use local execution only when direct changes to the current checkout are intentional.

Keep artifacts as the handoff surface

At every stage, judge the workflow by what it returns:

a Markdown draft
source pull requests
classification decisions
checks run
unresolved questions
next action

Artifacts can be reviewed, versioned, compared, and passed to another person or system. Conversational confidence cannot.

The same pattern works beyond release notes:

incident triage becomes a skill plus observability tools
dependency review becomes repository guidance plus a scheduled scan
document processing becomes a schema, extraction tool, and review queue
PR review becomes a rubric, diff tools, and an evidence packet

Use this promotion test

Move a workflow up the ladder only when the next layer solves a repeated problem:

one-off prompt
  → repeated repository context? add AGENTS.md
  → repeated method? build a skill
  → missing live capability? add a narrow tool
  → stable recurring work? schedule it

Do not build a plugin because a prompt worked once. Do not keep a twenty-step procedure in a prompt because it is familiar.

The mature Codex workflow is not the one with the most configuration. It is the one where each piece of knowledge has one durable home and every run returns evidence.