🔮 Agent Oracle

An AI agent orchestration design skill for Claude Code. Governs how autonomous agent systems get built: how many agents a task actually needs, what stops a loop before it burns budget on nothing, and what a harness has to lock down before it can run unattended.

GitHub repository Latest release

Install as a Claude Code skill

git clone https://github.com/AlveeeRahman/agent-oracle.git ~/.claude/skills/agent-oracle

Python 3.10+, standard library only, and neither bundled script opens a network connection. Then ask Claude: "design the supervisor topology for this pipeline", "write the launch prompt for this long-running agent", "build a regression suite before I ship this", or invoke agent-oracle directly for the full sequence.

Every invocation starts with an orchestrator

Before any of the five segments below get touched, the request goes through a fixed, bounded decision step that answers four questions and states the answers out loud: scope, agent count, loop design, and harness controls. Each answer is grounded in a specific guide section, not improvised. A narrow request gets a one-line decision. A long-running or multi-agent request gets a written one, citing the topology, the bound, and the budget, before a single worker starts.

What an AI agent orchestration design skill decides first

Default to one agent. Under a fixed thinking-token budget, splitting work across agents adds serialization and re-summarization steps that can only lose information relative to one agent reasoning directly over the same tokens. That's a Data Processing Inequality argument (Tran and Kiela, arXiv 2604.02460), not a house opinion.

Pass results by reference. Tool results held as live objects, with the model reading a bounded typed preview instead of a full serialized dump every turn, reported near-halved token cost at equal or better accuracy on SWE-bench Verified: 82.2% at ~1.1M tokens versus 78.2% at 2.2M tokens for a comparison harness (NVIDIA, "Six Agent Harness Capabilities for Higher Model Performance").

How it resolves loops

The dominant failure isn't a missing termination check. It's a bound that exists but doesn't cover the actual feedback path: a retry cap on one tool call with nothing capping the outer loop that keeps calling it. A static analysis of 6,549 repositories found 68 confirmed infinite-loop failures across 47 of them, and most trace back to exactly that shape (Hou, Wang, Zhao, and Wang, "When Agents Do Not Stop," arXiv 2607.01641). Every loop's continuation controller gets classified before it's trusted: deterministic, model-controlled, tool-controlled, external-state-controlled, exception-controlled, or mixed. Only the deterministic kind counts as a real bound.

The five segments

#	Segment	Answers
1	Evaluation	What does success look like, without one number hiding the failure?
2	Multi-agent patterns	Does this need more than one agent, and what topology and budget contract?
3	Harness engineering	What's locked, what terminates the loop, who approves what?
4	Long-horizon prompting	How do you write a launch brief that survives a run long enough to need one?
5	Self-improvement loops	What happens when the harness itself is the thing being optimized?

Project resources

Part of a three-skill suite: Skill Vision · Agent Oracle (this page) · Research Hound