---
title: "mk:agent-detector"
description: "mk:agent-detector"
---

## What This Skill Does

`mk:agent-detector` is the highest-priority MeowKit skill that runs first on every user message. It analyzes task content, technology mentions, user intent, project context, and file patterns through a 5-layer scoring system to auto-detect which agent should handle the task, at what complexity level, with which model, and whether team mode is warranted. The output is a detection banner shown at the start of every response.

## When to Use

**ALWAYS** — every user message, no exceptions. This skill fires before any other skill or agent action. It determines who handles the task, at what complexity level, and with which model.

## Core Capabilities

### 5-Layer Detection System

| Layer | Name | What It Checks | Score Range |
|-------|------|---------------|-------------|
| 0 | Task Content Analysis | Task patterns regardless of repo type (e.g., PDF styling in a backend repo) | +50 to +60 |
| 1 | Explicit Technology Detection | Direct tech mentions (React, Go, Laravel, etc.) | +60 |
| 2 | Intent Detection | Action keywords (fix, implement, test, design, audit) | +50 exact / +35 semantic |
| 3 | Project Context Detection | Package files, directory structure, config files | +40 |
| 4 | File Pattern Detection | Recent file names, naming conventions | +20 |

**Key rule:** Layer 0 task content can override repo-based detection. A frontend task in a backend repo routes to the right agent regardless.

### Agent Thresholds

| Level | Score | Role |
|-------|-------|------|
| PRIMARY | >= 80 | Leads the task |
| SECONDARY | 50-79 | Supporting role |
| OPTIONAL | 30-49 | May assist |
| Not Activated | < 30 | Not selected |

### Complexity Auto-Detection

| Level | Criteria | Model | Approach |
|-------|----------|-------|----------|
| Quick | Single file, typo fix, explicit path | Haiku | Direct implementation |
| Standard | 2-5 files, feature add, some unknowns | Sonnet | Scout then implement |
| Deep | 6+ files, architecture, vague scope | Sonnet/Opus | Research + plan + implement |

### Model Selection

| Model | When Used |
|-------|-----------|
| Haiku | Quick tasks, simple queries, orchestration routing, journal-writing |
| Sonnet | Standard implementation, coding, testing, bug fixes, reviews |
| Opus | Architecture design, security audits, complex planning, refactoring |

### QA Agent Conditional Activation

- **tester is SECONDARY** when Intent = Implementation or Bug Fix
- **tester is PRIMARY** when Intent = Testing or user explicitly asks for tests
- **tester is SKIPPED** for pure docs, design discussions, or research-only tasks

### Team Mode Detection

Team mode (parallel Claude Code teammates) only activates when ALL conditions are met:

1. `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` is enabled
2. Complexity = Deep
3. 2+ domains each score >= 50
4. Task requires cross-domain collaboration

Team mode costs ~3x tokens; only justified when parallel cross-domain work would take 3x longer sequentially.

### Token Budget Levels

After detection, the skill silently sets response verbosity:

| Level | Budget | Trigger Signal Words |
|-------|--------|---------------------|
| Essential | 25% | "brief", "short", "tldr", "quick" |
| Moderate | 50% | "explain", "how does", "walk me through" |
| Detailed | 75% | "detailed", "thorough", "step by step" |
| Exhaustive | 100% | "exhaustive", "everything", "complete" |

Complexity fallback: TRIVIAL -> Essential, STANDARD -> Moderate, COMPLEX -> Detailed. Security/payment/architecture tasks always start at Detailed.

## Workflow

1. **Pre-Step: Check Cache** — Check `.claude/cache/agent-detection-cache.json`. If same workflow and phase > 1, reuse cached result (saves ~500-1000 tokens). Invalidate on new workflow, phase reset, or user override.

2. **Step 0: Task Content Analysis** — Analyze the actual task, not just the repo. Classify task domain (frontend, backend, database, security, etc.) regardless of the repository's primary language.

3. **Step 1: Extract Keywords** — Extract action keywords ("fix", "implement", "design"), component names, platform mentions, and issue descriptions from the user message.

4. **Step 2: Check Project Context** — Read `.claude/memory/fixes.md`, `review-patterns.md`, `architecture-decisions.md`. If insufficient, run `mk:scout` or read `package.json`/`tsconfig.json` directly.

5. **Step 3: Score All Agents** — Combine task scores and repo scores across all 5 layers. Each agent gets a weighted total.

6. **Step 4: Select Agents** — PRIMARY if >= 80, SECONDARY if 50-79, OPTIONAL if 30-49. Check team mode eligibility if Deep + multi-domain.

7. **Step 5: Show Banner** — Display detection result banner at start of response. Single-agent or multi-agent format depending on collaboration needs.

8. **After Detection** — Load agent instructions from `.claude/agents/[agent-name].md`. Invoke the appropriate skill (mk:cook, mk:fix, mk:investigate, mk:review, mk:cso). Context loaded on demand from `.claude/memory/` topic files.

## Example Prompt

```
User: "Fix the login button not working on iOS"

Detection:
- Layer 0: "button" → frontend task content (+50)
- Layer 1: "iOS" → mobile platform
- Layer 2: "fix", "not working" → Bug Fix intent
- Layer 3: package.json has React → +40
- Layer 4: *.phone.tsx files present → +20

Result:
  Agent: developer (PRIMARY, 85 pts)
  Model: sonnet
  Complexity: Standard
  Secondary: tester (35 pts — bug fix triggers QA)
```

## Common Use Cases

- **Every message** in a MeowKit-enabled project — runs automatically
- **Multi-domain tasks** — user says "add a security check to the payment UI"; detector splits scores and picks the right primary agent
- **Cross-repo tasks** — frontend task in a backend repo; Layer 0 overrides repo-based detection
- **Quick fixes** — "fix typo in README.md line 42" routes to orchestrator with Haiku and bypasses planning

## Pro Tips

- If the banner shows an unexpected agent or model tier, override via `--quick` or use explicit skill shorthands like `/mk:fix --quick`.
- For cross-domain tasks, state the primary concern explicitly at the start (e.g., "Security task: add check to the payment UI") so Layer 0 detection anchors correctly.
- The detection cache does NOT invalidate on pivot signals. After any explicit task change ("actually, let's do X instead"), confirm the banner is correct — if not, start a new message explicitly describing the new task.
- Short messages with domain keywords ("fix the auth token") score high for complex agents even for one-line changes — the detector favors keyword matches over scope signals.

## Session-cached safety/phase-zero load (since 2.9.6)

Steps 0 and 0b first scan the context window for a cached-sentinel marker emitted by the `UserPromptSubmit` handler. When present, the 10-file Read loop (5 safety + 5 phase-zero rules) is skipped and a single-line confirmation is emitted instead.

| Marker | Effect |
|--------|--------|
| `## Safety baseline: verified (cached, session <id>)` | Step 0 skips the 5-file safety Read loop |
| `## Phase-zero rules: verified (cached, session <id>)` | Step 0b skips the 5-file phase-zero Read loop |

**State source:** `session-state/session-sentinels.jsonl` — one JSONL line per Stop with `{session_id, safety, phase_zero, ts}`. The file is truncated on new-session detection (HOOK_SESSION_ID change), so sentinels never cross session boundaries.

**Safety guarantee preserved.** The rules remain in context from the host runtime's auto-load of `CLAUDE.md` + `.claude/rules/`. The sentinel only suppresses redundant re-reads; it does not weaken the existence check on turn 1 of any new session.

**Bypass.** `MEOWKIT_SKIP_SAFETY_SENTINEL=off` disables marker injection. The skill then runs the full 10-file Read loop every turn.

**Scope.** The optimization depends on the inner harness firing the Stop and UserPromptSubmit hooks that write and read the JSONL log. Inner harnesses that do not fire those hooks see no sentinel in context and run the full check on every turn — no safety regression, just no speedup.

## Step 0b — Agile context detection (additive)

After loading the 5 phase-zero rules, Step 0b checks for an Agile context and conditionally loads 3 additional rules from `.claude/rules-conditional/agile-*.md`. Non-Agile sessions skip this load silently — zero context cost.

**Pre-flight:** verify `.claude/rules-conditional/` directory exists. If absent → log and skip steps 2–4 (defensive against drift between status doc and filesystem).

**Detection (OR-logic, any one match triggers load):**

| Condition | Mechanism |
|-----------|-----------|
| Sprint-state contract present | Glob `tasks/contracts/sprint-state-*-sprint-*.md` returns ≥1 result |
| Active plan frontmatter | Non-empty `jira_tickets:` |
| Env var | `MEOW_JIRA_BASE_URL` set |
| User prompt | Last user message matches `[A-Z]{2,10}-\d+` |

**Load:** if Agile context detected, `Read` each of the 3 rules. Per-file Read failure → log and skip THAT rule; do NOT abort Step 0b.

**Sprint-goal banner:** if a sprint-state contract exists, parse `sprint_goal:` from the newest active sprint-state file (status: active) and surface in the orient banner.