Skip to content
Back to search

goal-prompt-builder

Build audit-friendly /goal prompts for OpenAI Codex

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/win4r-goal-prompt-builder/badge.svg)](/listings/win4r-goal-prompt-builder)

HTML

<a href="/listings/win4r-goal-prompt-builder"><img src="/api/listings/win4r-goal-prompt-builder/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Option 1: One-line install (Claude Code / Claude.ai with skill support)

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

Option 2: Clone and link

git clone https://github.com/win4r/goal-prompt-builder.git
ln -s "$(pwd)/goal-prompt-builder/goal-prompt-builder" ~/.claude/skills/goal-prompt-builder

Option 3: Manual

Download `goal-prompt-builder.skill` from [the latest release](https://github.com/win4r/goal-prompt-builder/releases) (or copy the `goal-prompt-builder/` folder from this repo) into your Claude skills directory:

- **Claude Code**: `~/.claude/skills/` - **Claude Desktop**: see [Anthropic's docs](https://docs.claude.com) - **Cursor / other clients**: check the client's documentation for skill paths

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 359 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # [🚀观看我的哔哩哔哩视频](https://space.bilibili.com/3493277319825652)
  2. # goal-prompt-builder
  3. > **A Claude Skill for writing high-quality `/goal` prompts that don't go off the rails.**
  4. [简体中文](./README_CN.md) · English
  5. ---
  6. 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**.
  7. 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.
  8. 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.
  9. ---
  10. ## TL;DR
  11. ```bash
  12. # Install (one-time)
  13. curl -L -o /tmp/goal-prompt-builder.skill \
  14. https://github.com/win4r/goal-prompt-builder/raw/main/goal-prompt-builder.skill
  15. mkdir -p ~/.claude/skills && unzip -o /tmp/goal-prompt-builder.skill -d ~/.claude/skills/
  16. # Use (in any Claude conversation)
  17. You: help me write a /goal for refactoring the auth module
  18. Claude: [skill triggers, walks you through 6 steps, outputs a paste-ready /goal]
  19. ```
  20. ---
  21. ## What you get
  22. A `.skill` bundle containing:
  23. | File | Lines | Purpose |
  24. |---|---|---|
  25. | `SKILL.md` | ~250 | Main routing logic + 6-step workflow |
  26. | `references/project-types.md` | ~260 | Defaults for Node / Python / Swift / Go / Rust / static |
  27. | `references/scenarios.md` | ~330 | Skeletons for 7 scenarios (refactor / feature / batch / archaeology / UI audit / gatekeeper / custom) |
  28. | `references/examples.md` | ~260 | 5 worked input→output transformations |
  29. 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).
  30. ---
  31. ## Why this exists
  32. `/goal` ships with a built-in audit prompt (`continuation.md`) that runs after every idle boundary. It tells the model:
  33. > 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.**
  34. 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.**
  35. Most users write goals like:
  36. ```
  37. /goal Fix all the flaky tests and clean up the codebase
  38. ```
  39. 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.
  40. This skill exists to make sure your goal text is **always** mappable to a real audit checklist.
  41. ---
  42. ## What the skill does
  43. When triggered, Claude walks 6 steps:
  44. 1. **Pick interaction mode** — step-by-step, full-description, or hybrid (default)
  45. 2. **Auto-detect project type** — by inspecting filesystem (`package.json`, `Cargo.toml`, `*.xcodeproj`, etc.) or fetching repo URL. Reads `AGENTS.md` / `CLAUDE.md` if present.
  46. 3. **Pick scenario template** — 7 templates (refactor / SDD feature / batch / archaeology / UI audit / gatekeeper / custom)
  47. 4. **Gather 5 inputs** — Objective / Scope / Constraints / Done when / Stop if
  48. 5. **Predict audit-friendliness** — internal scoring; refuses to render if too vague
  49. 6. **Render** — copy-pasteable `/goal` + brief design rationale
  50. Output looks like:
  51. ```
  52. /goal <objective>.
  53. First action: [if SDD-driven] read X, Y, Z and report counts. Wait for ack.
  54. Scope: <files / subsystem>.
  55. Constraints:
  56. - <project-type-specific defaults>
  57. - <rules from AGENTS.md / CLAUDE.md>
  58. Done when:
  59. 1. <verifiable artifact 1 — cite file or command>
  60. 2. <verifiable artifact 2>
  61. ...
  62. Stop if:
  63. - <mechanically detectable condition 1>
  64. ...
  65. Use a token budget of <N> tokens for this goal.
  66. ```
  67. ---
  68. ## Installation
  69. ### Option 1: One-line install (Claude Code / Claude.ai with skill support)
  70. ```bash
  71. curl -L -o /tmp/goal-prompt-builder.skill \
  72. https://github.com/win4r/goal-prompt-builder/raw/main/goal-prompt-builder.skill
  73. mkdir -p ~/.claude/skills
  74. unzip -o /tmp/goal-prompt-builder.skill -d ~/.claude/skills/
  75. rm /tmp/goal-prompt-builder.skill
  76. ```
  77. ### Option 2: Clone and link
  78. ```bash
  79. git clone https://github.com/win4r/goal-prompt-builder.git
  80. ln -s "$(pwd)/goal-prompt-builder/goal-prompt-builder" ~/.claude/skills/goal-prompt-builder
  81. ```
  82. ### Option 3: Manual
  83. Download `goal-prompt-builder.skill` from [the latest release](https://github.com/win4r/goal-prompt-builder/releases) (or copy the `goal-prompt-builder/` folder from this repo) into your Claude skills directory:
  84. - **Claude Code**: `~/.claude/skills/`
  85. - **Claude Desktop**: see [Anthropic's docs](https://docs.claude.com)
  86. - **Cursor / other clients**: check the client's documentation for skill paths
  87. ---
  88. ## Usage
  89. Once installed, the skill triggers automatically on phrases like:
  90. - "help me write a /goal for ..."
  91. - "design a goal for X"
  92. - "make a /goal command for this repo"
  93. - "review my goal command"
  94. - "I want to use /goal to ..."
  95. - (any mention of long-running Codex tasks)
  96. You don't need to type "use the goal-prompt-builder skill" — Claude will pick it up.
  97. ### Example session
  98. ```
  99. You: I want to use /goal to add Cohere rerank as a 5th provider to my retrieval pipeline.
  100. Claude (with skill loaded): I'll help you build that. First — interaction mode?
  101. A. Step-by-step (safest)
  102. B. Full description (fastest)
  103. C. Hybrid (default, recommended)
  104. You: C
  105. Claude: [auto-detects Node/TS project from package.json, reads AGENTS.md]
  106. Detected: Node/TypeScript project. Found AGENTS.md with 3 iron rules.
  107. This sounds like a "feature implementation" scenario. Do you have a SDD spec
  108. already, or should we go with a freeform feature template?
  109. You: I have an OpenSpec change at openspec/changes/add-cohere-rerank/
  110. Claude: Perfect — that maps to scenario B (SDD-driven feature). A few questions:
  111. 1. Token budget? (suggest 120K based on scope)
  112. 2. Anything in AGENTS.md that I should pull into Constraints I might miss?
  113. ...
  114. [after a few rounds]
  115. Claude: Audit-friendliness: 94/100. Here's your /goal:
  116. ```
  117. /goal Implement openspec/changes/add-cohere-rerank/ exactly as specified.
  118. First action: read the 4 spec files + AGENTS.md and report counts.
  119. Wait for my acknowledgment before implementation.
  120. Scope: design.md "MUST NOT modify" list strictly enforced.
  121. Constraints:
  122. - AGENTS.md iron rules are non-negotiable
  123. - No new npm dependencies
  124. - Mirror the existing 4 rerank providers' code style
  125. Done when:
  126. 1. Each task in tasks.md checked off, cite file path + commit
  127. 2. Each SHALL has a passing test, cite test name
  128. 3. Each GIVEN/WHEN/THEN scenario covered by integration test
  129. 4. `npx tsc --noEmit` exits 0
  130. 5. `npm test` exits 0; paste summary
  131. 6. README.md updated with new provider row
  132. 7. CHANGELOG.md has Unreleased entry
  133. Stop if:
  134. - A task requires modifying a MUST NOT file
  135. - SHALLs conflict (escalate, don't decide)
  136. - npm install needed for new dep
  137. - Existing rerank provider tests fail
  138. - jiti cache wasn't cleared before plugin tests
  139. Use a token budget of 120000 tokens.
  140. ```
  141. Key design choices:
  142. - First action enforces read+report — sidesteps `@filename` ref uncertainty
  143. - Each AGENTS.md rule maps to both Constraint AND Stop-if (defense in depth)
  144. - jiti cache rule pulled from CLAUDE.md — easily missed false-completion source
  145. You: [pastes into Codex CLI, walks away for 3 hours, comes back to a green PR]
  146. ```
  147. ---
  148. ## Why three interaction modes?
  149. | Mode | When to use | Time to render |
  150. |---|---|---|
  151. | **A. Step-by-step** | First time using `/goal`; high-stakes refactor | ~5 min |
  152. | **B. Full description** | You've thought through the task; want speed | ~1 min |
  153. | **C. Hybrid** | Daily use; balanced safety + speed | ~2-3 min |
  154. 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.
  155. ---
  156. ## Why auto-detect project type?
  157. Because the **Stop if** section is where most goals fail — and Stop-if rules are heavily project-type-specific:
  158. - Swift project? Add "do not modify `project.pbxproj`" (PBXFileSystemSynchronizedRootGroup will pick up new files automatically)
  159. - Node project? Add "no `npm install` for new deps"
  160. - Python project? Add "no new entries in `requirements.txt`"
  161. - iOS project with iPhone simulators? Add "halt if iPhone N simulator unavailable, run `xcrun simctl list` and let me decide"
  162. Without auto-detection, the user has to remember these. With auto-detection, the skill loads the right defaults silently.
  163. The detection priority:
  164. 1. Filesystem probe — `ls` for telltale files (`package.json`, `Cargo.toml`, etc.)
  165. 2. URL fetch — if user gave a GitHub link, fetch the README
  166. 3. Read `AGENTS.md` / `CLAUDE.md` if present (these contain project-specific rules that override defaults)
  167. 4. Fallback — ask the user
  168. If detection succeeds, the skill **announces what it found** so you can correct it before proceeding.
  169. ---
  170. ## What the skill does NOT do
  171. - ❌ Does not run `/goal` for you — only generates the prompt text
  172. - ❌ Does not validate your project state (no `git status` checks, no test runs)
  173. - ❌ Does not handle Codex versions older than 0.128 (`/goal` doesn't exist there)
  174. - ❌ Does not generate prompts for `/plan`, `/compact`, or other Codex slash commands
  175. ---
  176. ## Hard rules baked into the skill
  177. These come from analyzing Codex's actual `continuation.md` audit prompt:
  178. 1. **Reject vague verbs** — "improve", "optimize", "clean up", "all", "everything", "全部", "彻底" trigger pushback
  179. 2. **Force token budgets** — missing budget = no soft stop = potential runaway
  180. 3. **Force regression guards** — any goal touching tested code gets a "do not edit tests to make them pass" stop-if
  181. 4. **Force read+report first** for SDD-driven goals — sidesteps `@filename` reference uncertainty
  182. 5. **Force "MUST NOT modify" probing** for brownfield projects — #1 cause of scope creep
  183. 6. **Refuse to render** if audit-friendliness score < 70%
  184. The full rule set is in `goal-prompt-builder/SKILL.md` under "Hard rules".
  185. ---
  186. ## Compatibility
  187. - **Codex CLI**: 0.128.0+ (where `/goal` exists)
  188. - **Claude**: any client that supports Claude Skills (Claude Code, Claude Desktop, Claude.ai with skill support)
  189. - **Project types tested**: Node, Python, Swift / iOS, Go, Rust, static / docs sites
  190. - **Languages**: skill is bilingual (English + Chinese); generates prompts in either based on user input
  191. ---
  192. ## Repository structure
  193. ```
  194. goal-prompt-builder/
  195. ├── README.md (this file)
  196. ├── README_CN.md (中文版)
  197. ├── LICENSE (MIT)
  198. ├── goal-prompt-builder.skill (packaged, ready to install)
  199. └── goal-prompt-builder/ (source)
  200. ├── SKILL.md (main skill — routing + 6-step workflow)
  201. └── references/
  202. ├── project-types.md (per-language defaults)
  203. ├── scenarios.md (7 scenario skeletons)
  204. └── examples.md (5 worked examples)
  205. ```
  206. ---
  207. ## Updating
  208. The `.skill` file is just a zip of the `goal-prompt-builder/` folder. To rebuild after editing:
  209. ```bash
  210. cd goal-prompt-builder
  211. zip -r goal-prompt-builder.skill goal-prompt-builder/ \
  212. -x "*.DS_Store" "*__pycache__*"
  213. ```
  214. Or use Anthropic's official `package_skill.py` from the [skill-creator skill](https://github.com/anthropics/skills) for validation + packaging in one step.
  215. ---
  216. ## Background reading
  217. If you want to understand *why* the skill is shaped the way it is:
  218. - **Codex 0.128 changelog** — official `/goal` announcement
  219. - **PR #18073-#18077** — the 5-PR stack that built `/goal`
  220. - **`continuation.md` template** — the audit prompt that runs every idle boundary ([commit `6014b66`](https://github.com/openai/codex))
  221. - **Issue #20536** — `/goal` documentation gap
  222. - **Issue #20656** — Plan-mode silently suppresses goal continuation
  223. - **Issue #20792** — `/goal`-first sessions missing from `codex resume` lists
  224. - **Issue #19910** — mid-turn `/compact` loses goal context
  225. - **Simon Willison's writeup** — the best public explainer (Apr 30, 2026)
  226. ---
  227. ## License
  228. MIT — see [LICENSE](./LICENSE). Use it however you want, including commercially.
  229. ---
  230. ## Contributing
  231. PRs welcome, especially:
  232. - New project type defaults (Elixir, Ruby, Java, Kotlin, etc.)
  233. - New scenario skeletons not covered by the current 7
  234. - Worked examples from your real production goals
  235. - Translation of `SKILL.md` into other languages (Japanese, Korean, etc.)
  236. For bugs or proposed changes to the core 6-step workflow, please open an issue first to discuss.
  237. ---
  238. ## Related
  239. - **OpenAI Codex** — [github.com/openai/codex](https://github.com/openai/codex)
  240. - **OpenSpec** — pairs beautifully with this skill ([openspec.dev](https://openspec.dev))
  241. - **GitHub Spec Kit** — alternative SDD tool ([github.com/github/spec-kit](https://github.com/github/spec-kit))
  242. - **Anthropic Skill Creator** — the official skill that builds skills
  243. ---
  244. *Built for developers who got tired of `/goal` jobs running 4 hours and producing the wrong thing.*

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.