I Built a CLI That Turns Claude Code's /insights Report Into Actionable Skills, Rules, and Workflows

claude-insights parses your Claude Code /insight HTML report and generates personalized CLAUDE.md rules, custom skills, hook configs, and a prioritized to-do list — all derived from your actual friction patterns.

title: "I Built a CLI That Turns Claude Code's /insights Report Into Actionable Skills, Rules, and Workflows" published: true description: "claude-insights parses your Claude Code /insight HTML report and generates personalized CLAUDE.md rules, custom skills, hook configs, and a prioritized to-do list — all derived from your actual friction patterns." tags: claude, ai, cli, productivity cover_image:

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:

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:

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:

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

1. Copy CLAUDE.md rules into your project's CLAUDE.md
2. Merge settings into .claude/settings.json
3. Copy skill files to .claude/skills/
4. Test with /skill-name on your next task

Links

• npm: npmjs.com/package/claude-insights
• GitHub: github.com/yahav10/claude-insights
• License: MIT

claude-insights is open source and MIT licensed. Contributions, issues, and feedback are welcome on GitHub.