Hooks, rules and customization

Customization has three layers: instructions explain how to work, controls constrain permitted behavior, and tools connect data and actions.

#AGENTS.md

Use project instructions for:

• Directory structure and important modules.
• Install, start, test and build commands.
• Code style and architecture constraints.
• PR and review standards.
• Protected areas and completion criteria.

Codex loads applicable user and project instructions along the directory path. More specific instructions refine broader guidance.

# Project instructions

## Commands
- npm run lint
- npm run typecheck
- npm run build

## Done when
- Relevant checks pass
- Diff is reviewed
- No unrelated refactor

Generate a draft:

/init

#Custom prompts

Reusable prompts suit fixed instructions such as release checks, PR descriptions or log analysis. When the workflow also requires reference files, scripts, templates or multiple steps, a skill is a better package.

#Memories

Do not store credentials, private customer data or temporary tokens in memory.

#Hooks

Hooks run at lifecycle events and can implement checks or notifications. They can be loaded from hooks.json or inline TOML.

[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = './.codex/hooks/pre_tool_use_policy.sh'
timeout = 30
statusMessage = "Checking Bash command"

If one layer defines both forms, Codex can load both and warn. Prefer one representation per layer.

#Rules

Rules suit predictable command-prefix policy outside the ordinary sandbox boundary:

prefix_rule(
    pattern = ["git", "push"],
    decision = "prompt",
    justification = "Pushing branches requires explicit review",
    match = ["git push origin feature"],
)

When several rules match, the more restrictive decision wins.

#Skills and plugins

Skills package repeatable workflows:

$skill-creator
/skills
$readme-skill

A plugin is a distribution package that can include skills, MCP configuration, assets, app mappings and a manifest. Stabilize a useful workflow before packaging it for a team.

#Import

/import migrates supported Claude Code setup, project information or recent chats. Review imported settings instead of accepting all historical configuration unchanged.

1. Import project instructions or command rules first.
2. Check conflicts with existing AGENTS.md.
3. Decide whether hooks, skills and prompts should migrate.
4. Inspect effective configuration with /debug-config afterward.

#Subagents

Custom agent definitions can live in:

Definitions include name, description and developer_instructions. Use focused roles for exploration, tests, review or migrations. Isolate concurrent edits with worktrees rather than assigning the same files to several agents.

#Adoption order

1. Write a short AGENTS.md.
2. Turn repeated instructions into prompts or skills.
3. Use rules for explicit command policies.
4. Use hooks for checks, audit and notifications.
5. Connect needed external tools with MCP.
6. Package stable reusable capabilities as plugins.

#Official references

• AGENTS.md
• Codex manual: hooks and rules
• Codex manual: skills and plugins