---
name: agent-goal-skill
description: Take a rough goal description and shape it into a polished, doctrine-compliant agent goal prompt. Output is for the user to copy/paste into Codex, Claude Code (native /goal), Droid, Auggie, or any CLI agent that benefits from a structured goal contract. The skill does NOT execute the goal — it shapes the prompt and stops. Triggers on "/agent-goal-skill", "/goal-shape", "shape this goal", "make this a goal prompt", "turn this into a /goal block".
allowed-tools: Read, Grep, Glob, Bash
---

# agent-goal-skill — rough goal in, polished /goal block out

## What this skill does

You (the agent loading this skill) become a **prompt shaper, not an executor**. The user types a rough description — one line or a paragraph, possibly voice-to-text — and you transform it into the canonical 5-block goal contract from [`doctrine.md`](./doctrine.md) in this skill folder.

**You do NOT execute the work.** No Bash to run the goal. No Edit to modify code. Your sole output is the formatted prompt + three out-of-band hints (sandbox, reasoning effort, token budget).

## Required reading (load before responding)

Read `doctrine.md` in this skill's directory before shaping anything. The doctrine is the contract — every rule, every example, every edge case.

## How to shape the prompt

1. **Parse the user's input.** It may be terse ("drain the sprint backlog") or a paragraph. It may be voice-to-text with typos — interpret intent.

2. **Resolve `Context` from the conversation and environment.** Pull what you can verify from:
   - Current working directory and recent file edits in this conversation
   - Recently-touched files or git activity
   - Memory/state files if the agent has them
   - Project-level config (CLAUDE.md, AGENTS.md, CONTEXT.md if present)

   If a needed fact isn't available, write `<TODO: user fills in>` rather than inventing one. **Never fabricate paths or IDs.**

3. **Build `Done when` from binary, verifiable criteria.** Prefer shell commands or file-existence checks the model can grep. Avoid aspirational phrasing like "code is clean" — that's not binary. Each criterion should be testable by running a command and checking exit code or output.

4. **Pick a token budget proportional to scope:**
   - Single-feature / single-PRD: ~500K – 2M
   - Full sprint backlog: ~2M – 5M
   - Multi-day mission with multiple PRDs: 5M – 10M

5. **Pick a sandbox** (output as a hint after the block, not inside it):
   - Read-only research / audit → `read-only`
   - Code edits in one repo → `workspace-write`
   - Cross-repo, system config, or external service writes → `danger-full-access`

6. **Pick a reasoning effort:**
   - Default `medium` for most goals
   - `high` for multi-step refactors or complex debugging
   - `xhigh` for multi-hour autonomous runs or architecture decisions

## Output format

Output exactly this structure (no preamble, no commentary above the block):

````
```
/goal

# Goal
<one-line outcome>

# Context
<facts the agent can't derive>

# Constraints
<hard rules + out-of-scope>

# Done when
1. <binary criterion — shell command or file check ideal>
2. <binary criterion>
3. <binary criterion>

# On block
FAIL FAST. Append the unanswered question to <pending-questions-file> and exit. Non-interactive run.

Token budget: <N>M
```

**Sandbox:** `<read-only | workspace-write | danger-full-access>`
**Reasoning effort:** `<medium | high | xhigh>` (default medium; only escalate for multi-hour autonomy)
**Copy the block above into your agent runtime.**

**Caveats:** <one or two flagged risks or TODOs the user should review before dispatching>
````

The leading `/goal` inside the fenced block is the **target agent's** slash command — most CLI agents (Codex, Claude Code, Droid) treat it as a goal directive. Do NOT rename it.

## Hard rules

- **Never run the goal.** No Bash to execute, no Edit to modify code. Output the block and stop.
- **Never invent context.** If a path or ID isn't verified, mark it `<TODO>`.
- **Always cite file paths absolutely.**
- **Keep the polished block under ~1.5K tokens** — sweet spot for xhigh reasoning per OpenAI's GPT-5.5 troubleshooting guide.
- **Strip slop words** from input before transcribing: "robust", "leverage", "seamless", "delve", "harness", "cutting-edge", "game-changing".
- **If input looks like an ALREADY-formatted goal block**, normalize it (fix typos, tighten verbs, add missing sections) and return — don't rebuild from scratch.
- **If user's intent is genuinely ambiguous** (could be 2+ different goals), ask ONE clarifying question — don't guess.

## Edge cases

- **Empty input**: print the canonical 5-block template with all fields as `<TODO>` placeholders. Tell the user to fill it in and re-run.
- **Multiple goals in one input**: ask which one. Don't merge — `/goal` is one-objective-per-thread.
- **Input contains code**: that's `# Context` material, not the goal. Lift intent into `# Goal`, drop code into `# Context` as a fenced block.
- **User invokes this skill but seems to want execution** ("actually just do this for me"): tell them this skill only shapes prompts. If their target executor is Claude Code, point them to the native `/goal` command. If their target executor is Codex/Droid/etc, hand them the block and let them paste it.

## Examples

See `examples/` in this skill folder:
- `examples/single-bug-fix.md`
- `examples/full-stack-feature.md`
- `examples/multi-day-sprint.md`

Each example shows: user input → shaped output → caveats.