reflect-and-improve
Skill0 starsChanged 9 months agoMITView on GitHub
Use after completing significant work, recovering from errors, or at session breakpoints to review actions, synthesize learnings, and write persistent improvements to memory files. Reduces repeated mistakes and user friction over time.
- Reads credentials
- Installs packages
- Commits and pushes
2 other projects use a version of this, 1 of them edited.
Adopted by
Most recently taken up by
- ShaishavMaisuria/research-paper-lifecycle-skillstheir own version, first seen Nov 1, 2026
- aroyburman-codes/compound-product-managementedited, first seen Feb 21, 2026
Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 1
- aroyburman-codes/compound-product-management★ 161% same
Wrote their own version · 1
- ShaishavMaisuria/research-paper-lifecycle-skills★ 59same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
The file
Show its rules and text
We split this skill into the rules it gives an agent
30 rules. About 0 are common, 29 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈29
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 12
Goal: Every session leaves Claude Code slightly better calibrated to the user and codebase.
- Distinctive: line 16
After completing multi-file edits, project setup, or debugging sessions
- Distinctive: line 17
After making an error and recovering from it
- Very specific: line 18
When the user explicitly runs /reflect-and-adapt
- Distinctive: line 20
After a tool call is denied and you had to adjust approach
- Distinctive: line 24
Run these 6 steps in order.
- Distinctive: line 48
Action: If you find 0 signals, skip to step 6.
- Distinctive: line 82
Only record permissions observed across 2+ instances OR explicitly stated by user
- Distinctive: line 83
Never persist token values, passwords, or secrets
- Distinctive: line 84
Update existing entries rather than appending duplicates
- Distinctive: line 123
Only log errors that are likely to recur (not one-off typos)
- Distinctive: line 125
After 30 days with no recurrence, consider archiving old entries
- Distinctive: line 168
Only record preferences confirmed by user behavior (2+ instances) or explicit statement
- Distinctive: line 169
Don't record preferences that are already in CLAUDE.md or project config files
- Distinctive: line 170
If a preference contradicts project config (e.g., .prettierrc), project config wins
- Distinctive: line 176
Write confirmed learnings to persistent memory files.
- Distinctive: line 195
Check if a relevant topic file already exists (permissions.md, errors.md, preferences.md)
- Distinctive: line 196
If yes: use Edit tool to update existing entries, add new ones, remove outdated ones
- Distinctive: line 197
If no: create the topic file with clear structure
- Distinctive: line 198
If MEMORY.md needs a link to a new topic file, add it (keep MEMORY.md under 200 lines)
- Distinctive: line 228
If the fix is a memory update, do it now (step 5)
- Distinctive: line 229
If the fix requires a workflow change, note it but don't over-engineer
- Distinctive: line 236
Every entry should have a "last confirmed" or "last updated" date
- Distinctive: line 238
If a preference has been contradicted by recent behavior, update or remove it
- Distinctive: line 243
If a file grows too large, archive old/low-value entries
- Distinctive: line 285
Edit, don't append: Keep files clean by updating existing entries.
- Distinctive: line 286
Confirm before persisting: Don't save assumptions — save observed facts.
- Distinctive: line 287
Privacy first: Never persist secrets, tokens, or personal data.
- Distinctive: line 288
Respect existing docs: Don't duplicate what's in CLAUDE.md or project config.
- Distinctive: line 289
Date everything: Every entry needs a timestamp for staleness tracking.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Reflect and Improve
Overview
A self-improvement loop for Claude Code. After significant work, this skill triggers a structured review of what happened — errors made, permissions granted, user corrections, implicit preferences — and writes confirmed learnings to persistent memory files so future sessions start smarter.
Goal: Every session leaves Claude Code slightly better calibrated to the user and codebase.
When to Invoke
- After completing multi-file edits, project setup, or debugging sessions
- After making an error and recovering from it
- When the user explicitly runs
/reflect-and-adapt - At natural session breakpoints (switching tasks, wrapping up)
- After a tool call is denied and you had to adjust approach
The Reflection Framework
Run these 6 steps in order. Skip any step that has no findings.
1. Review Checkpoint
Scan recent actions in the current session for signals worth learning from.
Look for:
- Tool calls that failed or were retried
- User corrections ("no, I meant...", "not that file", "use X instead")
- Permission denials (user clicked "deny" on a tool call)
- Approaches that were abandoned mid-way
- Tasks that required multiple attempts
Output format:
## Review Checkpoint — [date]
- [RETRY] Ran tests 3 times before realizing venv wasn't activated
- [CORRECTION] User said "use pnpm, not npm" — package manager preference
- [DENIED] User denied `git push` — wants to review before pushing
- [ABANDONED] Started editing wrong file, had to switch to correct oneAction: If you find 0 signals, skip to step 6. Don't force findings.
2. Permission Patterns
Track which operations the user approved or denied to reduce future permission prompts.
Capture:
- Operations the user said "yes" to (especially repeated ones)
- Operations the user denied (and why, if stated)
- Implicit permissions (user asked you to do X, so Y is clearly fine too)
Write to: permissions.md in the project memory directory
Format:
# Permission Patterns
Last updated: YYYY-MM-DD
## Approved
- git commit with co-author — always approved
- npm install — approved for this project
- file creation in src/ — approved
## Denied
- git push — user wants to review first
- modifying .env — never touch without asking
## Implicit
- if user asks to "set up tests", creating test files is implicitly approvedRules:
- Only record permissions observed across 2+ instances OR explicitly stated by user
- Never persist token values, passwords, or secrets
- Update existing entries rather than appending duplicates
3. Error Catalog
Classify errors you made and record the fix so you don't repeat them.
Error categories:
| Category | Example |
| Wrong assumption | Assumed Python 3.10 but project uses 3.8 |
| Missing context | Didn't read package.json before running npm commands |
| Tool misuse | Used cat instead of Read tool |
| Wrong file | Edited the test file instead of the source file |
| Stale knowledge | Used deprecated API method |
| Ordering error | Ran tests before installing dependencies |
Write to: errors.md in the project memory directory
Format:
# Error Catalog
Last updated: YYYY-MM-DD
## [date] Wrong assumption — Python version
- What happened: Used match/case syntax, but project requires Python 3.8
- Root cause: Didn't check pyproject.toml before writing code
- Fix: Always read pyproject.toml or setup.cfg for Python version constraints
- Prevention: Before writing Python code, check version requirements
## [date] Missing context — Package manager
- What happened: Ran `npm install` but project uses pnpm
- Root cause: Didn't check for pnpm-lock.yaml
- Fix: Check for lock files (pnpm-lock.yaml, yarn.lock, package-lock.json) first
- Prevention: Before any install command, check which lock file existsRules:
- Only log errors that are likely to recur (not one-off typos)
- Include the prevention step — that's the real value
- After 30 days with no recurrence, consider archiving old entries
4. User Preference Signals
Capture implicit preferences the user reveals through their behavior and corrections.
Signal types:
- Coding style: tabs vs spaces, single vs double quotes, semicolons, naming conventions
- Communication style: prefers short answers, wants explanations, likes/dislikes emojis
- Tool choices: preferred package manager, test framework, linter, editor
- Workflow patterns: commits frequently vs batches, reviews diffs vs trusts agent
- Architecture preferences: monorepo vs multi-repo, OOP vs functional, etc.
Write to: preferences.md in the project memory directory
Format:
# User Preferences
Last updated: YYYY-MM-DD
## Coding Style
- TypeScript: single quotes, no semicolons, 2-space indent
- Python: black formatter, type hints preferred
- Prefers functional style over classes
## Communication
- Likes concise responses — no fluff
- Doesn't want time estimates
- Prefers bullet points over paragraphs
## Tools
- Package manager: pnpm
- Test framework: vitest (not jest)
- Linter: biome
## Workflow
- Wants to review git diffs before committing
- Prefers small, focused commits over large batchesRules:
- Only record preferences confirmed by user behavior (2+ instances) or explicit statement
- Don't record preferences that are already in CLAUDE.md or project config files
- If a preference contradicts project config (e.g., .prettierrc), project config wins
5. Memory Synthesis
Write confirmed learnings to persistent memory files. This is the actual "getting smarter" step.
Target directory: The project-level memory directory
- For project-scoped learnings:
~/.claude/projects/<project>/memory/ - For global learnings:
~/.claude/memory/(but be conservative — most things are project-scoped)
What qualifies as a confirmed learning:
- Pattern observed 2+ times in this session
- Explicit user instruction ("always do X", "never do Y")
- Error that was fixed and has a clear prevention rule
- Permission pattern that's clearly stable (not a one-off)
What does NOT qualify:
- Speculation or single observations
- Anything already in CLAUDE.md or project docs
- Session-specific context (current task, temporary state)
- Sensitive data (tokens, passwords, personal details)
Process:
- Check if a relevant topic file already exists (permissions.md, errors.md, preferences.md)
- If yes: use Edit tool to update existing entries, add new ones, remove outdated ones
- If no: create the topic file with clear structure
- If MEMORY.md needs a link to a new topic file, add it (keep MEMORY.md under 200 lines)
Anti-patterns to avoid:
- Append-only logging (leads to bloat — edit and consolidate instead)
- Saving everything (only save what changes future behavior)
- Duplicating project docs (if it's in .eslintrc, don't also put it in preferences.md)
6. Friction Audit
Identify moments where the user experience could be smoother.
Look for:
- User had to repeat themselves (said the same thing twice)
- User had to correct a misunderstanding
- User had to provide context that should have been known
- A task took multiple rounds when it could have been done in one
- User seemed frustrated or impatient
Output format:
## Friction Audit — [date]
- User corrected package manager twice → saved to preferences.md
- Had to re-read config file I should have cached → added to review checklist
- User provided project structure context that exists in README → read README first next timeActions:
- For each friction point, identify if there's a systemic fix (memory update, workflow change)
- If the fix is a memory update, do it now (step 5)
- If the fix requires a workflow change, note it but don't over-engineer
Memory File Hygiene
Staleness Prevention
- Every entry should have a "last confirmed" or "last updated" date
- During reflection, scan for entries older than 90 days — flag for review
- If a preference has been contradicted by recent behavior, update or remove it
Size Limits
- Each topic file: aim for under 100 lines
- MEMORY.md: must stay under 200 lines
- If a file grows too large, archive old/low-value entries
File Organization
~/.claude/projects/<project>/memory/
MEMORY.md # Index + high-level context (loaded into system prompt)
permissions.md # Approved/denied operations
errors.md # Error catalog with prevention rules
preferences.md # User style and tool preferencesExample: Full Reflection Output
=== Reflect and Improve — 2026-02-17 ===
## Review Checkpoint
- [CORRECTION] User said "use vitest not jest" — test framework preference
- [RETRY] Failed to run tests — forgot to install deps first
- [DENIED] git push denied — user reviews before pushing
## Permission Patterns
→ Updated permissions.md: added "git push — review first"
## Error Catalog
→ Updated errors.md: "Always run install before test commands"
## User Preferences
→ Updated preferences.md: "Test framework: vitest (not jest)"
## Memory Synthesis
→ Wrote 3 entries across 3 topic files
→ No MEMORY.md changes needed (topic files already linked)
## Friction Audit
- 1 friction point: had to be told test framework twice
→ Fixed: saved to preferences.md, won't happen againImportant Principles
- Less is more. A few high-quality memory entries beat a bloated log.
- Edit, don't append. Keep files clean by updating existing entries.
- Confirm before persisting. Don't save assumptions — save observed facts.
- Privacy first. Never persist secrets, tokens, or personal data.
- Respect existing docs. Don't duplicate what's in CLAUDE.md or project config.
- Date everything. Every entry needs a timestamp for staleness tracking.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

