agentleFS
sefaertuncsefaertunc/anthropic-watch/.claude/skills/agent-routing/SKILL.md

agent-routing

Skill1 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

The file

Show its rules and text

We split this skill into the rules it gives an agent

17 rules. 0 are common, 17 are distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 4 edited versions we read keep these.

  • 17

    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
  1. Distinctive:

    Read this file at the start of every session.

    line 8
  2. Distinctive:

    Never spawn more than 3 agents simultaneously.

    line 14
  3. Distinctive:

    If a task is small enough to do yourself in 2 minutes, don't spawn an agent for it.

    line 15
  4. Distinctive:

    When: Before every commit. After merging worktree branches.

    line 44
  5. Distinctive:

    When: After a feature is implemented and tests pass.

    line 51
  6. Distinctive:

    When: After completing implementation of any feature or module.

    line 58
  7. Distinctive:

    Expect back: Test files committed to worktree branch.

    line 61
  8. Distinctive:

    Expect back: All checks passing, with a summary of what was fixed and why.

    line 80
  9. Distinctive:

    When: Before releasing a new version.

    line 84
  10. Distinctive:

    When: After adding new packages.

    line 98
  11. Distinctive:

    When: Before deploying to staging or production.

    line 105
  12. Distinctive:

    When: After implementing new features.

    line 112
  13. Distinctive:

    When: After implementing user-facing features.

    line 126
  14. Distinctive:

    When: Before executing any implementation prompt.

    line 140
  15. Distinctive:

    When: Before creating a PR. After major changes.

    line 161
  16. Distinctive:

    When in doubt, spawn the agent.

    line 207
  17. Distinctive:

    If you spawn an agent and it's not useful, tell the user — they may remove it.

    line 208

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md
<!-- 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 off origin/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.

ci-fixer

  • Model: Sonnet | Isolation: Worktree
  • When: CI pipeline fails. Build errors in GitHub Actions/CI. Flaky tests blocking merges.
  • Trigger: Manual — spawn when needed
  • What it does: Reads CI logs, identifies root cause, implements fix in worktree isolation.
  • Expect back: Fix committed to worktree branch with CI passing.

dependency-manager

  • Model: Haiku | Isolation: None
  • When: After adding new packages. During regular maintenance. When security advisories are published.
  • Trigger: Manual — spawn when needed
  • What it does: Audits, updates, and resolves dependency issues. Checks for security vulnerabilities in packages.
  • Expect back: Dependency audit report with update recommendations.

deploy-validator

  • Model: Sonnet | Isolation: None
  • When: Before deploying to staging or production. After infrastructure changes. New environment setup.
  • Trigger: Manual — spawn when needed
  • What it does: Validates deployment readiness — environment configs, secrets management, health checks, rollback strategy.
  • Expect back: Deployment readiness checklist with pass/fail.

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.

docker-helper

  • Model: Sonnet | Isolation: None
  • When: Creating or modifying Dockerfiles. Compose file changes. Multi-stage build optimization. Container debugging.
  • Trigger: Manual — spawn when needed
  • What it does: Manages containerization, Dockerfile optimization, compose file configuration, multi-stage builds.
  • Expect back: Optimized Docker configuration with size/performance improvements.

e2e-runner

  • Model: Sonnet | Isolation: Worktree
  • When: After implementing user-facing features. Before releases. When unit tests pass but integration is suspect.
  • Trigger: Manual — spawn when needed
  • What it does: Writes and runs end-to-end tests for critical user journeys. Detects E2E framework (Playwright/Cypress) or recommends setup. Tests web, API, or CLI flows.
  • Expect back: E2E test results with pass/fail per journey and reproduction steps for failures.

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 thisAuto?
Got a bug report mid-taskbug-fixerManual
Build or tests are brokenbuild-fixerManual
Are about to commitbuild-validatorYes
Preparing a releasechangelog-generatorManual
CI pipeline is failingci-fixerManual
Notice code getting complexcode-simplifierYes
Added new dependencies or running maintenancedependency-managerManual
Preparing for deploymentdeploy-validatorManual
Need docs updated after implementationdoc-writerManual
Working with Docker or containersdocker-helperManual
Need end-to-end testing of user flowse2e-runnerManual
Suspect performance issuesperformance-auditorManual
Got an implementation promptplan-reviewerManual
Need large-scale refactoringrefactorerManual
Made security-sensitive changessecurity-reviewerManual
Finished implementing a featuretest-writerYes
Finished a task, ready for PRverify-appManual

Rules

  1. Universal agents are your defaults. Use them every session.
  2. Project agents are specialists. Use them when their domain is relevant.
  3. Worktree agents are safe to run in parallel — they can't break your work.
  4. Non-worktree agents share your context — don't edit the same files they're reading.
  5. When in doubt, spawn the agent. A wasted agent run costs less than a missed bug.
  6. If you spawn an agent and it's not useful, tell the user — they may remove it.
<!-- AUTO-GENERATED-END -->

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.