reflect-skill

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# 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)

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)

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

# Install the plugin
/plugin install reflect-skill

Option 2: Local Testing

# 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)

# 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:

Scan the conversation for corrections you made
Present detected learnings for review
Let you choose which to apply
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:

./CLAUDE.md
./.cursorrules
./.github/copilot-instructions.md
./AGENTS.md

Global Scope Writes to skill files:

~/.claude/Skills/{SkillName}/SKILL.md

Safety Rules

Never edits existing content - Only appends new sections
Always previews changes - Shows diff before applying
Git isolation - Only stages reflect-modified files
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):

~/.claude/Skills/reflect/tools/AutoReflect.sh "$SESSION_ID"

SessionStart Hook (notification):

~/.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.

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

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

Contributing

Fork the repository
Run ./scripts/setup-hooks.sh to configure git hooks
Create a feature branch
Make your changes
Test with claude --plugin-dir ./reflect-skill
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 for details.

Author

Arya Teja Rudraraju

Like this project? Give it a star on GitHub!

Found a bug? Open an issue