agentmods.dev

codex-cli-best-practice AGENTS.md

A repository guide for Codex CLI, an AI coding assistant, showing how configuration, agents, and reusable skills work together. It uses a weather-data example and serves as documentation rather than a normal application.

In plain words
What is it for?
Use it to understand AGENTS.md guidance, layered configuration, agent definitions, skill packages, and the main directories in a Codex CLI setup.
Why use it?
It gives coding agents consistent instructions about the repository’s structure, settings, and task-handling flow. This reduces guesswork when an agent reads or changes the project.

Instructions file for CodexOpenCode

978 2mo ago B scan 969 tokens original MIT
View the source file shanraisshan/codex-cli-best-practice
Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods
npx agentmods add instructions/shanraisshan/codex-cli-best-practice/agents-md
Clone the repo
git clone --depth 1 https://github.com/shanraisshan/codex-cli-best-practice

Made for: Codex, OpenCode.

Per session 969 This file is loaded in full into every session.
When invoked 969 The same file — it is already loaded in full.
Security scan B 1 finding. Scan, not verified.
Origin original No closer match found in the catalogue.
Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

ModelPer sessionOnce invoked
Fable 5 $0.00969 $0.00969
Opus 5 $0.00485 $0.00485
Sonnet 5 $0.00194 $0.00194
Haiku 4.5 $0.00097 $0.00097

Measured yesterday against content hash 2830ba313026, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade B, and why

codex-cli-best-practice AGENTS.md scanned grade B with 1 finding against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured yesterday.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Reads agent configuration directoriesmediumAgent snooping

.claude/, .codex/, .gemini/ hold keys, settings and other credentials a mod has no legitimate need for.

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 (`~/.c
Origin

Copies of this mod

1 near-identical copy found in the catalogue:

AGENTS.md · 71 lines

How it starts

The opening of the file, as written. The whole thing — 71 lines — stays where its author put it; the contents beside it link to each section on GitHub.

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

Read the full file on GitHub · 71 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

  1. yesterday First seen · 71 lines · 969 tokens per session scan B 2830ba313026

Subscribe to this mod's changes

codex-cli-best-practice AGENTS.md is an instructions file published in the GitHub repository shanraisshan/codex-cli-best-practice (978 stars, last pushed 2mo ago), licensed MIT. It adds 969 tokens to every session, about $0.0048 per session on Opus 5. A static security scan graded it B with 1 finding (reads agent configuration directories). No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.

PlanningProductivityWriting and docsagentic-aiagentic-codingagentic-engineeringagentic-workflowaiai-agents
Related

Other instructions, from other repositories

claude-code-best-practice CLAUDE.md

Claude Code instructions for shanraisshan/claude-code-best-practice, covering claude.md, repository overview, key components, weather system (example workflow) and skill definition structure.

shanraisshan/claude-code-best-practice · 1,830 tokens

claude-code-hooks CLAUDE.md

Instructions for shanraisshan/claude-code-hooks, covering claude code hooks, project structure, critical: hook count consistency, agent hooks and workflows.

shanraisshan/claude-code-hooks · 898 tokens

codex-cli-hooks CLAUDE.md

Claude Code instructions for shanraisshan/codex-cli-hooks, covering claude.md / agents.md, what this repo is, common commands, run a single test and manually invoke a hook (what codex does internally).

shanraisshan/codex-cli-hooks · 1,458 tokens

codex-cli-hooks AGENTS.md

AGENTS.md instructions for shanraisshan/codex-cli-hooks, a project described as: codex cli hooks - adding voice on each hook.

shanraisshan/codex-cli-hooks · 4 tokens

claude-code-tresor CLAUDE.md

Instructions for alirezarezvani/claude-code-tresor, covering claude.md - development guide, 🎯 repository purpose, 🏗️ architecture, 🛠️ common development commands and building & testing.

alirezarezvani/claude-code-tresor · 5,338 tokens

turbo-flow CLAUDE.md

Claude Code instructions for marcuspat/turbo-flow, covering claude.md — turbo flow, what this repo is, key files and conventions.

marcuspat/turbo-flow · 158 tokens