Reflect – Self-Improving Skills

Overview

This skill enables Claude Code to learn from conversations by analyzing corrections, approvals, and patterns, then proposing updates to relevant skills. It implements a “correct once, never again” learning system.

Usage Modes

1. Manual Reflection (/reflect)

Trigger analysis of the current conversation:

/reflect [skill-name]

• Without skill-name: Analyzes all skills used in conversation
• With skill-name: Focuses on specific skill

2. Automatic Reflection

When enabled via /reflect-on, runs automatically at session end via Stop hook.

3. Toggle Commands

• /reflect-on – Enable automatic reflection
• /reflect-off – Disable automatic reflection
• /reflect-status – Show current configuration

Confidence Levels

HIGH – Explicit corrections:

• User contradicts Claude’s approach with specific alternative
• Pattern: “Don’t do X, do Y instead”
• Action: Direct updates with deprecation warnings

MEDIUM – Approvals and patterns:

• User approves specific approach
• Pattern succeeds multiple times
• Action: Add to “Best Practices” section

LOW – Observations:

• User questions or suggests alternatives
• Pattern: “Have you considered…” or “Why not try…”
• Action: Add to “Considerations” section

Workflow

1. Signal Detection – Scan transcript for corrections/patterns
2. Context Analysis – Extract 5-message context around signals
3. Skill Mapping – Match signals to relevant skills
4. Change Proposal – Generate diff of proposed updates
5. User Review – Interactive approval with natural language editing
6. Application – Safe YAML/markdown updates with backups
7. Git Commit – Automatic commit with descriptive message

Scripts

Core Engine

• scripts/reflect.py – Main orchestration logic
• scripts/extract_signals.py – Pattern detection engine
• scripts/update_skill.py – Safe skill file updates
• scripts/present_review.py – Interactive review interface

Automation

• scripts/hook-stop.sh – Stop hook integration
• scripts/toggle-on.sh – Enable auto-reflection
• scripts/toggle-off.sh – Disable auto-reflection
• scripts/toggle-status.sh – Show status

Safety Features

• Timestamped backups before all edits
• YAML validation before writing
• Lock files prevent concurrent runs
• Graceful error handling with rollback
• Git status checks before commits

References

See references/signal-patterns.md for detailed pattern library.