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.

---

Install

Claude Code

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

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)

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/:

• single-bug-fix.md — minimum scope
• full-stack-feature.md — medium scope
• multi-day-sprint.md — large scope

---

License

MIT. See LICENSE.

---

Contributing

PRs welcome. Especially:

• Examples from your stack (link your repo, redact secrets)
• Translations of doctrine.md
• Adapters for other CLI agent runtimes