Goal Writer

Goal Writer is a Codex Skill for turning rough long-running tasks into strong /goal prompts.

It helps Codex ask the right clarifying question, define an evidence-based finish line, and produce a compact Goal that can guide multi-turn work until the target is complete or honestly blocked.

Why This Exists

Codex Goals work best when the prompt defines a finish line that can be checked against concrete evidence. A vague instruction like "improve performance" leaves too much ambiguity around success, verification, and stopping conditions.

Goal Writer converts a rough request into a completion contract:

• outcome: what should be true at the end
• verification surface: what proves the outcome
• constraints: what must stay intact
• boundaries: what Codex may inspect, edit, run, or use
• iteration policy: how Codex should choose the next attempt
• blocked stop condition: what Codex should report when progress is blocked

The skill follows the Goal-writing pattern from OpenAI's Codex Goals guidance: durable objective, evidence-based finish line, bounded continuation, and explicit blocked reporting.

What It Does

Goal Writer can:

• turn a rough task into a ready-to-use /goal
• refine a weak Goal into a stronger auditable Goal
• ask one focused clarification question at a time
• stop after a small number of questions and report the remaining blocker
• recommend a normal prompt for simple one-turn tasks
• create Goals for coding, testing, performance, migration, research, experiments, docs, and review follow-through

Installation

Clone this repository into your Codex skills directory:

mkdir -p ~/.codex/skills
git clone https://github.com/muxuuu/goal-writer.git ~/.codex/skills/goal-writer

Restart Codex so the skill appears in the available skills list.

If you maintain a shared skills repository, copy the folder into that repository's skills/ directory:

cp -R goal-writer /path/to/Agent_Skills/skills/goal-writer

Quick Start

Ask Codex to use the skill:

Use $goal-writer to turn this into a strong /goal:
I want Codex to keep working on a flaky checkout test until it is fixed.

If the verification surface is missing, Goal Writer asks one question:

需要先确认一个关键点：用什么测试命令或连续通过标准判断这个 flaky checkout test 已经修好？

After the answer, it produces a Goal:

/goal Reproduce and fix the flaky checkout test so it passes 20 consecutive runs, verified by `npm test -- checkout`, while preserving checkout API behavior and existing correctness tests. Use the checkout test files, checkout service code, fixtures, and related logs. Between iterations, record the observed failure mode, hypothesis, change, and rerun result. If reproduction stays unavailable or valid paths are exhausted, stop with reproduction attempts, logs, most likely absent condition, blocker, and next input needed.

Readiness Gate

Goal Writer checks whether the task has enough information before drafting.

Required:

• outcome: the final state
• verification surface: the evidence that proves completion

Important:

• constraints: preserved behavior, APIs, quality bars, files, or results
• boundaries: allowed files, repositories, data, tools, commands, and sources
• blocked stop condition: what Codex reports when completion is blocked

Question policy:

• one question per turn
• highest-impact missing field first
• default limit of 3 questions
• after 3 questions, produce the strongest defensible Goal or identify the single missing item that blocks a defensible Goal

Goal Template

/goal <desired end state>, verified by <specific evidence>, while preserving <constraints>. Use <allowed inputs, tools, files, data, or repositories>. Between iterations, <how Codex should choose and report the next best action>. If blocked or valid paths are exhausted, stop with <attempted paths, evidence gathered, blocker, and next input needed>.

Examples

Performance

Input:

Use $goal-writer to make the checkout endpoint faster.

Likely clarification:

需要先确认一个关键点：用哪个 benchmark 或指标阈值判断 checkout endpoint 已经足够快？

Strong Goal:

/goal Reduce checkout p95 latency below 120 ms, verified by the checkout benchmark, while keeping the correctness suite green. Use the checkout service, benchmark fixtures, and related tests. Between iterations, record what changed, what the benchmark showed, and the next best experiment. If the benchmark is blocked or the threshold stays unreachable under current constraints, stop with attempted paths, evidence gathered, blocker, and required input.

Bug Hunt

Input:

Use $goal-writer to make Codex investigate why image upload fails in production-like local mode.

Strong Goal:

/goal Identify and fix the root cause of image upload failure in production-like local mode, verified by the local production-mode upload flow and a regression test, while preserving existing upload API behavior. Use the upload service, frontend upload path, local production config, logs, and related tests. Between iterations, move from reproduction to hypothesis to targeted fix to verification, recording evidence at each step. If blocked, stop with the closest reproduction, ruled-out hypotheses, blocker, and requested input.

Research Reproduction

Input:

Use $goal-writer to reproduce this paper as far as possible with available materials.

Strong Goal:

/goal Produce the strongest evidence-backed reproduction of the paper using available materials and local resources. Attempt the headline results where feasible, verify outputs where possible, and end with a report that separates confirmed findings, approximate reconstructions, blocked claims, and remaining uncertainty.

Documentation

Input:

Use $goal-writer to write docs for this feature.

Strong Goal:

/goal Produce a documentation page for the feature, verified by the local docs build and source-checked command examples, while keeping all referenced behavior accurate. Use the feature implementation, tests, existing docs style, and current CLI behavior. Between iterations, validate claims against source material and update the page. If source truth is missing, mark the claim unresolved and report the needed source.

Repository Structure

goal-writer/
├── SKILL.md
├── agents/
│   └── openai.yaml
├── references/
│   └── goal_patterns.md
├── LICENSE
└── README.md

SKILL.md contains the main workflow and readiness gate. references/goal_patterns.md contains reusable templates for common task types. agents/openai.yaml provides UI metadata for Codex skill listings.

Design Principles

Goal Writer is intentionally narrow:

• one default path: clarify, then write one recommended Goal
• low question count: one question per turn, default limit 3
• evidence first: verification surface gates drafting
• conservative completion: the final Goal defines how success and blockage are reported
• uncertainty preserved: research Goals separate confirmed findings, approximate support, blocked claims, and remaining uncertainty

Validation

Validate the skill frontmatter and file shape with the Codex skill creator validator when available:

python ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py ~/.codex/skills/goal-writer

If your Python environment lacks PyYAML, validate frontmatter with any YAML parser and check that:

• SKILL.md starts with valid YAML frontmatter
• name is goal-writer
• description is a single string
• agents/openai.yaml parses as YAML
• references/goal_patterns.md is present

Source

This skill is inspired by OpenAI's Codex Goals practice in the Cookbook:

https://developers.openai.com/cookbook/examples/codex/using_goals_in_codex

License

MIT. See LICENSE.