Reflect Skill for Claude Code - Review sessions and capture insights to REFLECTIONS.local.md

README.md

Reflect Skill for Claude Code

A Claude Code skill that reviews completed sessions to identify learnings and capture insights for future interactions.

What It Does

After you complete a task, this skill:

1. Analyzes the conversation - identifies what worked, where you got stuck, and any misunderstandings
2. Evaluates if recording is warranted - not every session has insights worth capturing
3. Saves to REFLECTIONS.local.md - captures insights in a structured, append-only file
4. Adds CLAUDE.md reference - one-time reference so future sessions know to check reflections
5. Lets you review and approve - you're always in control of what gets saved

Auto-Invocation

This skill is designed to be auto-invoked by Claude when:

• You confirm a task is complete ("thanks", "that works", "done")
• A significant piece of work has been finished
• The conversation reaches a natural conclusion

Claude will ask if you'd like to reflect before proceeding.

Installation

Using the Claude Skills Installer:

curl -fsSL https://gist.githubusercontent.com/rvanbaalen/2e4c2840d06de810f771a4514f97c6da/raw/claude-skills.mjs -o /tmp/claude-skills.mjs && node /tmp/claude-skills.mjs

Or manually:

mkdir -p ~/.claude/skills/reflect
curl -fsSL https://gist.githubusercontent.com/rvanbaalen/b482577d1eaca2c7b83c2e5ff7f2cbc3/raw/SKILL.md -o ~/.claude/skills/reflect/SKILL.md

Key Features

• Smart evaluation - only records when genuinely useful insights exist
• Structured reflections - dated entries with context, insights, and challenges
• Project or user level - saves to .claude/REFLECTIONS.local.md at appropriate scope
• Git-friendly - .local.md suffix indicates file should not be committed
• Non-invasive - always asks before making changes
• "No insights needed" is valid - won't force unnecessary entries

File Structure

Reflections are saved to .claude/REFLECTIONS.local.md with this format:

## 2024-01-28 - Task Summary

**Context:** Brief description of what was being worked on

**Key Insights:**
- Specific, actionable insight

**What Worked:**
- Effective approach or pattern

**Challenges Encountered:**
- Challenge and how it was resolved

License

MIT

---

_{Created by Robin van Baalen}

SKILL.md

name

description

reflect

This skill should be used when the user confirms a task is complete (e.g., "thanks", "that works", "done", "perfect"), when a significant piece of work has been finished, or when the conversation has reached a natural conclusion point. Critically reviews the conversation to identify what worked, where challenges occurred, and any misunderstandings. Captures key insights in a structured REFLECTIONS.local.md file.

Session Reflection

This skill reviews completed tasks to improve future interactions by capturing insights in .claude/REFLECTIONS.local.md.

Trigger Confirmation

Before reflecting, confirm with the user via AskUserQuestion:

question: "Task complete! Would you like me to reflect on our session?"
header: "Reflect"
options:
  - label: "Yes, reflect"
    description: "Review what worked and what could be improved"
  - label: "Skip"
    description: "End without reflection"

If the user chooses "Skip", thank them and end. Otherwise, proceed with the reflection process.

Reflection Process

1. Analyze the Conversation

Review the entire conversation to identify:

What worked well:

• Approaches that led to quick solutions
• Clear communication patterns
• Effective tool usage
• Good assumptions made

Where we got stuck:

• Points where multiple attempts were needed
• Misinterpretations of requirements
• Technical blockers encountered
• Inefficient approaches taken before finding the right one

Key learnings:

• Requirements that needed clarification
• Assumptions that turned out to be wrong
• Context that was missing initially
• Patterns or conventions discovered
• Workflow preferences established

2. Evaluate if Reflection is Warranted

Critically assess whether the session produced insights worth recording:

Recording IS warranted when:

• A recurring pattern was identified that would help in future sessions
• Project-specific conventions were discovered that aren't documented
• A significant misunderstanding occurred that clear context could prevent
• Workflow preferences were established that should persist
• Useful approaches or solutions were found after initial struggles

Recording is NOT warranted when:

• The issue was a one-off situation unlikely to recur
• The learning is too generic or obvious
• No significant challenges occurred - the session went smoothly
• Nothing new was learned that would help future sessions

If no reflection is needed, summarize briefly and end:

"Reflection complete. The session went smoothly and no insights need to be recorded."

3. If Recording Is Warranted

Confirm where to save the reflection via AskUserQuestion:

question: "I have insights worth recording. Where should I save them?"
header: "Save to"
options:
  - label: "Project reflections (Recommended)"
    description: "Save to ./.claude/REFLECTIONS.local.md for this project"
  - label: "User reflections"
    description: "Save to ~/.claude/REFLECTIONS.local.md for all projects"
  - label: "Just show me"
    description: "Show reflection without saving"

4. Check for REFLECTIONS.local.md Reference in CLAUDE.md

Before writing to REFLECTIONS.local.md, check if the appropriate CLAUDE.md file already references it:

For project-level reflections:

1. Check if ./CLAUDE.md exists
2. If it exists, check if it contains a reference to .claude/REFLECTIONS.local.md
3. If no reference exists, add one

For user-level reflections:

1. Check if ~/.claude/CLAUDE.md exists
2. If it exists, check if it contains a reference to REFLECTIONS.local.md
3. If no reference exists, add one

Reference to add (if missing):

- See `.claude/REFLECTIONS.local.md` for accumulated insights and learnings from past sessions.

This reference should be added once at the end of the CLAUDE.md file, or under a relevant existing section if one fits naturally.

5. Structure the Reflection Entry

Each reflection entry in REFLECTIONS.local.md should follow this format:

## [DATE] - [Brief Topic/Task Summary]

**Context:** [1-2 sentences about what was being worked on]

**Key Insights:**
- [Specific, actionable insight 1]
- [Specific, actionable insight 2]

**What Worked:**
- [Effective approach or pattern]

**Challenges Encountered:**
- [Challenge and how it was resolved]

---

6. Write to REFLECTIONS.local.md

If the file doesn't exist: Create it with a header and the first entry:

# Reflections

> This file is excluded from version control (*.local.md) and contains personal insights from Claude Code sessions.

This file contains accumulated insights and learnings from Claude Code sessions. These reflections help improve future interactions by documenting patterns, conventions, and lessons learned.

---

## [DATE] - [Topic]
...

If the file exists: Append the new entry at the end of the file, maintaining the existing structure.

7. Present Changes

Show the user what will be added:

## Reflection Entry

**File:** ./.claude/REFLECTIONS.local.md

**New entry:**
## 2024-01-28 - [Task Summary]

**Context:** ...

**Key Insights:**
- ...

If a CLAUDE.md reference needs to be added, show that too:

**Also adding reference to:** ./CLAUDE.md
+ See `.claude/REFLECTIONS.local.md` for accumulated insights and learnings from past sessions.

8. Confirm

question: "Save this reflection?"
header: "Confirm"
options:
  - label: "Save"
    description: "Add reflection entry to REFLECTIONS.local.md"
  - label: "Edit"
    description: "Let me modify before saving"
  - label: "Skip"
    description: "Don't save"

If "Edit" is selected, ask what changes are needed and revise accordingly.

If confirmed:

1. Create or append to REFLECTIONS.local.md
2. Add CLAUDE.md reference if needed (first time only)

Important Guidelines

• Be honest when no reflection is needed - don't force entries
• Quality over quantity - one meaningful insight beats several generic ones
• Be specific to the project/context, not generic
• Date every entry for historical context
• Preserve history - never delete or modify existing reflections, only append
• Add the CLAUDE.md reference only once (check if it already exists)
• The .local.md suffix indicates this file should not be committed to version control
• Ask before making any changes