Diagnose the availability of a Codex custom subagent TOMLavailability—whether it can be correctly loaded by Codex and run as expected. The companion agent creation/authoringuses agent-creator; this skill only performs read-only checks and does not rewrite the agent (fixes require user confirmation).
Contract
Single responsibility: scan one or more agent TOMLs and give each one a PASS / WARN / FAIL and reason.
Not allowed:
- Rewriting agent files without user confirmation.
- Installing, publishing agents, or modifying the global Codex configuration.
- Actually starting an MCP server process or calling its tools (only check whether the command exists).
Why it is needed
Codex agents are TOML. TOML has one fatal rule:Any [table] table header (such as [mcp_servers.x]、[[skills.config]]) swallows all bare keys after it. If mcp_servers is written before developer_instructions ,developer_instructions will be parsed as mcp_servers.x.developer_instructions, so this agent has no instructions—the file parses normally and does not error, but the agent is effectively mute. The primary task of this skill is to catch this kind of silent failure.
Check items
| # | Check | Level |
|---|---|---|
| 1 | Whether the TOML can be parsed | FAIL |
| 2 | Required top-level keys are complete:name / description / developer_instructions |
FAIL |
| 3 | field order: all [mcp_servers] / [[skills.config]] table blocks are after all top-level scalar keysafter |
FAIL |
| 4 | No unknown/unsupported top-level keys | WARN |
| 5 | sandbox_mode value is valid (read-only / workspace-write / danger-full-access） |
WARN |
| 6 | name matches the file name |
WARN |
| 7 | mcp_servers.*.command points to an executable file that exists in PATH/on disk |
WARN |
FAIL = the agent cannot reliably load or run;WARN = can load but has hidden issues;PASS = no findings.
Workflow
1. Determine the check targets
By default, scan .codex/agents/ and ~/.codex/agents/; you can also pass in a specific file or directory.
2. Run the checker
python3 skills/agent-doctor/assets/check_agents.py # 默认目录
python3 skills/agent-doctor/assets/check_agents.py .codex/agents/
python3 skills/agent-doctor/assets/check_agents.py path/to/one.toml
python3 skills/agent-doctor/assets/check_agents.py --json .codex/agents/ # 机器可读
Requires Python 3.11+ (uses the built-in tomllib). Exit code: returns 1 if there is any FAIL , otherwise 0.
3. Report and fix as needed
Report each agent's PASS / WARN / FAIL and reason. For FAIL：
- field order bug → suggest moving all
[mcp_servers.*]/[[skills.config]]blocks to the end of the fileend, placing them afterdeveloper_instructions. After fixing, apply the change via agent-creator or direct editing, and rerun the checker to confirm it turns intoPASS。 - missing required keys → fill them in; if they were swallowed due to an order bug, fix the order first.
- Confirm with the user before any rewriting (this skill is read-only by default).
Output Contract
- List of checked files.
- Each agent's status and specific findings (including line numbers, for easy locating).
- Summary: pass / warn / fail counts.
- Fix suggestions given, and whether they have been applied (if the user approves).
Red Flags
- The agent parses normally but is missing
developer_instructions→ it is almost certainly a field order bug; do not treat it as "forgot to write instructions". mcp_servers.*.commandis an absolute macOS path (such as/Applications/...) → it will fail after switching machines/platforms; markWARNand prompt.- The checker reports
FAILbut no actionable fix suggestions → report is unqualified.
Validation
# 自检：内置基线 agents 应全部 PASS
python3 skills/agent-doctor/assets/check_agents.py skills/built-in-agents/assets/
- Each target agent has a clear PASS/WARN/FAIL conclusion
- Each FAIL provides actionable fix suggestions (including line numbers or table names)
- Field order bugs can be reliably detected (including exclusion of false positives from documentation inside triple-quoted strings)
- No agent files were modified without user confirmation