goal-crafter

Goal Crafter

Turn a vague task into a verifiable goal that an AI agent can run unattended.

Leading principle: A goal without a checkable completion criterion is just a wish. The agent must be able to answer "Am I done?" without asking a human.

Invocation modes

Choose the mode before following the process:

Standalone mode: the user brings a vague task or directly asks for a goal. Run Phase 1 and clarify the task one question at a time.
Compiled-handoff mode: approved planning evidence already supplies the answers. Do not interview the user again. Apply only this skill's verifiability rules and target-harness formatting. The evidence may come from a conversation, spec, issue, document, or another skill.

In compiled-handoff mode, if a required product decision or completion condition is genuinely absent from the sources, report that the source is not agent-ready and name the missing evidence. Do not reopen the planning interview from inside goal compilation.

Process

Phase 1 — Clarify the task

Run this phase only in standalone mode. In compiled-handoff mode, extract the five answers from the upstream evidence without asking questions.

Ask the user, one question at a time, in this shape (standalone interview only — keep compiled-handoff mode emoji-free):

❓ **QN** - **<short title>**
<body>

💡 <your recommended answer, when you have one>

Walk these five in order:

What exactly should the agent do? Get the task in one sentence. If it's vague ("optimize the code", "improve the UI"), push for specifics.
Where does it run? Which project / repo / workspace? Is there a specific branch or file area?

What does DONE look like? This is the most important question. Push for observable, machine-checkable conditions:

❌ Vague (bad)	✅ Verifiable (good)
"Improved code quality"	"`tsc --noEmit` 0 errors + `eslint` 0 warnings"
"Better-looking UI"	"The page looks visually consistent at the three breakpoints 375px / 768px / 1440px, with no overflow"
"Fix all bugs"	"`npm test` all pass, and `git diff` contains only fix-related changes"
"Write good documentation"	"README.md contains three sections: installation/usage/API, each with code examples"
"Performance optimization"	"Lighthouse Performance score ≥ 90, LCP < 2.5s"

Any constraints? Don't touch certain files? Must use specific tools? Budget limit? Time limit?
What agent / harness? Claude Code (/goal), Codex (Automations), Pi, or generic?

Phase 1 complete when you have answers to all 5 questions. If the user can't answer #3, help them brainstorm verifiable conditions — this is the most common failure point.

Phase 2 — Draft the goal

Write the goal in the target agent's format. Follow these rules:

The three shapes below are the formats this skill deliberately maintains for the harnesses it is most often pointed at. They are a snapshot, not a standard: when the target harness documents a different shape, follow the harness and treat the block here as the fallback. Any harness not listed uses the generic block.

For Claude Code /goal:

Goal: [one-line task description]

Completion criteria:
- [ ] [checkable condition 1]
- [ ] [checkable condition 2]
- [ ] [checkable condition 3]

Constraints:
- [file/area restrictions]
- [tool/approach restrictions]
- [budget/time limits]

Context:
- [key files to read first]
- [relevant docs/specs]
- [related issues/PRs]

For Codex Automations:

Task: [one-line description]
Frequency: [once / on push / on schedule]
Verification: [checkable condition]
Workspace: [project path]

For Pi / generic:

任务：[一句话]
完成标准：
- [ ] [可验证条件 1]
- [ ] [可验证条件 2]
限制：[约束条件]

Phase 3 — Verify the goal

Before presenting the final goal, self-check:

Can an agent read the completion criteria and unambiguously decide "done" vs "not done"?
Is every criterion observable without human judgment? (No "looks good", "feels right")
Are the constraints specific enough to prevent scope creep?
Is the context sufficient for the agent to start working without asking "where" or "how"?

If any check fails in standalone mode, go back to Phase 1 and ask the user to clarify that specific point. In compiled-handoff mode, report the source as not agent-ready and name the missing evidence instead of asking a new planning question.

Phase 4 — Deliver

In standalone mode, present the final goal and end with:

🎯 Paste this goal into [agent name], and it will run on its own until completion. If it gets stuck along the way, tell me which completion criterion wasn't met, and I'll help you adjust it.

In compiled-handoff mode, the upstream skill owns the delivery wrapper. Return the goal in the requested harness format without adding this standalone closing line.

Examples

The repository names, directory structures, and file paths in the two examples below are all placeholders and do not represent the conventions of any real project. The goal actually produced must use the target repository'scurrentreal paths; do not copy the shapes shown here.

Example 1: Code review automation

User: "Help me write a goal to automatically review PRs"

Clarified:

Task: Review all changes in the current branch relative to main
Where: The current working repository
Done: Output a review report listing all P0/P1 issues, with each issue annotated with its file and line number
Constraints: Read-only, do not modify files
Agent: Claude Code

Output:

Goal: 审查当前分支相对于 origin/main 的 diff

Completion criteria:
- [ ] 已读取完整的 git diff
- [ ] 已检查安全漏洞（SQL 注入、XSS、密钥泄露）
- [ ] 已检查逻辑错误（空指针、竞态条件、边界条件）
- [ ] 已检查代码规范（命名、结构、重复代码）
- [ ] 输出审查报告，每个问题标注：严重度 + 文件:行号 + 问题描述 + 修复建议

Constraints:
- 只读，不修改任何文件
- 只关注当前分支的改动，不审查已有代码

Context:
- 项目背景：<一句话说明这个仓库是什么>
- 设计 spec：<仓库内的设计文档>

Example 2: UI redesign

User: "Help me write a goal to redo this page"