Contributing to my-codex

July 27, 2026 · View on GitHub

Thank you for contributing. This guide covers how to author agents for Codex CLI, meet quality standards, and submit pull requests.

Repository Structure

codex-agents/
  core/                   # Self-owned core agent — boss (always loaded)
  omo/                    # Self-owned OMO agents, 9 (always loaded)
  packs/                  # Vendored opt-in agent packs (data-ai 13, llmops 4)
upstream/                 # Git submodules (4 upstream sources)
  ecc/                    # everything-claude-code (skills)
  gstack/                 # gstack (sprint-process skills)
  omx/                    # oh-my-codex (worker agents, CLI runtime)
  superpowers/            # superpowers (skills)
  SOURCES.json            # AI-BOM — SHA pins, licenses, removed-source records
skills/
  core/                   # Self-owned skills (4)

This repository aggregates agents and skills from four upstream submodules, plus one vendored snapshot. Every skill and upstream agent that ships is named in scripts/skill-allowlists.sh — nothing is copied wholesale.

Source	Origin	Method	Format
`ecc`	everything-claude-code — 79 skills	submodule	MD
`gstack`	gstack — 27 sprint-process skills	submodule	MD
`omx`	oh-my-codex — 7 worker agents, CLI runtime	submodule	MD → TOML
`superpowers`	superpowers — 13 skills	submodule	MD
`codex-agents/packs`	awesome-codex-subagents — 17 opt-in agents	vendored (MIT)	TOML

The agency-agents and awesome-codex-subagents submodules were removed on 2026-07-27; upstream/SOURCES.json records both removals.

New contributions that originate from this repository go into codex-agents/core/ (infrastructure) or codex-agents/omo/ (OMO agents).

Authoring Agents

File Format

Agents are TOML files.

Required fields:

name = "my-agent-name"
description = "Use when a task needs X in order to Y."
developer_instructions = """
[Agent instructions here]
"""

Optional fields:

Field	Values	Notes
`model`	`"gpt-5.6"`, `"gpt-5.6-luna"`	Defaults to `gpt-5.6` if omitted
`model_reasoning_effort`	`"high"`, `"medium"`, `"low"`	Applies when model supports reasoning
`sandbox_mode`	`"read-only"`, `"workspace-write"`	Use `read-only` for reviewers; `workspace-write` for implementers
`nickname_candidates`	array of strings	Short invocation aliases

Model guidance:

Model	Use For
`gpt-5.6`	Standard development work, analysis, orchestration
`gpt-5.6-luna`	Fast lookups, lightweight agents, frequent invocation

Sandbox mode guidance:

read-only: Agents that analyze, review, or audit without modifying files
workspace-write: Agents that implement, generate, or modify files

File Location

Core/infrastructure agents: codex-agents/core/{name}.toml
OMO agents: codex-agents/omo/{name}.toml
File name must match the name field: security-reviewer.toml for name = "security-reviewer"

developer_instructions Structure

Instructions should be task-shaped, not persona-shaped. A well-structured developer_instructions block includes:

developer_instructions = """
[Brief role statement — what this agent owns and why it exists]

Working mode:
1. [First step]
2. [Second step]
3. ...

Focus on:
- [Key area]
- [Key area]

Quality checks:
- verify [criterion]
- confirm [criterion]

Return:
- [What the agent produces and in what format]
"""

Quality Bar

Descriptions must:

Start with "Use when..." followed by a concrete trigger condition
Name the specific task, not the general domain
Be one sentence

developer_instructions must:

Be task-shaped, not persona-shaped
State what the agent does, not just what role it plays
Include working mode steps, focus areas, and quality checks
Avoid phrases like "You are a helpful assistant who..."
Avoid assuming capabilities or tools not available in Codex CLI

High signal-to-noise: Remove any instruction that does not change behavior. If a line could be deleted without affecting output, delete it.

Naming Conventions

Agent names: kebab-case (security-reviewer, backend-architect)
File names: {name}.toml matching the name field exactly
Category directories: lowercase with hyphens (game-development, paid-media, data-ai)

Pull Request Process

One agent per PR is preferred. Multiple agents are acceptable when they form a cohesive domain pack.
PR body must include:
- The use case that motivated the contribution
- The agent name and target directory
- Confirmation that the name is unique across the repository
README updates: Add the agent to the relevant category table in README.md if applicable.
Verify TOML syntax before submitting. Run python3 -c "import tomllib; tomllib.load(open('yourfile.toml','rb'))" or any TOML validator to confirm the file parses without errors.

Commit Message Format

Follow conventional commits:

feat: add security-reviewer agent for pre-commit analysis
fix: correct sandbox_mode in backend-architect.toml
docs: update README table for engineering agents

Types: feat for new agents/skills, fix for corrections, docs for documentation updates, refactor for restructuring without behavior change.

If you work through an installed my-codex environment, Codex-authored commits may automatically include:

🤖 Generated with [Codex CLI](https://github.com/openai/codex)
AI-Contributed-By: Codex
optional Co-authored-by: Codex <...> if you configured my-codex.codexContributorEmail

This is expected.