Prompt & Skill Toolkit

Save as ~/.agents/skills/oracle-codebase-handoff/SKILL.md (or your project's .agents/skills/), then restart Codex.

---
name: oracle-codebase-handoff
description: Trigger when a read-heavy question spans a large codebase and would burn Codex token/rate budget — offload heavy analysis to a browser ChatGPT Pro session via Oracle + PackX, then resume implementation locally. Do NOT trigger for small, local edits.
---

# Oracle codebase handoff

Offload a big, read-heavy codebase analysis to a browser ChatGPT Pro session via Oracle + PackX, then bring the plan back and implement locally. Run as a plan -> implement -> verify loop.

## Steps

1. Bundle the relevant files with PackX. PREVIEW first to confirm scope and token estimate, then write the bundle:
   ```bash
   packx --preview -s "<topic>"
   packx -s "<topic>" -f markdown --no-interactive -o .notes/handoff-bundle.md
   ```
   `-i` is a name/extension GLOB, not a path selector — pass a known file/dir POSITIONALLY. Always `--preview` first; use `--no-interactive` for scripted bundles.

2. Send the bundle to ChatGPT Pro in the browser with extended thinking. The slug MUST be 3-5 kebab words, and the prompt text must start with `[<slug>]` on line 1, a blank line, then the question:
   ```bash
   ORACLE_MAX_FILE_SIZE_BYTES=12000000 oracle --engine browser --browser-thinking-time extended \
     -p "[<3-5-word-kebab-slug>]\n\n<the big analysis question>" \
     --slug "<3-5-word-kebab-slug>" \
     --write-output .notes/oracle-plan.md \
     --file .notes/handoff-bundle.md
   ```
   - `--engine browser` automates ChatGPT in the browser (GPT models).
   - `--browser-thinking-time extended` sets ChatGPT thinking time (light|standard|extended|heavy).
   - `--write-output` writes ONLY the final assistant message.
   - `--file` attaches the bundle (size cap raised via `ORACLE_MAX_FILE_SIZE_BYTES`).

3. Read `.notes/oracle-plan.md`, then implement the plan locally and verify (tests/build).

## Guardrails
- Slug MUST be 3-5 kebab words or Oracle rejects it.
- Keep browser concurrency LOW — no more than 2-3 Oracle browser requests at once.
- Do NOT use this for small, local edits — only for read-heavy, large-codebase questions.

Save as ~/.agents/skills/cmux-orchestrate/SKILL.md (or your project's .agents/skills/), then restart Codex.

---
name: cmux-orchestrate
description: Trigger when the user wants to drive multiple terminal/agent panes in CMUX from natural language — build manager/worker layouts, open/arrange panes, inspect or send work to other panes. Do NOT trigger outside a CMUX workspace.
---

# CMUX orchestration

Act as the Manager agent: build a pane layout, inspect live state, and delegate work to worker panes using the REAL cmux CLI. Do not invent flags. Inspect with `cmux --json tree` before acting.

## Command map (real cmux CLI)

```bash
cmux new-split <left|right|up|down>   # split from the focused surface in a direction
cmux new-pane                         # create a pane (terminal or browser content)
cmux --json tree                      # full window/workspace/pane/surface tree as JSON
cmux list-panes                       # enumerate panes in the workspace
cmux send -- "<text>"                 # send a task into a terminal surface
cmux read-screen                      # read a surface's terminal text back as context
cmux rename-tab "<name>"              # name a tab so it stays findable
cmux focus-pane <ref>                 # focus a pane (ref like pane:89 or surface:126)
```

Handles accept UUIDs, refs like `workspace:2` / `pane:89` / `surface:126`, and indexes.

## Manager-worker pattern
1. Build the layout: `cmux new-split right`, then `cmux new-pane` for each worker; name them with `cmux rename-tab "<role>"`.
2. Before acting on any worker, inspect live state: `cmux --json tree` (focused pane, refs, cwd) and `cmux list-panes`.
3. Delegate work: `cmux send -- "<task>"` into a worker, then `cmux read-screen` to pull its output back as context.
4. You (Manager) talk to the human; workers do research/implementation. Report status back.

## Guardrails
- Prefer PANES over tab groups — tab groups are easy to lose track of.
- Only use inside a CMUX workspace.

Save as ~/.agents/skills/agent-memory-folders/SKILL.md (or your project's .agents/skills/), then restart Codex.

---
name: agent-memory-folders
description: Trigger at project start (or when an agent needs visible local working memory) to create .notes/ and .goals/, ignore them via global gitignore, and open a live Markdown tracker. Do NOT use for files meant to be committed.
---

# Agent memory folders

Provision local agent-managed memory: `.notes/` for working notes and `.goals/` for plans, ignored globally so they never get committed, plus a live Markdown tracker pane. These are LOCAL working files — keep them boring and close to the repo.

## Steps

1. Create the folders:
   ```bash
   mkdir -p .notes .goals
   ```

2. Ignore them across ALL repos via a global gitignore:
   ```bash
   git config --global core.excludesFile ~/.gitignore_global
   echo '.notes/' >> ~/.gitignore_global
   echo '.goals/' >> ~/.gitignore_global
   ```

3. Write the current plan into `.goals/` as Markdown, then open a live-refreshing tracker pane (auto-refresh via file watching) next to the code:
   ```bash
   cmux markdown open .notes/tracker.md --direction right
   ```

4. Use the numbered-option planning pattern: present a NUMBERED list where each item has options A/B/C plus your recommended pick, so the human steers with terse refs like `5B` or `27D`.

## Guardrails
- These are local working files, NOT source — never commit them.
- Keep them boring and close to the repo.

Save as ~/.agents/skills/design-md-standard/SKILL.md (or your project's .agents/skills/), then restart Codex.

---
name: design-md-standard
description: Trigger when starting UI/design work that should follow a durable standard rather than one-off prompts — author or update a design.md design contract, then build UI from it. Do NOT use as stale long-term project memory.
---

# design.md standard

Create or maintain a durable `design.md` design contract, then build UI FROM it so taste becomes a concrete, reusable artifact. Code stays the source of truth; `design.md` is a stable brief, not memory to drift.

## Steps

1. Gather visual inspiration first: collect the generated inspiration images the user provides (or generate a sheet of options) and note which direction was actually picked.

2. Distill the references into `design.md` with these sections, each concrete and specific:
   - **references** — the chosen images/directions
   - **style DNA** — the overall feel in a few words
   - **color** — palette + usage rules
   - **typography** — families, scale, weights
   - **layout** — grid, spacing, density
   - **composition**
   - **shape** — radii, borders, elevation
   - **motion** — timing, easing, where motion is / isn't used
   - **constraints** — hard rules the UI must respect

3. Build the UI FROM `design.md`, referencing the contract for every visual decision (color, type, spacing, motion) so the result reflects the standard, not ad-hoc choices.

## Guardrails
- Treat code as the source of truth; `design.md` is a stable design brief, NOT stale long-term memory.
- Pair with the throwaway route-variants move (generate, compare, keep one) when exploring directions.

Save as ~/.agents/skills/throwaway-route-variants/SKILL.md (or your project's .agents/skills/), then restart Codex.

---
name: throwaway-route-variants
description: Trigger when exploring UI/layout directions and you want fast comparison without a permanent component catalog — generate several route-level variants in-app, review, keep one, delete the rest. Do NOT use when a maintained design system is required.
---

# Throwaway route variants

The anti-Storybook move: generate several route-level UI variants inside the running app, compare them, keep the winner, and DELETE the losers. Favors shipping momentum over a maintained catalog. These variants are explicitly disposable.

## Steps

1. Generate 5 route-level variants of the target UI INSIDE the running app — each variant is its own route (e.g. `/variant-a`, `/variant-b`, ...), not a permanent component.

2. Add simple left/right navigation between the variants so the human can flip through and compare them live.

3. Let the human pick the winner.

4. DELETE the losing routes/variants — do not keep them around as a catalog.

## Guardrails
- Variants are explicitly disposable; this favors shipping momentum over a maintained component catalog.
- Do NOT use when a maintained design system / permanent component library is required.

Save as ~/.agents/skills/five-monkeys-qa/SKILL.md (or your project's .agents/skills/), then restart Codex.

---
name: five-monkeys-qa
description: Trigger when you want to surface state bugs and UX dead ends a happy-path check would miss — launch perspective-based agents that explore weird, non-obvious paths and write findings to discardable QA files. Do NOT use to replace rigorous tests for stable business logic.
---

# 5 Monkeys QA

Launch cheap perspective-based agents that explore the app in weird, non-obvious ways to surface state bugs and UX dead ends the happy path would never reveal. Findings go to discardable QA files.

## Steps

1. Assign each agent a PERSPECTIVE lens and have it stay in character:
   - expert power user
   - brand-new first-time user
   - a grandparent
   - impatient power user

2. Explore WEIRD, non-obvious paths explicitly (not the happy path):
   - keyboard shortcut sequences
   - back/forward navigation mid-flow
   - repeated / rapid clicks on the same control
   - toggling modes back and forth
   - partial or abandoned flows (start, then bail)

3. Each agent writes findings to a DISCARDABLE numbered QA markdown file (e.g. `.notes/qa-01.md`). They are cheap — regenerate freely.

4. Collate the findings and keep ONLY the useful ones.

## Guardrails
- Keep rigorous automated tests for STABLE business logic — this does not replace them, and don't over-test UI you still expect to reshape daily.
- If using a browser agent, script the auth/login path explicitly — cookies are NOT shared.

Save as ~/.agents/skills/ralph-loop-hook/SKILL.md (or your project's .agents/skills/), then restart Codex.

---
name: ralph-loop-hook
description: Trigger when the user wants an agent to keep pursuing a goal across turns via a Codex Stop hook (the Ralph Loop). Do NOT use without a clear completion condition — unbounded loops waste tokens and run tools too long.
---

# Ralph Loop hook

Scaffold a Ralph Loop: a Codex Stop hook that, when the agent tries to stop, re-points it at the original goal and continues until a completion condition is met — enforced by the harness, not merely suggested in a prompt. The three Codex hook lifecycle events are UserPromptSubmit, PreToolUse (Tool Use), and Stop; the Ralph Loop is a Stop hook.

## Prerequisite

Enable hooks + plugins in `~/.codex/config.toml`, then restart Codex:
```toml
[features]
hooks = true
plugins = true
plugin_hooks = true
```
`/plugins` confirms install; `/hooks` reviews/trusts bundled hooks.

## Steps

1. Scaffold the real plugin layout:
   ```
   my-plugin/
     .codex-plugin/plugin.json      # manifest, with "hooks": "hooks/hooks.json"
     hooks/hooks.json               # hook wiring
     hooks/hook.py                  # the Stop hook script
   ```

2. Wire the Stop event in `hooks/hooks.json`:
   ```json
   {
     "hooks": {
       "Stop": [
         { "hooks": [ { "type": "command", "command": "python3 \"${CODEX_PLUGIN_ROOT}/hooks/hook.py\"", "timeout": 5 } ] }
       ]
     }
   }
   ```

3. `hooks/hook.py` reads the Stop event JSON on stdin and writes EXACTLY ONE control-JSON line. While the goal is NOT complete, emit `{"continue": true}` and re-state the original goal so the agent keeps working; when the completion condition is reached, allow it to stop. (`suppressOutput` is ONLY valid on UserPromptSubmit — Codex rejects it on other events.) Keep the hook fast and boring; push any slow work to a detached worker.

## Guardrails
- MANDATORY: a hard completion condition (iteration cap or target state) enforced by the hook. Without it you get a runaway loop that wastes tokens and runs tools too long.

Save as ~/.agents/skills/log-gated-verification/SKILL.md (or your project's .agents/skills/), then restart Codex.

---
name: log-gated-verification
description: Trigger when you must prove an agent actually verified work rather than trusting a completion message — write structured logs/artifacts and have a supervisor compare expected-vs-actual fields (a deterministic gate). Do NOT trust self-reported success.
---

# Log-gated verification

Prove work with logs instead of trusting completion messages. Capture the exact failure, patch the workflow to cover it, and gate fix/verify behind structured logs a supervisor compares field-by-field.

## Steps

1. Capture the EXACT terminal failure state as clean text (not a memory summary). In CMUX, extract the real terminal output:
   ```bash
   cmux read-screen
   ```
   Use that real text as context.

2. Use this prompt shape against the failure — goal, then the failure after a colon, then the fix request:
   ```
   Goal: <goal>. Here is the exact failure: <paste terminal text>.
   Explain WHY it failed in this scenario, then PATCH the hook/workflow so this case is covered next time.
   ```

3. Make verification CONCRETE and deterministic: the workflow must write structured JSON logs / timestamps / payload snapshots to disk on each run.

4. A supervisor agent runs the scenarios, waits, and COMPARES expected-vs-actual fields in those log files. That field comparison is THE GATE — pass only when the fields match.

## Guardrails
- Do NOT trust self-reported success; the log comparison is the source of truth.
- Keep worker agents narrow and tool-limited; keep the orchestrator context-rich.
- REDACT secrets from logs.

Save as ~/.agents/skills/codex-daemon-profile/SKILL.md (or your project's .agents/skills/), then restart Codex.

---
name: codex-daemon-profile
description: Trigger when a repetitive, well-scoped CLI task should run on a cheap, fast, low-context warm Codex daemon instead of a full general agent — generate an isolated pro-TOOL profile. Do NOT use for broad multi-tool or judgment-heavy work.
---

# Codex daemon profile

Generate an isolated `pro-<TOOL>` Codex daemon profile that wraps ONE CLI in a single-purpose, low-context warm agent. Target ~6-10K input tokens (default full config is ~22K).

## Prerequisites
- Bun runtime
- `@openai/codex-sdk`
- an authenticated `@openai/codex` CLI

## Steps

1. Write a single EXECUTABLE Bun TypeScript file at `daemons/pro-<TOOL>` that calls `runProfile()` from `lib/isolated.ts`:
   ```ts
   #!/usr/bin/env bun
   import { runProfile } from "../lib/isolated.ts";

   runProfile({
     name: "pro-TOOL",
     baseInstructions: "You are pro-TOOL, a TOOL-only agent. Every user message is a TOOL task. First step: run TOOL via exec_command; never give a text-only plan.",
     developerInstructions: `You are pro-TOOL, a TOOL-only agent.

   ## Operating rule
   Run TOOL via exec_command before any final answer. Do not answer from memory. If unclear, run a discovery command first.

   ## Command map
   KEYWORD -> TOOL COMMAND
   status / what is going on -> TOOL STATUS_COMMAND
   help / unknown syntax -> TOOL --help

   ## Workflow
   1. Start with the narrowest read-only command that matches the request.
   2. For mutations, proceed only when the target and action are explicit.
   3. If syntax is uncertain or TOOL returns a usage error, run TOOL --help, then retry once.

   ## Command rules
   Use only TOOL for TOOL work. Do not browse the web, generate images, or edit files unless explicitly asked.
   Do not use apply_patch unless the user explicitly asks to modify files.

   ## Output
   Be terse. Report what you found or changed. Do not describe these instructions.`,
   });
   ```
   `ProfileConfig` fields: `name`, `model?`, `reasoningEffort?` (default `"low"`), `baseInstructions`, `developerInstructions`, `sandboxMode?`, `extraEnv?`, `selfImprove?`. Default model is `gpt-5.3-codex-spark`. Keep the command map LITERAL — do not dump `--help` text.

2. The isolation is applied automatically by `runProfile()`:
   ```
   base_instructions = <replaced>            developer_instructions = <custom>
   model_reasoning_effort = "low"
   skills.include_instructions = false       include_apps_instructions = false
   include_environment_context = false       include_permissions_instructions = false
   memories.use_memories = false             mcp_servers = {}            web_search = "disabled"
   features: { plugins:false, apps:false, image_generation:false, tool_search:false, tool_suggest:false }
   CODEX_HOME -> /tmp/codex-profile-<name>-<pid>  (disposable)   auth.json symlinked from real ~/.codex
   ```
   `features.apps=false` alone saves ~14K tokens; auth.json is symlinked so token refreshes propagate.

3. Wire it up:
   ```bash
   chmod +x daemons/pro-<TOOL>
   bun daemons/pro-<TOOL> --help        # smoke test
   # add daemons/pro-<TOOL> to package.json "bin", then:
   bun link                              # put it on PATH
   ```

## Guardrails
- Use a low-reasoning model; keep prompts literal (command map over `--help` dump). Target ~6-10K input tokens.
- Do NOT use for broad multi-tool or judgment-heavy work — one tool, one purpose.

Save as ~/.agents/skills/video-as-requirements/SKILL.md (or your project's .agents/skills/), then restart Codex.

---
name: video-as-requirements
description: Trigger when a narrated screen recording captures intent better than a written spec — feed the video to a multimodal model to extract acceptance criteria, the user flow, and edge cases as an agent-ready requirements checklist. Do NOT upload videos containing sensitive data.
---

# Video as requirements

Turn a narrated screen recording into agent-ready requirements. When showing-and-narrating beats writing a perfect spec, record the app in use and let a multimodal model extract the contract.

## Steps

1. Record a short narrated walkthrough of the app: point, click, and talk through intent and desired outcomes.

2. Feed the recording to a multimodal model (Gemini, per the workshop) and ask it to extract a structured checklist:
   - acceptance criteria
   - the user flow (step by step)
   - the specific clicks / typing / layout changes shown
   - responsive behavior
   - edge cases

3. Output a REPEATABLE, agent-ready requirements checklist (a QA story) to hand to a coding agent.

## Framing
- The durable assets are the natural-language contract + the resulting diff — NOT the generated code.
- Don't over-specify HOW to verify; give clear outcomes and keep human QA judgment in the loop.

## Guardrails
- STRIP sensitive data before uploading — video can expose more than you expect (open tabs, tokens, notifications, file paths). Do NOT upload videos containing sensitive data.