Skip to main content
skill CX Codex

codex-goals — Codex skill: goals and installation

Guidance for writing and checking persistent Codex Goals, from a verifiable finish line to iteration rules. Useful when a task spans turns but has a clear outcome.

MIT 158 installs ★ 227 updated 2026-08-15

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add pproenca/dot-skills --skill codex-goals -a claude-code
Open on GitHub

What codex-goals does

This skill helps decide whether a task calls for /goal or a regular prompt. Its guidance covers measurable outcomes, runnable verification surfaces, constraints, iteration policies, and what to report when work is blocked. Research Goals have a separate focus on evidence.

The reference also covers Goal lifecycle: setting an objective with /goal <text>, pausing it for an unrelated detour, resuming it, and clearing stale Goals. It stresses checking concrete evidence before calling work complete. Goals became available in Codex 0.128.0, so the /goal instructions depend on that feature being present.

What it helps with

  • decide whether a task warrants /goal
  • define a measurable outcome and how to verify it
  • set boundaries and rules for choosing the next iteration
  • specify what to report when work is blocked
  • check completion against concrete evidence

Example prompts for the agent

  • Should this multi-turn task use /goal or a regular prompt? Explain the choice.
  • Rewrite this Codex Goal with a measurable outcome, a verification method, and a blocked stop condition: “…”
  • Check whether this Goal finished against the requested evidence or only a proxy.

How to install codex-goals

1Skills CLI (Vercel)

npx skills add pproenca/dot-skills --skill codex-goals -a claude-code

2Manually: put the files in place

~/.claude/skills/codex-goals/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/codex-goals/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about codex-goals

How do I install codex-goals in Codex?

Run npx skills add pproenca/dot-skills --skill codex-goals -a codex. The skill file is at .agents/skills/codex-goals/SKILL.md.

What does the codex-goals skill do?

It guides drafting, reviewing, and debugging Codex Goals, including outcome definition, verification, iteration, and Goal lifecycle.

Which Codex version supports /goal?

The Goals feature is available from Codex 0.128.0. The skill covers setting an objective with /goal <text> and managing its state.

Source text

SKILL.md · MIT
---
name: codex-goals
description: Patterns and anti-patterns for using OpenAI Codex Goals — the persistent objectives feature introduced in Codex 0.128.0. Use this skill whenever writing, reviewing, or debugging a `/goal` invocation, deciding whether a task should be a Goal at all, drafting a research Goal that needs an evidence ledger, or diagnosing a Goal that completed against the wrong surface. Triggers on `/goal`, "Codex Goal", "Codex goals", "persistent objective", "evidence-based completion", "iteration policy", "blocked stop condition", or any user message describing a multi-turn Codex task with a defined finish line. Trigger even if the user doesn't explicitly mention Goals — if they're typing "/goal" or asking Codex to "keep going until X", this skill applies.
---

# OpenAI Codex Goals Best Practices

Reference for writing and managing Codex Goals — the persistent objective feature introduced in Codex 0.128.0. "Best practices" here means the patterns and anti-patterns that determine whether a Goal completes against the right evidence vs. silently against the wrong surface. Contains 31 rules across 8 categories, ordered by how much they affect whether a Goal completes correctly. Derived from the official OpenAI cookbook article ["Using Goals in Codex"](https://developers.openai.com/cookbook/examples/codex/using_goals_in_codex).

## When to Apply

Reference these guidelines when:
- Deciding whether a task warrants a `/goal` or a normal prompt
- Drafting or strengthening a `/goal` invocation
- Reviewing a Goal someone else wrote before activating it
- Debugging a Goal that completed against the wrong verification surface
- Setting up a research Goal where exact proof may not be available
- Managing Goal lifecycle (pause, resume, clear) across thread sessions
- Writing the iteration policy or blocked stop condition for a long-running Goal
- Diagnosing a Goal that hit its budget without completing

## Rule Categories by Priority

| Priority | Category | Impact (worst rule) | Prefix |
|----------|----------|--------|--------|
| 1 | Goal Fit Decisions | CRITICAL | `fit-` |
| 2 | Outcome Definition | CRITICAL / HIGH | `outcome-` |
| 3 | Verification Surface | CRITICAL / HIGH | `verify-` |
| 4 | Boundaries & Iteration | HIGH | `bound-` |
| 5 | Lifecycle Commands | HIGH | `life-` |
| 6 | Evidence-Based Completion | HIGH | `evidence-` |
| 7 | Crafting Strong Goals | MEDIUM | `craft-` |
| 8 | Research Goals & Anti-Patterns | MEDIUM | `research-` |

Individual rule impacts are listed inline in the per-rule frontmatter.

## Quick Reference

### 1. Goal Fit Decisions (CRITICAL)

- [`fit-when-to-use`](references/fit-when-to-use.md) — Use a Goal When the Finish Line Is Clear but the Path Is Uncertain
- [`fit-three-required-properties`](references/fit-three-required-properties.md) — Require Three Properties Before Setting a Goal — Durable Objective, Evidence Finish Line, Multi-Turn Path
- [`fit-prompt-vs-goal`](references/fit-prompt-vs-goal.md) — Choose a Prompt for Single-Turn Work, a Goal for Outcome-Driven Continuation
- [`fit-skip-for-vague-targets`](references/fit-skip-for-vague-targets.md) — Skip a Goal When the Finish Line Is Vague

### 2. Outcome Definition (CRITICAL)

- [`outcome-measurable-end-state`](references/outcome-measurable-end-state.md) — State the Outcome as a Measurable End State, Not an Activity
- [`outcome-quantify-thresholds`](references/outcome-quantify-thresholds.md) — Pin Thresholds with Numbers, Not Relative Comparatives
- [`outcome-narrow-but-discoverable`](references/outcome-narrow-but-discoverable.md) — Make the Outcome Narrow Enough to Audit, Broad Enough to Allow Discovery
- [`outcome-name-the-artifact`](references/outcome-name-the-artifact.md) — For Generated Artifacts, Name the Artifact and Its Validity Conditions

### 3. Verification Surface (CRITICAL)

- [`verify-name-the-surface`](references/verify-name-the-surface.md) — Always Name the Verification Surface Inside the Goal
- [`verify-include-constraints`](references/verify-include-constraints.md) — Include Constraints That Must Not Regress Alongside the Primary Metric
- [`verify-multiple-checks-when-needed`](references/verify-multiple-checks-when-needed.md) — Use Multiple Verification Surfaces When a Single Check Is Insufficient
- [`verify-surface-must-be-runnable`](references/verify-surface-must-be-runnable.md) — The Verification Surface Must Be Something Codex Can Actually Run or Inspect

### 4. Boundaries & Iteration (HIGH)

- [`bound-tools-and-files`](references/bound-tools-and-files.md) — Bound the Files, Tools, and Repositories Codex May Use
- [`bound-iteration-policy`](references/bound-iteration-policy.md) — Define an Iteration Policy — How Codex Chooses the Next Experiment Between Turns
- [`bound-blocked-stop-condition`](references/bound-blocked-stop-condition.md) — Define a Blocked Stop Condition — What to Report When No Defensible Path Remains
- [`bound-respect-budget`](references/bound-respect-budget.md) — Treat the Budget Limit as Halt-and-Summarize, Not Extend

### 5. Lifecycle Commands (HIGH)

- [`life-set-with-slash-goal`](references/life-set-with-slash-goal.md) — Set a Goal with `/goal <text>` — Available from Codex 0.128.0
- [`life-pause-during-detours`](references/life-pause-during-detours.md) — Pause the Goal Before Unrelated Detours, Resume When Returning
- [`life-clear-stale-goals`](references/life-clear-stale-goals.md) — Clear Stale Goals on Resumed Threads
- [`life-inspect-with-slash-goal`](references/life-inspect-with-slash-goal.md) — Use Bare `/goal` to Inspect Current Objective and State Before Continuation

### 6. Evidence-Based Completion (HIGH)

- [`evidence-audit-before-completion`](references/evidence-audit-before-completion.md) — Audit the Objective Against Concrete Evidence Before Marking a Goal Complete
- [`evidence-budget-is-not-completion`](references/evidence-budget-is-not-completion.md) — Reaching the Budget Limit Is Not the Same as Completing the Objective
- [`evidence-honest-blockers`](references/evidence-honest-blockers.md) — Surface Blockers Explicitly — Never Substitute a Proxy for the Asked Claim

### 7. Crafting Strong Goals (MEDIUM)

- [`craft-six-components`](references/craft-six-components.md) — Define Six Components in Every Strong Goal — Outcome, Verification, Constraints, Boundaries, Iteration Policy, Blocked Stop
- [`craft-template-pattern`](references/craft-template-pattern.md) — Use the Canonical "verified by … while preserving … Use … Between iterations … If blocked …" Pattern
- [`craft-let-codex-draft-it`](references/craft-let-codex-draft-it.md) — Ask Codex to Draft the Goal from a Plain-Language Description, Then Tighten
- [`craft-strengthen-weak-goals`](references/craft-strengthen-weak-goals.md) — Strengthen a Weak Goal by Naming the End State, Verification Surface, and Constraints

### 8. Research Goals & Anti-Patterns (MEDIUM)

- [`research-define-evidence-standard-first`](references/research-define-evidence-standard-first.md) — For Research Goals, Define the Evidence Standard Before Investigation Begins
- [`research-build-claim-inventory`](references/research-build-claim-inventory.md) — Decompose Research Goals into a Claim Inventory Mapped to Evidence Channels
- [`research-preserve-epistemic-ledger`](references/research-preserve-epistemic-ledger.md) — Final Report Must Preserve Epistemic Levels Per Claim — Use a Structured Ledger Entry
- [`research-anti-patterns`](references/research-anti-patterns.md) — Avoid the Three Common Goal Anti-Patterns — Keep-Going Wishes, Hidden Uncertainty, Overclaim on Proxy

## How to Use

Read individual reference files for detailed explanations and worked examples comparing weak vs strong Goal text:

- [Section definitions](references/_sections.md) — Category structure and impact levels
- [Rule template](assets/templates/_template.md) — Template for adding new rules

Each rule file contains:
- A 2-4 sentence explanation of WHY the rule matters
- An "Incorrect" example of a weak Goal or anti-pattern
- A "Correct" example showing how to strengthen it
- Reference back to the cookbook section it derives from

## Reference Files

| File | Description |
|------|-------------|
| [AGENTS.md](AGENTS.md) | Compiled TOC built by `build-agents-md.js` |
| [references/_sections.md](references/_sections.md) | Category definitions and impact ordering |
| [assets/templates/_template.md](assets/templates/_template.md) | Template for new rules |
| [metadata.json](metadata.json) | Version and reference information |
| [gotchas.md](gotchas.md) | Failure points discovered through use |

© pproenca · MIT · pproenca/dot-skills

Similar skills

All skills for Code review and refactoring →

From the same set139

The whole set →
expo-ios-hig expo-ios-hig is a Claude Code skill with Apple Human Interface Guidelines rules for screens, components, and navigation in Expo and React Native. CX Codex +1 169installs web-taste web-taste — a skill that makes the agent work out who the user is and what they need before it writes any React 19, Next.js 16 and Tailwind CSS. CX Codex +1 169installs typescript-advanced-patterns typescript-advanced-patterns — a TypeScript skill with 40 rules on type-level programming, library API design and deeper use of TS 5.x features. Useful once plain typings stop being enough. CX Codex +1 162installs react-hook-form-audit react-hook-form-audit scans a Next.js App Router project for 16 React Hook Form anti-patterns and writes a markdown report citing file:line. Read-only. CX Codex +1 158installs expo-design-system expo-design-system is a Claude Code skill for building and reviewing shared UI in Expo and React Native apps for web and iOS. It applies to tokens, themes, and reusable components. CX Codex +1 156installs complexity-optimizer complexity-optimizer detects algorithmic complexity bottlenecks in codebases and suggests safe runtime optimizations. CX Codex +1 156installs nextjs-bundle-optimizer nextjs-bundle-optimizer measures Next.js bundle size and build time, then checks optimizations one change at a time. Useful when First Load JS grows or production builds slow down. CX Codex +1 152installs implementation-design-patterns implementation-design-patterns is a Claude Code skill that identifies a Gang of Four pattern from a problem description and explains when to apply or avoid it. CX Codex +1 151installs

Project sponsors

Companies that keep this analytics open