Agents and Skills for Codex
This guide describes how to configure Codex instructions, custom agents, and skills. These files help Codex follow shared repository practices and load specialized workflows when needed.
AGENTS.md
AGENTS.md is an instruction file that tells Codex how to work in a specific environment. It is important because it gives Codex durable guidance that does not need to be repeated in every prompt.
Use clear Markdown section names so Codex can quickly find the right rule. Keep each section short, specific, and actionable. Prefer commands that can be copied and run.
Recommended section names include:
## Working agreements## Repository overview## Project structure## Setup## Common commands## Coding standards## Testing and verification## Review guidelines## Security## Files to avoid## Domain terminology
Codex can load multiple AGENTS.md files. More specific files closer to the working directory take precedence over broader instructions.
Example AGENTS.md structure:
# AGENTS.md
## Working agreements
- Preserve existing architecture and naming conventions.
- Make the smallest correct change.
- Ask before adding new production dependencies.
## Repository overview
- This repository contains <brief description>.
- Main application code lives in `<path>`.
- Documentation lives in `<path>`.
## Project structure
- `<path>`: <purpose>
- `<path>`: <purpose>
- `<path>`: <purpose>
## Setup
- Install dependencies with `<command>`.
- Required environment variables are documented in `<path>`.
## Common commands
- Build: `<command>`
- Test: `<command>`
- Lint: `<command>`
- Format: `<command>`
## Coding standards
- Follow existing patterns in nearby files.
- Keep business logic close to where it is used.
- Do not introduce broad rewrites without explicit approval.
## Testing and verification
- Run `<command>` after changing application code.
- Run `<command>` after changing documentation or configuration.
- If a check cannot be run, explain why.
## Review guidelines
- Prioritize bugs, regressions, security issues, and missing tests.
- Include file and line references when reporting findings.
## Security
- Do not expose secrets, tokens, keys, or credentials.
- Do not commit `.env` files.
- Treat logs and generated files as potentially sensitive.
## Files to avoid
- Do not edit generated files under `<path>` unless explicitly requested.
- Do not modify vendored dependencies under `<path>`.
## Domain terminology
- `<term>` means `<definition>`.
- `<term>` means `<definition>`.
Global Level AGENTS.md
The global AGENTS.md file is stored in the Codex home folder:
$HOME\.codex\AGENTS.md
Use the global file for personal defaults that should apply across most repositories.
Recommended global section names include:
## Working agreements## Communication## Default commands## Testing expectations## Security## Git behavior
Good global guidance includes:
- Preferred communication style
- General engineering principles
- Default testing expectations
- Personal preferences for plans, summaries, and command approvals
- Security reminders that apply everywhere
Avoid putting project-specific commands or repository paths in the global file.
Project Level AGENTS.md
The project AGENTS.md file is stored in the repository, usually at the repo root:
<repo_root>\AGENTS.md
Project agent files can also exist in subfolders when a specific area needs different instructions:
<repo_root>\services\api\AGENTS.md
Use project agent files for guidance that should be shared by everyone working in that repository.
Recommended project section names include:
## Repository overview## Project structure## Setup## Common commands## Coding standards## Testing and verification## Review guidelines## Security## Deployment notes
Good project guidance includes:
- Project setup steps
- Required commands before commits or pull requests
- Framework and architecture conventions
- Dependency management rules
- Test data rules
- Deployment or environment notes
Custom Agents
Custom agents are different from AGENTS.md. An AGENTS.md file gives Codex standing instructions for a folder or repository. A custom agent defines a named specialist that Codex can spawn for a specific kind of work.
Project custom agents are stored under:
<repo_root>\.codex\agents\<agent-name>.toml
Global custom agents are stored under:
$HOME\.codex\agents\<agent-name>.toml
Codex custom agent files use TOML. They do not use the AGENTS.md format, and they do not use SKILL.md YAML frontmatter.
Required fields include:
name: Agent identifier used by Codex.description: Human-readable guidance for when this agent should be used.developer_instructions: Core behavior and operating rules for the agent.
Common optional fields include:
model: Override the model for this agent.sandbox_mode: Override sandbox behavior for this agent.nickname_candidates: Optional display names for spawned agents.
Example project custom agent:
name = "pulumi_azure"
description = "Use when writing or reviewing Pulumi Python for Azure, choosing azure-native resource types, converting Terraform to Pulumi, or planning pulumi import adoption."
developer_instructions = """
You are the workspace specialist for Azure infrastructure authored with Pulumi Python.
Focus on safe, incremental work in this repository, especially under `cnh-pulumi-infra/`.
## Repository Context
- Pulumi projects live under `cnh-pulumi-infra/`.
- Python version is `>=3.13`.
- Core dependencies include `pulumi`, `pulumi-azure-native`, and `pulumi-azuread`.
- Typical project commands use `pulumi preview -C <project> -s <stack>` and `pulumi up -C <project> -s <stack>`.
## Responsibilities
- Author and review Pulumi Python for Azure services.
- Prefer `pulumi_azure_native` unless a narrower exception is verified.
- Convert Terraform resources or modules into Pulumi Python components and stacks.
- Plan safe import and adoption of existing Azure resources.
- Keep configuration, secrets, naming, and tagging consistent.
## Operating Rules
1. Classify each request as greenfield authoring, Terraform conversion, import/adoption, or code review.
2. Gather only the minimum local context needed from the relevant project or Terraform folder.
3. Prefer the smallest change that achieves the objective.
4. Avoid broad repo-wide migrations in one pass unless the user explicitly asks for that scope.
5. Use `pulumi.Config` and `require_secret` for environment values and credentials.
6. Favor `ComponentResource` abstractions for repeated patterns.
7. Keep naming deterministic and apply consistent tags.
8. Before finishing, validate with the smallest appropriate check, usually `pulumi preview` for the targeted project, or provide a concrete validation plan if execution is not possible.
## Skill Routing
- Use `$pulumi-azure-authoring-workflow` for end-to-end Azure authoring workflow and validation.
- Use `$azure-native-mapping` when selecting Azure Native namespaces and resource types.
- Use `$terraform-converter` for HCL or module to Pulumi Python translation.
- Use `$import-adoption-playbook` for safe import and adoption of existing Azure resources.
- Use `$cli-conversion-helper` for converter or plugin command sequences.
- Use `$pulumi-python-azure-best-practices` for structure, stacks, config, naming, tagging, and maintainability guidance.
Prefer one primary skill per request. Combine skills only when needed.
## Output Format
Return:
1. Task classification
2. Planned or completed changes
3. Files and commands involved
4. Validation status
5. Risks or follow-up items
"""
The YAML-frontmatter style shown below is not the Codex custom agent format:
---
name: "Pulumi Azure"
description: "Use when writing Pulumi Python for Azure."
tools: [read, search, edit]
---
That style is used by some other agent systems. For Codex, use .toml files under .codex\agents\.
Skills
Skills are reusable Codex capabilities for repeatable workflows. A skill contains a required SKILL.md file with metadata and instructions, and may also include scripts, templates, references, or other assets.
Skills are useful because they let Codex load detailed workflow knowledge only when needed. This keeps normal conversations smaller while still making specialized processes available.
Use clear metadata and section names so Codex can decide when to load the skill and how to execute it.
Required SKILL.md metadata:
name: Short skill identifier.description: Clear trigger guidance. Include when to use the skill and when not to use it.
Recommended SKILL.md section names include:
## Purpose## When to use## When not to use## Inputs## Workflow## Verification## Output format## Constraints## References
Example SKILL.md structure:
---
name: release-notes
description: Use when asked to draft release notes from recent commits or pull request history. Do not use for code review or changelog file edits unless explicitly requested.
---
# Release Notes
## Purpose
Create concise release notes that summarize user-visible changes, fixes, and operational risks.
## When to use
- User asks for release notes.
- User asks for a summary of changes since a tag or release branch.
- User asks for customer-facing change descriptions.
## When not to use
- User asks for a code review.
- User asks for a commit message only.
- User asks to modify release automation.
## Inputs
- Target version or date range.
- Commit range, pull request list, or changelog source.
- Audience, such as internal team, customer, or support.
## Workflow
1. Identify the requested change range.
2. Group changes into features, fixes, and operational notes.
3. Remove internal implementation details unless they affect users.
4. Flag missing context or risky assumptions.
## Verification
- Confirm each note maps to a commit, pull request, or issue.
- Confirm no secrets, internal-only links, or unsupported claims are included.
## Output format
- Use Markdown.
- Include sections for `Features`, `Fixes`, and `Operational notes` when applicable.
- Keep bullets short and user-focused.
## Constraints
- Do not invent version numbers.
- Do not claim a fix shipped unless the change is in the requested range.
## References
- Use files in `references/` for product naming, release style, and examples.
Optional skill folder structure:
<skill-name>\
SKILL.md
scripts\
references\
assets\
Use scripts for executable helpers, references for supporting documentation, and assets for templates or other resources.
Skills can be installed by using the Codex skill installer when available. This is a Codex chat command, not a PowerShell command. Run it in the Codex chat pane:
$skill-installer <skill-name>
Skills can also be installed manually by placing a skill folder in a global or project skills directory. Restart Codex if a newly installed skill does not appear.
Global Skills
Global skills are stored under the Codex home folder:
$HOME\.codex\skills\<skill-name>\SKILL.md
Use global skills for workflows that apply across many repositories.
Good global skills include:
- Commit message generation
- Pull request review workflows
- General debugging workflows
- Common cloud or CLI procedures
- Personal productivity workflows
Avoid making a skill global if it contains repository-specific paths, internal project rules, or team-only assumptions.
Project Skills
Project skills are stored in the repository, commonly under:
<repo_root>\.codex\skills\<skill-name>\SKILL.md
Use project skills for workflows that should travel with the repository and be available to the team.
Good project skills include:
- Project release procedures
- Repository-specific test workflows
- Internal architecture review checklists
- Deployment steps for the application
- Domain-specific code generation guidance
Project skills are a good choice when the workflow depends on repository structure, local scripts, internal terminology, or team-specific standards.