What does this skill do, and when should you use it?
claude-reflect is a self-learning plugin for Claude Code (v2.6.0, MIT licensed). Automatically-running hooks capture corrections, positive feedback, and preferences during your sessions and queue them; you then run /reflect to review each learning and sync it to global or project CLAUDE.md and AGENTS.md files. Version 2 adds skill discovery: it analyzes past sessions to find repeating workflows and turns them into reusable slash commands. Every learning carries a confidence score, gets human review before landing, supports corrections in any language via AI semantic validation, and includes semantic deduplication.
Runs four hooks automatically: one reminds of pending learnings at session start; capture_learning.py detects correction patterns on every prompt (regex matches like "no, use X", "actually...", "remember:") and queues them to ~/.claude/learnings-queue.; one backs up the queue before context compaction; one reminds after git commits. When you run /reflect, an AI semantic filter validates the queue (understanding any language), filters false positives, and assigns confidence scores (0.60–0.95); approved learnings sync to ~/.claude/CLAUDE.md, ./CLAUDE.md, subdirectory CLAUDE.md files, AGENTS.md, .claude/rules/*.md, or the relevant skill file. Running /reflect-skills uses AI semantic analysis over session history to distill repeated intents into skill candidates (e.g., generating /daily-review from 15 similar requests), creating draft skill files in .claude/commands/ for your approval. Supporting flags include --dry-run, --dedupe for semantic deduplication, and --scan-history.
- Developers who repeatedly correct Claude about wrong models or tools and want those mistakes to stop recurring
- Engineers on large projects who want conventions (naming, build commands, structure) remembered across sessions
- Users who type similar instructions repeatedly (daily productivity reviews, deploy routines) and want them codified into one command
- Teams using multiple AI coding tools (Codex, Cursor, Aider, etc.) who want learnings synced to AGENTS.md
- Custom skill authors who want corrections made during skill execution routed back into the skill file itself
- Users on a new machine who want to recover learnings by scanning up to 90 days of past sessions
How do you install this skill?
- Static review only; no code was executed. Test badges (160 passing) and CI status are self-reported and independently unverified.
- Hooks analyze and persist prompt content automatically on every submission to multiple files under ~/.claude; sensitive prompt content may be written to disk queues — evaluate privacy implications before installing.
- Documentation inconsistencies exist (README badge 2.6.0 vs CHANGELOG 3.1.0, conflicting queue path descriptions); rely on actual behavior rather than docs.
- CJK detection (including Chinese correction patterns) is claimed only in the changelog with no pattern list or test evidence in the reviewed material; Chinese users should trial with a small scope first.
- CLAUDE.md is shared by multiple tools; automatic writes may affect Codex/Cursor and others — review changes with --dry-run first.
- Shell / CLI
- Local filesystem
Claude Code CLIPython 3.6+
Prerequisites: Claude Code CLI and Python 3.6+ (macOS, Linux, and Windows natively supported; no WSL needed). Install with:
claude plugin marketplace add bayramannakov/claude-reflect
claude plugin install claude-reflect@claude-reflect-marketplace
You must fully exit and restart Claude Code afterward so hooks auto-configure. When upgrading from older versions, known Claude Code cache issues ("Duplicate hooks file detected") require manually clearing the two cache directories under ~/.claude/plugins/ before reinstalling — see the README steps.
git clone --depth 1 https://github.com/BayramAnnakov/claude-reflect.git ~/.claude/skills/claude-reflectGenerated from the source repository and skill path; it copies only this skill's folder. If the author's install steps above differ, follow those first. To scope it to one project, replace ~/.claude/skills with that project's .claude/skills.
How do you use this skill?
Once installed, send your agent any of these to trigger it:
- no, use gpt-5.1 not gpt-5
Daily flow: correct Claude naturally (e.g., "no, use gpt-5.1 not gpt-5") — hooks queue it automatically; after finishing work, run /reflect (or say "remember: ..." for high-confidence capture), then apply, edit, or skip each learning. Skill discovery: run /reflect-skills --days 30 to analyze recent sessions, use --dry-run to preview and --all-projects for cross-project patterns. First-time users should run /reflect --scan-history. Note: Claude Code deletes local sessions after 30 days by default; set { "cleanupPeriodDays": 99999 } in ~/.claude/settings. to preserve history.
What are this skill's strengths and limitations?
- Human review gate before anything is written, preventing bad learnings from polluting memory files
- Multi-target sync covers CLAUDE.md, AGENTS.md, rules directories, and skill files — works across several AI tools
- Hybrid regex + AI semantic detection understands corrections in any language, with visible confidence scores
- Safety options like --dry-run, --dedupe, and --targets; 160 tests passing
- Skill improvement routing makes custom skills smarter over time
- Deeply tied to Claude Code-specific mechanisms (plugin hooks, slash commands, CLAUDE.md) — not portable as-is
- Stage 2 is manual; if you forget to run /reflect, learnings pile up unprocessed
- Historical scan and skill discovery depend on local session files, which Claude Code purges after 30 days by default
- README screenshots and example outputs cannot be independently verified; contributing guidelines are referenced but not included in the source
- Upgrading older versions hits known Claude Code plugin cache bugs (upstream issues #14061, #15369) requiring manual cache clearing
How does this skill compare with similar options?
Side by side with related skills; every score comes from the same FSRS standard.
| Skill | FS score | Stars | Last updated | License |
|---|---|---|---|---|
| Claude Reflect Self-Learning Memory this page | 57 · Use with care | ★ 1.9k | 1mo ago | MIT |
| Agents Observe | 54 · Use with care | ★ 712 | 2mo ago | MIT |
| Peon Ping Session Voice Pack Selector | 50 · Use with care | ★ 5.1k | 18d ago | MIT |
| TDD Guard | 61 · Recommended | ★ 2.4k | 11d ago | MIT |
| DeepTutor CLI Skill | 57 · Use with care | ★ 52k | 9d ago | Apache-2.0 |
The source names no direct competitors, but the README notes AGENTS.md sync targets Codex, Cursor, Aider, Jules, Zed, and Factory — positioning it as a complementary memory layer across those tools' native mechanisms.
How did FollowSkills review this skill?
Data flow is well disclosed (hooks capture → queue → human review before writing to CLAUDE.md/AGENTS.md), writes are gated by [y/n] confirmation and --dry-run preview, MIT license; deducted because hooks automatically capture prompt/session content and persist it across multiple ~/.claude locations with broad scope, no explicit rollback mechanism, and limited sensitive-data handling disclosure.
Repo includes CI workflows (3 OSes, 2 Python versions) and committed pytest suites (test_memory_hierarchy.py etc.) covering key paths like rule parsing, file discovery and routing, plus abnormal-input tests (invalid JSON, missing files); but this is a static review — pass status unverified — and CLAUDE.md's example queue path (~/.claude/learnings-queue.) contradicts the per-project queue path described in changelog 3.1.0.
SKILL.md trigger conditions are explicit (user corrections, 'remember', pre-compaction reminders) and scenarios are clear; changelog claims CJK correction patterns added in v3.1.0; deducted for missing declared non-fit boundaries (non-Claude-Code environments, missing Python) and unverified real-world CJK detection accuracy.
MIT license, Keep-a-Changelog format, semantic versioning, and RELEASING.md release process are all present; deducted because the README version badge (2.6.0) is out of sync with changelog 3.1.0, SKILL.md itself is thin beyond examples, publisher identity is unverified, and maintenance responsibility rests on a single personal repository.
The two-stage design (automatic capture + manual review) addresses a real pain point and produces standard CLAUDE.md entries, with --dry-run and --dedupe reducing cost; deducted because static review cannot verify output quality, and false positive/negative rates of the regex+semantic hybrid detection are unknown.
Auditable primary material exists: CI config, 160 tests (including bash/Python equivalence integration tests), and reproducible CLI test commands; but all evidence is self-reported, test passage could not be independently reproduced in this static review, and there is no third-party corroboration, so capped at 5.
Open a dimension to read why it scored that way
Evidence confidence：Low — Mostly static review, author material or a limited demo; useful for discovery, not high-risk decisions.
See the full review method →