[FEATURE] /insights: Feature Fluency report card — per-feature adoption grades and gap analysis

Summary

Extend /insights with a Feature Fluency report card: a per-feature grade showing which Claude Code capabilities the user is leveraging well, which they're using superficially, and which they've never touched — with concrete, copyable next steps for each gap. Think Claude Desktop's "AI Fluency" surface, but native to the CLI and grounded in the user's actual session data and config.

Why

/insights already does the hard part — it scans ~/.claude/projects/** session logs, classifies sessions, and produces an HTML coaching report (~/.claude/usage-data/report.html) with an "At a Glance" section, friction analysis, and a "Features to Try" list. It's already AI-Fluency-coded in tone.

But the feature-adoption side is thin:

• The "Existing CC Features to Try" list is hardcoded to 5 items (MCP, custom skills, hooks, headless mode, task agents). It never changes regardless of what the user does.
• Feature-adoption signals are already collected but never surfaced. The per-session facet classifier records uses_task_agent, uses_mcp, uses_web_search, uses_web_fetch and aggregates sessions_using_* counts — but they don't appear anywhere in the rendered report.
• No gap analysis against the user's actual config. /insights doesn't introspect ~/.claude/settings.json, .claude/skills/, .claude/commands/, .claude/agents/, .mcp.json, or hooks to figure out what's installed vs. used vs. never tried.
• No grading, no trends. It's a snapshot with prose suggestions, not a scorecard the user can track over time.

Most users plateau on a small subset of features. A report card that says "you've never touched X, and here's the task you did Tuesday where it would have saved 40 minutes" would move people up the leverage curve far more than a generic features list.

Proposal

Add a "Feature Fluency" section to the /insights report (and a one-line score in the terminal summary) with:

1. Per-feature grade (Strong / Average / Under-utilized, or A–F) based on adoption rate × effectiveness signals (e.g., for plan mode: % of multi-file tasks that used it; for /compact: ratio of manual compacts to auto-compacts; for subagents: parallel fan-outs vs. serial passes on review tasks).
2. Complete feature inventory — replace the hardcoded 5-item list with the full surface, including power-user features (see below).
3. Config-aware gap analysis — cross-reference what's configured vs. what's actually invoked in sessions. "You have 3 MCP servers configured but only ever called 1." "You have 0 custom commands but repeated this prompt 11 times."
4. Concrete next steps — for each under-utilized feature, a copyable command, config snippet, or prompt linked to a real session where it would have helped (the report already does this pattern in "New Ways to Use Claude Code").
5. Trend — compare the score against the last /insights run so users can see progress.

Mockup (terminal summary)

╭─ Claude Code Fluency · last 30 days ──────────────────────────────╮
│                                                                   │
│  Overall: B+   ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░  82   (▲ +6 vs. last report)  │
│                                                                   │
│  Strong                                                           │
│   ✓ Context setup       A   CLAUDE.md in 9/10 repos               │
│   ✓ Plan mode           A-  used on 71% of multi-file tasks       │
│   ✓ Iteration speed     A   avg 3.1 turns to green tests          │
│                                                                   │
│  Average                                                          │
│   ~ Context hygiene     C+  auto-compact hit 14× — try /compact   │
│                              at natural breakpoints               │
│   ~ Cost efficiency     B-  18% of tokens spent re-reading files  │
│                              already in context                   │
│                                                                   │
│  Under-utilized                                                   │
│   ✗ Subagents           F   0 parallel fan-outs — went serial     │
│                              on 6 review tasks                    │
│   ✗ Custom commands     D   2 prompts repeated 11+ times — make   │
│                              them /commands                       │
│   ✗ Routines            —   never used /schedule                  │
│   ✗ Remote control      —   never used /rc or teleport            │
│                                                                   │
│  Try next:  /agents · .claude/commands/review.md · /schedule      │
│  Full report → file://~/.claude/usage-data/report.html            │
╰───────────────────────────────────────────────────────────────────╯

Feature inventory to grade

Core:

• CLAUDE.md / .claude/rules/ / CLAUDE.local.md
• Plan mode (Shift+Tab, /plan)
• /compact & context management (/context, manual vs. auto-compact ratio)
• Custom slash commands (.claude/commands/)
• Skills (.claude/skills/, /skills)
• Hooks (/hooks, settings.json)
• MCP servers (/mcp, .mcp.json, configured vs. actually invoked)
• Subagents / Agent tool / custom agent types (.claude/agents/)
• Plugins / marketplace
• Output styles
• Permission tuning (allowlists, permissionMode)
• Checkpoints / /rewind
• Auto-memory (/memory)
• /usage

Power-user (the part most users never discover):

• Routines / scheduled tasks — /schedule, claude --routine, claude.ai/code routines
• Teleport — claude --teleport, /teleport, moving sessions web ↔ local
• Remote control — /remote-control / /rc, controlling local sessions from web/mobile
• Agent view — claude agents, ← from a session
• Agent teams — multi-agent coordination, SendMessage, /team-onboarding
• Git worktree isolation — claude -w, --tmux, EnterWorktree
• Headless mode / Agent SDK — claude -p, --output-format json, CI integration
• Background bash & monitors — Ctrl+B, /tasks, Monitor tool
• Multi-Clauding — running parallel sessions (already has a chart in /insights, just no grade)

Data sources (all already available locally)

• ~/.claude/projects/**/*.jsonl — session transcripts (already parsed by /insights)
• Existing facet classifier output (~/.claude/usage-data/facets/) — already records uses_task_agent, uses_mcp, etc.
• ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json — hooks, MCP, permissions
• .claude/skills/, .claude/commands/, .claude/agents/, ~/.claude/skills/, etc. — what's installed
• .mcp.json, ~/.claude.json — MCP config
• Tool-call mix per session (already aggregated into "Top Tools Used")
• Previous /insights run output — for trend deltas

No new telemetry needed; this is a re-presentation of data /insights already touches.

Related

• #57979 — "Autopsy feature" (post-task effectiveness report; closest existing proposal to a report card)
• #28153 — Per-project insights reports
• #1549, #21943, #13892 — usage analytics / export requests
• The unrendered "Closing the Loop: Feedback for Other Teams" section in /insights (currently hardcoded empty in the rendered report) is another natural slot for adoption data.