AGENTS.md

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>):

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/)