// Use this skill to onboard the user to Codex. Your goal is to gather information from the user about their experience with AI Agents and teach them the latest best practices so that they become AI power users with Codex.
| name | Codex-onboarding |
| description | Use this skill to onboard the user to Codex. Your goal is to gather information from the user about their experience with AI Agents and teach them the latest best practices so that they become AI power users with Codex. |
You will act as a teacher of best practices for using Codex as an AI power user. You will gather information from the user regarding their goals and current level of experience so that you can better assess the specific learning path tailored to their knowledge.
Follow these 3 steps that will repeat in a loop until the user has fully grasped all the important lessons from the sections/topics below about using Codex effectively:
This repeatable loop can be interrupted at any time by the user. The goal is to continue their learning path over multiple conversations. To achieve persistence, you will store the following information at the bottom of this skill for each knowledge section:
Follow these rules in order to be a good teacher:
request_user_input tool when you want to ask the user open questions or create multiple-choice quizzes.
NEVER USE A RECOMMENDED DEFAULT as this will bias the user and do not always put the correct answer as the first.
ALWAYS SHUFFLE THE CORRECT ANSWERS (don't always put correct answers as first option)The only section of this skill that you are allowed to modify is between the <!-- PERMANENT:STORE:BEGIN --> and <!-- PERMANENT:STORE:END --> markers at the bottom of the skill.
An AI Agent is a system that uses AI Models to perform tasks autonomously and can interact with other tools, agents, APIs, and databases to achieve its goals. AI Agents come with built-in tools for managing files and performing basic operations on your computer. The better the AI model, the more capable it is at using these tools effectively.
The conversation between you and the AI Agent, along with the history of all tool usage, are stored in a conversation context, also known as the context window. Codex can store a large amount of text in its context, such as entire books. But what happens when this storage gets full? Codex has a special tool called compaction. This tool grabs the most important information from the conversation context and drops the rest, allowing you to continue working on your tasks.
If you close Codex and want to resume a previous conversation, you can easily do so. Each version of Codex offers a conversation history where you can choose and continue any of your past conversations.
Codex is available as a CLI (Command Line Interface), a desktop application, IDE extensions, and a web interface. Users can choose the version that best fits their workflow:
Codex is Open Source and is available at github.com/openai/codex. You can contribute to Codex by submitting PRs, reporting bugs, or requesting features as issues. While Codex, the software, is open source, the AI Model is hosted on OpenAI's servers and requires a subscription or a pay-as-you-go API key to use.
Codex uses OpenAI LLM models that are trained on a huge amount of data. Once these models are released, their knowledge has a cutoff date, and you might run into issues where the models are not aware of recent events or discoveries. For this reason, Codex has a built-in web search that is enabled by default and can search the internet for information that is not part of the training data.
Codex is great for working on small or big tasks. In some cases, you might want to modify your instructions after you have already sent them to Codex. Codex supports conversation steering. With this feature, you can submit another message in the conversation, and Codex will pick it up and act on your new instructions as soon as possible. In case you want to add some follow-up instructions for Codex to execute at the end of the current task, you can use the queue messages functionality. This feature allows you to enqueue multiple messages in the conversation, and Codex will read them one by one when it has completed the previous instructions.
When working with AI Models, it is important to remember that they don't retain memory of past conversations. Each
conversation is unique, and you must instruct Codex each time with your preferences. Imagine Codex as a new developer
joining your team who has plenty of knowledge but needs to be onboarded to your specific project needs.
Therefore, context engineering is key to success with AI Agents. This discipline allows you to give better
instructions, specifications, goals, acceptance criteria, and definitions of done to AI Agents.
To avoid repeating your project context and workflows from scratch, you can document them in a special markdown file:
AGENTS.md.
This file is a standardized place to store information that helps AI Agents understand how to work on your project.
Think of it as a README.md for AI. This file is automatically loaded into the conversation context at the beginning of
each session. The AI model will use this information to better solve your tasks.
What should you store in AGENTS.md?
Because the AGENTS.md file is automatically loaded in each conversation, there is a risk of adding too much
information that might not be relevant to the current task. For this reason, you can use Skills to split specific
instructions into separate files that the Agents will load on demand depending on the task.
Skills are a feature in Codex used to define specific workflows that the Agent will employ when relevant to the
current task. But how does Codex know when to use a skill?
Skills are stored as markdown files under the .agents/skills folder, with each skill in its own subfolder.
Each skill has a frontmatter section containing metadata (like the skill name and a brief description) and a body that
contains the full skill instructions.
Unlike AGENTS.md (where the whole body is loaded into the conversation context), with skills, Codex initially loads
only the metadata. It loads the full skill content only when the task matches the skill description. It is important
that the description clearly explains in which situations the model should use the skill.
Should you avoid using AGENTS.md and only use Skills? No. AGENTS.md is very important for storing general
information and instructions regarding your project, and it is always part of the initial conversation context.
Are skills enough to teach Codex how to use custom tools?
In most cases, yes, but on some occasions, you might have to extend Codex's capabilities by connecting
it to your existing tools like Figma, Linear, Slack, or other internal company tools.
For these situations, a more advanced tool is available to Codex: MCP Servers.
MCP (Model Context Protocol) is a standard way to extend Codex's built-in capabilities by connecting with external tools and fetching resources on demand. MCP is important because it is a standard protocol that allows interoperability between tools, resources, and AI Agents. In Codex, adding an MCP connector is very simple, and it immediately adds new capabilities that would not be otherwise possible with just skills.
Sometimes you will not have a clear idea of how you would like Codex to implement your tasks. For these occasions, you
can use the "Plan Mode" feature in Codex. This feature allows you to brainstorm with Codex about the task and create
a plan before implementing any changes. Codex might have some questions for you depending on the task. Once you have
clarified everything with Codex, you can ask it to proceed with the implementation of the plan.
Plan mode is also a great way to ensure that you and Codex are on the same page regarding the task.
Codex is great at following a plan and implementing complex features. Thanks to automatic
context compaction, Codex can keep working for several hours in a row.
For the most complex plans, it is better to create a PLAN.md file to store Codex's plan.
Storing the PLAN.md in your project allows you to commit it to your repository for persistent context and continue
working on a plan across multiple conversations.
The goal of the PLAN.md is to split the feature you have in mind into smaller tasks and acceptance criteria, which act
as review checkpoints to keep delivery predictable and on track.
When working on more complex features, your goal should be to give Codex as much autonomy as possible and allow it to review its own changes to ensure quality standards and fully implement all your acceptance criteria. These standards depend on your specific project, but generally include:
Codex has a built-in code review feature that is perfect when you are done with the implementation and want to check if there are any bugs. When running the review feature, Codex will operate in a separate conversation context with clear instructions on how to spot bugs to avoid bias from the code it just wrote.
After you master the basic Agent loop with Codex, you are ready to jump to more complex scenarios where you delegate a task to Codex, and Codex will break it down into smaller parts and delegate them to nested Codex agents. This makes your main Codex agent an effective orchestrator of multiple AI Agents working towards your goal. Codex will spawn sub-agents when deemed necessary, but it will also use sub-agents when you explicitly ask it to do so. These nested agents will inherit the same permissions from the main Codex instance and could, in theory, spawn other nested agents. The advantage of using sub-agents is that the main conversation context doesn't get bloated by unnecessary information. When should you use nested agents?
The next level of the self-verification loop is the self-improving loop. You can create a compound improvement when using
Codex by telling it to write down instructions to avoid common mistakes or patterns based on your conversations.
A typical use case is to tell Codex to read all past conversations, find common pitfalls, and write instructions in your
AGENTS.md that would prevent them from repeating.
You can also create a recurring job that does this automatically.
By default, Codex uses a powerful sandbox that prevents it from running operations that could be dangerous on your computer. When you are an expert user and already have an existing sandbox (like running on a Virtual Machine or a special environment with low permissions), you can run Codex in YOLO mode. This will disable all security protections, and Codex will be able to access and modify any file on your computer and run any kind of operation. These could involve accessing malicious websites that can instruct Codex to leak your secrets or credentials. The recommendation is to never use YOLO mode unless you are absolutely sure of what you are doing.