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

--- 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: ```bash 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](https://github.com/cheeriojs/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: ```markdown --- 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: ```markdown ## 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](https://github.com/ryoppippi/ccusage) | Token/cost analysis from JSONL session files | | [claude-code-usage-analyzer](https://github.com/aarora79/claude-code-usage-analyzer) | Cost breakdown by model and token type | | [awesome-claude-skills](https://github.com/ComposioHQ/awesome-claude-skills) | Curated collections of hand-written skills | | [claude-code-skill-factory](https://github.com/alirezarezvani/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 ```bash npm install -g claude-insights ``` ### Or run directly with npx ```bash npx claude-insights analyze ~/.claude/usage-data/report.html ``` ### With a specific output directory ```bash 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](https://www.npmjs.com/package/claude-insights) - **GitHub**: [github.com/yahav10/claude-insights](https://github.com/yahav10/claude-insights) - **License**: MIT --- *claude-insights is open source and MIT licensed. Contributions, issues, and feedback are welcome on GitHub.*