claude-reflect (Claude Skill) — Use Cases, Install & Live Demo

Why use it

Key features

Detects implicit corrections ("actually, do it this way") and positive signals
Drafts rule additions; you approve before they land in CLAUDE.md
Same rules surface in AGENTS.md for non-Claude tooling
Periodic consolidation removes contradictory or stale rules
Diff-based updates keep git history readable

Live Demo

What it looks like in practice

ready

Install

Pick your client

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "claude-reflect-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/BayramAnnakov/claude-reflect",
        "~/.claude/skills/claude-reflect"
      ],
      "_inferred": true
    }
  }
}

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "claude-reflect-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/BayramAnnakov/claude-reflect",
        "~/.claude/skills/claude-reflect"
      ],
      "_inferred": true
    }
  }
}

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "claude-reflect-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/BayramAnnakov/claude-reflect",
        "~/.claude/skills/claude-reflect"
      ],
      "_inferred": true
    }
  }
}

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "claude-reflect-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/BayramAnnakov/claude-reflect",
        "~/.claude/skills/claude-reflect"
      ],
      "_inferred": true
    }
  }
}

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "claude-reflect-skill",
      "command": "git",
      "args": [
        "clone",
        "https://github.com/BayramAnnakov/claude-reflect",
        "~/.claude/skills/claude-reflect"
      ]
    }
  ]
}

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json

{
  "context_servers": {
    "claude-reflect-skill": {
      "command": {
        "path": "git",
        "args": [
          "clone",
          "https://github.com/BayramAnnakov/claude-reflect",
          "~/.claude/skills/claude-reflect"
        ]
      }
    }
  }
}

Add to context_servers. Zed hot-reloads on save.

claude mcp add claude-reflect-skill -- git clone https://github.com/BayramAnnakov/claude-reflect ~/.claude/skills/claude-reflect

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use claude-reflect

Evolve CLAUDE.md without manual curation

👤 Solo devs who hate maintaining doc files ⏱ ~5 min beginner

When to use: You want CLAUDE.md to keep up with your preferences without being a writing chore.

Prerequisites

Skill installed — git clone https://github.com/BayramAnnakov/claude-reflect ~/.claude/skills/claude-reflect
Reflection enabled — Add use claude-reflect to your project's CLAUDE.md preamble

Flow

Work normally

Just code with Claude as usual. Correct it when wrong, praise it when right.✓ Copied

→ Skill silently captures — you don't notice it
End-of-day review

Use claude-reflect. Show me today's drafted rule additions. Approve or skip each.✓ Copied

→ 5–10 candidate rules with provenance (which session, what prompt)
Commit the diff

Apply approved rules and commit CLAUDE.md.✓ Copied

→ Clean git diff; rules now in effect

Outcome: CLAUDE.md that grows with you, no manual upkeep tax.

Pitfalls

Skill captures one-off context as durable rules — Always review the daily candidates; reject anything situational

Combine with: filesystem

Build team-wide AI conventions from collective corrections

👤 Tech leads standardizing AI workflows ⏱ ~60 min intermediate

When to use: Multiple devs all correct Claude on similar things; you want a shared rule set.

Flow

Collect per-developer drafts

Each dev runs claude-reflect daily and pushes their candidate rules to a shared review branch.✓ Copied

→ Branch with N drafts pending
Merge sessions

Use claude-reflect consolidate. Find rules captured by ≥2 people; promote those to AGENTS.md.✓ Copied

→ Common-ground rule set
Roll out

Merge to main. New AGENTS.md applies to everyone.✓ Copied

→ Team uses same baseline; per-dev local rules remain

Outcome: Bottom-up standardization without a process committee.

Pitfalls

Loud devs dominate; quiet ones' patterns missed — Ensure everyone runs the skill; weight by reflection events, not file edits

Combine with: github

Audit and prune stale rules in CLAUDE.md

👤 Long-time CLAUDE.md users ⏱ ~25 min intermediate

When to use: Your CLAUDE.md is now 600 lines and Claude's context is bloated.

Flow

Score relevance

Use claude-reflect. Score each rule by recency-of-last-application and current-codebase-fit.✓ Copied

→ Per-rule score
Propose deletions

Suggest 30 rules to remove (stale or obsolete).✓ Copied

→ Removal list with rationale
Diff + commit

Apply approved removals; commit with message 'reflect: prune stale rules'.✓ Copied

→ Slimmer CLAUDE.md

Outcome: CLAUDE.md that's actually read, not skimmed.

Pitfalls

Prune a rule that wasn't applied because Claude was respecting it — When in doubt, keep — but mark with 'last verified' so you re-check next quarter

Combinations

Pair with other MCPs for X10 leverage

claude-reflect-skill + pro-workflow-skill

pro-workflow for explicit capture, claude-reflect for passive — two-channel learning

Use pro-workflow when you say 'remember this'; let claude-reflect catch the rest in the background.✓ Copied

claude-reflect-skill + github

Reviewable rule changes via PR

Each Friday, claude-reflect opens a PR with proposed CLAUDE.md edits for human review.✓ Copied

Tools

What this MCP exposes

Tool	Inputs	When to call
watch_session	—	Always-on background process
review_candidates	since?	Daily / weekly approve loop
consolidate	scope?	Periodic dedupe / contradiction resolution
score_rules	—	Pre-prune audit
apply_to_files	approved_ids[], files[]	Land approved candidates into CLAUDE.md / AGENTS.md

Cost & Limits

What this costs to run

API quota: None — local
Tokens per call: Background capture is free; review/consolidate uses local LLM if configured
Monetary: Free
Tip: Approve candidates conservatively — quality > quantity

Security

Permissions, secrets, blast radius

Minimum scopes: filesystem-write

Credential storage: Skill state in .claude/reflect/; commit to repo if you want shared

Data egress: None by default

Reflection logs may include sensitive code snippets — gitignore the raw log; commit only distilled rules

Troubleshooting

Common errors and fixes

No candidates captured

Verify skill is invoked in CLAUDE.md preamble; check .claude/reflect/log for entries

Candidates are noise

Tighten the trigger sensitivity; only capture from explicit corrections, not generic chat

AGENTS.md drifts from CLAUDE.md

Run consolidate periodically; the tool is designed to keep them in sync but manual edits diverge them

Approval prompt overwhelming

Run review with --limit 5 daily; build a habit instead of doing 50 at once

Alternatives

claude-reflect vs others

Alternative	When to use it instead	Tradeoff
pro-workflow-skill	You prefer explicit capture and worktree orchestration	More manual; more powerful for parallel work
Manual CLAUDE.md curation	You're disciplined enough to write rules yourself	Frequently neglected; relies on willpower

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills