Agent Stats — System-Level Pipeline Health

Render a summary of agent pipeline health from ~/.claude/tasks/<project>/metrics.jsonl files. The aggregation is read-only — no metrics are modified, no events are emitted.

This skill answers questions a staff/principal engineer asks about the system, not about a single run:

• What is Cyrus's first-pass success rate?
• How often does Optimus's plan need a CI-fix retry?
• What does the classification distribution look like — am I escalating too often?
• Are swarm runs converging or stalling?

When to Use

• The user types /agent-stats.
• The user asks "how is the agent pipeline doing?", "show me agent metrics", "is Cyrus first-passing?", "what's our first-pass rate?", or any system-level question that single-ticket views cannot answer.
• A briefing or scheduled job wants to surface a weekly health snapshot.

What It Is Not

• Not a per-ticket view (use /swarm-retro for run-level analysis).
• Not a real-time monitor — it reads the on-disk metrics.jsonl, which is updated by emitters at pipeline completion.
• Not a writer — it never modifies metrics, never promotes lessons, never opens PRs.

Workflow

Step 1: Resolve scope

Parse the user's invocation for filters:

If the user names a project that does not match a directory under ~/.claude/tasks/, run anyway — the script will report "no events in window" cleanly.

Step 2: Run the aggregator

Invoke the script:

bash "$(readlink ~/.claude/skills/agent-stats)/../../../scripts/agent-stats.sh" [--project <name>] [--days <N>]

The script lives at scripts/agent-stats.sh in the dotfiles-core repo, which is not itself symlinked into ~/.claude/ — resolving through this skill's own symlink locates it regardless of where the repo is checked out.

The script's output is plain text designed to be copy-pasted as-is. Do not reformat it. Do not summarize it. Display the raw output.

Step 3: Add interpretation, only if signal warrants it

After the raw output, add a short interpretation only when there is something the numbers don't say outright:

• If the script raised health flags: name the most likely cause based on what the user has been working on recently. Example: "First-pass rate dropped — your last 3 swarm runs were on the auth-rewrite branch, which is the most architecturally novel work this month."
• If sample size is small: say it once, then stop. Don't editorialize on noisy data.
• If first-pass rate is high (≥85%) and stable: a one-liner acknowledging it. Healthy systems deserve a sentence too.

If the numbers speak for themselves, do not add interpretation. The script's output is sufficient.

Step 4: Suggest one next step (optional)

Only if a flag is actionable, suggest exactly one next command:

Never suggest more than one. The user is reading a dashboard, not running a triage.

Failure Modes

Schema Reference

This skill consumes events defined in ~/.claude/evals/schemas/metrics-event.schema.json. The five event types it reads:

• pipeline_complete — emitted by cyrus-tdd-engineer and ticket-pickup. Contributes to first-pass and CI-fix metrics. Events with outcome: advisory (a correct no-code answer) are counted on their own line and excluded from the first-pass denominator.
• ticket_classified — emitted by ticket-pickup after the classification gate. Contributes to classification distribution.
• swarm_complete — emitted by ticket-swarm at run end. Contributes to swarm outcomes.
• multi_repo_split — emitted by ticket-pickup on multi-repo detection. Contributes to the Multi-Repo Splits section: counts split by mode and gate_choice, plus the notice-vs-gate ratio — the detection false-positive denominator.
• review_round_posted — emitted by review-respond once per posted or updated review-round summary. Contributes to the Review Rounds section: the total and the split by action (post vs update).

All five are read by scripts/agent-stats.sh. If a new event type beyond these is added to the schema, this skill will silently ignore it until the script is updated. That is intentional — the dashboard prefers stability over completeness.

Responsibility Boundaries