Reflect Skill

Analyze the current session and propose improvements to skills based on what worked, what didn't, and edge cases discovered.

Trigger

Run /reflect or /reflect [skill-name] after a session where you used a skill.

Additional commands:

/reflect on - Enable automatic end-of-session reflection
/reflect off - Disable automatic reflection
/reflect status - Check if auto-reflect is enabled

Workflow

Step 1: Identify the Skill

If skill name not provided, ask:

Which skill should I analyze this session for?
- frontend-design
- code-reviewer
- [other]

Step 2: Analyze the Conversation

Look for these signals in the current conversation:

Corrections (HIGH confidence):

User said "no", "not like that", "I meant..."
User explicitly corrected output
User asked for changes immediately after generation

Successes (MEDIUM confidence):

User said "perfect", "great", "yes", "exactly"
User accepted output without modification
User built on top of the output

Edge Cases (MEDIUM confidence):

Questions the skill didn't anticipate
Scenarios requiring workarounds
Features user asked for that weren't covered

Preferences (accumulate over sessions):

Repeated patterns in user choices
Style preferences shown implicitly
Tool/framework preferences

Step 3: Propose Changes

Present findings using accessible colors (WCAG AA 4.5:1 contrast ratio):

┌─ Skill Reflection: [skill-name] ───────────────────┐
│                                                    │
│ Signals: X corrections, Y successes                │
│                                                    │
│ Proposed changes:                                  │
│                                                    │
│ 🔴 [HIGH] + Add constraint: "[specific constraint]"│
│ 🟡 [MED]  + Add preference: "[specific preference]"│
│ 🔵 [LOW]  ~ Note for review: "[observation]"       │
│                                                    │
│ Commit: "[skill]: [summary of changes]"            │
│                                                    │
└────────────────────────────────────────────────────┘

Apply these changes? [Y/n] or describe tweaks

Accessible Color Palette (use ANSI codes in terminal output):

HIGH: \033[1;31m (bold red #FF6B6B - 4.5:1 on dark)
MED: \033[1;33m (bold yellow #FFE066 - 4.8:1 on dark)
LOW: \033[1;36m (bold cyan #6BC5FF - 4.6:1 on dark)
Reset: \033[0m

Avoid: pure red (#FF0000) on black, green on red (colorblind users)

User Response Options:

Y – Apply changes, commit, and push
n – Skip this update
Or describe any tweaks to the proposed changes

Step 4: If Approved

Read the current skill file from .claude/skills/[skill-name]/SKILL.md
Apply the changes using the Edit tool

Run git commands:

cd .claude/skills
git add [skill-name]/SKILL.md
git commit -m "[skill]: [change summary]"
git push origin main

Confirm: "Skill updated and pushed to GitHub"

Step 5: If Declined

Ask: "Would you like to save these observations for later review?"

If yes, append to .claude/skills/[skill-name]/OBSERVATIONS.md

Toggle Commands

`/reflect on`

Enable automatic end-of-session reflection:

Create/update ~/.claude/reflect-skill-state.json with {"enabled": true, "updatedAt": "[timestamp]"}
Confirm: "Auto-reflect enabled. Sessions will be analyzed automatically when you stop."

`/reflect off`

Disable automatic reflection:

Update ~/.claude/reflect-skill-state.json with {"enabled": false, "updatedAt": "[timestamp]"}
Confirm: "Auto-reflect disabled. Use /reflect manually to analyze sessions."

`/reflect status`

Check current status:

Read ~/.claude/reflect-skill-state.json
Report: "Auto-reflect is [enabled/disabled]" with last updated timestamp

Note: The state file is saved in the global Claude user directory (~/.claude/) so it persists across plugin upgrades.

Example Session

User runs /reflect frontend-design after a UI session:

┌─ Skill Reflection: frontend-design ───────────────┐
│                                                   │
│ Signals: 2 corrections, 3 successes               │
│                                                   │
│ Proposed changes:                                 │
│                                                   │
│ 🔴 [HIGH] + Constraints/NEVER:                    │
│    "Use gradients unless explicitly requested"    │
│                                                   │
│ 🔴 [HIGH] + Color & Theme:                        │
│    "Dark backgrounds: use #000, not #1a1a1a"      │
│                                                   │
│ 🟡 [MED] + Layout:                                │
│    "Prefer CSS Grid for card layouts"             │
│                                                   │
│ Commit: "frontend-design: no gradients, #000 dark"│
│                                                   │
└───────────────────────────────────────────────────┘

Apply these changes? [Y/n] or describe tweaks

Git Integration

This skill has permission to:

Read skill files from .claude/skills/
Edit skill files (with user approval)
Run git add, git commit, git push in the skills directory

The skills repo should be initialized at .claude/skills with a remote origin.

Important Notes

Always show the exact changes before applying
Never modify skills without explicit user approval
Commit messages should be concise and descriptive
Push only after successful commit

reflect

Preview