AGENTS.md and Skills Mastery

Your Codex sessions keep going off track. The agent uses console.log instead of your structured logger. It writes tests with Jest when your project uses Vitest. It ignores your error handling patterns. Every prompt, you re-explain the same constraints. This is exactly the problem AGENTS.md and skills solve — but only when they are structured well. A poorly written AGENTS.md wastes context tokens on guidance the agent ignores, while a well-structured one makes every session start with the right constraints.

What You’ll Walk Away With

• An AGENTS.md hierarchy that scales from personal preferences to team-wide conventions
• The override pattern for temporary project phases
• Skills creation and organization patterns
• Context budget management so your guidance does not crowd out conversation space
• Debugging techniques for when instructions seem to be ignored

How AGENTS.md Discovery Works

Codex builds its instruction chain at session start by scanning files in this order:

1. Global scope: ~/.codex/AGENTS.override.md (if it exists), otherwise ~/.codex/AGENTS.md
2. Project scope: Starting at the project root (Git root), walking down to your current working directory. At each level, Codex checks AGENTS.override.md, then AGENTS.md, then fallback filenames
3. Merge order: Files are concatenated root-to-leaf. Later files override earlier ones because they appear last in the combined prompt

Codex includes at most one file per directory and stops when the combined size exceeds project_doc_max_bytes (32 KB by default).

The Three-Layer Pattern

Layer 1: Global Preferences

~/.codex/AGENTS.md

## Working Agreements
- Always run tests after modifying source files
- Prefer pnpm when installing dependencies
- Ask before adding new production dependencies
- Use TypeScript strict mode for all new files

Keep this under 20 lines. These are universal preferences that apply to every repository you work in.

Layer 2: Project Conventions

repo-root/AGENTS.md

## Repository Rules
- Use Vitest for all tests (not Jest)
- Follow error handling patterns in src/lib/errors.ts
- Run pnpm lint && pnpm test before committing
- New API endpoints need OpenAPI annotations
- Database changes need a migration file in migrations/

Keep this under 50 lines. Focus on project-specific conventions that differ from your global defaults.

Layer 3: Module-Specific Rules

services/payments/AGENTS.md

## Payments Service Rules
- Use the centralized error handler, never throw raw errors
- Rate limiting must be added to all public endpoints
- Authentication middleware is in src/middleware/auth.ts
- Test utilities are in tests/utils/api-helpers.ts
- Never rotate API keys without notifying the security channel

Keep this under 30 lines. Only include rules that apply specifically to this module.

Prompt: Generate AGENTS.md from your codebase

“Analyze this repository’s structure, coding patterns, and existing documentation. Generate an AGENTS.md that captures: the testing framework and how to run tests, the linting setup, error handling patterns, naming conventions, and any project-specific rules I should enforce. Keep it under 40 lines.”

The Override Pattern

Use AGENTS.override.md for temporary guidance that should not permanently live in your repo:

services/api/AGENTS.override.md

# TEMPORARY: Remove after the v3 migration is complete (target: March 2026)

- All new endpoints must use the v3 router in src/routes/v3/
- Do NOT modify any v1 or v2 routes
- Migration tracking doc: docs/v3-migration.md
- Use the new AuthContext from src/lib/auth-v3.ts for all new middleware

When the override file exists, Codex uses it instead of the regular AGENTS.md at that directory level. Delete the override to restore the permanent guidance.

This pattern is invaluable during:

• Large migrations where temporary rules apply
• Feature flag rollouts that change coding patterns
• Sprint-specific focus areas

Context Budget Management

Monitor Your Budget

Every token spent on AGENTS.md is a token unavailable for conversation. Check your allocation:

/status

This shows remaining context, loaded AGENTS.md files, and active MCP servers.

Reduce AGENTS.md Token Overhead

Technique	Impact
Remove redundant guidance (things the model already knows)	High
Split into nested files so only relevant layers load	Medium
Remove examples and keep only rules	Medium
Reduce fallback filenames to avoid loading extra files	Low

Disable Unused MCP Servers

Each MCP server adds tool schemas to context. Disable ones you are not using:

[mcp_servers.unused-server]
enabled = false

Increase the Byte Limit

If your guidance is genuinely needed and keeps getting truncated:

project_doc_max_bytes = 65536  # 64 KB (default: 32 KB)

But this is a last resort. Prefer splitting into nested files first.

Prompt: Audit your context budget

“Run /status and tell me: how much context window is remaining, what AGENTS.md files are loaded, and how many MCP servers are active. Suggest which MCP servers I should disable for the current task, and whether my AGENTS.md files could be more concise.”

Writing Effective Skills

Skill Structure

A skill is a directory with a SKILL.md file:

my-skill/
  SKILL.md          # Required: instructions + metadata
  scripts/          # Optional: executable code
  references/       # Optional: documentation
  assets/           # Optional: templates, resources
  agents/
    openai.yaml     # Optional: UI appearance, MCP dependencies

The SKILL.md Format

---
name: pr-ready
description: Prepare the current changes for a pull request by running
  all checks, fixing issues, and generating a PR description.
---

# PR Readiness Check

1. Run pnpm lint and fix any issues automatically
2. Run pnpm test and fix any failures
3. Run pnpm type-check and fix any type errors
4. Generate a PR description with:
   - Summary of changes (what and why)
   - Testing approach
   - Breaking changes (if any)
5. Report the results with a pass/fail summary

Skill Invocation

Skills can be triggered two ways:

• Explicit: Type $pr-ready or use /skills in the CLI/App
• Implicit: Codex matches your prompt to a skill’s description automatically

Write descriptions with clear scope boundaries so implicit matching works reliably.

Where to Save Skills

Scope	Location	Use Case
Repository	.agents/skills/ (any dir up to repo root)	Team-shared skills
User	~/.agents/skills/	Personal skills for all repos
Admin	/etc/codex/skills/	Organization-wide skills
System	Bundled with Codex	Built-in skills like $skill-creator

Create Skills Quickly

Use the built-in skill creator:

$skill-creator

Describe what the skill should do, and Codex generates the SKILL.md with proper metadata and instructions.

Install Community Skills

$skill-installer install the linear skill from the .experimental folder

Or install from the skills marketplace using the universal CLI:

npx skills add openai/skills

Enable/Disable Skills

~/.codex/config.toml

[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

Fallback Filenames

If your team already uses a different filename for project instructions:

~/.codex/config.toml

project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md", "CODEX.md"]

Codex checks each directory in this order: AGENTS.override.md, AGENTS.md, then each fallback name. This lets you adopt Codex without renaming existing documentation.

Debugging Guidance Issues

Verify What Loaded

codex --ask-for-approval never "Summarize the current instructions and list all instruction files you loaded."

Codex will echo back the guidance in precedence order.

Check for Override Files

An AGENTS.override.md higher in the directory tree can silently replace the regular AGENTS.md. Search for overrides:

find . -name "AGENTS.override.md" -type f

Verify Project Root Detection

Codex uses .git as the project root marker by default. If your workspace has an unusual structure:

project_root_markers = [".git", ".hg", ".sl"]

Or disable parent-directory scanning entirely:

project_root_markers = []

Prompt: Validate AGENTS.md setup

“Check my AGENTS.md configuration: list all AGENTS.md and AGENTS.override.md files in this repository, show their sizes, verify they are within the project_doc_max_bytes limit, and identify any redundant or contradictory instructions between layers.”

When This Breaks

• Agent ignores instructions: The guidance may have been compacted away in a long session. Repeat critical constraints in your current prompt, or start a fresh thread.
• AGENTS.md not loading: Verify the file is not empty. Check that project_doc_max_bytes has not been exceeded. Run the verification prompt above.
• Override file causes confusion: Search for AGENTS.override.md files you may have forgotten about. Delete temporary overrides when their purpose is complete.
• Skills not appearing: Skills must be in .agents/skills/ directories. Codex scans from the current directory up to the repository root. Restart Codex if a newly added skill does not appear.
• Cloud tasks ignore conventions: Cloud environments use the AGENTS.md committed to the repository, not your local files. Ensure critical guidance is committed.

What’s Next

• Advanced Techniques — Combine AGENTS.md with profiles and automations
• Team Collaboration — Scale AGENTS.md across your engineering team
• Setup and Configuration — Config settings that complement AGENTS.md