Instructions and skills
Standing instructions in AGENTS.md, reusable skills, and plugins that connect an agent to other systems.
You have an AGENTS.md file with your house rules and you have made your first skill.
You have an AGENTS.md with house rules that Codex reads each time, and a first skill that Codex can reuse.
You have a project AGENTS.md, you know how it composes with global instructions, and you have a first skill.
The top layers are instructions and skills. They stop you from repeating yourself.
The last layers are standing instructions and reusable skills. They carry your rules and recipes from one task to the next.
The top of the stack moves repeated context out of the prompt: persistent instructions, on-demand procedures and connectors.
AGENTS.md holds house rules
AGENTS.md is a plain file of rules. Codex reads it at the start of each task.
It is like a note stuck on the office door. Everyone who comes in sees the same rules.
Put rules there that you would otherwise type again and again.
A thread is one chat with Codex inside a project.
AGENTS.md is a file of standing instructions. Codex reads it at the start of each task, so you do not repeat your rules in every prompt.
Good rules are short and checkable: the spelling you use, the folder for outputs, which files are off limits, when to ask first.
Codex follows the file as an instruction. It still makes mistakes, so check that a rule works.
Codex builds an instruction chain at the start of a run. A global file comes from ~/.codex/AGENTS.override.md, or else ~/.codex/AGENTS.md. Project files come from each folder from the git root down to the project folder. The nearest file wins when they conflict, and the combined size has a limit of 32 KiB.
The /init command drafts a file for you. Keep the content short and specific, since it consumes context on every run.
A file is an instruction, not a guarantee. Test each rule with a new thread.
Write your first AGENTS.md
Ask Codex to create the file
Open a new thread in the
CodexWorkproject. Paste the first prompt below.Codex shows the file and asks for approval to create it. Read it, then approve.
Start a new thread and test a rule
Open a new thread. Ask for a small task, for example: "Summarise procurement/rfq-laptops.md in three bullet points."
Check that Codex follows your rules. Look at the spelling and at where it wants to write.
Create a file called AGENTS.md in this project with these house rules: 1. Use Australian English. 2. Never change files in the starter pack folders. Write all new files to outputs/. 3. Ask before you install anything. 4. At the end of every answer, list your assumptions.
New threads read the file at the start. That is how you test it.
Rules apply to new threads. If a rule does not work, make it more specific and test again.
Instruction files load when a run starts, so test in a fresh thread. The combined chain has a size limit, so keep files lean.
Skills are reusable recipes
A skill is a recipe you save once and use many times. It lives in a folder with a file called SKILL.md.
The file has a name and a short description. Codex can pick the skill when your request matches the description.
You can also call a skill by name. Type a dollar sign and the name, for example $invoice-extract.
A skill is a folder with a SKILL.md file. The file has a name and a description, and the folder can also hold scripts, reference notes and templates.
Skills live in .agents/skills in the project, or in ~/.agents/skills for all your projects. Type $name to use one. Codex also picks a skill when your request matches its description.
Use a skill for work you repeat, such as turning supplier invoices into a table with fixed columns.
A skill is a directory with a required SKILL.md carrying name and description frontmatter, and optional scripts/, references/ and assets/. Locations are .agents/skills in the project and ~/.agents/skills for the user.
A skill loads when you type $name (or /skills in the CLI and IDE) or when the request matches its description.
Built-in skills include $skill-creator and $skill-installer. A third-party skill is code and instructions you will run, so read it before you install it.
Make a skill with $skill-creator
Ask for the skill
Paste the second prompt below into a new thread. Codex starts the built-in skill creator.
Answer its questions. Approve each file it writes.
New thread
- Create the invoice-extract skill
$skill-creator Create a skill called invoice-extract.
I created the skill. It reads supplier invoices, writes a CSV with fixed columns and checks the GST.
Codex has written the skill file inside the project. Open the file and read it
Open
SKILL.mdin File Explorer. Check the name, the description and the steps.Edit anything that does not match how you work.
$skill-creator Create a skill called invoice-extract. It extracts supplier invoices into a CSV with fixed columns: supplier, invoice number, date, net amount, GST and total. It checks that the GST is one tenth of the net amount and flags any invoice where it is not.
Plugins and MCP
A plugin is a bundle. It can hold skills and links to other tools, such as Google Drive.
MCP is a shared plug standard. It lets Codex connect to other systems in one standard way.
Your admin decides which plugins you can use. Type @ to use one.
A plugin bundles skills with connections to other systems. The Codex docs name Gmail, Google Drive and Slack as examples. Install from the Plugins tab in the app, and type @ to use one.
MCP, the Model Context Protocol, is a standard way to connect an agent to other systems. Plugins often use it.
Admins can control which plugins and skills your workspace allows. A connection can read or send real data, so check what it can reach.
A plugin bundles skills, MCP servers and hooks. MCP is a client-server protocol: the agent harness is the client, and a server exposes tools, resources and prompts over JSON-RPC (modelcontextprotocol.io). Servers are set under [mcp_servers.<name>] in ~/.codex/config.toml or .codex/config.toml, or in Settings, then MCP servers.
A connected server enlarges the attack surface. Tool results are untrusted input, and each connection is a permission you grant. Admin controls govern which plugins and skills are available.
| Item | What it is | Loaded when | Example |
|---|---|---|---|
| AGENTS.md | Standing rules for a folder | At the start of every task | Use Australian English and write to outputs/ |
| Skill | A reusable recipe in a folder | When you type $name or the request matches its description | invoice-extract |
| Plugin | A bundle of skills and connections | When you install it and call it with @ | A Google Drive connection |
Key terms
- AGENTS.md
A file of rules that Codex reads at the start of each task.
A file of standing instructions Codex reads at the start of each task.
A persistent instruction file loaded into the context at run start, with the nearest file taking precedence and a 32 KiB combined limit.
- Skill
A recipe you save once and use many times.
A reusable recipe in a folder with SKILL.md.
A packaged procedure: SKILL.md with name and description, plus optional scripts, references and assets, loaded on demand.
- Plugin
A bundle of skills and links to other tools.
A bundle of skills and connections to other systems.
A distributable bundle of skills, MCP servers and hooks.
- MCP (Model Context Protocol)
A shared standard for plugging an agent into other systems.
A standard way to connect an agent to other systems.
An open client-server protocol over JSON-RPC by which a server exposes tools, resources and prompts to an agent.
Check yourself
When does Codex read AGENTS.md?
At the start of each task.
At the start of each task, so your rules apply without being typed again.
When a run starts. Files from the git root down to the project folder are combined, and the nearest wins.
What is the difference between a skill and AGENTS.md?
AGENTS.md holds rules for every task. A skill is a recipe for one kind of job.
AGENTS.md is read for every task. A skill loads when you call it or when the request matches its description.
AGENTS.md is read at the start of each run. A skill loads when you type $name or when the request matches its description.
Why read a third-party skill before you install it?
It can tell Codex what to do and can run programs. You should know what it does.
A skill is instructions and sometimes scripts that will run on your laptop. You are trusting its author.
A third-party skill is code and instructions executed with your permissions, and a vector for prompt injection. Review it as you would any dependency.
OtterBlock is not affiliated with OpenAI. Codex and ChatGPT are OpenAI products.