Finishing a Development Branch
obra/superpowers
Walks the last step of a branch: confirm tests pass, detect the git environment, ask how to integrate, carry out your choice and clean up the worktree.
Patterns and anti-patterns for using OpenAI Codex Goals — the persistent objectives feature introduced in Codex 0.128.0.
Install Codex Goals
$ npx skills add pproenca/dot-skills --skill codex-goals -a claude-codeProject install by default; add -g for ~/.claude/skills/.
$ gh skill install pproenca/dot-skills codex-goals --agent claude-codeProject scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).
$ git clone --depth 1 https://github.com/pproenca/dot-skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/.experimental/codex-goals .claude/skills/codex-goals && rm -rf skills-srcUse ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.
Claude Code skills documentation · loads skills from .claude/skills/
Install the "codex-goals" agent skill from https://github.com/pproenca/dot-skills/tree/master/skills/.experimental/codex-goals into .claude/skills/codex-goals/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "codex-goals", then confirm the skill loads.Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$skill-installer install https://github.com/pproenca/dot-skills/tree/master/skills/.experimental/codex-goalsType this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.
$ npx skills add pproenca/dot-skills --skill codex-goals -a codexProject install goes to .agents/skills/; add -g for ~/.codex/skills/.
$ gh skill install pproenca/dot-skills codex-goals --agent codexProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/pproenca/dot-skills.git skills-src && mkdir -p .agents/skills && cp -r skills-src/skills/.experimental/codex-goals .agents/skills/codex-goals && rm -rf skills-srcUse ~/.agents/skills/ instead of .agents/skills for a personal install.
Codex skills documentation · loads skills from .agents/skills/
Install the "codex-goals" agent skill from https://github.com/pproenca/dot-skills/tree/master/skills/.experimental/codex-goals into .agents/skills/codex-goals/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "codex-goals", then confirm the skill loads.Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add pproenca/dot-skills --skill codex-goals -a cursorProject install goes to .agents/skills/; add -g for ~/.cursor/skills/.
$ gh skill install pproenca/dot-skills codex-goals --agent cursorProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/pproenca/dot-skills.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/skills/.experimental/codex-goals .cursor/skills/codex-goals && rm -rf skills-srcUse ~/.cursor/skills/ instead of .cursor/skills for a personal install.
Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/
Install the "codex-goals" agent skill from https://github.com/pproenca/dot-skills/tree/master/skills/.experimental/codex-goals into .cursor/skills/codex-goals/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "codex-goals", then confirm the skill loads.Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gemini skills install https://github.com/pproenca/dot-skills.git --path skills/.experimental/codex-goals--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.
$ npx skills add pproenca/dot-skills --skill codex-goals -a gemini-cliProject install goes to .agents/skills/; add -g for ~/.gemini/skills/.
$ gh skill install pproenca/dot-skills codex-goals --agent gemini-cliProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/pproenca/dot-skills.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/skills/.experimental/codex-goals .gemini/skills/codex-goals && rm -rf skills-srcUse ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.
Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/
Install the "codex-goals" agent skill from https://github.com/pproenca/dot-skills/tree/master/skills/.experimental/codex-goals into .gemini/skills/codex-goals/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "codex-goals", then confirm the skill loads.Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gh skill install pproenca/dot-skills codex-goalsInstalls for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).
$ npx skills add pproenca/dot-skills --skill codex-goals -a github-copilotProject install goes to .agents/skills/; add -g for ~/.copilot/skills/.
$ git clone --depth 1 https://github.com/pproenca/dot-skills.git skills-src && mkdir -p .github/skills && cp -r skills-src/skills/.experimental/codex-goals .github/skills/codex-goals && rm -rf skills-srcUse ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.
GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/
Install the "codex-goals" agent skill from https://github.com/pproenca/dot-skills/tree/master/skills/.experimental/codex-goals into .github/skills/codex-goals/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "codex-goals", then confirm the skill loads.GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add pproenca/dot-skills --skill codex-goals -a opencodeOpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.
$ gh skill install pproenca/dot-skills codex-goals --agent opencodeProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/pproenca/dot-skills.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/skills/.experimental/codex-goals .opencode/skills/codex-goals && rm -rf skills-srcUse ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.
OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/
Install the "codex-goals" agent skill from https://github.com/pproenca/dot-skills/tree/master/skills/.experimental/codex-goals into .opencode/skills/codex-goals/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "codex-goals", then confirm the skill loads.OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
Facts
- Skill name
codex-goals- GitHub stars
- 214
- Token cost
- ~2.1k tokens
- SKILL.md length
- 734 words
- Files
- 37 (incl. references, assets)
- Skills in repo
- 182
- Repo updated
- First seen
- Licence
- MIT
At a glance
Patterns and anti-patterns for using OpenAI Codex Goals — the persistent objectives feature introduced in Codex 0.128.0.
- Works in 8 steps: Goal Fit Decisions (CRITICAL) → Outcome Definition (CRITICAL) → Verification Surface (CRITICAL) → …
- Debugging a /goal invocation
- SKILL.md covers When to Apply, Rule Categories by Priority, Quick Reference and How to Use, plus 1 more section
- Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md
What it does
Codex Goals is an agent skill from pproenca/dot-skills. 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…
Its SKILL.md is about 2.1k tokens, which your agent loads only when the skill is triggered. The skill folder holds 39 other files, including reference files and assets (for example `AGENTS.md`, `assets/templates/_template.md` and `gotchas.md`).
It sits in Development. The repository describes itself as: A collection of AI agent skills following the Agent Skills open format. The licence is MIT.
When your agent uses it
- Debugging a /goal invocation
- Deciding whether a task should be a Goal at all
- Drafting a research Goal that needs an evidence ledger
- Diagnosing a Goal that completed against the wrong surface
Example prompts
- “Codex Goal”
- “Codex goals”
- “persistent objective”
- “/codex-goals”
Workflow steps
8 steps, taken from the step headings in SKILL.md.
What it can do on your machine
Read from SKILL.md and the folder at commit cf93c57. It shows what the files ask for, not the result of running them.
Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
No scripts in the folder and no shell commands in SKILL.md.
From the folder's file list and the shell code blocks in SKILL.md.
Network
Links to these hosts (documentation or services it may open):
developers.openai.com
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.
Context cost
Codex Goals loads about 2.1k tokens when it runs, and up to ~21k if it reads all its reference files. Until then it costs about 190 tokens; SKILL.md has 734 words of instructions outside code blocks.
Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.
Safety
Auto-check passed
The automated check found no risky patterns in SKILL.md.
Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.
SKILL.md
The full file from pproenca/dot-skills at commit cf93c57, republished under its MIT licence (© pproenca). 734 words, ~2,150 tokens.
Download SKILL.mdSave it as
.claude/skills/codex-goals/SKILL.md (or your agent's skills folder). This skill also uses 36 other files; get the full folder from GitHub.- 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".
When to Apply
Reference these guidelines when:
- Deciding whether a task warrants a
/goalor a normal prompt - Drafting or strengthening a
/goalinvocation - 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— Use a Goal When the Finish Line Is Clear but the Path Is Uncertainfit-three-required-properties— Require Three Properties Before Setting a Goal — Durable Objective, Evidence Finish Line, Multi-Turn Pathfit-prompt-vs-goal— Choose a Prompt for Single-Turn Work, a Goal for Outcome-Driven Continuationfit-skip-for-vague-targets— Skip a Goal When the Finish Line Is Vague
2. Outcome Definition (CRITICAL)
outcome-measurable-end-state— State the Outcome as a Measurable End State, Not an Activityoutcome-quantify-thresholds— Pin Thresholds with Numbers, Not Relative Comparativesoutcome-narrow-but-discoverable— Make the Outcome Narrow Enough to Audit, Broad Enough to Allow Discoveryoutcome-name-the-artifact— For Generated Artifacts, Name the Artifact and Its Validity Conditions
3. Verification Surface (CRITICAL)
verify-name-the-surface— Always Name the Verification Surface Inside the Goalverify-include-constraints— Include Constraints That Must Not Regress Alongside the Primary Metricverify-multiple-checks-when-needed— Use Multiple Verification Surfaces When a Single Check Is Insufficientverify-surface-must-be-runnable— The Verification Surface Must Be Something Codex Can Actually Run or Inspect
4. Boundaries & Iteration (HIGH)
bound-tools-and-files— Bound the Files, Tools, and Repositories Codex May Usebound-iteration-policy— Define an Iteration Policy — How Codex Chooses the Next Experiment Between Turnsbound-blocked-stop-condition— Define a Blocked Stop Condition — What to Report When No Defensible Path Remainsbound-respect-budget— Treat the Budget Limit as Halt-and-Summarize, Not Extend
Show full SKILL.md (307 more words)Show less
5. Lifecycle Commands (HIGH)
life-set-with-slash-goal— Set a Goal with/goal <text>— Available from Codex 0.128.0life-pause-during-detours— Pause the Goal Before Unrelated Detours, Resume When Returninglife-clear-stale-goals— Clear Stale Goals on Resumed Threadslife-inspect-with-slash-goal— Use Bare/goalto Inspect Current Objective and State Before Continuation
6. Evidence-Based Completion (HIGH)
evidence-audit-before-completion— Audit the Objective Against Concrete Evidence Before Marking a Goal Completeevidence-budget-is-not-completion— Reaching the Budget Limit Is Not the Same as Completing the Objectiveevidence-honest-blockers— Surface Blockers Explicitly — Never Substitute a Proxy for the Asked Claim
7. Crafting Strong Goals (MEDIUM)
craft-six-components— Define Six Components in Every Strong Goal — Outcome, Verification, Constraints, Boundaries, Iteration Policy, Blocked Stopcraft-template-pattern— Use the Canonical "verified by … while preserving … Use … Between iterations … If blocked …" Patterncraft-let-codex-draft-it— Ask Codex to Draft the Goal from a Plain-Language Description, Then Tightencraft-strengthen-weak-goals— Strengthen a Weak Goal by Naming the End State, Verification Surface, and Constraints
8. Research Goals & Anti-Patterns (MEDIUM)
research-define-evidence-standard-first— For Research Goals, Define the Evidence Standard Before Investigation Beginsresearch-build-claim-inventory— Decompose Research Goals into a Claim Inventory Mapped to Evidence Channelsresearch-preserve-epistemic-ledger— Final Report Must Preserve Epistemic Levels Per Claim — Use a Structured Ledger Entryresearch-anti-patterns— 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 — Category structure and impact levels
- Rule template — 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 | Compiled TOC built by build-agents-md.js |
| references/_sections.md | Category definitions and impact ordering |
| assets/templates/_template.md | Template for new rules |
| metadata.json | Version and reference information |
| gotchas.md | Failure points discovered through use |
© pproenca, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file
Files
SKILL.md and 36 other files (references, assets) in skills/.experimental/codex-goals of pproenca/dot-skills.
- SKILL.md
- AGENTS.md
- assets/templates/_template.md
- gotchas.md
- metadata.json
- references/_sections.md
- references/bound-blocked-stop-condition.md
- references/bound-iteration-policy.md
- references/bound-respect-budget.md
- references/bound-tools-and-files.md
- references/craft-let-codex-draft-it.md
- references/craft-six-components.md
- references/craft-strengthen-weak-goals.md
- references/craft-template-pattern.md
- references/evidence-audit-before-completion.md
- references/evidence-budget-is-not-completion.md
- references/evidence-honest-blockers.md
- references/fit-prompt-vs-goal.md
- … and 19 more
Open the folder on GitHubat commit cf93c57
Compare with similar skills
Codex Goals next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.
| Skill | Stars | Used in | Tokens | Auto-check | Licence | Repo updated |
|---|---|---|---|---|---|---|
| Codex Goals this skillpproenca/dot-skills | 214 | — | ~2.1k | Automated safety check: Pass | MIT | |
| Finishing a Development Branchobra/superpowers | 296k | 5 repos | ~1.9k | Automated safety check: Pass | MIT | |
| Typescript Advanced Typesrolling-scopes/rsschool-app | 10k | 24 repos | ~4.2k | Automated safety check: Pass | MPL-2.0 | |
| PR Babysitteropeninterpreter/openinterpreter | 69k | 3 repos | ~4.2k | Automated safety check: Pass | Apache-2.0 | |
| Code Review ChecklistshareAI-lab/learn-claude-code | 78k | 5 repos | ~1.1k | Automated safety check: Pass | MIT | |
| Greplooponyx-dot-app/onyx | 32k | 4 repos | ~3.3k | Automated safety check: Pass | MIT |
Similar skills
Typescript Advanced Types
rolling-scopes/rsschool-app
Master TypeScript's advanced type system including generics, conditional types, mapped types, template literals, and utility types for building type-safe applications.
PR Babysitter
openinterpreter/openinterpreter
Watches an open GitHub pull request until it merges, handling review comments, diagnosing CI failures and retrying flaky checks along the way.
Code Review Checklist
shareAI-lab/learn-claude-code
Reviews code against a five-part checklist covering security, correctness, performance, maintainability and testing, and reports findings in a fixed format.
Greploop
onyx-dot-app/onyx
Iteratively improves a PR (GitHub), MR (GitLab), or shelved changelist (Perforce) until Greptile gives it a 5/5 confidence score with zero unresolved comments.
Guidelines
akash-network/node
Behavioral guidelines to reduce common LLM coding mistakes. An agent skill from akash-network/node.
More from pproenca/dot-skills
All 182 skills in this repoAudio Voice Recovery
pproenca/dot-skills
Audio forensics and voice recovery guidelines for CSI-level audio analysis.
Codemod React Pipeline
pproenca/dot-skills
Guided, scripted pipeline for running JSX/TSX/React codemods safely across large legacy codebases.
Dev Rfc
pproenca/dot-skills
Create well-structured RFCs and technical proposals for software projects.
Dx Harness
pproenca/dot-skills
Developer-experience friction auditing and fixing — slow onboarding, repeated manual setup steps, missing bootstrap/reset/seed scripts, undiscoverable conventions.
Language Spec Author
pproenca/dot-skills
Turn a rough idea for a language into a complete, implementable specification — a DSL, query, config/data, template, or protocol language — by interviewing the author dimension by dimension until…
Python Pep Author
pproenca/dot-skills
Drafting Python Enhancement Proposals (PEPs) — proposing a Python language feature, a standard library change, an interoperability standard, or an informational/process document for the Python…
Related
Categories
Questions about Codex Goals
What does Codex Goals do?
Patterns and anti-patterns for using OpenAI Codex Goals — the persistent objectives feature introduced in Codex 0.128.0. Codex Goals is an agent skill from pproenca/dot-skills.0.
When should I use Codex Goals?
Codex Goals fits situations like: debugging a /goal invocation; deciding whether a task should be a Goal at all; drafting a research Goal that needs an evidence ledger; diagnosing a Goal that completed against the wrong surface.
How do I install Codex Goals in Claude Code?
Run `npx skills add pproenca/dot-skills --skill codex-goals -a claude-code`. Or copy the skill folder (skills/.experimental/codex-goals in pproenca/dot-skills) into .claude/skills/codex-goals in your project. Claude Code loads it when a task matches its description.
How do I install Codex Goals in Codex?
Run `npx skills add pproenca/dot-skills --skill codex-goals -a codex`. Or copy the skill folder (skills/.experimental/codex-goals in pproenca/dot-skills) into .agents/skills/codex-goals in your project. Codex loads it when a task matches its description.
Can I use Codex Goals in Cursor, Gemini CLI or GitHub Copilot?
Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add pproenca/dot-skills --skill codex-goals -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/codex-goals, .gemini/skills/codex-goals, .github/skills/codex-goals and .opencode/skills/codex-goals in your project.
What does Codex Goals need to run?
SKILL.md names no scripts, command-line tools or credentials: Codex Goals is instructions for the agent only.
Does Codex Goals access the network?
SKILL.md names 1 domain. As links in the text: developers.openai.com. This is read from the text; nothing was executed.
Is Codex Goals safe to install?
Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.
What licence does Codex Goals use?
Codex Goals is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.
How many tokens does Codex Goals use?
About 2.1k tokens (SKILL.md is roughly 8.6k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 19k tokens, read only when the agent opens those files.
What are the alternatives to Codex Goals?
Skills that share tags, products or a category with Codex Goals: Finishing a Development Branch (obra/superpowers, 296k stars), Typescript Advanced Types (rolling-scopes/rsschool-app, 10k stars), PR Babysitter (openinterpreter/openinterpreter, 69k stars) and Code Review Checklist (shareAI-lab/learn-claude-code, 78k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.
Who maintains Codex Goals?
pproenca (a GitHub user) maintains it in pproenca/dot-skills, which has 214 GitHub stars. The repository holds 182 skills in this directory. The repository was last updated on August 15, 2026.
Source: pproenca/dot-skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.