| name | performance |
| description | Use this skill when the user says /performance, /digest, asks for a weekly Claude performance report, or wants to review how their Claude Code sessions have been going. Reads JSONL session files from ~/.claude/projects/, computes six effectiveness metrics (activity distribution, one-shot edit rate, subagent turn count, model mix, project allocation, hookify firings), fires diagnostic rules when thresholds breach, and writes behavioral rules into ~/.claude/CLAUDE.md so future sessions adapt. Closes the measurement loop for self-improving AI workflows. |
| version | 1.0.0 |
Performance Digest
Measurement layer for Claude Code. Turns session telemetry into prescriptive behavioral rules that Claude reads on the next session start.
A static rule is a wish. A measured rule is a system.
What it does
Every seven days, reads all Claude Code session files from the last week and computes:
- Activity distribution: Coding, Exploration, Debugging, Delegation, Planning, Conversation
- One-shot edit rate: percentage of file edits that landed without a retry cycle
- Agent spawn analysis: how many subagents fired and how many turns each took
- Model mix: Opus vs. Sonnet vs. Haiku across all turns
- Project allocation: which codebases consumed the most attention
- Hookify firings: which behavioral guardrails actually triggered
Then runs six diagnostic rules. When a rule fires, one of two things happens:
- Behavioral prescriptions (verbose agents, model routing, low one-shot rate, exploration overhead) are written directly to
~/.claude/CLAUDE.md as permanent rules Claude reads on future session starts.
- Investigation prescriptions (recurring errors, hookify repeats) are appended to a Claude To-dos list for the user to review.
Next week the digest re-measures. If the number moved, the rule worked. If it did not, the rule fires again with updated numbers.
Setup
Expected vault layout (follows ai-brain-starter conventions):
<vault-root>/
⚙️ Meta/
Performance/ (reports land here)
Claude To-dos.md (prescriptions go here)
scripts/
claude_performance_digest.py
Copy scripts/claude_performance_digest.py into your vault at the matching path. The script self-locates via __file__ and expects to sit at <vault>/⚙️ Meta/scripts/.
Optional: edit the PROJECT_LABELS dict at the top of the script to map project directory substrings to clean display labels.
Optional: tune the THRESHOLDS dict. Defaults are calibrated for daily power users.
Usage
Run manually:
python3 "<vault>/⚙️ Meta/scripts/claude_performance_digest.py"
Or schedule weekly. Examples:
Cron (Monday 1am UTC, adjust offset for your timezone):
0 1 * * 1 /usr/bin/python3 "/path/to/vault/⚙️ Meta/scripts/claude_performance_digest.py"
Or via the scheduled-tasks Claude Code plugin, if installed.
Flags
--days N: lookback window (default 7)--dry-run: print report to stdout, do not write files--no-report: skip the markdown report, apply prescriptions only
What the output looks like
A dated markdown file at ⚙️ Meta/Performance/weekly-YYYY-MM-DD.md:
# Performance Digest: 2026-04-09 to 2026-04-16
**767 sessions** across 3 projects. 20,822 assistant turns. 773 files edited.
## Activity Distribution
| Category | Turns | % |
| Coding | 1392 | 7% |
| Exploration | 3062 | 15%|
| Debugging | 2719 | 13%|
| Delegation | 324 | 2% |
| Planning | 2292 | 11%|
| Conversation | 13033 | 52%|
## One-Shot Edit Rate
**83%** (773 files edited, 129 required retries) - on target
## Agent Spawns
**324 agents spawned**. Average turns per agent: **22.0**
## Diagnostics
- **VERBOSE AGENTS**: Avg agent turns is 22.0 (target: <5). Review agent
prompts: add file paths, expected output format, and clear scope.
## Trending
*Baseline week. No prior data for comparison.*
And a behavioral rule written into ~/.claude/CLAUDE.md:
- [VERBOSE AGENTS fix](performance_verbose_agents.md) | Agent briefings must
include: specific file paths, expected output format, and scope boundary.
Target: <8 turns per agent. Current avg: 22.0. (updated 2026-04-16)
Why this exists
Self-improvement by memory alone has a failure mode: a rule gets written, Claude reads it at session start, and under the wrong context the behavior recurs anyway. Without measurement, you cannot tell whether a correction actually worked. You can only tell that you wrote the rule.
This skill closes the loop. Rules come with a number attached. Baseline, target, check-in. Next week the measurement tells you whether the rule is alive, needs revising, or can retire.
Integration
If you use the /weekly skill from claude-insights, the weekly review auto-surfaces the most recent performance digest in its report. The two skills compose: /weekly tells you what happened in your life, /performance tells you what happened in your AI workflow.
