| name | tool-efficiency |
| model | opus |
| effort | high |
| description | Audit how a tool, command, or MCP server is actually used across coding-agent sessions and produce calibrated recommendations — tool-vs-task fit, error forensics, fix recommendations, permission friction, MCP health, and token economics. Use when the user says "tool efficiency", "am I using X efficiently", "audit tool usage", "why does X keep failing", "how do I fix this error", "what should I change", "permission friction", "is this MCP worth it", "tool error rate", "fix recommendations", or invokes /tool-efficiency. Do NOT use for auditing a skill or agent definition (that is /skill-improver) or for one-off interactive log queries (that is /session-analytics).
|
| allowed-tools | Read, Agent, Bash |
tool-efficiency
Audit how a tool / command / MCP server behaves in practice across sessions,
then produce calibrated recommendations. Judgment skill — it scores findings
with the shared confidence × severity model, it does not just report numbers.
Input
A target: a tool name (Bash, Read, Edit), a command prefix (git,
cargo), or an MCP server (serena, tilth). If none given, ask. Optionally a
harness filter (all default, or claude/codex/opencode).
Owned domains
This skill owns six analytics packs under references/:
| Domain | Pack | What it surfaces |
|---|
| tool-usage | tool-usage.md | Frequency, project spread, tool-vs-task fit |
| error-forensics | error-forensics.md | Error rate vs baseline, recurring failures |
| fix-recommendations | fix-recommendations.md | Turns errors/friction into concrete fixes (allowlist adds, tool swaps, MCP repair/retire) — advisory only |
| permission-friction | permission-friction.md | Denials, allowlist gaps, compound-command friction |
| mcp-health | mcp-health.md | Per-MCP call volume, error rate, idle servers |
| token-economics | token-economics.md | Token/cost where logged — degrades to "insufficient signal" |
Protocol
-
Ingest — python3 ~/Dev/dotfiles/skills/session-analytics/scripts/ingest.py
(1-hour TTL, fast if cached). Best-effort; skip the analytics if it fails.
-
Fan out — spawn one parallel duckdb-expert per relevant domain
(one-domain-per-spawn; never a single all-domains spawn):
spawn duckdb-expert "Run analytics pack tool-efficiency/references/<domain>.md for target {TARGET}. harness={HARNESS}"
Pick the domains that fit the target: MCP targets → mcp-health +
error-forensics + fix-recommendations; a Bash command → tool-usage +
permission-friction + error-forensics; "how do I fix X" / high error rate
→ error-forensics + fix-recommendations; broad audit → all six.
-
Collect the ~2 KB digests.
-
Calibrate each finding with the shared model in
../session-analytics/references/calibration.md — confidence
(<certain>/<speculative>/<don't know>) × severity
(blocker/high/medium/low). <don't know> never surfaces.
-
Report (below).
Report
## Tool Efficiency Report: {TARGET}
### Summary
- Target: <tool/command/MCP> · Harness: <filter>
- Domains run: <list>
- Findings: N surfaced, N below the bar
### Recommendations (surfaced)
| # | Severity | Confidence | Domain | Issue | Recommendation |
|---|----------|------------|--------|-------|----------------|
### Detail
For each surfaced finding: What / Why (with the metric that evidences it) / How.
### Below the Bar
N findings were `<don't know>` or insufficient-signal (not shown).
What this skill never does
- Score with a 0-100 number — it uses the shared qualitative model.
- Surface
<don't know> findings or fabricate when a domain returns empty.
- Run more than one domain per
duckdb-expert spawn.
- Modify tools, settings, or allowlists — it recommends; the human decides. The
fix-recommendations domain names the fix (allowlist entry, tool swap, MCP
retirement); it never applies it. Hand the surfaced fixes to /cure or
/settings-clean if the user wants them applied.
Gotchas
token-economics is <don't know> on most logs (no token fields) — say
"insufficient signal", do not invent a cost.- Permission denials and stop-hooks are claude-dominant; on codex/opencode treat
their absence as missing signal, not as zero friction.
