How to install Codex skills: a beginner’s guide to AI agent workflows

OpenAI Codex helps developers write code, investigate bugs and complete software development tasks. However, repeatedly explaining the same coding standards or testing procedures can slow down a workflow. Codex skills address this problem by packaging reusable instructions into files that the agent can follow. Developers can browse an AI skills marketplace with ready-to-use SKILL.md files to explore existing workflows before creating their own.

Key takeaways

• Codex skills use a SKILL.md file to define reusable instructions.
• Skills can support code reviews, testing, debugging and documentation.
• Installation involves placing skill files in a directory supported by Codex.
• Third-party skills should be inspected and tested before regular use.
• Developers remain responsible for reviewing AI-generated changes.

What are Codex skills and SKILL.md files?

A Codex skill is a collection of instructions and optional supporting resources designed for a specific task. Its central component is a SKILL.md file containing a name, description and workflow instructions. For example, a testing skill might guide Codex through identifying missing test cases, generating tests and reviewing the results. Unlike a one-time prompt, a skill can be reused whenever a similar task appears.

Prepare your environment before installation

Before installing a skill, make sure your Codex environment supports skills and that you have access to the relevant project files. You should also understand the skill’s purpose and any additional tools it requires. Some skills include scripts or instructions for executing commands, so reviewing their contents before installation is an important security precaution.

How to install Codex skills in five steps

The exact installation process depends on your Codex environment and whether the skill is intended for personal or project-wide use. The following steps describe a general workflow for installing and evaluating a skill.

Step 1: find a skill that matches your task

Start with a recurring activity such as code review, debugging or automated testing. Developers can explore Codex skills on Agensi to find relevant options. Select a skill with a clearly defined purpose and instructions that match your development environment. A focused workflow is generally easier to evaluate than a skill promising to automate an entire project.

Step 2: review the SKILL.md instructions

Open the SKILL.md file and examine its description, instructions and references to additional resources. Check whether the skill requests access to sensitive files, executes unfamiliar commands or depends on external services. Developers should understand the expected behaviour before allowing an AI agent to follow third-party instructions.

Step 3: install the skill in the correct directory

Codex discovers skills from supported directories. Personal skills can be stored in a user-level skills directory, while project-specific skills can be placed in a repository’s .agents/skills directory in supported configurations. Preserve the original folder structure so the SKILL.md file and supporting resources remain together. Confirm the correct location in the documentation for your Codex version.

Step 4: make the skill available in Codex

After placing the files in the appropriate directory, start a new Codex session or follow the refresh procedure supported by your client. Codex can discover available skills and use their instructions when they match a task. Some interfaces also allow developers to reference skills explicitly. Available controls may differ between Codex environments.

Step 5: test the workflow before regular use

Run the skill on a small task in a non-sensitive project or disposable branch. Review any generated code, commands and documentation to confirm that the output meets your requirements. If the skill produces unexpected results, examine its instructions and adjust the workflow before using it on important project files.

Where should you install Codex skills?

Skill location determines where a workflow is available. Personal skills are useful for individual preferences, while project-specific skills help teams share consistent instructions.

Skill type	Typical location	Recommended use
Personal skill	User-level Codex skills directory	Individual workflows across projects
Project skill	Repository-level .agents/skills directory	Shared development conventions
Installer-managed skill	Directory selected by a supported installer	Workflows added through an installation tool

The supported directories and discovery behaviour may vary between Codex versions. Always check the documentation for your environment.

Troubleshooting common installation problems

If Codex cannot find a skill, first check the installation directory, folder structure and SKILL.md filename. Confirm that the file contains the required metadata and that the skill is compatible with your environment. If Codex discovers the skill but produces poor results, inspect the workflow instructions and test whether the task matches its intended purpose. Installation alone does not guarantee useful output.

Are third-party Codex skills safe?

Third-party skills can influence how an AI agent reads files, uses tools and executes commands. Developers should inspect unfamiliar scripts, limit access to sensitive information and avoid testing new skills with production credentials. Repository permissions, approval settings and human review remain essential. A skill should support an existing security process rather than replace it.

Codex skills vs MCP: understanding the difference

Codex skills describe reusable instructions and procedures, while the Model Context Protocol (MCP) provides a standard way for AI applications to connect with external tools and data sources. For example, a skill might describe how to review a database migration, while an MCP connection could provide access to a tool needed for that workflow. The technologies serve different purposes and can work together.

How can you create your own Codex skill?

Developers can create their own skills by organising a dedicated folder around a SKILL.md file. The file should clearly explain the skill’s purpose, when to use it and which steps the agent should follow. Start with a narrow task, test the instructions against representative examples and refine the workflow based on the results. Teams can also review changes to project-specific skills through their normal version control process.

Build a reliable workflow with your first skill

Start with one development activity that your team already understands, such as generating unit tests or reviewing documentation. Evaluate whether the skill improves consistency and produces useful results without introducing unnecessary complexity. Codex skills are most effective when they reinforce established engineering practices, while developers remain responsible for validating changes and making final decisions.