Markdown Files for Codex: A Beginner's Guide

When you open a Codex project, you may see files named README.md, AGENTS.md, or SKILL.md. They all use Markdown, but they do not all perform the same job.

The most important rule is this: the .md ending tells you how the text is formatted. The filename and folder tell Codex what the document is for.

What is a .md file?

.md is the usual extension for a Markdown file. Markdown is plain text with a small set of symbols for headings, lists, links, emphasis, and code. You can read it in any text editor, while GitHub, Codex, and many documentation tools can display it with formatting.

# Main heading

## Smaller heading

This is a paragraph with **bold text** and `inline code`.

- First item
- Second item

1. First step
2. Second step

[OpenAI documentation](https://learn.chatgpt.com/docs)

A blank line separates paragraphs. A hash mark creates a heading. Hyphens create bullet points, and backticks distinguish filenames, commands, or code. That small vocabulary is enough for most project documentation.

Three jobs for Markdown in a Codex project

1. Project instructions: AGENTS.md

AGENTS.md is not just a note with a convenient name. Codex looks for it when starting work and uses it as project guidance. It can define the authorized workspace, files that must not change, required checks, writing conventions, and approval boundaries.

# Website project rules

## Before editing

- Run git status.
- Preserve unrelated work.
- Read the existing page before changing it.

## Verification

- Run the production build.
- Report the files changed.
- Do not publish without explicit approval.

A root AGENTS.md can govern the whole repository. A narrower AGENTS.md inside app/blog/ can add blog-specific rules when Codex is started in that directory or a directory beneath it. Codex builds its instruction chain from the project root to its current working directory, with closer instructions taking precedence.

Use AGENTS.md for durable rules. Do not fill it with today's task, temporary results, or a long learning diary.

2. Reusable procedures: SKILL.md

A Codex skill is a folder whose required instruction file is named SKILL.md. It describes one repeatable job: when the skill should be used, what inputs it needs, which steps to follow, and what output to return.

---
name: article-source-check
description: Verify the sources for a draft article before publication.
---

# Article source check

1. Read the complete draft.
2. Identify claims that may have changed.
3. Prefer primary and official sources.
4. Report unsupported claims and suggested corrections.
5. Do not publish or edit the draft unless asked.

The opening block between --- marks contains metadata. The instructions below it describe the workflow. A skill can also include scripts, references, and assets, but the SKILL.md file is its center.

Use a skill after a procedure has become stable and repeatable. A one-time project note usually belongs in ordinary documentation instead.

3. Human-readable project knowledge

Most Markdown files are ordinary documents. Their names communicate their purpose to people and to Codex:

README.md explains what the project is and how to use it.
PLAN.md records an agreed plan for a larger piece of work.
DECISIONS.md records important choices and their reasons.
LEARNING-LOG.md preserves short lessons from completed tasks.
CHECKLIST.md provides a repeatable list for people to follow.

These files are not automatically executable, and Codex does not treat every .md file as an instruction source. Ask Codex to read a normal document, or connect it through an applicable AGENTS.md, skill, or task prompt.

Markdown is not the right file for every job

Choose the file type according to the responsibility:

Use .md for readable instructions, explanations, notes, and procedures.
Use page.tsx for an actual webpage in a Next.js App Router site.
Use .json, .yaml, or .csv for structured data that software must parse consistently.
Use .ts, .js, or .py for executable logic.

For this blog, the article that visitors see lives in app/blog/markdown-files-for-codex/page.tsx. Markdown is the subject and a useful drafting format, but the finished site follows its existing page.tsx article structure.

A simple file hierarchy

my-project/
├── AGENTS.md                 # Rules for the whole project
├── README.md                 # Project introduction
├── docs/
│   ├── DECISIONS.md          # Important decisions
│   └── LEARNING-LOG.md       # Lessons from completed work
├── .agents/
│   └── skills/
│       └── source-check/
│           └── SKILL.md      # One reusable workflow
└── app/
    └── blog/
        ├── AGENTS.md         # Narrower blog instructions
        └── my-article/
            └── page.tsx      # The actual webpage

This arrangement separates four things: repository rules, project knowledge, reusable methods, and application code. Codex can work more reliably when one file does not try to serve all four purposes.

How to ask Codex about unfamiliar .md files

Before changing a repository, ask Codex to explain the Markdown files it finds:

Inspect this project without editing anything.

For every relevant .md file, tell me:
1. Its path
2. Its purpose
3. Whether Codex loads it automatically or only when asked
4. Which folders or tasks it applies to
5. Whether any instructions conflict

Then explain which file types control the actual application.

This prevents a common mistake: reading a helpful note and assuming it has the authority of AGENTS.md, or editing a Markdown draft when the live webpage is actually generated by page.tsx.

Common beginner mistakes

Assuming all Markdown files are automatic instructions. Special discovery rules depend on filename and location.
Putting everything in AGENTS.md. Keep lasting working rules there; store explanations and history elsewhere.
Creating conflicting nested rules. Make narrower instructions specific and deliberate.
Treating Markdown as a program. A code block displays a command; it does not run the command.
Saving secrets in documentation. Never place passwords, API keys, private tokens, or sensitive personal data in a tracked .md file.
Writing one enormous document. Small, clearly named files are easier for people and Codex to locate and maintain.

The practical rule

Use Markdown to make knowledge readable. Use AGENTS.md to define how Codex should work. Use SKILL.md to preserve a reusable procedure. Use ordinary .md files for explanations and records. Keep the website, data, and executable logic in the file types the project already uses.

Once you understand those boundaries, a folder full of unfamiliar .md files becomes a map: each document tells you what it knows, while its name and location tell Codex how much authority that knowledge has.

For the current discovery and precedence rules, see OpenAI's AGENTS.md documentation. For the required structure and activation of reusable workflows, see OpenAI's Build skills guide.

More Codex Learning →