Codex Agentic Agent Skill

All agent state lives under .codex/ in the project root:

.codex/
├── SKILL.md         ← This file (the agent's operating manual)
├── progress.md      ← Running log of what has been done and what is next
├── mistakes.md      ← Catalogue of past errors and how to avoid them
└── screenshots/     ← Playwright-captured images, named by step and timestamp

On first run, the agent creates this folder and all files if they do not exist.

mkdir -p .codex/screenshots
touch .codex/progress.md .codex/mistakes.md

2. Phase 0 — Context Ingestion (ALWAYS the first phase)

Rule: The agent must never write code, run commands, or make decisions until Phase 0 is complete.

2.1 Read the full prompt

Read the entire user prompt from beginning to end. Do not skim.

2.2 Decompose the prompt

Extract and explicitly state:

• Goal: What is the end state that constitutes success?
• Scope: What is in scope and what is explicitly or implicitly out of scope?
• Constraints: Time limits, technology choices, file paths, environment restrictions.
• Ambiguities: Any part of the prompt that could be interpreted in more than one way.
• Dependencies: Tools, packages, services, or files that must exist before tasks can proceed.

2.3 Resolve ambiguities

If any ambiguity cannot be resolved from context alone, log it in progress.md under a ## Unresolved section and ask the user before proceeding.

2.4 Build the execution plan

Write a numbered list of steps — the full execution plan — into progress.md before starting execution. Each step must have:

• A clear action
• Expected output or artifact
• A success criterion

2.5 Check mistakes.md

Read .codex/mistakes.md in full. For each past mistake, check whether the current task is at risk of repeating it. If so, annotate the relevant step in the plan with a ⚠️ Watch: note.

3. Phase 1 — Environment Setup

3.1 Playwright installation check

Before running any screenshot capture, verify Playwright is available:

npx playwright --version 2>/dev/null || echo "NOT_FOUND"

If not found, install it:

npm install playwright
npx playwright install chromium

Log the install result to progress.md.

3.2 App / target reachability

Confirm the target app or URL the agent needs to screenshot is accessible:

curl -o /dev/null -s -w "%{http_code}" <TARGET_URL>

If the app is a local server, check the process or start it before proceeding. Log status.

4. Phase 2 — Step-by-Step Execution

The agent executes the plan from progress.md one step at a time.

4.1 Step lifecycle

For every step:

1. Mark as In Progress in progress.md:

   - [ ] 🔄 Step N: <description> — started <timestamp>
   

2. Execute the action.
3. Verify the success criterion.
4. Mark as Done (or Failed):

   - [x] ✅ Step N: <description> — completed <timestamp>
   

   or

   - [ ] ❌ Step N: <description> — FAILED <timestamp> — see mistakes.md
   

5. If failed, go to Phase 3 (Mistake Logging) before retrying or moving on.

4.2 Screenshot capture

Screenshots are taken at every major state transition of the app:

// playwright-screenshot.js
const { chromium } = require('playwright');

(async () => {
  const browser = await chromium.launch();
  const page = await browser.newPage();
  await page.goto(process.env.TARGET_URL || 'http://localhost:3000');
  await page.waitForLoadState('networkidle');

  const label   = process.env.STEP_LABEL   || 'step';
  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
  const filename  = `.codex/screenshots/${label}_${timestamp}.png`;

  await page.screenshot({ path: filename, fullPage: true });
  console.log(`Screenshot saved: ${filename}`);
  await browser.close();
})();

Run it as:

STEP_LABEL="step-03-login" TARGET_URL="http://localhost:3000/login" node .codex/playwright-screenshot.js

Log the screenshot path in progress.md under the relevant step.

4.3 Never skip steps

If a later step seems simpler or more urgent, the agent resists the impulse to jump ahead. Dependencies between steps are real even when not explicit. Sequence matters.

5. Phase 3 — Mistake Logging

Whenever a step fails, produces unexpected output, or requires a correction:

5.1 Document the mistake immediately

Append to .codex/mistakes.md:

## Mistake: <short title>
- **Date**: <ISO timestamp>
- **Step**: Step N — <step description>
- **What happened**: <factual description of what went wrong>
- **Root cause**: <why it happened — be specific>
- **Impact**: <what had to be redone or what was lost>
- **Fix applied**: <what the agent did to correct it>
- **Prevention rule**: <a concrete rule to avoid this in the future>

5.2 Apply the fix

Correct the failed step. Re-run it. Re-take any affected screenshots. Update progress.md.

5.3 Update the execution plan if needed

If the mistake revealed a flaw in the plan (missing step, wrong order, wrong assumption), update the plan in progress.md and note the revision:

> ⚠️ Plan revised at <timestamp> due to: <reason>

6. progress.md Format

progress.md is the single source of truth for where the agent is at any point in time.

# Task Progress

## Task
<One-line summary of the overall goal>

## Started
<ISO timestamp>

## Execution Plan
- [ ] Step 1: <action> → <success criterion>
- [ ] Step 2: <action> → <success criterion>
- [ ] Step 3: ...

## Log

### <ISO timestamp> — Phase 0 complete
Prompt fully parsed. N ambiguities found. N resolved. Execution plan written.
mistakes.md reviewed — N past mistakes noted. Watch notes applied to steps: N, N.

### <ISO timestamp> — Step 1 started
<Brief note>

### <ISO timestamp> — Step 1 complete
Screenshot: `.codex/screenshots/step-01_<ts>.png`

### <ISO timestamp> — Step 2 FAILED
See mistakes.md: "Mistake: <title>"

### <ISO timestamp> — Step 2 retried and complete

## Status
IN PROGRESS | COMPLETE | BLOCKED

## Unresolved
- <list any ambiguities waiting on user input>

7. mistakes.md Format

mistakes.md is the agent's long-term memory of what not to do.

# Mistakes Log

> This file is read at the start of every task and before every major decision.
> Each entry is a permanent lesson. Do not delete entries.

## Mistake: <title>
- **Date**: ...
- **Step**: ...
- **What happened**: ...
- **Root cause**: ...
- **Impact**: ...
- **Fix applied**: ...
- **Prevention rule**: ...

---

8. Task Completion Checklist

Before declaring a task complete, the agent verifies:

• All steps in progress.md are marked ✅
• At least one screenshot exists per major app state transition
• progress.md status is updated to COMPLETE with a final timestamp
• mistakes.md has entries for every failure that occurred during the task
• No Unresolved items remain in progress.md
• The agent can state, in plain language, what was accomplished and what artifacts were produced

9. Anti-Patterns to Avoid

These are recurring failure modes. The agent checks this list before every decision:

10. Quick-Start for a New Task

1. mkdir -p .codex/screenshots && touch .codex/progress.md .codex/mistakes.md
2. Read .codex/mistakes.md in full
3. Read the full user prompt — do not skip a word
4. Decompose, plan, resolve ambiguities → write plan to progress.md
5. Check Playwright: `npx playwright --version` — install if missing
6. Execute plan one step at a time, logging every action
7. Screenshot the app at every key state
8. On any failure: log to mistakes.md, fix, retry, continue
9. Run the completion checklist
10. Report done with a summary of artifacts produced