---
slug: "reflect-skill"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/aryateja2106/reflect-skill@main/README.md"
repo: "https://github.com/aryateja2106/reflect-skill"
source_file: "README.md"
branch: "main"
---
# Reflect Skill

**Teach your AI coding agent to learn from mistakes.**

A Claude Code plugin that analyzes conversations for user corrections and updates configuration files to prevent repeated mistakes. Works with Claude Code, Cursor, and other AI coding assistants.

## The Problem

AI coding agents make the same mistakes repeatedly because they don't remember corrections from previous sessions. You find yourself saying "Don't use npm, use bun" or "Never use inline CSS" over and over.

## The Solution

Reflect detects when you correct your AI agent and offers to persist those learnings to configuration files (`CLAUDE.md`, `.cursorrules`, etc.) so the agent remembers next time.

## Features

- **Automatic Detection** - Recognizes correction patterns like "don't", "never", "use X instead"
- **Safe Append Only** - Never edits existing content, only adds new rules
- **Multiple Scopes** - Apply learnings to current project or globally
- **Git Integration** - Isolated commits for tracked changes
- **Queue System** - Auto-captures corrections at session end for later review
- **Backup Protection** - Creates timestamped backups before any changes

## Installation

### Option 1: Claude Code Plugin (Recommended)

```bash
# Add the plugin marketplace
/plugin marketplace add aryateja2106/reflect-skill

# Install the plugin
/plugin install reflect-skill
```

### Option 2: Local Testing

```bash
# Clone the repository
git clone https://github.com/aryateja2106/reflect-skill.git

# Run Claude Code with the plugin
claude --plugin-dir ./reflect-skill
```

### Option 3: Manual Installation (Skills Folder)

```bash
# Copy to your Claude Code skills directory
cp -r reflect-skill/skills/reflect ~/.claude/Skills/
chmod +x ~/.claude/Skills/reflect/tools/*.sh

# Copy the command (optional - for /reflect slash command)
cp reflect-skill/commands/reflect.md ~/.claude/commands/
```

## Usage

### Manual Reflection

After a session where you've made corrections:

```
/reflect
```

This will:
1. Scan the conversation for corrections you made
2. Present detected learnings for review
3. Let you choose which to apply
4. Safely append to your configuration files

### Process Queued Corrections

If you have auto-queued corrections from previous sessions:

```
/reflect process
```

### Natural Language Triggers

The skill also activates when you say things like:
- "Remember this for next time"
- "Learn from this mistake"
- "Don't do that again"
- "Update my preferences"

## How It Works

### Detection Patterns

**HIGH Priority (Explicit Corrections)**
- "don't" / "do not" / "never"
- "wrong" / "incorrect"
- "stop doing" / "stop using"
- "use X instead"

**MEDIUM Priority (Implicit Corrections)**
- "actually..." followed by alternative
- User rewrites code immediately after AI attempt
- Same issue clarified 3+ times

**LOW Priority (Preferences)**
- "I prefer"
- "let's use" / "we use"
- "in this project"

### Target Files

**Project Scope (Default)**
Writes to the first file found:
1. `./CLAUDE.md`
2. `./.cursorrules`
3. `./.github/copilot-instructions.md`
4. `./AGENTS.md`

**Global Scope**
Writes to skill files:
- `~/.claude/Skills/{SkillName}/SKILL.md`

### Safety Rules

1. **Never edits existing content** - Only appends new sections
2. **Always previews changes** - Shows diff before applying
3. **Git isolation** - Only stages reflect-modified files
4. **Automatic backups** - Creates `.bak.{timestamp}` files

## Example Session

```
You: Create a React component for user login

AI: [Creates component with npm install]

You: Don't use npm, always use bun in this project

AI: [Fixes to use bun]

You: /reflect

AI: Running the Analyze workflow from the Reflect skill...

Found 1 correction in this session:

### HIGH Priority
1. **"Don't use npm, always use bun in this project"**
   - Category: CONSTRAINT
   - Suggested: Use bun instead of npm for package management

Select learnings to apply: [1]
Scope: Project (./CLAUDE.md)

Preview:
+ ## Learnings
+ <!-- Generated by /reflect | 2026-01-06 -->
+ ### Constraints
+ - Use bun instead of npm for package management

[Apply] [Cancel]
```

## Configuration

### Hook Integration (Optional)

For automatic correction capture at session end, add to your hooks:

**Stop Hook** (session end):
```bash
~/.claude/Skills/reflect/tools/AutoReflect.sh "$SESSION_ID"
```

**SessionStart Hook** (notification):
```bash
~/.claude/Skills/reflect/tools/CheckQueue.sh
```

## Directory Structure

```
reflect-skill/
├── .claude-plugin/
│   └── plugin.json           # Plugin manifest
├── skills/
│   └── reflect/
│       ├── SKILL.md          # Main skill definition
│       ├── workflows/        # 5 workflow files
│       │   ├── Analyze.md    # Detect corrections
│       │   ├── Review.md     # Selection UI
│       │   ├── Apply.md      # Safe file updates
│       │   ├── Auto.md       # Session-end queue
│       │   └── Process.md    # Queue processing
│       ├── tools/            # 5 shell scripts
│       │   ├── DetectTarget.sh
│       │   ├── SafeAppend.sh
│       │   ├── GitSafeCommit.sh
│       │   ├── AutoReflect.sh
│       │   └── CheckQueue.sh
│       └── templates/
│           └── LearningsSection.txt
├── commands/
│   └── reflect.md            # Slash command definition
├── docs/
│   ├── IMPLEMENTATION_SPEC.md  # Technical specification
│   └── RALPH_PROMPT.md         # Development guide
├── README.md
└── LICENSE
```

## Development

### Building from Source

The skill uses pure bash scripts with no external dependencies.

```bash
# Test tools individually
./skills/reflect/tools/DetectTarget.sh list
./skills/reflect/tools/SafeAppend.sh --help

# Validate the plugin
/plugin validate ./reflect-skill
```

### Contributing

1. Fork the repository
2. Run `./scripts/setup-hooks.sh` to configure git hooks
3. Create a feature branch
4. Make your changes
5. Test with `claude --plugin-dir ./reflect-skill`
6. Submit a pull request

> **Note**: This repository includes git hooks that strip AI co-author attribution from commits. Run `./scripts/setup-hooks.sh` after cloning to enable them.

See `docs/IMPLEMENTATION_SPEC.md` for detailed technical documentation.

## Compatibility

- **Claude Code** v2.0+
- **macOS**, **Linux**, **Windows** (WSL)
- Works alongside other AI coding tools (Cursor, GitHub Copilot, etc.)

## Roadmap

- [ ] Support for more configuration file formats
- [ ] Deduplication of similar corrections
- [ ] Export/import learnings between projects
- [ ] Integration with team shared configurations
- [ ] VS Code extension

## License

MIT License - see [LICENSE](https://github.com/aryateja2106/reflect-skill/tree/HEAD/LICENSE) for details.

## Author

**Arya Teja Rudraraju**

---

**Like this project?** Give it a star on GitHub!

**Found a bug?** [Open an issue](https://github.com/aryateja2106/reflect-skill/issues)