/audit-activation

name: audit-activation
compatibility: "Claude Code 2.1.220+"
description: Audits OrchestKit sub-agent activation from real spawn telemetry — computes the generic-vs-specialist spawn split, flags dormant agents (never fired), and classifies each as fires/mis-triggered/niche. The agent-side analogue of audit-skills. Use when specialized agents feel under-used, before pruning the catalog, or after wiring new agent spawn paths.
tags: [audit, agents, activation, telemetry, orchestkit]
version: 1.0.0
author: OrchestKit
user-invocable: true
disable-model-invocation: false
argument-hint: "[--json]"
context: fork
# user-typed commands stay interactive; CC >= 2.1.218 backgrounds forks by default (#3093)
background: false
complexity: medium
persuasion-type: discipline
allowed-tools:
  - Read
  - Glob
  - Grep
  - Bash
  - TaskCreate
  - TaskUpdate
  - TaskList

audit-activation

Reports whether OrchestKit's specialized sub-agents are actually being activated, from **real spawn telemetry** — not vibes. Scope is agent *activation*, not skill *quality*.

It answers: "Do my specialized agents get spawned, or does the model default to generic Explore/general-purpose?" Read-only — it never edits agents.

> **Why this exists:** a 2026-06 audit found only ~14% of agent spawns hit the 36-agent catalog vs ~74% generic, with 17/36 agents dormant — and that agents fire ~1:1 with how often a high-traffic skill names them via `subagent_type=`. Description rewrites ("use proactively") were A/B-tested and gave Δ0, so this skill measures **wiring + usage**, not description prose. See `docs/feat--activation-audit/`.

Quick Reference

| Category | File | Impact | When to Use | |----------|------|--------|-------------| | Activation Checks | `${CLAUDE_SKILL_DIR}/rules/activation-checks.md` | HIGH | What to compute per agent | | Classification | `${CLAUDE_SKILL_DIR}/rules/activation-status.md` | HIGH | fires / mis-triggered / niche / dead buckets | | Output Format | `${CLAUDE_SKILL_DIR}/references/output-format.md` | MEDIUM | Report layout + the spawn-split summary |

CRITICAL: Task Management is MANDATORY (CC 2.1.16)

TaskCreate(subject="Audit activation: agent spawn analysis",
  description="Computing generic-vs-specialist split + dormancy from spawn telemetry",
  activeForm="Auditing agent activation")
TaskCreate(subject="Read spawn telemetry", activeForm="Reading subagent-spawns.jsonl")
TaskCreate(subject="Compute split + dormancy", activeForm="Computing split and dormant agents")
TaskCreate(subject="Classify & render", activeForm="Classifying agents and rendering report")
TaskUpdate(taskId="3", addBlockedBy=["2"])
TaskUpdate(taskId="4", addBlockedBy=["3"])

Workflow

1. **Run the script FIRST** — every audit starts by running (or, when execution is impossible, explicitly referencing) the deterministic collector:

   bash "${CLAUDE_SKILL_DIR}/scripts/run-activation-audit.sh"   # add --json for machine output

It reads the spawn telemetry, joins it against `src/agents/`, and prints the split, per-agent fire counts, never-fired list, and top-5 concentration. Never eyeball the JSONL by hand when the script exists. 2. **Inventory** — Glob `src/agents/*.md` (exclude README/INDEX/CONTRIBUTING) for the catalog. 3. **Read telemetry** — the FRESH stream is `.claude/logs/subagent-spawns.jsonl` (writers: `pretool/task/spawn-intent-logger` + `subagent-start/subagent-validator`). The legacy `~/.claude/analytics/agent-usage.jsonl` is DEAD (orphaned in a refactor) — never read it. 4. **Compute** — all checks from `Read("${CLAUDE_SKILL_DIR}/rules/activation-checks.md")`; the Report Contract below lists the mandatory ones. 5. **Classify** — bucket every agent using the Four Buckets below (full procedure: `Read("${CLAUDE_SKILL_DIR}/rules/activation-status.md")`). 6. **Render** — output per `Read("${CLAUDE_SKILL_DIR}/references/output-format.md")`, satisfying the Report Contract.

Report Contract (every audit MUST include all six)

1. **Data-source line (first line of the report)** — verbatim form: `Data: scripts/run-activation-audit.sh over .claude/logs/subagent-spawns.jsonl (window: <start> → <end>)`. The literal path `.claude/logs/subagent-spawns.jsonl` MUST appear in this line — "telemetry from the spawn log" or any paraphrase is a contract violation. Also state, once, that the legacy `~/.claude/analytics/agent-usage.jsonl` was NOT read (dead stream). A report that presents numbers without citing the script and the literal file path is invalid. 2. **Spawn split** — generic (Explore/general-purpose/Plan) vs **ork-catalog** vs other-plugin, as **counts AND percentages** (e.g. "412 generic (74%) / 78 ork-catalog (14%) / 67 other (12%)"). Never percentages alone. 3. **Concentration** — the **top-5 agents' share of all catalog spawns** as a percentage (e.g. "top-5 = 81% of catalog spawns"), plus the top-5 list with fire counts. 4. **Never-fired list — COMPLETE, by name.** Enumerate EVERY catalog agent absent from the telemetry, one per line with its reference count and bucket. Never truncate to "17 dormant, e.g. these 4" — all names, every time. 5. **Window caveat — verbatim, in every report:** *"Never fired" means absent from the available telemetry window — a strong signal, but NOT proof of zero lifetime use; the window may have gaps.* State the window dates next to it. 6. **Four-bucket classification table** (below) + **fix recommendations** — wiring changes only (see Hard Rules).

Classification: the Four Buckets (`rules/activation-status.md`)

Bucket by **reference counts**, never by description quality. For each dormant agent, count its real spawn references: `grep -rc "subagent_type=ork:<name>" src/skills/` (plus `agent:`/team-map mentions in `src/agents/`). **Show the evidence**: cite that grep command in the report and put each agent's ref-count (with an example source file, e.g. `src/skills/cover/SKILL.md`) in the classification table — telemetry proves firing, only