improve-system

name	improve-system
description	Keep your system sharp. Reviews your setup, captures learnings, audits for rot, recaps your sessions. Run it regularly to keep improving.

/improve-system

Keep your system sharp. One skill, four modes. Detect the right mode from conversation context, or ask.

Modes

Mode	Trigger	What it does
Setup Review	Default for new users, "review my setup", "how's my setup".	Full audit of your Claude Code environment with prioritized action items.
Experience Capture	"capture this", "log this", user describes a win/lesson.	Quick structured entry written to knowledge folder.
Session Review	"recap my week", "what did I do", bare invocation for returning users.	Weekly recap from session history and git log.
Audit	"audit", "health check", "what's stale".	Check for stale rules, unused servers, dead skills, contradictions.

If unclear, ask:

"What are we working on? I can:

1. Review your setup (CLAUDE.md, MCP servers, skills, hooks, project structure)
2. Capture an experience (a win, lesson, or story)
3. Recap your sessions (weekly review from session history)
4. Audit your system (find stale or conflicting content)

Or describe what you're thinking and I'll figure it out."

Data Sources

Everything comes from local files. No MCP read calls.

• Session history: Read JSONL session files from ~/.claude/projects/*/. Extract: projects worked on, tools used, skills invoked, timestamps, summaries, duration.
• Setup files: ~/.claude/CLAUDE.md, project-level CLAUDE.md, ~/.claude/settings.json, MCP server configs (~/.claude/mcp_servers.json).
• Git history: git log --oneline --since="2 weeks ago" for what was actually committed.
• Knowledge folder: ./knowledge/ (if exists).

Rules

• Every finding must be backed by data from their sessions or files. Don't suggest generic improvements.
• "Fix" actions should be specific enough to copy-paste or act on immediately.
• If a fix is something you can do right now (edit CLAUDE.md, create a skill), offer to do it.
• Always include "What's Working Well" so it doesn't feel like a list of failures.
• Don't force learnings from single instances. Only flag a pattern if it recurs.
• Don't auto-run changes without approval. Show what you'll change and ask first.
• Never mention raw session counts or token totals. Use streak, relative terms ("your recent sessions"), or project names instead.
• Contradictions aren't always bad. Document when each approach applies rather than picking a winner.

Instructions

Step 0: Determine Mode

Read local session files from ~/.claude/projects/*/ to understand usage level.

• < 5 local sessions (or no session data): Run Onboarding (within Setup Review).
• 5+ sessions, bare invocation: Run Session Review.
• Explicit trigger: Run the matching mode from the table above.

---

Mode 1: Setup Review

The core coaching mode. Full audit of their Claude Code environment.

Onboarding (< 5 sessions or no data)

When someone is new, don't punt them. Teach them what Claude Code can do, understand their goals, and set them up right.

Step 1: Welcome

"Welcome! Looks like you're just getting started. Let me walk you through what's possible and help you set things up right from the start."

Step 2: Understand their goal

Ask ONE question:

"What are you mainly using Claude Code for? Building an app, automating workflows, writing content, learning to code, something else?"

Wait for their answer. This shapes everything that follows.

Step 3: Project structure check

Read the folder structure, CLAUDE.md, README, and key files. Based on their stated goal + what the project contains:

If the project is new or minimal, suggest structure based on project type:

• knowledge/ folder with relevant subfolders
• .claude/skills/ with 1-2 starter skills matching their goal
• projects/ folder if they'll manage multiple workstreams

If the project already has structure, acknowledge what's there and suggest gaps.

Offer to set up whatever they want right now.

Step 4: Claude Code walkthrough

Based on their goal, walk them through the capabilities that matter most. Keep it practical, not a feature dump.

For everyone:

• CLAUDE.md - The most important file. Tells Claude your preferences, tech stack, rules. Without it, Claude starts from zero every session. Check if they have one, offer to create it.
• Plan mode - Before big tasks, ask Claude to plan first. Catches mistakes before they happen.
• Tools - Briefly explain Read, Edit, Grep, Bash and when to use each.

Based on their goal:

• Building apps: Mention parallel sessions, agents/subagents, structuring complex tasks.
• Automating workflows: Mention hooks, custom skills, MCP servers.
• Content creation: Mention research, drafting, iteration workflows.
• Learning: Mention asking Claude to explain as it goes, using Plan mode for understanding.

Keep each section to 2-3 sentences max.

Step 5: Quick config check

Even without session data, check their config files:

• Do they have a CLAUDE.md? If not, offer to create one based on their stated goal.
• What MCP servers are configured?
• Any hooks set up?

If you can fix something right now, offer to do it. End with a clear next action, not a menu.

Skip to End of Skill after onboarding.

---

Standard Setup Review (5+ sessions)

Step 1: Check for previous reviews

If this is a return visit, mention:

"Last time I suggested: {previous recommendations}. Want me to check how you're doing on those, or start fresh?"

For first review, ask:

"Want a quick review or a deep dive?"

• Quick: I'll check your setup, recent sessions, and give you 3 things to fix this week.
• Deep: I'll read every config file, audit your full environment, and give you a prioritized action plan.

Step 2: Quick Review

Analyze from local session files:

• Usage patterns: What tools do they lean on vs. underuse? Are sessions getting shorter or longer?
• Skill usage: Which skills have they tried? What haven't they touched?
• Workflow signals: Do they use Plan mode? Agents? Hooks? Parallel sessions?
• Recent prompts: What are they asking Claude to do? Any repeated patterns that could be automated?
• Project fit: Does the project have structure that helps Claude understand context?

Output exactly 3 action items, ranked by impact:

## Setup Review

**Activity**: {current streak, main focus}

### What's Working Well
- {1-2 things they're doing well}

### What to Improve
1. {Most impactful action item with specific steps}
2. {Second action item}
3. {Third action item}

### Quick Win
{One thing they can do in the next 5 minutes}

Step 3: Deep Dive

Read and audit every layer. For each layer, read the relevant files and cross-reference with session history.

Layer 1: CLAUDE.md

Read ~/.claude/CLAUDE.md (global) and any project-level CLAUDE.md.

Check:

• Are there rules? If empty or missing, that's a high-priority finding.
• Do the rules match what they actually do? (Compare rules to session patterns)
• Are rules too generic? ("Write clean code" is useless)
• Are rules too long? (Best CLAUDE.md files are under 30 lines)
• Missing rules they need based on their tech stack and patterns

Analyze the gap between what they do and what their CLAUDE.md says:

• Missing rules from session patterns (e.g., writes TypeScript but no TS conventions)
• Rules to remove (generic advice, tools they don't use, duplicates)
• Rules to sharpen (vague rules that should be specific)

Layer 2: MCP Servers

Read ~/.claude/mcp_servers.json (or equivalent config).

Check:

• What MCP servers are configured?
• Are they using database tools manually when an MCP server could handle it?
• MCP servers configured but never used?
• Missing MCP servers based on their workflow

Layer 3: Skills

Read all skills in ~/.claude/skills/.

Check:

• How many custom skills do they have?
• Which skills have they used vs not used?
• Are there custom skills that are stale or broken?
• Could they benefit from creating skills for repeated workflows?

Layer 4: Hooks

Check ~/.claude/settings.json and project-level settings for hooks.

Check:

• Are any hooks configured?
• Could they benefit from pre/post hooks?

Layer 5: Project Structure and Knowledge

Classify the project type:

• Code/app (package.json, src/, build configs)
• Content/creative (drafts, scripts, assets, writing)
• Knowledge/operations (docs, processes, playbooks, reports)

Based on project type, check for:

• .claude/skills/ folder (repeated workflows should become skills)
• knowledge/ or equivalent context folder
• Project-specific skills vs. generic skills
• Finished work organization (archive/done patterns)

Layer 6: Workflow Patterns

From session history, identify:

• Plan mode usage
• Parallel sessions
• Agents/subagents
• Session length patterns (short = tactical, long = could benefit from planning)
• Commit frequency
• Repeated prompts that could become a skill or hook

Deep Dive Output Format:

## Deep Dive Results

**Environment Score**: {X}/10
Based on recent sessions across {Y} projects.

### Critical (fix now)
1. {Finding}: {what's wrong and why it matters}
   Fix: {exact action to take}

### High Impact (do this week)
1. {Finding}: {what's wrong and why it matters}
   Fix: {exact action to take}

### Nice to Have (when you have time)
1. {Finding}
   Fix: {action}

### CLAUDE.md
**Current**: {line count} lines, {rule count} rules

Add:
1. `{exact rule text}` - You did {X} in {Y} of your recent sessions.

Remove:
1. `{quoted existing rule}` - {reason}

Sharpen:
1. Before: `{existing rule}` -> After: `{improved rule}`

### What's Working Well
- {Positive finding}
- {Positive finding}

Keep the total list to 10 items max. Prioritize ruthlessly. Keep CLAUDE.md under 30 lines if fixing.

Step 4: Follow-up on previous recommendations

If return visit and user wants to check progress:

• Compare current state against each previous recommendation
• Mark each as: done, partially done, or not started
• For items not started, re-evaluate: still relevant? Reprioritize if needed.
• Drop recommendations that no longer apply.

Step 5: Apply on approval

"Want me to fix any of these now? I can update your CLAUDE.md, create missing skills, or configure MCP servers."

Work through fixes one by one, confirming each before applying.

---

Mode 2: Experience Capture

Quick capture. No recap needed.

Step 1: Extract the experience

From what the user said, extract:

# {Date} - {Brief Title}

## What happened
{1-2 paragraphs based on what they described}

## Key learning
- {The transferable insight}

## Why it matters
{One sentence on why this is worth remembering}

## Tags
{topic1, topic2, topic3}

Step 2: Write

Write to ./knowledge/experiences/{YYYY-MM-DD}-{brief-slug}.md. Create directory if needed with mkdir -p.

Step 3: Confirm

## Captured

**{title}** saved to `{filename}`

---

Mode 3: Session Review

Weekly recap from session history and git log.

Step 1: Read local session history

Read JSONL session files from ~/.claude/projects/*/. Focus on the last 7 days. Also run git log --oneline --since="7 days ago" for commit context.

Extract:

• Projects worked on (group by project name)
• Activity types (coding, content, research, other)
• Tools and skills used
• Session durations and timestamps
• Summaries

Step 2: Weekly Recap

## This Week

**{streak} day streak | Focus: {main project/activity}**

### What you worked on
- {Project/activity 1}
- {Project/activity 2}

### Best session
{The most interesting or productive session this week. One sentence.}

### Add to your playbook
{1-2 specific things they should start doing based on this week's patterns.}

Keep the recap under 15 lines. If < 3 sessions this week: "Light week. Here's what I have:" and generate what you can.

Step 3: Capture additional experiences

After showing the recap, ask:

"Anything else from this week worth capturing? A win, a lesson, something you figured out. A sentence or two is plenty, or type 'skip'."

If they share something, capture it as an experience entry. If they skip, move on.

Step 4: Write recap

Write the weekly recap to ./knowledge/experiences/recaps/{YYYY-MM-DD}-weekly-recap.md. Create directories as needed with mkdir -p.

---

Mode 4: Audit

Quick health check for rot.

Step 1: Read setup files

Read all setup files from the Data Sources section above.

Step 2: Run checks

• Stale CLAUDE.md rules: Rules about tools/patterns not seen in recent sessions
• Unused MCP servers: Configured but never called in session history
• Dead custom skills: Skills in ~/.claude/skills/ that reference missing files or broken patterns
• Contradictions: Rules that conflict with each other or with actual behavior
• Orphaned knowledge: Files in knowledge directories that nothing references

Step 3: Report

## System Audit

**Health**: {Good / Needs attention / Needs cleanup}

### Issues Found
1. {Issue} - {what's wrong and what to do}
2. {Issue} - {what's wrong and what to do}

### Clean
- {Things that checked out fine}

Keep to 10 items max. If everything is clean, say so and suggest Setup Review mode instead.

Step 4: Fix on approval

"Want me to fix any of these?"

Apply only what they approve. Never auto-delete without explicit approval.

---