Skip to main content
skill CX Codex

agent-fitness — Claude Code skill: reports and installation

The agent-fitness Claude Code skill tracks sub-agent dispatch results and highlights blocked or failed runs. It responds to requests about agent calibration and performance trends.

MIT ★ 26 updated 2026-11-16

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add wrg32786/aigent-os --skill agent-fitness -a claude-code
Open on GitHub

What agent-fitness does

The skill extracts dispatch records from JSONL and appends new rows to memory/AGENT_FITNESS.md. Run /agent-fitness to get dispatch totals, per-agent outcome counts, and recent trends. Add --days N to limit the report to a time window.

The report separates clean, blocked, errored, and partial outcomes. Calibration ratios exclude infrastructure errors, while repeat-blocker alerts appear after two or more blocks in the selected window. Classification relies on keyword matching; the skill does not reroute dispatches. Extraction runs through python3.

What it helps with

  • compare clean and blocked dispatch counts across agents
  • spot agents with repeated blocks in a chosen period
  • find agent-and-task pairs that often end in failure
  • check recent outcome trends for a sub-agent

Example prompts for the agent

  • Extract new sub-agent dispatch records with /agent-fitness extract.
  • Show the overall agent report with /agent-fitness.
  • Limit the report to the last 7 days with /agent-fitness --days 7.

How to install agent-fitness

1Skills CLI (Vercel)

npx skills add wrg32786/aigent-os --skill agent-fitness -a claude-code

2Manually: put the files in place

~/.claude/skills/agent-fitness/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/agent-fitness/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about agent-fitness

How do I install agent-fitness in Claude Code?

Run npx skills add wrg32786/aigent-os --skill agent-fitness -a claude-code. The skill file is at ~/.claude/skills/agent-fitness/SKILL.md.

What does agent-fitness do?

It tracks sub-agent dispatch outcomes and produces per-agent reports. The results include blocks, errors, and recent trends.

What does agent-fitness need to run?

Extraction uses python3. Dispatch records come from JSONL, and the skill appends them to memory/AGENT_FITNESS.md.

Source text

SKILL.md · MIT
---
name: agent-fitness
agent: none
description: "Track sub-agent dispatch calibration from JSONL or ledgers. Use when checking agent fitness, clean/blocked/error trends, or which agents work."
allowed-tools: Bash, Read
user-invocable: true
triggers:
  - agent fitness
  - agent calibration
  - agent stats
  - sub-agent stats
  - which agents work
  - /agent-fitness
  - agent dispatch trends
---

# /agent-fitness

Three modes:

**`/agent-fitness extract`** — runs `python3 daemons/agent-fitness-extract.py` to scan the latest JSONL transcript and append new dispatch rows to `memory/AGENT_FITNESS.md`. Idempotent (dedup by session_id + tool_use_id).

**`/agent-fitness`** (no args) — runs `python3 daemons/agent-fitness-report.py`. Surfaces:
- Total dispatches (all-time, last 30d, last 7d)
- Per-agent calibration table (Total / Clean / Blocked / Errored / Partial / Ratio)
- Per-agent recent outcome trend (last 10 dispatches encoded as `c7 b1 e0 p0`)
- ⚠ Repeat-blocker callouts (any agent with >=2 blocks in window)
- Top 3 failing (agent, task) pairs

**`/agent-fitness --days 7`** — same as above but windowed to last N days. Useful for "is this agent failing more lately?"

## Computation

Calibration ratio per agent: `clean / (total − errored)`. The denominator excludes hard errors (infrastructure/tool failures) and only counts agent-level outcomes.

Trend signal: any agent with >=2 blocks in the window surfaces a repeat-blocker callout. The classifier was hardened in v0.5.1 to catch real Lyra-style block patterns ("BLOCKED:", "are denied", "blocker-found" etc).

## When to run

- After major sessions where multiple sub-agents fired (today S30d had ~7 dispatches)
- Periodically (weekly?) to spot trends
- Before relying on a sub-agent for something heavy ("am I about to dispatch an agent that's been failing?")

## What it does NOT do

- Does not auto-reroute dispatches based on calibration. Surfaces data; principal decides.
- Does not LLM-classify failures — heuristic only (keyword matching on result content).
- Does not pool across sessions for cluster analysis. Future v0.5.x.
- Does not include task-type clustering. All tasks pooled per agent.

## Cross-links

- [[concepts/Somatic v0.5.0 Agent Fitness]] — spec
- [[memory/AGENT_FITNESS]] — the data
- [[concepts/Somatic Roadmap]]
- [[memory/TRUST_DECAY]] — sibling claim → outcome ledger

© wrg32786 · MIT · wrg32786/aigent-os

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set58

The whole set →
compact-note The compact-note Claude Code skill condenses long notes and logs while keeping the reasoning behind decisions. It runs on requests to shorten a note, log, or memory. CX Codex +1 ★ 26repo stars comms-summarize The comms-summarize Claude Code skill summarizes unread messages from an inbox, channel, or thread. It flags items that need action and separates them from FYI and stale messages. CX Codex +1 ★ 26repo stars cognitive-update The cognitive-update Claude Code skill updates goals, beliefs, self-model fields, and procedures from explicit evidence. It activates for cognitive or runtime state changes. CX Codex +1 ★ 26repo stars codex-adapter The codex-adapter Claude Code skill hands one bounded, mechanical change to OpenAI Codex CLI. It activates on an explicit request to delegate a rename, config edit, or scripted replacement. CX Codex +1 ★ 26repo stars close This Claude Code skill saves session outcomes to durable memory and prepares a resume point. Run /close to wrap up work and update notes in vault/. CX Codex +1 ★ 26repo stars capsule-compact The capsule-compact Claude Code skill condenses long chains of context capsules. Run it on request or when a chain has grown too long. CX Codex +1 ★ 26repo stars brief This Claude Code skill drafts a structured brief for handing work to a sub-agent. It runs when a task needs to be assigned, handed off, or explained to another agent. CX Codex +1 ★ 26repo stars body-check The body-check Claude Code skill reads existing signals about context, memory, and pending work. It reports the current state and suggests a next action. CX Codex +1 ★ 26repo stars

Project sponsors

Companies that keep this analytics open