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 logicscripts/extract_signals.py- Pattern detection enginescripts/update_skill.py- Safe skill file updatesscripts/present_review.py- Interactive review interface
Automation
scripts/hook-stop.sh- Stop hook integrationscripts/toggle-on.sh- Enable auto-reflectionscripts/toggle-off.sh- Disable auto-reflectionscripts/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.