Codex Subagents

Reusable Codex custom-agent templates, skill packages, and quality references for building focused multi-agent workflows.

This repository is a catalog, not an application. It provides copyable OpenAI/Codex agent TOML files, progressively disclosed skill packages, and shared quality references.

Current Inventory

• 154 OpenAI agent templates in AGENTS/openai/.
• 30 skill gateways in SKILLS/ covering 125 workflows.
• 30 skill-sidecar files at SKILLS/*/agents/openai.yaml.
• 248 selectively loaded workflow and artifact references under SKILLS/*/references/.

Text Composition and Editing

The catalog covers briefs and outlines, complete fiction/nonfiction/essay/poetry/drama/professional/scholarly drafts, structural and language revision, feedback, continuity, reader orientation, adaptation, translation, textual scholarship, proofing, format review, indexing, submission packages, and edition maintenance.

Start with $text-composition, $text-revision, $text-translation, $textual-scholarship, or $publishing-editorial and name the requested stage. Full drafting and applied editing return the actual text or files. The canonical registry maps stages, specialist ownership, and handoffs.

The verification record covers every affected asset and retains representative live inputs, outputs, failures, and corrective reruns.

Heritage and Fieldwork

Four specialist categories add archaeological fieldwork, language documentation, oral history, and heritage conservation for objects and sites. Their 21 agents prepare source-linked records, complete editorial artifacts, plans, and evidence-backed reviews across 21 workflows.

Start with $archaeological-fieldwork, $language-documentation, $oral-history, or $heritage-conservation and name the requested stage. The canonical registry distinguishes ownership from existing archives, media, research, and textual-scholarship roles.

The verification record documents complete asset review, structural checks, runtime discovery, and representative live scenarios.

Repository Layout

AGENTS/openai/                 Reusable OpenAI custom-agent TOML templates
SKILLS/<skill-name>/           Reusable Codex skill packages
SKILLS/<skill-name>/SKILL.md   Concise trigger, mode router, and shared boundaries
SKILLS/<skill-name>/agents/    Skill sidecar metadata
SKILLS/<skill-name>/references/workflows/ Mode-specific execution guidance
SKILLS/<skill-name>/references/artifacts/  Conditional checklists and templates
REFERENCES/                    Shared catalog references and quality rules
AGENTS.md                      Repository-wide asset placement and catalog rules

Use AGENTS.md as the source of truth for where new catalog assets belong.

Key References

• REFERENCES/software-development-crew.md: lifecycle map, routing rules, model coverage, intentional overlap, and implemented skill registry.
• REFERENCES/quality-rubric.md: readiness rubric for skills and agents.
• REFERENCES/subagent-toml.md: TOML format guidance for custom-agent files.
• REFERENCES/prompt-patterns.md: prompt patterns for delegating work to subagents.
• SKILLS/codex-subagent-designer/SKILL.md: workflow for designing or reviewing subagent systems.

Validation

Review every changed gateway mode against REFERENCES/quality-rubric.md; the weakest mode determines gateway readiness. Confirm that TOML and YAML parse, each $skill resolves, workflow and artifact links exist, no reference is orphaned, and no router eagerly loads sibling guidance. Run git diff --check before relying on the catalog.

The current model lineup is gpt-6-luna (14 templates), gpt-6.1-sol (116), and gpt-6-astra (24). See the model coverage registry for reasoning-effort counts and the 2026-10-03 migration mapping. Historical verification records retain the models actually used; they do not establish live behavior for this refreshed lineup.

Using Agent Templates

1. Pick the role from REFERENCES/software-development-crew.md.
2. Copy the matching file from AGENTS/openai/<agent-name>.toml into a project's .codex/agents/ directory.
3. Keep only the agents that are useful for that project; this catalog is not meant to be installed wholesale into every repo.
4. Review each copied agent's sandbox_mode, model, reasoning effort, and handoffs against the target project's risk profile.

Most agent files reference skills with $skill-name. If a copied agent depends on a skill, install or copy that skill too, or include the skill's workflow in the parent prompt.

Using Skill Packages

Each skill package lives under SKILLS/<skill-name>/ and normally includes:

SKILL.md
agents/openai.yaml
references/workflows/<mode>.md
references/artifacts/<focused-checklist-or-template>.md

Invoke the gateway and name the intended mode, for example $interface-design-review in accessibility-audit mode. The router chooses one primary workflow and loads additional modes or artifacts only when the request explicitly needs them.

When copying a skill outside this repo, preserve its workflow references, artifact references, and sidecar metadata. For SKILLS/codex-subagent-designer/, also preserve the top-level references linked by its mode workflows.

Preview a selective installation

Use Python 3.11 or later to plan an installation without changing any files:

python3 tools/plan_install.py \
  --agent code-reviewer --skill codex-subagent-designer \
  --project /path/to/project

python3 tools/plan_install.py \
  --agent technical-planner --personal --format json

Repeat --agent and --skill to select more assets. The planner includes agents' literal $skill-name dependencies and complete tracked skill packages, but does not select handoff agents. It reads current working-tree contents and reports the source commit and selected-file content changes. Untracked files and caches are excluded.

Project destinations use .codex/agents/ and .agents/skills/ beneath the supplied path. Personal destinations default to ~/.codex/agents/ and ~/.agents/skills/; override them with --agents-dir and --skills-dir. These overrides require --personal. Use --source-root to inspect another catalog checkout.

Shared references are planned under each consuming skill's references/catalog/, with link changes calculated in memory. Historical evidence links become absolute paths into the source checkout and are listed as dependencies; the planned installation therefore requires that checkout to remain available. Nothing is copied or rewritten.

Each file reports its inclusion reasons, source/proposed/destination SHA-256 hashes, link adaptations, and one status:

Status	Meaning
missing	No destination file exists.
current	Destination matches the proposed installed contents.
link-adaptation-needed	Destination matches raw source but needs the proposed link changes.
conflict	Destination differs from both raw and adapted source; the planner does not infer why.
blocked	A symlink, unreadable file, or path collision prevents comparison.

Exit codes are 0 for a complete plan without conflicts, 1 for destination conflicts/blockers, and 2 for invalid arguments or unresolved source dependencies. JSON reports use schema_version: 1, include structured errors and the exit code, and sort files deterministically. A report containing errors is incomplete and must not be treated as an installable manifest. Text errors go to stderr. Prior installation receipts are not consulted, and unrelated destination files are not inventoried or removed.

The planner uses only the Python standard library and Git. It never invokes Codex or performs an installation. Run its isolated tests with:

python3 -B -m unittest discover -s tests -v

Adding Or Changing Assets

Before adding a new skill or agent:

1. Read REFERENCES/quality-rubric.md.
2. Place the asset in the canonical directory defined in AGENTS.md.
3. Make the asset specific enough to change future agent behavior; do not add generic prompt advice.
4. Update REFERENCES/software-development-crew.md when the asset affects routing, lifecycle coverage, or implemented skill coverage.
5. Review every affected mode; do not infer gateway readiness from a sample.
6. Perform the validation checks above.

An asset is catalog-ready only when it has concrete domain checks, boundaries, validation guidance, handoffs, and an owner-facing output contract.

What This Repo Does Not Provide

• No packaged application or runtime service.
• No package-manager install workflow.
• No Docker or CI configuration.
• No guarantee that model names or runtime fields remain valid forever; check the target Codex/OpenAI environment before broad installation.

Maintenance Notes

The catalog is intentionally broad. Keep future changes narrow, scored against the rubric, and backed by validation evidence. If an asset only passes structurally, treat it as unfinished until the rubric says it is useful enough to reuse.