agent-routing
Skill4 starsChanged 7 months agoMITView on GitHub
Agent Routing Guide — when to spawn each installed agent
4 other projects use a version of this, 1 of them edited.
Adopted by
Most recently taken up by
- undark-ai/Meta-Ads-OStheir own version, first seen Nov 15, 2026
- EtanHey/golemstheir own version, first seen Oct 28, 2026
- sefaertunc/anthropic-watchedited, first seen Apr 30, 2026
- oaustegard/claude-skillstheir own version, first seen Mar 11, 2026
Other versions4 projects use a version of this.
Word for word · 0
None found.
Edited · 1
- sefaertunc/anthropic-watch★ 180% same
Wrote their own version · 3
- oaustegard/claude-skills★ 398same name
- EtanHey/golems★ 0same name
- undark-ai/Meta-Ads-OS★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository18 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- backend-conventionsSkill
- claude-md-maintenanceSkill
- coding-principlesSkill
- context-managementSkill
- coordinator-modeSkill
- frontend-design-systemSkill
- git-conventionsSkill
- memory-architectureSkill
- planning-with-filesSkill
- project-patternsSkill
- prompt-engineeringSkill
- review-and-handoffSkill
- security-checklistSkill
- subagent-usageSkill
- testingSkill
- verificationSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
14 rules. 0 are common, 14 are distinctive, and 0 are very specific to this project.
0
Common
Most of the 4 edited versions we read keep these.
14
Distinctive
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 8
Read this file at the start of every session.
- Distinctive: line 14
Never spawn more than 3 agents simultaneously.
- Distinctive: line 15
If a task is small enough to do yourself in 2 minutes, don't spawn an agent for it.
- Distinctive: line 44
When: Before every commit. After merging worktree branches.
- Distinctive: line 51
When: After a feature is implemented and tests pass.
- Distinctive: line 58
When: After completing implementation of any feature or module.
- Distinctive: line 61
Expect back: Test files committed to worktree branch.
- Distinctive: line 80
Expect back: All checks passing, with a summary of what was fixed and why.
- Distinctive: line 84
When: Before releasing a new version.
- Distinctive: line 91
When: After implementing new features.
- Distinctive: line 105
When: Before executing any implementation prompt.
- Distinctive: line 126
When: Before creating a PR. After major changes.
- Distinctive: line 167
When in doubt, spawn the agent.
- Distinctive: line 168
If you spawn an agent and it's not useful, tell the user — they may remove it.
“Common” is measured: kept by at least 6 in 10 of the 4 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
<!-- AUTO-GENERATED-START -->Agent Routing Guide
Read this file at the start of every session. It tells you which agents are available and when to use them.
How Agents Work
- Agents are specialist subprocesses. Spawn them to keep your main context clean.
- Worktree agents run in isolation — safe to run in parallel with your work.
- Non-worktree agents share your context — don't edit the same files they're reading.
- Never spawn more than 3 agents simultaneously.
- If a task is small enough to do yourself in 2 minutes, don't spawn an agent for it.
Background-Agent Concurrency
Two background agents on the same branch coexist cleanly:
- Worktree-isolated agents (
isolation: "worktree") each create their own sibling worktree offorigin/HEAD. They never collide on files, refs, or the index — running multiple in parallel is safe by design. - Non-isolated agents share the main checkout but are read-only by convention. The main session and these agents must avoid editing the same files concurrently; otherwise behavior is up to whoever writes last.
Worktree lock semantics: Claude Code locks each agent worktree with the agent's
pid; the lock survives agent completion. Stale locks are normal. Clean up with
git worktree remove -f -f <path> or the project's worktree-cleanup helper.
The earlier "lock file per branch" plan was rejected after the 2026-04-26 concurrency test — worktree isolation already provides the guarantee a lock file would have, and a lock would block the legitimate parallel-agents case.
Automatic Triggers
These agents should be spawned without being asked when their trigger condition is met.
build-validator
- Model: Haiku | Isolation: None
- When: Before every commit. After merging worktree branches.
- Trigger: Automatic — spawn when trigger condition is met
- What it does: Quick validation — tests pass, build succeeds, lint clean. Fast and cheap (Haiku model).
- Expect back: Pass/fail with specific errors if failed.
code-simplifier
- Model: Sonnet | Isolation: Worktree
- When: After a feature is implemented and tests pass. Also when you notice growing complexity or duplication.
- Trigger: Automatic — spawn when trigger condition is met (also: /simplify)
- What it does: Reviews code for duplication, unnecessary abstraction, missed reuse opportunities. Simplifies without changing behavior.
- Expect back: Cleanup commits on worktree branch. Diff review before merge.
test-writer
- Model: Sonnet | Isolation: Worktree
- When: After completing implementation of any feature or module.
- Trigger: Automatic — spawn when trigger condition is met
- What it does: Writes unit tests, integration tests, edge case tests. Covers happy path, error cases, boundary conditions.
- Expect back: Test files committed to worktree branch. Merge when reviewed.
Manual Triggers
These agents are spawned when you or the user explicitly requests them.
bug-fixer
- Model: Sonnet | Isolation: Worktree
- When: Bug reported. Test failing. Error in logs. Something broke but you don't want to derail current work.
- Trigger: Manual — spawn when needed
- What it does: Investigates the bug in isolation. Reads logs, reproduces, finds root cause, implements fix, writes regression test.
- Expect back: Fix committed to worktree branch with regression test.
build-fixer
- Model: Sonnet | Isolation: Worktree
- When: Build is broken. Tests failing. Lint errors blocking commit. Type errors after a merge or dependency update.
- Trigger: Manual — spawn when needed
- What it does: Reads error output, categorizes failures (build/test/lint/type), fixes in priority order, verifies each fix. Works in worktree isolation.
- Expect back: All checks passing, with a summary of what was fixed and why.
changelog-generator
- Model: Haiku | Isolation: None
- When: Before releasing a new version. After merging a batch of PRs. When preparing release notes.
- Trigger: Manual — spawn when needed
- What it does: Generates changelogs from git history, PR descriptions, and commit messages. Formats for release notes.
- Expect back: Formatted changelog entry for the release.
doc-writer
- Model: Sonnet | Isolation: Worktree
- When: After implementing new features. After API changes. When README is outdated. Before release.
- Trigger: Manual — spawn when needed
- What it does: Updates documentation, README, API docs from code changes. Keeps docs in sync with implementation.
- Expect back: Updated docs committed to worktree branch.
performance-auditor
- Model: Sonnet | Isolation: None
- When: Performance concern raised. Slow endpoint discovered. Before releasing to production. After major changes.
- Trigger: Manual — spawn when needed
- What it does: Profiles code, identifies bottlenecks, checks database query efficiency, measures response times, suggests optimizations.
- Expect back: Performance report with benchmarks and recommendations.
plan-reviewer
- Model: Opus | Isolation: None
- When: Before executing any implementation prompt. Always.
- Trigger: Manual — /review-plan
- What it does: Reviews implementation plans as a senior staff engineer. Challenges assumptions, finds ambiguity, checks verification strategy, identifies missing edge cases.
- Expect back: Refined plan with concerns addressed, or list of blocking questions.
refactorer
- Model: Sonnet | Isolation: Worktree
- When: Large-scale renames. Architectural pattern changes. Library migrations. Moving code between modules.
- Trigger: Manual — spawn when needed
- What it does: Handles large-scale refactoring in worktree isolation. Renames, architectural changes, pattern migrations with full test verification.
- Expect back: Refactored code on worktree branch with all tests passing.
security-reviewer
- Model: Opus | Isolation: None
- When: Auth changes. User input handling. New API endpoints exposed to external users. Dependency updates.
- Trigger: Manual — spawn when needed
- What it does: Scans for injection vulnerabilities, auth bypasses, data exposure, insecure defaults, dependency vulnerabilities.
- Expect back: Security report with severity ratings.
verify-app
- Model: Sonnet | Isolation: Worktree
- When: Before creating a PR. After major changes.
- Trigger: Manual — /verify
- What it does: Full end-to-end verification. Runs the app, tests all major flows, checks for regressions. More thorough than build-validator.
- Expect back: Detailed verification report. Blocking issues listed.
Reserved
upstream-watcher
- Model: Sonnet | Isolation: None
- Status: Reserved — no in-session command currently invokes this agent.
- Why kept: Reserved for future revival. The /upstream-check slash command was retired in Phase 2 (2026-04); the agent definition is preserved so the scheduled GitHub Actions workflow (.github/workflows/upstream-check.yml) and any future on-demand variant have an established contract to revive.
- Do NOT spawn this agent in regular sessions. It exists for scheduled automation (CI/Actions) and for future revival; spawning it manually has no defined entry path today.
Decision Matrix
| You just... | Spawn this | Auto? |
| Got a bug report mid-task | bug-fixer | Manual |
| Build or tests are broken | build-fixer | Manual |
| Are about to commit | build-validator | Yes |
| Preparing a release | changelog-generator | Manual |
| Notice code getting complex | code-simplifier | Yes |
| Need docs updated after implementation | doc-writer | Manual |
| Suspect performance issues | performance-auditor | Manual |
| Got an implementation prompt | plan-reviewer | Manual |
| Need large-scale refactoring | refactorer | Manual |
| Made security-sensitive changes | security-reviewer | Manual |
| Finished implementing a feature | test-writer | Yes |
| Finished a task, ready for PR | verify-app | Manual |
Rules
- Universal agents are your defaults. Use them every session.
- Project agents are specialists. Use them when their domain is relevant.
- Worktree agents are safe to run in parallel — they can't break your work.
- Non-worktree agents share your context — don't edit the same files they're reading.
- When in doubt, spawn the agent. A wasted agent run costs less than a missed bug.
- If you spawn an agent and it's not useful, tell the user — they may remove it.
<!-- AUTO-GENERATED-END -->Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

