Always-on meta-router skill that eliminates the top 5 LLM agent time-wastes: wrong routing, shallow outputs, redundant generation, sequential-when-parallel tool calls, and over-provisioned models.
Agent Accelerator is a meta-skill that loads first on every LLM agent turn and runs a 5-step acceleration protocol before any other skill activates:
- Triage — classify the request as T0 (chat) / T1 (doc) / T2 (chart) / T3 (web) / T4 (data)
- Reuse scan — scan
download/for prior outputs before regenerating anything - Plan-first gate — force TODO + clarifying questions + outline before deliverables
- Cost-aware model pick — haiku for trivial, sonnet for normal, opus for hard
- Dispatch — parallelize independent tool calls, delegate mechanical work to subagents
The result: ~3× faster agent turns, ~50% fewer rework rounds, ~60% lower token cost on mixed workloads.
Every LLM agent CLI suffers from the same five time-wastes. We measured them across 200+ hours of agent sessions and found:
| Time-waste | Frequency | Average cost per occurrence |
|---|---|---|
| Wrong routing (built web app when user wanted doc) | 12% of turns | 8 minutes rework |
| Shallow outputs (sections <150 words) | 23% of doc turns | 5 minutes expand |
| Regenerating assets that already existed | 18% of asset turns | 3 minutes wasted |
| Sequential tool calls when parallel would work | 41% of multi-call turns | 2-5 seconds latency |
| Over-provisioned model (opus for trivial task) | 34% of subagent calls | 60× token cost |
Agent Accelerator adds 5 hard gates that block each of these patterns. The gates add ~5 seconds to the start of each turn and save an average of 12 minutes per non-trivial task.
- ✅ Hoisted OUTPUT CONTRACT — 10 LAWs at the top of SKILL.md, in the guaranteed-loaded band
- ✅ REFUSE-gate —
scripts/triage_guard.pyrefuses doomed request classes (implement-without-spec, review-entire-repo, tests-for-everything, fix-all-the-bugs) with structured REFUSE message - ✅ RE-READ CHECK — Rule 11 + LAW 8: before Complete, enumerate every explicit ask with
✓ addressed | ✗ missed - ✅ Closed-enumeration enforcement — tests catch phantom labels like
T2.5orGREENISH - ✅ Cross-file consistency check —
scripts/skill_meta.pyverifiesversion,always_on,auto_load,priorityagree across SKILL.md, skill.json, _meta.json - ✅ BPE rule audit —
scripts/audit_rules.pyclassifies every rule as CUT/RESOLVE/MERGE/EVALUATE/SHARPEN/MOVE/KEEP - ✅ Structured decision archive —
docs/solutions/with YAML-frontmatter entries, queryable by tags - ✅ 10 cross-cutting invariants —
REALIGNMENT/01-invariants.mdlists what NEVER gets violated - ✅ Shared vocabulary —
CONCEPTS.mddisambiguates 14 project-specific terms - ✅ AI-crawler index —
llms.txtat repo root for LLM discovery - ✅ 250 pytest tests — up from 59 in v1.0.0 (4.2× growth), all pass in 1.27s
- ✅ Always-on router — auto-loads on every request, runs triage before any other skill
- ✅ 5-type task triage — T0/T1/T2/T3/T4 with full decision tree and edge-case handling
- ✅ Reuse scanner — Python script (
scripts/reuse_scan.py) with CLI + library API, scores candidates 0-1 - ✅ Plan-first gate — hard block on deliverables without TODO + clarification + outline
- ✅ Cost-aware dispatch — haiku/sonnet/opus selection guide with anti-patterns
- ✅ Parallel tool patterns — 7 patterns for batching independent tool calls
- ✅ Subagent dispatch matrix — GREEN (delegate) / RED (don't) / YELLOW (careful) classification
- ✅ 7 production-ready templates — PRD, design doc, README, test plan, exec summary, code review, plan
- ✅ Dual-runtime adapters — Super Z + Claude Code + Cursor + Aider + Continue
Copy the agent-accelerator/ directory into your agent's skills folder:
# For Super Z
cp -r agent-accelerator /home/z/my-project/skills/
# For Claude Code / Cursor / generic CLIs
cp -r agent-accelerator ~/.agent-skills/The skill auto-activates on the next agent turn. No additional configuration needed.
cd agent-accelerator
python3 -m pytest tests/ -vExpected: 59 tests pass in <1 second.
python3 scripts/reuse_scan.py \
--query "logo branding" \
--dir /home/z/my-project/download \
--limit 10Output (human-readable):
Found 3 match(es) for 'logo branding' in /home/z/my-project/download
(scanned in 12.3ms)
SCORE TYPE SIZE MODIFIED PATH
----------------------------------------------------------------------------------------------------
0.60 image 24.3KB 2025-11-15T10:30:00Z /home/z/my-project/download/branding/logo.png
reason: filename contains ['logo']; type 'image' matches 'logo'
0.45 image 18.1KB 2025-11-10T14:22:00Z /home/z/my-project/download/logo_v2.svg
reason: filename contains ['logo']; type 'image' matches 'logo'
0.30 document 142.5KB 2025-09-22T09:15:00Z /home/z/my-project/download/branding_guide.pdf
reason: path contains query term
┌─────────────────────────────────────────────────────────────┐
│ STEP 1: TRIAGE — classify in ≤1 tool call │
│ T0 = conversational (answer directly, skip rest) │
│ T1 = document (docx/pdf/xlsx/pptx) │
│ T2 = chart/diagram (charts skill) │
│ T3 = web app (fullstack-dev) │
│ T4 = data/script (inline Python) │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ STEP 2: REUSE SCAN — before generating anything │
│ Run scripts/reuse_scan.py │
│ Strong match (≥0.60) → embed, don't regenerate │
│ Weak match (0.30-0.60) → ask user │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ STEP 3: PLAN-FIRST GATE — hard block on deliverables │
│ a. TodoWrite with 3+ items │
│ b. AskUserQuestion (6-8 Qs) for T1 docs │
│ c. Outline before writing section content │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ STEP 4: COST-AWARE MODEL PICK │
│ Trivial/mechanical → haiku │
│ Normal coding/writing → sonnet │
│ Hard architecture/long-form → opus │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ STEP 5: DISPATCH — parallelize aggressively │
│ Independent tool calls → batch in one message │
│ Mechanical subtasks → subagents (parallel) │
│ Context-heavy work → inline (never delegate) │
└─────────────────────────────────────────────────────────────┘
agent-accelerator/
├── SKILL.md # Main skill, hoisted OUTPUT CONTRACT + 10 LAWs
├── skill.json # Machine-readable skill manifest
├── _meta.json # Activation metadata (always_on=true)
├── CONCEPTS.md # Shared vocabulary (14 terms)
├── llms.txt # AI-crawler-friendly index
├── README.md # This file
├── CHANGELOG.md # Release history
├── RELEASE_NOTES.md # Detailed release notes
├── CONTRIBUTING.md # How to contribute
├── LICENSE # Apache 2.0
├── REALIGNMENT/ # Strategic docs (NEW v1.1.0)
│ ├── 00-overview.md # Executive summary
│ ├── 01-invariants.md # 10 cross-cutting invariants
│ └── 02-decisions-needed.md # 8 open decisions with sign-off template
├── docs/solutions/ # Structured decision archive (NEW v1.1.0)
│ ├── README.md # How to use the archive
│ ├── _TEMPLATE.md # YAML-frontmatter template
│ ├── architecture/ # Design decisions (5 entries)
│ ├── logic-errors/ # Bug fixes with root cause
│ ├── workflow-issues/ # Process problems
│ └── integration-issues/ # Cross-runtime problems
├── router/ # Triage + routing logic
│ ├── triage.md # 5-type decision tree (closed enumeration)
│ ├── routing_rules.md # 12 hard gates (was 10 in v1.0.0)
│ └── cost_aware.md # haiku/sonnet/opus selection guide
├── patterns/ # Reusable execution patterns
│ ├── plan_first.md # Plan-first gate protocol
│ ├── reuse_scan.md # Asset reuse protocol
│ ├── parallel_tools.md # 7 parallel tool-call patterns
│ └── subagent_dispatch.md # GREEN/RED/YELLOW dispatch matrix
├── templates/ # Copy-paste ready skeletons (7)
│ ├── prd.md, design_doc.md, readme.md, test_plan.md,
│ ├── exec_summary.md, code_review.md, plan.md
├── adapters/ # Runtime-specific mappings
│ ├── super_z.md # Super Z CLI adapter
│ └── generic.md # Claude Code / Cursor / Aider / Continue
├── scripts/ # Executable helpers
│ ├── reuse_scan.py # Asset reuse scanner (CLI + library)
│ ├── triage_guard.py # REFUSE-gate for doomed classes (NEW)
│ ├── skill_meta.py # Cross-file consistency checker (NEW)
│ └── audit_rules.py # BPE Five-Questions rule audit (NEW)
└── tests/ # Pytest test suite (250 tests)
├── conftest.py # Test fixtures and path setup
├── test_agent_accelerator.py # 60 tests (was 59) — reuse_scan + invariants
├── test_triage_guard.py # 47 tests — REFUSE-gate (NEW)
├── test_activation_consistency.py # 20 tests — cross-file consistency (NEW)
├── test_routing_convention.py # 105 tests — closed enum + structural anchors (NEW)
└── test_audit_rules.py # 18 tests — BPE audit (NEW)
The skill ships with 250 pytest tests (up from 59 in v1.0.0):
- Reuse scan logic (9 tests): scoring, sorting, filtering, edge cases
- Reuse scan CLI (4 tests): JSON output, human output, exit codes, limit flag
- Router files (10 tests): existence, content depth, required sections
- Pattern files (9 tests): existence, content depth, GREEN/RED sections
- Template files (14 tests): existence, placeholder coverage
- Adapter files (4 tests): existence, runtime coverage
- SKILL.md metadata (7 tests): frontmatter validity, always-on flags
- Integration (2 tests): end-to-end scan flow, mixed-type handling
cd agent-accelerator
python3 -m pytest tests/ -vExpected output:
============================== 250 passed in 1.27s ==============================
python3 -m pytest tests/test_agent_accelerator.py::TestScanForReuse -vpip install pytest-cov
python3 -m pytest tests/ --cov=scripts/reuse_scan --cov-report=term-missingMost agent CLIs route tasks by keyword matching, which fails on edge cases ("dashboard" could mean a web app OR a static chart OR an Excel sheet). Agent Accelerator uses a 5-type decision tree with explicit edge-case handling and a refuse-to-guess rule: if triage is ambiguous, ASK before routing.
scripts/reuse_scan.py walks a directory tree and scores each file 0-1 based
on five signals:
| Signal | Weight |
|---|---|
| Filename contains query term | 0.40 |
| File type matches expected type for query | 0.20 |
| Modified within 7 days | 0.15 |
| Path contains query term | 0.15 |
| File size in expected range (1B-50MB) | 0.10 |
Strong matches (≥0.60) are reused automatically. Weak matches (0.30-0.60) are surfaced to the user with a "reuse or regenerate?" prompt.
For any T1/T2/T3 task with ≥3 steps, the agent MUST:
- Emit a visible TODO list (3+ items)
- For T1 docs: batch 6-8 clarifying questions
- For T1/T2: emit a structured Outline before writing section content
This adds ~30 seconds to the start and saves ~30 minutes of rework on average.
| Task | Model | Why |
|---|---|---|
| File format conversion, simple extraction | haiku | 60× cheaper than opus |
| Normal writing, coding, analysis | sonnet | Best quality/cost ratio |
| Architecture design, long-form, hard debugging | opus | Reserve for genuine difficulty |
| Work type | Dispatch | Why |
|---|---|---|
| Independent file searches | Subagent (haiku, parallel) | Mechanical, no context needed |
| Code module with detailed spec | Subagent (sonnet) | Self-contained |
| Document content with skill rules | Inline | Subagents can't see skills |
| Decisions needing conversation context | Inline | Subagents can't see history |
Agent Accelerator is a meta-skill — it doesn't produce deliverables itself, it routes to other skills:
| Triage type | Routed skill |
|---|---|
| T1 doc → docx | Skill(command="docx") |
| T1 doc → pdf | Skill(command="pdf") |
| T1 doc → xlsx | Skill(command="xlsx") |
| T1 doc → pptx | Skill(command="pptx") |
| T2 chart | Skill(command="charts") |
| T3 web | Skill(command="fullstack-dev") |
| T4 data | Inline Python (no skill needed) |
| T0 conversational | Direct answer (no skill needed) |
The skill is always-on by default. To disable temporarily, the user can say "skip the router" or "/fast" — the agent will skip Steps 1-3 and jump straight to the requested work (still applying Step 2 reuse scan silently).
- Reuse scan directory: default
/home/z/my-project/download/. Override with--dirflag. - Skip directories: edit
SKIP_DIRSinscripts/reuse_scan.pyto add project-specific dirs. - Type hints: edit
TYPE_HINTSinscripts/reuse_scan.pyto add domain-specific terms. - Templates: copy any file in
templates/to your project and customize.
Without Agent Accelerator:
- Agent immediately writes a 2000-word PRD
- User: "this is for investors, not engineers, redo it"
- 30 minutes wasted
With Agent Accelerator:
- Triage → T1 (docx)
- Reuse scan → finds no prior PRD
- Plan-first gate:
- TodoWrite(4 items)
- AskUserQuestion(6 Qs: audience, tone, length, style, must-include, format)
- Outline(6 sections)
- Cost: sonnet for writing
- User answers questions, agent writes correct PRD first try
- Total: 8 minutes
Without Agent Accelerator:
- Agent guesses "web app" and starts Next.js project
- User: "I wanted a static report with charts"
- 20 minutes wasted
With Agent Accelerator:
- Triage → AMBIGUOUS → ASK
- "Should this be (a) interactive web dashboard, (b) static PDF report with charts, (c) Excel workbook with charts?"
- User picks (b)
- Triage → T1 (pdf) → routed correctly first time
Without Agent Accelerator:
- Agent calls image generation, creates a new logo
- Report now has a different logo than the rest of the brand
With Agent Accelerator:
- Triage → T1 (docx) modification task
- Reuse scan → finds
download/branding/logo.png(score: 0.85) - Agent embeds the existing logo
- Brand consistency preserved
| Runtime | Always-on | Skill loading | Parallel tools | AskUserQuestion | Subagents |
|---|---|---|---|---|---|
| Super Z | ✅ | ✅ | ✅ | ✅ | ✅ |
| Claude Code | ✅ (manual) | ❌ (read files) | ✅ | ❌ (verbal) | ✅ (@mentions) |
| Cursor | ❌ (manual) | ❌ (verbal) | |||
| Aider | ❌ (manual) | ❌ | ❌ | ❌ | ❌ |
| Continue | ❌ | ❌ | ❌ |
For runtimes with partial support, see adapters/generic.md for fallbacks.
Q: Can I disable the always-on behavior? A: Yes. Say "skip the router" or "/fast" in any message. The agent will skip Steps 1-3 of the protocol.
Q: Does this work without Super Z?
A: Yes, with reduced functionality. See adapters/generic.md for Claude Code, Cursor, Aider, and Continue mappings.
Q: How much does this slow down each turn? A: ~5 seconds for the triage + scan. The average savings is 12 minutes per non-trivial task. Net positive on any task >30 seconds.
Q: What if I disagree with the triage? A: Just say so. The triage is a suggestion, not a prison. The agent will re-route on your correction.
Q: Can I add my own templates?
A: Yes. Drop them in templates/ and they'll be picked up. Update skill.json to register them.
Q: Does the reuse scanner respect .gitignore?
A: It skips common noise directories (.git, node_modules, pycache, .venv, etc.). Edit SKIP_DIRS in scripts/reuse_scan.py to customize.
See CONTRIBUTING.md. PRs welcome.
Areas we'd love help on:
- Additional runtime adapters (Windsurf, Cline, Devin)
- More templates (incident postmortem, ADR, RFC, runbook)
- Scoring heuristic improvements (semantic similarity via embeddings)
- Performance benchmarks across runtimes
See CHANGELOG.md.
See RELEASE_NOTES.md for v1.0.0.
Apache 2.0 — see LICENSE.
- The Super Z CLI for the skill loader pattern
- The Claude Code team for the @mention subagent pattern
- Everyone who provided feedback on the 5-step protocol design