by win4r
Build audit-friendly /goal prompts for OpenAI Codex
# Add to your Claude Code skills
git clone https://github.com/win4r/goal-prompt-builderGuides for using cli tools skills like goal-prompt-builder.
A Claude Skill for writing high-quality
/goalprompts that don't go off the rails.
简体中文 · English
OpenAI Codex CLI 0.128 introduced /goal — a persistent agent objective with runtime audit, token budget, and a soft-stop state machine. It can drive a single task for 20+ hours unattended.
But it has one ugly failure mode: write the goal vaguely, and Codex will burn 100K tokens going in the wrong direction, then declare success.
This skill makes that failure mode hard to hit. It walks Claude (or you) through a 5-section golden template (Objective / Scope / Constraints / Done when / Stop if), auto-detects your project type, reads your AGENTS.md / CLAUDE.md, and predicts audit-friendliness before you run the command.
# Install (one-time)
curl -L -o /tmp/goal-prompt-builder.skill \
https://github.com/win4r/goal-prompt-builder/raw/main/goal-prompt-builder.skill
mkdir -p ~/.claude/skills && unzip -o /tmp/goal-prompt-builder.skill -d ~/.claude/skills/
# Use (in any Claude conversation)
You: help me write a /goal for refactoring the auth module
Claude: [skill triggers, walks you through 6 steps, outputs a paste-ready /goal]
A .skill bundle containing:
| File | Lines | Purpose |
|---|---|---|
| SKILL.md | ~250 | Main routing logic + 6-step workflow |
| references/project-types.md | ~260 | Defaults for Node / Python / Swift / Go / Rust / static |
| references/scenarios.md | ~330 | Skeletons for 7 scenarios (refactor / feature / batch / archaeology / UI audit / gatekeeper / custom) |
| | ~260 | 5 worked input→output transformations |
No comments yet. Be the first to share your thoughts!
Top skills in this category by stars
references/examples.mdTotal ~1100 lines of carefully designed prompt engineering — distilled from Codex's actual continuation.md audit prompt, the /goal PR stack (#18073-#18077), and the public issue tracker (#19910, #20656, #20792, #20536).
/goal ships with a built-in audit prompt (continuation.md) that runs after every idle boundary. It tells the model:
Build a prompt-to-artifact checklist that maps every explicit requirement, numbered item, named file, command, test, gate, and deliverable to concrete evidence. Treat uncertainty as not achieved.
This is one of the strongest anti-sandbagging mechanisms ever shipped in an AI coding tool. But it only works if your goal text can be mapped to a checklist.
Most users write goals like:
/goal Fix all the flaky tests and clean up the codebase
The audit can't construct a checklist from "all" or "clean up" — so it falls back to proxy signals like "tests passed" (which can mean "I ran them once and they didn't crash"). Result: the model declares done, you wake up to broken code.
This skill exists to make sure your goal text is always mappable to a real audit checklist.
When triggered, Claude walks 6 steps:
package.json, Cargo.toml, *.xcodeproj, etc.) or fetching repo URL. Reads AGENTS.md / CLAUDE.md if present./goal + brief design rationaleOutput looks like:
/goal <objective>.
First action: [if SDD-driven] read X, Y, Z and report counts. Wait for ack.
Scope: <files / subsystem>.
Constraints:
- <project-type-specific defaults>
- <rules from AGENTS.md / CLAUDE.md>
Done when:
1. <verifiable artifact 1 — cite file or command>
2. <verifiable artifact 2>
...
Stop if:
- <mechanically detectable condition 1>
...
Use a token budget of <N> tokens for this goal.
curl -L -o /tmp/goal-prompt-builder.skill \
https://github.com/win4r/goal-prompt-builder/raw/main/goal-prompt-builder.skill
mkdir -p ~/.claude/skills
unzip -o /tmp/goal-prompt-builder.skill -d ~/.claude/skills/
rm /tmp/goal-prompt-builder.skill
git clone https://github.com/win4r/goal-prompt-builder.git
ln -s "$(pwd)/goal-prompt-builder/goal-prompt-builder" ~/.claude/skills/goal-prompt-builder
Download goal-prompt-builder.skill from the latest release (or copy the goal-prompt-builder/ folder from this repo) into your Claude skills directory:
~/.claude/skills/Once installed, the skill triggers automatically on phrases like:
You don't need to type "use the goal-prompt-builder skill" — Claude will pick it up.
You: I want to use /goal to add Cohere rerank as a 5th provider to my retrieval pipeline.
Claude (with skill loaded): I'll help you build that. First — interaction mode?
A. Step-by-step (safest)
B. Full description (fastest)
C. Hybrid (default, recommended)
You: C
Claude: [auto-detects Node/TS project from package.json, reads AGENTS.md]
Detected: Node/TypeScript project. Found AGENTS.md with 3 iron rules.
This sounds like a "feature implementation" scenario. Do you have a SDD spec
already, or should we go with a freeform feature template?
You: I have an OpenSpec change at openspec/changes/add-cohere-rerank/
Claude: Perfect — that maps to scenario B (SDD-driven feature). A few questions:
1. Token budget? (suggest 120K based on scope)
2. Anything in AGENTS.md that I should pull into Constraints I might miss?
...
[after a few rounds]
Claude: Audit-friendliness: 94/100. Here's your /goal:
/goal Implement openspec/changes/add-cohere-rerank/ exactly as specified.
First action: read the 4 spec files + AGENTS.md and report counts. Wait for my acknowledgment before implementation.
Scope: design.md "MUST NOT modify" list strictly enforced.
Constraints:
Done when:
npx tsc --noEmit exits 0npm test exits 0; paste summaryStop if:
Use a token budget of 120000 tokens.
Key design choices:
- First action enforces read+report — sidesteps `@filename` ref uncertainty
- Each AGENTS.md rule maps to both Constraint AND Stop-if (defense in depth)
- jiti cache rule pulled from CLAUDE.md — easily missed false-completion source
You: [pastes into Codex CLI, walks away for 3 hours, comes back to a green PR]
| Mode | When to use | Time to render |
|---|---|---|
| A. Step-by-step | First time using /goal; high-stakes refactor | ~5 min |
| B. Full description | You've thought through the task; want speed | ~1 min |
| C. Hybrid | Daily use; balanced safety + speed | ~2-3 min |
The interaction mode affects how the skill collects your input, not the quality of the output. All three produce equally audit-friendly goals when you give them equal information.
Because the Stop if section is where most goals fail — and Stop-if rules are heavily project-type-specific:
project.pbxproj" (PBXFileSystemSynchronizedRootGroup will pick up new files automatically)npm install for new deps"requirements.txt"xcrun simctl list and let me decide"Without auto-detection, the user has to remember these. With auto-detection, the skill loads the right defaults silently.
The detection priority:
ls for telltale files (package.json, Cargo.toml, etc.)AGENTS.md / CLAUDE.md if present (these contain project-specific rules that override defaults)If detection succeeds, the skill announces what it found so you can correct it before proceeding.
/goal for you — only generates the prompt textgit status checks, no test runs)/goal doesn't exist there)/plan, /compact, or other Codex slash commandsThese come from analyzing Codex's actual continuation.md audit prompt: