gh-robbyt-claude-skills-plugins-claude-md-reflect/skills/claude-md-reflect/SKILL.md

name, description

name	description
claude-md-reflect	Analyze chat history to identify areas for improving CLAUDE.md instruction files. Use when the user says "reflect on CLAUDE.md", "improve CLAUDE.md", or requests analysis of instruction files after a work session. Reviews recent conversation for misunderstandings, inconsistencies, or areas where instructions could be clearer.

CLAUDE.md Reflection and Improvement

Overview

This skill analyzes recent chat history and existing CLAUDE.md files to identify improvement opportunities. It follows a three-phase workflow: Analysis, Interaction, and Implementation.

When to Use

Trigger this skill when the user requests:

• "reflect on CLAUDE.md"
• "improve CLAUDE.md"
• Analysis of instruction files after encountering issues

Workflow

Phase 1: Analysis

Use the Task tool with subagent_type='general-purpose' to analyze the entire session history.

Find all CLAUDE.md files:

python scripts/find_claude_md.py

The script returns paths to all CLAUDE.md files in the repository, sorted by depth (root first).

Analyze for:

• Inconsistencies in Claude's responses vs user expectations
• Misunderstandings of user requests
• Areas where Claude lacked necessary context
• Repetitive corrections from the user
• Common mistakes or confusion patterns
• Instructions that belong in a different CLAUDE.md file

Read reference materials:

• Read references/anthropic-best-practices.md for official CLAUDE.md guidelines
• Read references/anti-patterns.md for common mistakes to avoid

Phase 2: Interaction

Present findings to the user using the AskUserQuestion tool with checkboxes.

For each suggested improvement:

1. Explain the issue identified in chat history
2. Propose a specific change (add, update, or delete content)
3. Show which CLAUDE.md file to update
4. Explain the rationale and expected impact

Format suggestions as:

• Clear, actionable changes
• Specific text additions or modifications
• NOT vague improvements

Example:

Issue: Claude repeatedly used 'var' instead of 'const' in JavaScript code
Proposal: Add to CLAUDE.md: "NEVER use var in JavaScript, use const or let"
File: ./frontend/CLAUDE.md
Rationale: Prevents repeated corrections for JavaScript variable declarations

Wait for user approval on each suggestion before proceeding to implementation.

Phase 3: Implementation

For each approved change:

1. Identify correct file and section:

   • Root CLAUDE.md: Project-wide guidance
   • Subdirectory CLAUDE.md: Component-specific guidance
   • User CLAUDE.md (~/.claude/CLAUDE.md): Personal preferences

2. Update the file:

   • Add, update, or delete content as approved
   • Keep changes minimal and targeted
   • Maintain existing structure and formatting
   • Use bullet points, not paragraphs
   • Add emphasis (NEVER, ALWAYS, IMPORTANT) where critical

3. Follow anti-patterns guidance:

   • NO hyperbolic language (crucial, proper, robust, excellent)
   • NO vague instructions (write good code, use best practices)
   • NO historical comments (we used to do X, now we do Y)
   • NO redundant information
   • KEEP it concise and actionable

4. Verify hierarchy:

   • Root CLAUDE.md should link to subdirectory CLAUDE.md files
   • Instructions should be in the most appropriate file for their scope

File Organization

Root CLAUDE.md:

• Project-wide guidelines
• Links to subdirectory CLAUDE.md files
• Common commands and workflows

Subdirectory CLAUDE.md:

• Component-specific guidance
• Should be referenced from root CLAUDE.md

Example root CLAUDE.md structure:

# Project Instructions

## Subdirectories
- Frontend: @frontend/CLAUDE.md
- Backend: @backend/CLAUDE.md

## Commands
- npm run build: Build all components
- npm test: Run all tests

## Code Style
- Use 2-space indentation
- NEVER commit directly to main branch

Resources

• scripts/find_claude_md.py - Locate all CLAUDE.md files in repository
• references/anthropic-best-practices.md - Official Anthropic CLAUDE.md guidelines
• references/anti-patterns.md - Common mistakes to avoid