Preface¶

The most common way for AI programming assistants to go off the rails when modifying code is not that the model “can’t write code”, but that the original requirement itself is too vague. Phrases like “make the checkout API faster”, “look at this PR review comment”, or “keep troubleshooting” sound like tasks, but are actually just activity descriptions: there is no verifiable completion state, no evidence, and no scope boundaries. Agents often end up modifying a bunch of files first, then come back to ask you “does this count as done?”

OpenAI provides a curated Skill in its official Agent Skills repository: define-goal. Its responsibility is very narrow—it only takes vague intentions and turns them into specific, measurable, verifiable goals before starting work, and registers them via goal tools when needed. This article introduces what it is, how to install it, and how to use it, based on the official SKILL.md and related Codex Goals documentation.

What is it¶

define-goal is a curated Skill maintained by OpenAI, with its source code directory at:
https://github.com/openai/skills/tree/main/skills/.curated/define-goal

The main files in the directory are SKILL.md (workflow and quality standards), agents/openai.yaml (display name and default prompt for Codex), and the Apache 2.0 licensed LICENSE.txt. The frontmatter name of the Skill is define-goal, and its description roughly means: it helps define specific, measurable goals when the user requests to create a goal, clarify success criteria, or turn vague intentions into quantifiable results. It is only responsible for goal creation and refinement, not persistent snapshots, decision logs, or long-cycle execution artifacts.

It is paired with Codex’s Goals capability. Codex has supported persistent Goals since version 0.128.0: users can manage the lifecycle with /goal, and the model side has tools like get_goal / create_goal. define-goal formalizes the workflow of “first refine the goal to meet standards, then use create_goal” into a reusable process, avoiding creating a vague goal right off the bat.

Note: The README of the openai/skills repository has marked this repository as deprecated, and points to OpenAI Plugins as the current entry point for Codex skill/plugin examples; but as of the writing of this article, define-goal can still be viewed and installed directly at the aforementioned curated path. Agent Skills themselves use the universal SKILL.md format, and tools that support this standard such as Cursor, Claude Code, and Codex CLI can all load the same set of documentation; among them, get_goal / create_goal belong to the Codex Goals toolset, and other environments mainly reuse the part of the workflow that “refines the goal to meet standards”.

Core Workflow¶

The official SKILL.md splits the process into six clear steps:

Confirm whether goal-setting is actually needed.
Follow this workflow only when the user explicitly mentions $define-goal, wants to create/set a goal, intends to use goal tools, or wishes to refine their intent into a clear goal. If the user just requests a normal implementation (fix a bug, add a small feature), proceed directly with the work without force-inserting a goal creation step.
Restate the goal in concrete language.
A usable goal must at least clarify: what will be true upon completion; which deliverable, system, repository, environment, or user-facing behavior is involved; how to verify completion; what is within scope; when ambiguity would affect the outcome, what is outside the scope; and under what circumstances you should stop and ask the user instead of continuing blindly.
Quantify whenever possible.
Prioritize writing numbers or binary conditions that represent real success, rather than decorative precision. The official examples of several types of evidence include:
- Pass/fail validation: specific tests, checks, CI jobs, evals, commands, or acceptance criteria
- Quality thresholds: latency, error rate, cost, accuracy/recall/precision, coverage, flaky rate, package size, memory, availability, completion rate, or manual review standards
- Deliverable constraints: file paths, affected modules, allowed commands, output formats, target environments, deadlines, maximum scope of changes
- Evidence counts: number of reproductions, consecutive successful reruns, number of reviewed samples, number of migration records, number of processed comments, number of verified use cases
Refine weak goals before setting them.
When you have sufficient local context, rewrite vague goals into measurable ones; when missing details would change the outcome or validation method, only ask one short clarifying question. Pure activity-based expressions—“make some progress”, “keep investigating”, “improve something”, “tweak X”—should be rejected as goals unless they can be sharpened into verifiable results.
Check the current goal state before creating.
First call get_goal. If there is no active goal and the quality meets the standard, then use create_goal; if there is an existing goal that still matches the user’s intent, continue using it without recreating it; if the existing goal conflicts with the new request, ask the user: should we first complete the current goal, mark it as completed if it already is, or start a new goal-backed thread.
Create the goal only after it meets quality standards.
The goal should use a concise objective string; write verification evidence into the goal itself; write constraints into the scope; only include a token budget when the user explicitly requests it. Do not arbitrarily use create_goal just because a task has multiple steps when the user has not explicitly requested goal-backed work.

Goal Quality Standards: Good vs. Weak Goals¶

Before creating, the objective should answer these five questions: What specific facts will be true upon completion? What evidence proves it? What are the quantifiable or binary thresholds for success? Which scope boundaries matter? Under what circumstances should you stop and ask for help?

The official good example is similar to the one below—results, scope of changes, verification commands, and number of repetitions are all written in the same sentence:

Reduce checkout API p95 latency below 250 ms for the documented slow path by making the smallest safe server-side change, then verify with `npm run test:checkout` and the existing local latency benchmark showing p95 under 250 ms across 3 consecutive runs.

Another example for handling PR comments:

Resolve the open review comments on PR 123 that request code changes, update only the affected auth files and tests, and verify with the targeted auth test command plus `gh pr view 123` showing no unresolved change-request threads.

Weak goals are phrases like “Make checkout faster.” or “Keep investigating the PR comments.”—they have actions, but no completion state.

For different tasks, the official also provides quantitative heuristics: when fixing bugs, try to “first reproduce, then fix”, preferably with a validator that changes from failing to passing; when writing tests, clarify the command and passing conditions; when doing performance work, clarify metrics, thresholds, testing methods, and number of runs; when doing quality work, have observable acceptance criteria (sample reviews, lint/typecheck/test, or user-recognized deliverables); when doing research, clarify what decision the research is meant to support, scope of materials, and evidence standards; when doing operations, clarify health states, observation windows, failure thresholds, and rollback/upgrade trigger conditions.

Clarifying questions should also be restrained. Only ask when “a reasonable rewrite might go in the wrong direction”, keep the question short, and focus on missing validators or scope boundaries. The official recommended questions include: Should success be defined by latency, cost, accuracy, or user-facing behavior? Validate locally, in staging, or in production? What is the minimum evidence required to mark it as complete? When the user cannot provide metrics, propose the most honest binary validator you can think of and ask them to confirm it.

Installation and Enablement¶

Install in Codex¶

According to the openai/skills repository README, curated Skills can be installed by name using the system’s built-in $skill-installer (which defaults to skills/.curated):

$skill-installer define-goal

You can also directly point to the GitHub directory URL:

$skill-installer install https://github.com/openai/skills/tree/main/skills/.curated/define-goal

After installation, you need to restart Codex for the new Skill to load. The Codex UI metadata is in agents/openai.yaml: the display name is Define Goal, the short description is Shape clear measurable goals, and the default prompt will guide you to first use $define-goal to refine your intent into a measurable goal before starting work.

To use it with the Goals capability, confirm that your Codex version is at least 0.128.0. Common user-side commands are /goal, /goal pause, /goal resume, /goal clear; if /goal does not appear in the slash command list, you can enable features.goals according to the official instructions (for example, configure it in config.toml, or run codex features enable goals).

Use in Cursor / Claude Code and other tools¶

define-goal follows the universal Agent Skills directory structure: one folder plus SKILL.md. Just copy the official directory to the skills path that each tool scans, for example:
- Cursor: .cursor/skills/define-goal/SKILL.md within the project, or user-level ~/.cursor/skills/define-goal/SKILL.md
- Claude Code: .claude/skills/define-goal/ or ~/.claude/skills/define-goal/
- Codex: In addition to $skill-installer, you can also place it in its skills directory (please refer to the current Codex documentation for specifics)

It is recommended that the folder name match the name: define-goal field in the frontmatter. After loading, you can trigger it with $define-goal / the skill invocation method corresponding to the tool, or directly say “Help me define this intent into a measurable goal”. It is important to note that without the Codex Goals tool, the Skill can still constrain the Agent to “clarify the goal before taking action”; the actual calling of get_goal / create_goal to register an active goal still depends on whether the host environment provides these tools.

Typical Usage Examples¶

Scenario 1: You only have a vague requirement.
You can say to Codex / the assistant that supports this Skill:

Use $define-goal: I want to make the checkout API faster, first clarify the goal, and don't modify the code yet.

Following the workflow, the Agent should restate the objective with metrics, verification commands, and scope; only ask one short question when a key threshold is missing; when the quality meets the standard and you explicitly request goal-backed work, then run get_goal → create_goal.

Scenario 2: There are many PR review comments, and you are worried that the Agent will make off-course changes.
You can start with this prompt:

$define-goal
Please refine "handle the code change review comments on PR 123" into a verifiable goal, with the scope limited to auth-related files and tests.

Following the official good example, the final goal should include: which comments to handle, which files to modify, which test command to use, and how to use gh pr view to confirm there are no unresolved change-request threads.

Scenario 3: Do not force this Skill for normal implementation tasks.
If you say “add a null pointer check to this function and add unit tests”, according to the Skill description, you should implement it directly instead of forcing a create_goal first. Goals are suitable for long-range work where the end point is clear but the intermediate path needs to be figured out as you go; one-off small changes are often more appropriate with regular prompts.

Applicable Scenarios and Notes¶

Applicable scenarios: performance optimization, flaky bug troubleshooting, dependency migration, bugs that need to be reproduced before fixing, benchmark-driven parameter tuning, and research/audit tasks that require deliverables that can be inspected—in other words, work that “has a clear end point, but the intermediate path needs to be explored as you go”.

Not applicable or use with caution: Do not arbitrarily create goals when the user just wants a normal multi-step implementation and did not request goal-backed work; do not directly stuff activity descriptions like “make progress” into create_goal; this Skill explicitly does not create intermediate planning artifacts, persistent snapshots, ledgers, decision logs, or resume files—those belong to other planning/execution mechanisms.

In addition, the objective of create_goal should be a single concise string, with verification and scope written inside it; only add a token budget when the user explicitly requests it. When there is an active goal, resolve conflicts first to avoid cluttering thread state with duplicate goals.

Summary¶

What define-goal does is very restrained: before the Agent takes action, it refines the intent into “result + evidence + thresholds + scope + conditions for stopping and asking for help”. It aligns with Codex Goals (/goal, get_goal, create_goal), and also固化 the “define the goal first before executing” into a portable SKILL.md workflow.

Official address: https://github.com/openai/skills/tree/main/skills/.curated/define-goal

If you are interested in the current Codex skill/plugin distribution method, you can also check the OpenAI Plugins repository and the Using skills in Codex documentation; for Goals usage, please refer to Using Goals in Codex.

`define-goal`: Clarify the Goal First, Then Let the Agent Take Action