Guide · Agent skill
How to use the Codex Debugging Guide agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The codex-debugging skill is a written checklist that tells an AI agent how to investigate bugs in the Codex command-line tool and its related app by reading the local Codex source code first. It is written for maintainers and contributors who have a local clone of the codex-rs repository. After this guide you will know what the skill does, how to install it, how to phrase requests so the agent uses it, and what it needs to run.
Codex Debugging Guidesteipete/agent-scripts · MIT Download the skill Quick start
- 1Download the ZIP. Download the codex-debugging ZIP from this page.
- 2Unzip into a skills folder. Unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder.
- 3Or upload in the Claude apps. In the Claude apps, go to Settings → Capabilities → Skills and upload the skill.
- 4Clone the Codex repository. Make sure a local clone of the Codex repository exists at ~/Projects/codex.
- 5Install ripgrep. Make sure rg (ripgrep) and standard Unix tools such as sed are available on your machine.
- 6Ask a specific debugging question. Name the Codex area, the symptom, and any symbol, setting or error text you have.
What is an agent skill, and what does this one make the agent do?
An agent skill is a folder containing a SKILL.md file with instructions that an AI agent loads when a task matches the skill's description. This skill, named codex-debugging, is one of those instructions files. Its description is: Codex debugging: codex-rs core/tui/exec/cli/app-server/config.
When it applies, the skill tells the agent to prefer local source over web or documentation searches. It asks the agent to identify which area the behaviour belongs to (CLI, TUI, app server, protocol, config, or exec/tooling), read the owning module and adjacent tests, check ~/.codex/config.toml only after it understands the source contract, and prefer small reproductions or focused tests over broad guesses.
Install the codex-debugging skill
Download the ZIP from this page, then use one of two methods. For a personal setup, unzip it into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder. Alternatively, in the Claude apps, open Settings, go to Capabilities, and upload the skill under Skills.
After installing, the folder should contain SKILL.md. The skill ships as this single file.
- Personal: ~/.claude/skills/
- Project only: .claude/skills/ inside your project
- Claude apps: Settings → Capabilities → Skills, then upload
Prepare the requirements before you ask
The skill assumes a local clone of the Codex repository at ~/Projects/codex. If your clone lives elsewhere, the skill's commands will not point to the right place, so either move the clone or tell the agent where it is. The skill also uses ripgrep (rg) and standard Unix tools such as sed to search and read files.
If your question involves config parsing, you also need access to a local ~/.codex/config.toml. The skill only reads it when config checks are needed.
- A local clone of the Codex repository at ~/Projects/codex
- ripgrep (rg) and standard Unix tools such as sed
- Access to ~/.codex/config.toml if config checks are needed
Trigger the skill with natural requests
The skill is meant to be used when you investigate Codex CLI or app behaviour, config parsing, tool behaviour, prompts, MCP or app wiring, or runtime bugs. Name the area and the symptom in plain language, and the agent can match the request to the skill. Mention Codex and the part of it that is affected.
The skill's first step reads codex-rs/AGENTS.md and then searches the relevant directories, so a request that names a symbol, setting, error message or feature gives the agent something concrete to search for.
- Why does the Codex TUI show a stale status after a tool call? Check the source first.
- Our config parser in codex-rs seems to ignore a key in ~/.codex/config.toml. Find where it is read.
- Trace how MCP server wiring reaches the app server, then propose a fix with a small repro.
cd ~/Projects/codex
sed -n '1,220p' codex-rs/AGENTS.md
rg "<symbol|setting|error|feature>" codex-rs/{core,tui,exec,cli,app-server,app-server-protocol,config}Read the workflow the agent follows
The skill sets a fixed order so the agent does not jump to conclusions. It first classifies the behaviour, then reads the owning module and its neighbouring tests, then checks local config, and finally tries a small reproduction or focused test. You can check the agent's work against these four steps.
- Identify whether the behaviour is CLI, TUI, app server, protocol, config, or exec/tooling.
- Read the owning module and adjacent tests before proposing changes.
- Check ~/.codex/config.toml only after understanding the source contract.
- Prefer small repros or focused tests over broad speculation.
Safety notes: scripts and network
This skill runs no scripts and uses no network access. Its work consists of reading files and running search commands in your local clone. The skill points to official OpenAI docs only as a fallback when the source is not enough, so expect the agent to use the web only in that case.
Because the agent reads ~/.codex/config.toml when config checks are needed, be aware that this file may contain settings you consider private.
- No scripts are run by the skill.
- No network use is declared by the skill.
- Official docs are a fallback only when source is insufficient.
Tips for getting good results
Give the agent a precise symbol, error string, or setting name to search for, since broad questions produce broad searches. If the skill's assumed path is wrong for your machine, say so in the request. For non-Codex questions, such as general OpenAI API help or non-code tasks, this skill is the wrong tool.
- Use exact error text or symbol names in your request.
- Mention the affected area (TUI, exec, config, app server) to narrow the search.
- For CLI browser automation, the skill points to $browser-use, and notes that the bundled Browser plugin is Codex app-only.
What people use it for
- Tracing where a config key is parsed in codex-rs/config before changing it.
- Finding which module (core, tui, exec, cli, app-server) owns a runtime behaviour.
- Reading nearby tests to understand expected tool-call behaviour before proposing a fix.
- Building a small reproduction of an MCP wiring bug inside a local Codex checkout.
Frequently asked questions
How do I install the codex-debugging skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. You can also upload it in the Claude apps under Settings → Capabilities → Skills.
What do I need to use the codex-debugging skill?
You need a local clone of the Codex repository at ~/Projects/codex, ripgrep (rg), and standard Unix tools such as sed. Access to ~/.codex/config.toml is needed only if config checks are required.
Is the codex-debugging skill free?
The skill is published under the MIT licence, as listed on this page. The source does not mention pricing, so check the licence and repository for the terms that apply.
Does the skill run scripts or use the network?
According to this listing, it runs no scripts and uses no network access. It reads and searches files in your local clone, and it only points to official docs as a fallback.
Can regular Codex users use this skill?
It is written for maintainers and contributors with a local codex-rs checkout, not for end users who want general help. If you only use Codex, this skill is probably not the right fit.
What are alternatives to this skill?
The source does not name alternatives. For general help with Codex use, or for OpenAI API questions, the skill itself points to official OpenAI documentation as a fallback.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Choose this skill if you maintain or contribute to the open-source Codex codebase and want an agent to work from local source, tests and small reproductions. Pick something else if you only use Codex, need general help, or have questions about the OpenAI API or non-code tasks.
Download the skill