$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
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: "Strictscopedescriptionofwhatthiscommanddoes."
---
# Instructions
When this command is invoked, follow these exact steps...
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
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!