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
- Signal Detection - Scan transcript for corrections/patterns
- Context Analysis - Extract 5-message context around signals
- Skill Mapping - Match signals to relevant skills
- Change Proposal - Generate diff of proposed updates
- User Review - Interactive approval with natural language editing
- Application - Safe YAML/markdown updates with backups
- 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.