AGENTS.md

April 19, 2026 · View on GitHub

This file provides guidance to Codex CLI when working with code in this repository.

What This Is

A best practices reference repository for Codex CLI (v0.121.0+) and Claude Code, demonstrating the Agent → Skill orchestration pattern through a weather data system example. This is a documentation and configuration reference, not a traditional application codebase.

Maintained by Shayan Raees (@shanraisshan). Companion repos: claude-code-best-practice, codex-cli-hooks, claude-code-hooks.

Architecture

The repo demonstrates four interconnected systems:

  1. Config (.codex/config.toml) — TOML-based layered config with 5 profiles (conservative, development, trusted, ci, review), MCP server registration, and agent definitions. Project-level overrides user-level (~/.codex/config.toml); CLI flags override both.

  2. Agents (.codex/agents/*.toml) — Registered under [agents.<name>] in config.toml with dedicated role files. The weather-agent fetches temperature from Open-Meteo API and delegates rendering to a skill.

  3. Skills (.agents/skills/<name>/SKILL.md) — Reusable instruction packages with YAML frontmatter (name, description). Discovered progressively from cwd up to /etc/codex/skills. Invoked via /skills, $skill-name, or auto-triggered by description match.

  4. Hooks — Event-driven Python scripts. Claude Code has 27 hooks (.claude/settings.json → .claude/hooks/scripts/hooks.py); Codex CLI has 5 (.codex/hooks.json). Hooks play audio feedback per event with cross-platform support (macOS/Linux/Windows).

Orchestration Flow

User Prompt → weather-agent (fetches temp from Open-Meteo)
                → /weather-svg-creator skill (renders SVG card)
                    → orchestration-workflow/weather.svg
                    → orchestration-workflow/output.md

Run it: codex then prompt "Fetch the current weather for Dubai in Celsius and create the SVG weather card output using the repo."

Key Directories

  • best-practice/ — 8 comprehensive guides: config, agents-md, skills, subagents, hooks, mcp, marketplace, memory
  • orchestration-workflow/ — Weather system example with flow diagram and generated outputs
  • docs/SKILLS.md — Skills system reference
  • examples/ — Profile configs and CI/CD integration examples
  • AGENTS.md — Project guidance loaded hierarchically by Codex (cwd to git root, capped at 32 KiB)

Configuration Quick Reference

Profiles (codex --profile <name>):

ProfileModelSandboxApproval
conservativeo4-miniread-onlyuntrusted
developmento4-miniworkspace-writeon-request
trustedo3workspace-writenever
cio4-miniread-onlynever
reviewo3read-onlyon-request

Git Commit Convention

One file, one commit — do NOT bundle multiple file changes into a single commit. Each file gets its own commit with a descriptive message specific to that file's changes.

For example, if README.md, best-practice/codex-agents-md.md, and a skill file all changed:

  • Commit 1: git add README.md → commit with README-specific message
  • Commit 2: git add best-practice/codex-agents-md.md → commit with agents-doc-specific message
  • Commit 3: git add .agents/skills/weather-svg-creator/SKILL.md → commit with skill-specific message

This keeps git history clean and makes it easy to review, revert, or cherry-pick individual changes.

Content Guidelines

When editing best-practice guides or documentation in this repo:

  • Keep AGENTS.md under 150 lines (32 KiB byte cap)
  • Skill descriptions should be triggers ("when should I fire?"), not summaries
  • Use profiles for safety switching; keep behavioral rules out of AGENTS.md when config.toml is deterministic
  • Skills should stay under 150 lines with progressive disclosure (core in SKILL.md, details in references/)