DEV Community

Volodymyr Nehir
Volodymyr Nehir

Posted on

How to Build Custom Commands for Codex Using Agent Skills Standard

#ai #chatgpt #agents #tutorial

If you are using Codex (whether the CLI, IDE extension, or the standalone app), building custom commands relies on the open Agent Skills framework. This framework allows you to package instructions, resources, and optional scripts to extend Codex with highly specific capabilities.

In the Codex ecosystem, custom commands and skills are essentially the same thing. Here is the step-by-step process for building one.

1. Create the Directory Structure

A skill is defined by a dedicated folder. You have two options to create it:

  • The Easy Way: Use Codex's built-in creator by running $skill-creator in your prompt. It will interactively ask you what the skill does, when it should trigger, and generate the folder for you.
  • The Manual Way: If you prefer setting it up yourself, your directory can contain the following structure: 
my-skill/
├── SKILL.md             # Required: Contains metadata and AI instructions
├── scripts/             # Optional: Executable code (e.g., Node.js, bash)
├── references/          # Optional: Documentation context for the AI
├── assets/              # Optional: Templates and static resources
└── agents/openai.yaml   # Optional: Appearance and dependency configs
Enter fullscreen mode Exit fullscreen mode

2. Write the SKILL.md File

The SKILL.md file is the brain of your command. It requires metadata at the top (Name and Description) followed by instructions.

💡 Pro Tip: Understand "Progressive Disclosure"
Codex uses a technique called progressive disclosure. It reads only the descriptions of all available skills first to decide if a skill matches your current prompt. Write descriptions with clear boundaries and strict scopes so Codex knows exactly when to trigger it without wasting token context!

Here is how you structure it:

---
name: my-skill
description: "Strict scope description of what this command does."
---

# Instructions
When this command is invoked, follow these exact steps...
Enter fullscreen mode Exit fullscreen mode

3. Choose Where to Save the Command

Codex automatically detects skill changes based on where you save the folder. Choose the scope that fits your workflow:

  • Project/Repo Level: Save in $CWD/.agents/skills, $CWD/../.agents/skills, or $REPO_ROOT/.agents/skills. Perfect for repository-specific scripts (like a microservice deployer).
  • User Level (Global): Save in $HOME/.agents/skills. This makes the command available to you personally across any project you open.
  • Admin/System Level: Save in /etc/codex/skills. This makes the command available as a default tool to every user on that specific machine.

4. Configure Invocation Behavior (Optional)

By default, Codex can trigger your skill either explicitly (when you call its name) or implicitly (when your natural language prompt matches the description).

If you want this to act strictly as a manual command (preventing the AI from running it autonomously), create an agents/openai.yaml file inside your skill directory:

# agents/openai.yaml
allow_implicit_invocation: false
Enter fullscreen mode Exit fullscreen mode

5. Use Your Command

Once your files are saved, Codex detects them automatically (restart Codex if it doesn't). You can now trigger your workflow:

  • Explicitly (Manual): Run /skills to see your list, or type $ followed by your skill name (e.g., $my-skill) directly in your prompt.
  • Implicitly (Autonomous): If allow_implicit_invocation is true, simply type a prompt that matches your SKILL.md description, and Codex will seamlessly load the instructions and execute the task!

Top comments (0)