# agent-goal-skill

**A Claude Code skill that turns rough goal descriptions into polished, doctrine-compliant agent prompts.**

Use it to shape `/goal` prompts for Codex, Claude Code, Droid, Auggie — any CLI agent that benefits from a structured goal contract.

> 🪞 Your Claude becomes a prompt shaper. Type a one-liner. Get back a tight, executable goal block ready to paste into any agent.

---

## What problem this solves

Agent goal prompts fail in predictable ways:

- **Verbose**: 3 paragraphs of context the model derives from the codebase anyway
- **Aspirational**: "make the code clean" — not a binary criterion
- **Under-constrained**: no out-of-scope list, agent wanders
- **No fail-fast clause**: agent stalls on missing context, burns budget asking
- **Wrong scope hints**: token budget + sandbox level missing, agent picks badly

This skill enforces a **5-block doctrine** that closes all 5 failure modes. The shape is non-negotiable — what plugs into the blocks is what you bring.

---

## The 5-block doctrine

Every shaped goal has exactly these blocks, in this order, with markdown headers:

```
# Goal           — one-line verifiable outcome
# Context        — facts the agent can't derive (paths, IDs, prior decisions)
# Constraints    — hard rules + out-of-scope
# Done when      — numbered binary criteria (shell commands ideal)
# On block       — fail-fast clause + where to drop questions
```

Plus three out-of-band hints emitted alongside the block:
- **Sandbox** — `read-only | workspace-write | danger-full-access`
- **Reasoning effort** — `medium | high | xhigh`
- **Token budget** — sized to scope (~500K for single feature, ~5M for multi-day sprint)

Full doctrine: [`doctrine.md`](./doctrine.md).

---

## Install

### Claude Code

```bash
git clone https://github.com/<your-username>/agent-goal-skill.git ~/.claude/skills/agent-goal-skill
```

Restart Claude Code. The skill auto-registers — invoke via `/agent-goal-skill <rough description>`.

### Codex CLI

```bash
git clone https://github.com/<your-username>/agent-goal-skill.git ~/.codex/skills/agent-goal-skill
```

(`.codex/skills/` uses the same SKILL.md format as `.claude/skills/`.)

### Kimi / Droid / Auggie

Same pattern — clone to `~/.kimi/skills/`, `~/.factory/skills/`, or `~/.augment/skills/`. SKILL.md is universal across these CLIs.

### One-liner installer (Claude Code only)

```bash
curl -sSL https://raw.githubusercontent.com/<your-username>/agent-goal-skill/main/install.sh | bash
```

---

## Quick example

You type into Claude:

```
/agent-goal-skill drain my sprint backlog before the demo on friday
```

Claude returns:

````
```
/goal

# Goal
Drain all unblocked tasks in the sprint backlog to status=done before 2026-MM-DD.

# Context
- Source of truth: <TODO: user fills in path to backlog or ticket-tracker query>
- Each task has acceptance criteria — meet them before moving to done
- Demo deadline: Friday

# Constraints
- One sprint per task
- Skip tasks tagged blocked, ui-required, manual-review
- Do not push to client branch — dev only

# Done when
1. Your backlog query returns 0 unblocked actionable tasks
2. Every done task has a commit SHA recorded against it
3. Final handoff written to {repo}/handoff-{date}.md

# On block
FAIL FAST. If a task lacks acceptance criteria, mark blocked + move on.
Append unanswered questions to a pending-questions file. Non-interactive run.

Token budget: 4M
```

**Sandbox:** `workspace-write`
**Reasoning effort:** `medium`
**Caveats:** Confirm kanban CLI path before dispatching.
````

Paste the inner block into Codex CLI (`/goal <paste>`) or any other agent runtime.

---

## What this skill does NOT do

- It does not execute the goal. It only shapes the prompt.
- It does not invent context. Unknown facts get marked `<TODO: user fills in>`.
- It does not run agents, write code, or modify files.

If you want Claude Code to execute the goal directly, use the native `/goal` command (Claude Code v2.1.139+). This skill is for when the **target executor is a different agent** (Codex, Droid, etc) or when you want to inspect/edit the goal before dispatching.

---

## Why this exists

Inspired by:

- **OpenAI's GPT-5.5 prompting guidance**: "Treat 5.5 as a new model family — start with the smallest prompt that preserves the product contract."
- **Sam Altman**: "expert vs college student — you don't tell an expert how to think, you tell them what's true at the end."
- **Anthropic's effective-harnesses-for-long-running-agents essay**: the agent's environment is what makes the model reliable, not the model itself.

The 5-block format is the smallest contract that closes the 5 common failure modes above.

---

## Examples

See [`examples/`](./examples/):

- [`single-bug-fix.md`](./examples/single-bug-fix.md) — minimum scope
- [`full-stack-feature.md`](./examples/full-stack-feature.md) — medium scope
- [`multi-day-sprint.md`](./examples/multi-day-sprint.md) — large scope

---

## License

MIT. See [LICENSE](./LICENSE).

---

## Contributing

PRs welcome. Especially:
- Examples from your stack (link your repo, redact secrets)
- Translations of `doctrine.md`
- Adapters for other CLI agent runtimes