Custom agent requests are easy to misrout to skills instead of .codex/agents/*.toml custom agents

What version of the IDE extension are you using?

26.5417.40842

What subscription do you have?

pro

Which IDE are you using?

VS Code

What platform is your computer?

codespace

What issue are you seeing?

Codex supports true custom agents, but it is too easy for both users and Codex itself to confuse custom agents with skills.

Official Codex docs say custom agents are standalone TOML files under:

• ~/.codex/agents/ for personal agents
• .codex/agents/ for project-scoped agents

and each custom agent must define:

• name
• description
• developer_instructions

References:

• https://developers.openai.com/codex/subagents
• https://developers.openai.com/codex/config-reference
• https://developers.openai.com/codex/skills

However, when I asked Codex to create an agent, it steered the implementation toward the skills system instead:

• SKILL.md
• optional agents/openai.yaml
• references/scripts inside a skill bundle

That produced a skill, not a true custom agent.

This makes the product behavior and docs/discoverability confusing:

• “custom agent” and “skill” are different mechanisms
• but the skill path is much more visible/easy to fall into
• so even explicit requests for “an agent, not a skill” can still end up on the skill path

What steps can reproduce the bug?

1. Ask Codex something like:

Create a custom Kpler agent for me. I want an agent, not a skill.

1. Codex may choose the skill-authoring path first, such as:

• creating or modifying SKILL.md
• creating agents/openai.yaml
• building references/scripts as a skill bundle

1. The result is a skill-based artifact, not a true custom agent in:

• ~/.codex/agents/<name>.toml
• or .codex/agents/<name>.toml

1. Only after checking the official docs does it become clear that the correct mechanism for a real custom agent is the custom-agent TOML path documented under Subagents / Config.

Example of the kind of request that triggered the confusion:
I want an agent, not a skill.

What is the expected behavior?

If the user explicitly asks for a custom Codex agent, Codex should strongly prefer the true custom-agent mechanism:

• ~/.codex/agents/<name>.toml
• or .codex/agents/<name>.toml

and clearly distinguish that from:

• skills
• AGENTS.md
• agents/openai.yaml inside a skill bundle

At minimum, the docs/navigation and in-product guidance should make the distinction much more obvious.

Additional information

This looks like a docs/discoverability and product-guidance issue, not a model-quality issue.

The current official docs do describe custom agents, but they are documented under Subagents / Config, while skills are more discoverable and easier to author. That makes it easy to choose the wrong extension mechanism even when the user is explicit.

Concrete improvement ideas:

1. Add a dedicated top-level “Custom Agents” docs page
2. Add a comparison table for:

• Custom agents
• Skills
• AGENTS.md

1. Make Codex more likely to recommend .codex/agents/*.toml when the user explicitly says “agent, not skill”

Local Codex CLI version in my environment: codex-cli 0.121.0