Reflect Skill

Analyze conversations to extract corrections, preferences, and best practices, then persist them to skill files. Supports manual triggering, automatic hooks, and Git versioning.

Commands

Command Description

/reflect

Analyze current session and propose skill updates

/reflect [skill-name]

Reflect and update a specific skill

reflect on

Enable automatic reflection via stop hook

reflect off

Disable automatic reflection

reflect status

Show current reflection mode

Manual Reflection Flow

1. Analyze Session for Signals

Scan the conversation and categorize by confidence:

HIGH Confidence - Explicit corrections

• "No, use X instead of Y"

• "Never [action] in this project"

• "Always check for [condition]"

MEDIUM Confidence - Success patterns

• Approaches that worked after iteration

• Patterns user approved or praised

LOW Confidence - Observations

• Implied preferences

• Patterns to review later

2. Present Review & Approval

📊 Signals Detected:

HIGH CONFIDENCE:

• "Never generate button styles - reference existing components"
• "Always check for SQL injections"

MEDIUM CONFIDENCE:

• Arrow functions preferred for callbacks

LOW CONFIDENCE:

• Prefers concise explanations

📝 Proposed Changes to [skill-name].md:

• Security

• • Always validate database queries for SQL injection

• Code Style

• • Never generate UI components; reference existing library

💬 Commit message: "Add SQL injection and UI component rules"

Accept changes? [Y/n/edit with natural language]

User options:

• Y

• Accept all changes

• n

• Reject

• Natural language: "Remove the arrow function one" or "Change the wording to..."

3. Update Skill & Commit

• Locate target skill file (project or ~/.claude/skills/ )

• Merge new learnings (newer rules override conflicts)

• If Git repo: stage, commit with message, push

Automatic Reflection

Toggle Commands

reflect on # Enable auto-reflection on session end reflect off # Disable auto-reflection reflect status # Check current mode

How It Works

When enabled, the stop hook triggers automatic learning:

• Session ends → stop hook fires

• Analyzes conversation for learnings

• Updates skill file (shows notification: "Learned from session: [skill-name]")

• Commits to Git if configured

Hook Configuration

The session-end hook is auto-registered when you install this plugin. No manual configuration needed.

State stored in ~/.claude/.reflect-state (enabled/disabled).

Git Integration

Version your skills to track evolution over time:

cd ~/.claude/skills git init git remote add origin <your-repo>

Benefits:

• See how skills evolve with each learning

• Rollback if a learning causes regressions

• Track system improvement over time

Learning Categories

Category Examples

Code Style Naming conventions, formatting

Security Input validation, SQL injection

Testing Coverage requirements, edge cases

API Design Endpoint conventions, responses

UI/UX Component usage, accessibility

Workflow PR process, commit format

Example

You: Review the auth module Claude: [Reviews, misses SQL injection] You: You missed SQL injection - always check for that

You: /reflect

Claude: 📊 HIGH: "Always check for SQL injections"

    📝 Proposed for security-review.md:
    + - Validate all database queries for SQL injection
    
    Accept? [Y/n]

You: Y

Claude: ✅ Updated security-review.md 📤 Committed: "Add SQL injection validation rule"

Next session: Claude automatically checks for SQL injection.

Goal

Correct once, never again. Build a self-improving system where learnings persist and compound over time.