goal-prompt-builder

A Claude Skill for writing high-quality /goal prompts 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.

---

TL;DR

# 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]

---

What you get

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)
references/examples.md	~260	5 worked input→output transformations

Total ~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).

---

Why this exists

/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.

---

What the skill does

When triggered, Claude walks 6 steps: