The Problem: /insights Gives You a Report, Then What?
Claude Code's /insights command is one of its most underrated features. It analyzes your last 30 days of usage and generates a detailed HTML report: friction patterns, strengths, CLAUDE.md suggestions, workflow recommendations, and more.
The problem? The report is read-only. It's a beautiful HTML page that you read, nod at, and then close. The friction patterns it identifies are real — but translating them into CLAUDE.md rules, custom skills, and settings changes is manual, tedious work that most developers skip entirely.
That's the gap claude-insights fills.
What claude-insights Does
claude-insights is an open-source CLI tool that parses your /insight report HTML and generates production-ready output files — personalized to your specific friction patterns, not generic templates.
One command:
npx claude-insights analyze ~/.claude/usage-data/report.html
Generates:
| Output File | What It Contains |
|---|---|
insights-todo.md |
Prioritized task table with steps, time estimates, and expected friction reduction |
CLAUDE.md-additions.md |
Ready-to-paste rules organized by section (General, CSS, Testing, Debugging) |
.claude/settings-insights.json |
Hook configurations extracted from your report |
.claude/skills/*.SKILL.md |
Custom skill files — one per friction pattern — with triggers, steps, rules, and verification checklists |
insights-README.md |
Placement guide explaining where each file goes |
The Pipeline: Parse, Analyze, Generate
The tool follows a three-stage pipeline:
1. Parse
Uses cheerio to extract structured data from the HTML report — stats, project areas, friction categories with examples, CLAUDE.md suggestions with rationale, feature recommendations, workflow patterns, and more.
Parsing report...
Parsed report: 982 messages, Jan 5 — Feb 3, 2026
3 friction areas, 4 strengths, 5 CLAUDE.md suggestions
2. Analyze
This is where the tool does its heavy lifting. For each friction pattern in your report, it:
- Generates a custom skill file with YAML frontmatter containing trigger-rich descriptions extracted from your actual friction examples
- Matches friction patterns to CLAUDE.md suggestions using significant-word overlap scoring
- Cross-references workflow patterns from the report to include suggested starting prompts
- Builds verification checklists derived from your specific failure examples — so Claude is forced to check against each one
- Derives a prioritized to-do list ranked by impact: friction-derived tasks (High), CLAUDE.md rules (High), features (Medium), patterns (Medium)
3. Generate
Writes all output files to your chosen directory, creating the .claude/skills/ structure automatically.
What the Generated Skills Look Like
This is the part that matters most. Each friction pattern becomes a structured skill file that Claude Code can invoke with a slash command.
Here's a real example — generated from a report where Claude kept proposing fixes without checking the codebase first:
---
name: solutions-codebase-verification
description: |
Use when encountering premature solutions without codebase verification,
especially when adding new API endpoints to an existing controller,
or refactoring shared utility modules.
---
## When to Use This Skill
- When a task involves premature solutions without codebase verification.
- When adding new API endpoints to an existing controller.
- When refactoring shared utility modules.
## Steps
1. **Diagnose**: Read the relevant files and map the existing patterns.
Identify boundaries, ownership, and current behavior before changing
anything.
2. **Identify constraints**: List what must NOT change, which components
are affected, and document your assumptions. Get confirmation.
3. **Propose approach**: Describe your planned fix and explain why it
avoids the known failure patterns listed in "What Goes Wrong" below.
Wait for approval.
4. **Implement**: Apply the most minimal, narrowly-scoped change possible.
5. **Verify**: Confirm the fix works AND doesn't regress related components.
## Rules
- Before proposing a fix, always verify the approach against the existing
codebase patterns first
- Do NOT suggest options or solutions without confirming they work in this
specific codebase
- After implementing, verify the fix doesn't regress related components
## What Goes Wrong
Review these failure patterns before implementing. Your fix must not
repeat them:
- When adding a new endpoint, Claude reused a pattern from a different
controller that didn't match the authentication middleware in this one,
requiring a full rewrite after review.
- When refactoring the shared utility, Claude moved functions without
checking downstream consumers, breaking two dependent services.
## Verification Checklist
- [ ] Fix addresses the specific issue the user reported
- [ ] Change follows existing codebase patterns found during diagnosis
- [ ] Change is narrowly scoped — minimal blast radius
- [ ] Related/sibling components verified — no regressions
- [ ] Approach was proposed and confirmed before implementation
After placing this file in .claude/skills/, you invoke it with /solutions-codebase-verification at the start of any relevant task. Claude reads the skill, follows the steps, checks against your documented failure patterns, and runs through the verification checklist before claiming the work is done.
The key insight: these skills aren't generic. They contain your friction examples, your failure patterns, and your codebase-specific rules. That's what makes them effective.
The CLAUDE.md Rules: Categorized and Annotated
The tool doesn't just dump rules — it categorizes them by domain and includes the rationale from your report:
## General Rules
Before proposing a fix, always verify the approach against the existing
codebase patterns first. Do NOT suggest options or solutions without
confirming they work in this specific codebase.
> _Why: In multiple sessions Claude suggested approaches without verifying
> them against the codebase, leading to wrong patterns (e.g., incorrect
> test setup, mismatched import conventions), requiring repeated user
> corrections._
## CSS & Styling
When working with CSS in component libraries (especially scoped styles
and design tokens): 1) Always scope CSS fixes narrowly to avoid breaking
other components, 2) Test that changes don't regress sibling views.
## Testing
Follow the existing test patterns in the file's directory — check sibling
test files before writing new ones. Match existing mock/setup patterns
for unit tests and page object patterns for E2E tests.
## Debugging
When debugging production or intermittent issues, do NOT jump to
conclusions. First: reproduce locally. Second: add targeted diagnostic
logging. Third: only propose a fix when the root cause is confirmed.
You copy the rules you want into your project's CLAUDE.md. The _Why annotations help you decide which rules matter most for your workflow.
The Prioritized To-Do List
Instead of reading a report and trying to figure out what to do first, you get a ranked action plan:
| # | Task | Priority | Est Time |
|---|---|---|---|
| 1 | Address friction: "Premature Solutions Without Codebase Verification" | High | 5 min |
| 2 | Address friction: "Repeated Styling and Layout Failures" | High | 5 min |
| 3 | Address friction: "Debugging Wrong Root Causes" | High | 5 min |
| 4 | Add CLAUDE.md rule: "Before proposing a fix, always verify..." | High | 2 min |
| 5 | Set up Hooks | Medium | 10 min |
| 6 | Try workflow: High friction from premature solutions | Medium | 5 min |
Each task includes concrete steps: which file to copy, where to paste it, and how to test it.
Architecture
The tool is built with:
- TypeScript — strict types for every data structure (ReportData, FrictionCategory, SkillFile, AnalyzerOutput)
- cheerio — HTML parsing without a browser
- commander — CLI argument handling
- vitest — 83 tests covering parser, analyzer, generator, and full integration
- ESLint with typescript-eslint — zero violations
- GitHub Actions CI — automated build/test/lint on Node 18 and 20
The codebase is ~500 lines of source across 5 files. No frameworks, no runtime dependencies beyond cheerio and commander.
How It Compares to Existing Tools
There are several Claude Code usage tools in the ecosystem, but they solve different problems:
| Tool | Focus |
|---|---|
| ccusage | Token/cost analysis from JSONL session files |
| claude-code-usage-analyzer | Cost breakdown by model and token type |
| awesome-claude-skills | Curated collections of hand-written skills |
| claude-code-skill-factory | Toolkit for manually building skills |
| claude-insights | Automatically generates personalized skills, rules, and settings from your /insight report |
The distinction: existing tools either analyze costs or provide generic pre-built skills. claude-insights bridges the gap between Anthropic's insight analysis and your project configuration — automatically.
Getting Started
Install globally
npm install -g claude-insights
Or run directly with npx
npx claude-insights analyze ~/.claude/usage-data/report.html
With a specific output directory
npx claude-insights analyze ~/.claude/usage-data/report.html -o ./my-project
Then follow the generated to-do list
- Copy CLAUDE.md rules into your project's
CLAUDE.md - Merge settings into
.claude/settings.json - Copy skill files to
.claude/skills/ - Test with
/skill-nameon your next task
Links
- License: MIT
claude-insights is open source and MIT licensed. Contributions, issues, and feedback are welcome on GitHub.
Top comments (6)
how are you handling cases where the insights report flags something vague like "friction with testing patterns" and the tool has to generate a specific skill file from that? i built something similar for cursor rules recently (linting .mdc files for structural issues) and the hardest part was deciding what counts as actionable vs noise.
I think this is a good question, this was one of the trickiest design decisions in the tool.
The title is often vague, but each friction also carries a description and
examples[]with concrete scenarios.The skill generator derives specificity from those richer fields, the title is just an index key.
It cross-references each friction against the report's pattern cards and
CLAUDE.mdsuggestions via significant-word overlap, then builds each skill section from different sources: triggers are extracted from example text ("When X, Claude Y" patterns), rules come from the best-matchingCLAUDE.mditem (or domain-keyword fallback), and the examples go verbatim into a "What Goes Wrong" section, that it where most actionability lives.When both title and examples are vague, the output degrades to generic guardrails (narrow scope, verify regressions). It is not ideal, but harmless.
does the generic guardrail fallback ever produce something misleading? i'd worry about a placeholder that looks specific but is actually just "narrow scope, verify regressions" dressed up with the friction title. curious if you've considered letting users annotate frictions with their own examples after generation, so the next run has better input to work with
Fair point. The fallback does sneak the friction title into templates - so you'd get something like "Always inspect existing testing, patterns references before proposing a solution" which looks specific at first glance but is really just the title wearing a trench coat.
There's a "Why This Skill Exists" section at the bottom of every generated skill that shows the raw friction description, so you can judge for yourself how much substance is behind it.
On the annotation idea — I don't support that today, but the architecture could handle it. Each run is already cached as dated JSON in
~/.claude-insights/history/, and--applyis idempotent. A friction annotations file that feeds into the next run would slot in naturally alongside the existing--facetsenrichment - definitely something I want to explore.my worry was more about the vague friction titles becoming the "name" you'd grep for later. if the actionability lives in the "What Goes Wrong" section that's better than i expected. the annotation idea where you feed friction context back into the next run could get interesting, especially if you could mark which frictions were false positives vs actually useful catches
Good question — we actually built solutions for all three parts of this in our new version v1.3.
On the "vague titles" worry: The friction titles don't just become a label you grep for. They get transformed into clear kebab-case names like debugging-root-causes-directories, and inside each skill there are domain-specific steps, your real failure stories in a "What Goes Wrong" section, and a checklist that makes Claude verify it's not repeating past mistakes. The name is just the door, the value is what's behind it.
On "What Goes Wrong" being the key part: Agreed, and that's why each skill embeds your actual failure narratives — not generic advice.
Things like "Claude hypothesized the wrong root cause and added debug logs to the wrong project directory until you corrected it."
Claude reads these before acting and must self-check against each one before considering the task done.
On the false-positive/annotation idea: We built it. You can now mark any friction as useful or false-positive, either interactively or from the command line.
On the next run,
false-positivesget filtered out before any skills or rules are generated. So if a friction was a one-off incident and not a real pattern, just mark it and it won't pollute your output again.The feedback loop becomes: run, review, mark the noise, re-run, get cleaner results.