168 lines
5.1 KiB
Markdown
168 lines
5.1 KiB
Markdown
# 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
|