If you are using the Codex CLI and find yourself writing the same instructions over and over again, you are not using the tool to its full potential. Codex offers a powerful feature called Skills that allows you to package reusable workflows and give your AI agent new capabilities on demand. If you want to know more about it, then read this article until the end.
What Are Codex Skills?
A Codex Skill is a reusable workflow packaged into a folder. Instead of rewriting the same instructions every time, you write them once inside the skill and let Codex handle the work.
Skills help you extend Codex with specific expertise and save time.
How Skills Work — Progressive Disclosure
Skills use a method called Progressive Disclosure:
- Startup: Codex loads only the names and descriptions of all skills.
- On Demand: When you request a skill, Codex loads the full SKILL.md file.
- Efficient: Tokens are used only when needed.
This keeps performance fast and context clean.
Where Skills Live (Skill Scopes)
Skills can be stored in different places:
- Global Level: Across all projects
- User Level: Available to your user
- Repository Level: Inside a specific project
- System Level: Default built-in skills
How to Install Existing Skills
Before using or creating skills, make sure your Codex CLI is updated to the latest version. The Skill Creator and Skill Installer options depend on the latest CLI features. If your version is outdated, these options may not appear in the terminal.
To install an existing skill:
- Open Codex in the terminal
- Type $
- Choose Skill Installer
- Enter a skill name or paste a GitHub URL
- Codex installs it
- Restart Codex
After a restart, type $ again, and you will see your installed skills.
How to Create Custom Skills
There are two ways:
Method A: Using the CLI Creator
- Start Codex and type $
- Choose Skill Creator
- Enter the name
- Enter the instruction
- Codex asks follow-up questions and builds the skill
If the skill ends up outside the .codex/skills folder, you must install it manually.
Simply follow the instructions above, “How to Install Existing Skills”.
Method B: Manual Creation (Recommended)
A skill has a simple folder structure:
-
skill.md(Required): Main instruction file -
scripts/(Optional): Code scripts for logic -
references/(Optional): Docs or templates -
assets/(Optional): Extra resources
The template of SKILL.md file:
---
name: skill-name
description: "Description that helps Codex select the skill "
metadata:
short-description: "Optional user-facing description "
---
Skill instructions for the Codex agent to follow when using this skill.
The example of SKILL.md file:
---
name: prompt-optimization
description: Improve and rewrite user prompts to reduce ambiguity and improve LLM output quality. Use when a user asks to optimize, refine, clarify, or rewrite a prompt for better results, or when the request is about prompt optimization or prompt rewriting.
---
# Prompt Optimization
## Goal
Improve the user's prompt so Codex (or any LLM) produces better output while preserving intent.
## Workflow
1. Read the user's original prompt carefully.
2. Identify ambiguity, missing context, or unclear intent.
3. Rewrite the prompt to remove ambiguity and provide clear instructions.
4. Retain the core intention of the user's request.
5. Add relevant constraints (format, length, style) when helpful.
## Output format
Provide:
- Improved prompt
- Short explanation of what was improved
## Constraints
- Do not assume domain knowledge not in the original prompt.
- Preserve user intent.
## Example triggers
- “Draft me an email asking for feedback.”
- “Turn this into a daily to-do list.”
- $automating-productivity
In order to create a new skill, follow these steps:
- Go to
.codex/skills/ - Create a new folder
- Inside it, create
skill.md - Add:
- Name
- Short description
- Full instructions
- Trigger examples (optional)
Once the folder exists in .codex/skills/, Codex automatically recognizes it.
How Skills Are Detected and Triggered
You do not always have to invoke a skill manually. Inside skill.md, you can add trigger examples. When you type a prompt that matches one of those examples, Codex automatically runs the correct skill.
For example:
If a Writing Assistant skill has examples like:
- “Help me write a blog post”
- “Draft an introduction for a video script”
And you type:
- Help me write an article about Codex skills
Codex understands the intent and triggers the Writing Assistant.
If it didn’t, then you can call the skill with the $[skill-name] command.
Best Practices for Creating Codex Skills
Follow these guidelines:
- One Skill, One Job. Keep each skill focused on a single task.
- Zero Context Assumption. Skills should not rely on previous messages — they must be self-contained.
- Refine Descriptions. If a skill doesn’t trigger, adjust its description and examples.
- Prefer Instructions Over Scripts. Use text instructions before complex code scripts.
GitHub Skills Library (Ready to Use)
To help you get started quickly, I created a curated repository of ready-to-use Codex skills:
https://github.com/proflead/codex-skills-library/tree/master
This library includes:
- Developer-focused skills
- Team-oriented workflows
- Example skills you can install or adapt
Use these skills to improve your workflow or as templates for your own ideas.
Video Tutorial On Codex Skills
I recommend watching my video tutorial where I demonstrate everything step-by-step.
Watch on YouTube: Codex Skills 101
FAQ
Q: Do I need to use $ every time I run a skill?
A: No. If you provide trigger examples in skill.md, Codex can automatically detect and run skills based on your prompt.
Q: What happens if Codex doesn’t recognize my skill prompt?
A: Check your skill.md description and trigger examples. Make them clearer and more specific.
Q: Where should I store my skills?
A: Store them in .codex/skills/ for project-level use. For global use, place them in your user skills folder or system skills folder.
Q: Are scripts required inside a skill?
A: No. Skills can work with just instructions. Only use scripts when necessary for logic that cannot be expressed in text instructions.
Q: Can skills be shared with others?
A: Yes. You can share skill folders directly or publish them on GitHub. Others can install them using the Skill Installer.
Q: Will skills slow down Codex?
A: No. Because Codex only loads names and descriptions at startup, and loads full skill content only when needed, performance remains fast.
Conclusion
Codex Skills are a powerful way to automate your prompts, save time, and standardize workflows. You can start using ready-to-use skills from my GitHub library to make Codex work smarter for you.
If you find this article useful, please make sure to like and share it.
Cheers! ;)
Top comments (1)
Some comments may only be visible to logged-in visitors. Sign in to view all comments.