Comparing Codex and Claude Code project instruction files, locations, skills, MCPs, and hooks for beginners.Outlining Codex and Claude Code instruction files, skills, MCPs, and hooks for beginners.Adding Claude Code hierarchy, settings, slash commands, subagents, skills, and MCP scope details.Extending the summary with hooks, beginner analogies, and interoperability guidance.Adding file paths, scope rules, and safety warnings for Codex and Claude Code configurations. Think of both Codex (OpenAI) and Claude Code (Anthropic) like a **new super-smart intern**. They can code, but on day 1 they don't know YOUR project. You have 4 ways to teach them: 1. **Project Instructions** = Employee handbook. Always read. 2. **Skills** = Training playbook. Read only when needed. 3. **MCPs** = Hands to touch outside world. Database, GitHub, Figma, etc. 4. **Hooks** = Automatic rules/alarms. "After you edit a file, run format." They do the same job, but the file names and places are different. ### 1. Project Instructions: WHERE to write them This is 90% of what you need. **Codex = `AGENTS.md`** Super simple. One convention. Where to put it: ``` ~/.codex/AGENTS.md <- GLOBAL, for you on all projects (ex: always answer in TypeScript, my name is...) my-app/AGENTS.md <- PROJECT, shared with team via git. THIS IS THE MAIN ONE. my-app/backend/AGENTS.md <- OPTIONAL, only for files in /backend my-app/frontend/AGENTS.md <- OPTIONAL, only for files in /frontend ``` Codex automatically reads the closest one. Just create `AGENTS.md` in your project root and you're done. **Claude Code = `CLAUDE.md`** Same idea, more layers. Where to put it: ``` ~/.claude/CLAUDE.md <- GLOBAL, just for you my-app/CLAUDE.md <- PROJECT, shared with team. THIS IS THE MAIN ONE. my-app/.claude/CLAUDE.local.md <- PROJECT-LOCAL, just for you, add to .gitignore (ex: your personal preferences, local paths) ``` Claude also uses `.claude/settings.json` for rules and permissions, but instructions go in `CLAUDE.md`. **What to write inside? Keep it short. Same for both.** Don't paste all your docs. Beginner template: ```markdown # My Shop App Stack: Next.js 14, TypeScript, Tailwind, Postgres ## Commands - Run dev: npm run dev - Test: npm test - Lint: npm run lint ## Rules - ALWAYS use TypeScript, no `any` - ALWAYS run `npm run lint` after editing - NEVER edit files in /legacy, it's frozen - NEVER commit .env file ``` > **Using BOTH tools?** Do this: Write everything in `AGENTS.md`, then create a `CLAUDE.md` with just one line inside: > `@AGENTS.md` > Now both read the same file. Or just symlink them. ### 2. Skills: Reusable playbooks Instructions are *always* loaded. Skills are loaded *only when relevant*. This saves tokens and makes the AI smarter. Example: You have a skill called `pdf-filler`. Its description says "Use when working with PDFs". The AI ignores it until you say "edit this PDF", then it reads the playbook. A skill is just a folder with a `SKILL.md` file: ``` my-skill/ SKILL.md helper-script.py (optional) ``` `SKILL.md` looks like this: ```markdown --- name: pdf-filler description: Use when user wants to fill, merge or extract text from PDFs. Use pypdf library. --- # How to handle PDFs 1. Always use `python helper-script.py`, don't write from scratch 2. Never overwrite original, create `-filled.pdf` ``` **Where to put skills:** Codex: ``` ~/.codex/skills/my-skill/SKILL.md <- just for you my-app/.codex/skills/my-skill/SKILL.md <- for the team ``` Claude Code: ``` ~/.claude/skills/my-skill/SKILL.md <- just for you my-app/.claude/skills/my-skill/SKILL.md <- for the team ``` Good news: Both now use the same open format (Agent Skills), so you can copy-paste the same folder. Create your own for repetitive stuff in your project: "how we write API endpoints", "how we deploy", "how we write tests". ### 3. MCPs: Give the AI hands MCP = Model Context Protocol. Fancy name for "plugin to connect to outside tools". Without MCP: AI can only read files. With MCP: AI can query your Postgres DB, create GitHub issues, control Figma, search Notion. It's just a config telling the AI: "run this command to start the connection". **Codex MCP:** in `~/.codex/config.toml` (global) or `my-app/.codex/config.toml` (project) ```toml [mcp_servers.github] command = "npx" args = ["-y", "@modelcontextprotocol/server-github"] # it will ask you for GITHUB_TOKEN env var ``` **Claude Code MCP:** Easiest is with command line, don't edit JSON by hand: ```bash claude mcp add github -- npx -y @modelcontextprotocol/server-github # then choose: project (.mcp.json, shared) / local (only you) / user (you, all projects) ``` This creates a `my-app/.mcp.json` file for your team: ```json { "mcpServers": { "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] } } } ``` Beginner rule: Put shared stuff (team DB, GitHub repo) in project scope. Put personal tokens in local/user scope. ### 4. Hooks: Automatic rules Hooks = "When X happens, automatically run Y". Example: "After you edit any .ts file, automatically run prettier" or "Block any command that deletes the database". **Codex:** Almost no hooks. Very beginner-friendly, but less powerful. It only has `notify` = run a command when task finishes. That's it. In `config.toml`: ```toml notify = ["notify-send", "Codex finished!"] ``` **Claude Code:** Full hooks system. Very powerful. They live in `.claude/settings.json` (shared) or `~/.claude/settings.json` (personal). Example `my-app/.claude/settings.json`: ```json { "hooks": { "PostToolUse": [ { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "npm run prettier -- --write $FILE" }] } ], "PreToolUse": [ { "matcher": "Bash", "hooks": [{ "type": "command", "command": "node .claude/hooks/block-dangerous.js" }] } ] } } ``` Common hook events for beginners: `PreToolUse` (before AI runs a tool - can block it), `PostToolUse` (after - for auto-format), `UserPromptSubmit` (when you press enter), `Stop` (when AI finishes). Start with hooks later. You don't need them day 1. ### Cheat Sheet | Feature | Codex (OpenAI) | Claude Code (Anthropic) | | :--- | :--- | :--- | | **Instructions** | `AGENTS.md` at root | `CLAUDE.md` at root | | **Global instructions** | `~/.codex/AGENTS.md` | `~/.claude/CLAUDE.md` | | **Custom slash command** | `.codex/prompts/deploy.md` -> `/prompts:deploy` | `.claude/commands/deploy.md` -> `/deploy` | | **Skills** | `.codex/skills/*/SKILL.md` | `.claude/skills/*/SKILL.md` | | **MCPs** | `config.toml` `[mcp_servers]` | `.mcp.json` or `claude mcp add` | | **Hooks** | Almost none (just `notify`) | Powerful in `.claude/settings.json` | | **Philosophy** | Simple, one file | Layered, more control | **Beginner advice:** 1. Start with just ONE file: `AGENTS.md` or `CLAUDE.md` at root. <100 lines, bullet points, commands + do/don'ts. 2. Add a skill only when you repeat yourself 3 times. 3. Add an MCP only when AI says "I can't access X". 4. Add hooks only when AI keeps forgetting to format/test. Want me to give you a starter template for your specific project stack?

Explain exam