agentleFS
aroyburman-codesaroyburman-codes/compound-product-management/skills/reflect-and-improve/SKILL.md

reflect-and-improve

Skill1 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

  • Other versions2 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 1

    1. aroyburman-codes/claude-skills★ 035% same

    Wrote their own version · 1

    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.

  • In this repository2 other files it gives its agents.

The file

Show its rules and text

We split this skill into the rules it gives an agent

22 rules. About 0 are common, 22 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈22

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    After completing multi-file edits, project setup, or debugging sessions

    line 12
  2. Distinctive:

    After making an error and recovering from it

    line 13
  3. Distinctive:

    After a tool call is denied and you adjusted approach

    line 15
  4. Distinctive:

    Run these 6 steps in order.

    line 20
  5. Distinctive:

    If 0 signals found, skip to step 6.

    line 42
  6. Distinctive:

    Only record permissions observed 2+ times OR explicitly stated

    line 68
  7. Distinctive:

    Never persist tokens, passwords, or secrets

    line 69
  8. Distinctive:

    Update existing entries, don't append duplicates

    line 70
  9. Distinctive:

    Only log errors likely to recur

    line 100
  10. Distinctive:

    After 30 days with no recurrence, consider archiving

    line 102
  11. Distinctive:

    Only record preferences confirmed by 2+ instances or explicit statement

    line 117
  12. Distinctive:

    Don't duplicate what's already in CLAUDE.md or project config

    line 118
  13. Distinctive:

    Write confirmed learnings to persistent memory files.

    line 123
  14. Distinctive:

    Check if a relevant topic file exists (permissions.md, errors.md, preferences.md)

    line 138
  15. Distinctive:

    If yes: update existing entries, add new ones, remove outdated ones

    line 139
  16. Distinctive:

    If no: create the topic file

    line 140
  17. Distinctive:

    Update MEMORY.md if it needs a link to a new topic file (keep under 200 lines)

    line 141
  18. Distinctive:

    Every entry gets a "last updated" date

    line 164
  19. Distinctive:

    If a preference contradicts recent behavior, update or remove it

    line 166
  20. Distinctive:

    Edit, don't append: Keep files clean by updating existing entries.

    line 174
  21. Distinctive:

    Privacy first: Never persist secrets, tokens, or personal data.

    line 176
  22. Distinctive:

    Respect existing docs: Don't duplicate CLAUDE.md or project config.

    line 177

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Reflect and Improve

A self-improvement loop for Claude Code. After significant work, this skill reviews what happened — errors made, corrections received, implicit preferences — and writes confirmed learnings to persistent memory files. Future sessions start smarter.

When to Invoke

  • After completing multi-file edits, project setup, or debugging sessions
  • After making an error and recovering from it
  • At natural session breakpoints (switching tasks, wrapping up)
  • After a tool call is denied and you adjusted approach
  • When explicitly requested

The Reflection Framework

Run these 6 steps in order. Skip any step with no findings.

1. Review Checkpoint

Scan recent actions 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
  • Approaches 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

If 0 signals found, skip to step 6.

2. Permission Patterns

Track which operations the user approved or denied.

Write to: permissions.md in the project memory directory

Format:

# Permission Patterns
Last updated: YYYY-MM-DD

## Approved
- git commit — always approved
- npm install — approved for this project

## 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 approved

Rules:

  • Only record permissions observed 2+ times OR explicitly stated
  • Never persist tokens, passwords, or secrets
  • Update existing entries, don't append duplicates

3. Error Catalog

Classify errors and record the fix.

Error categories:

CategoryExample
Wrong assumptionAssumed Python 3.10 but project uses 3.8
Missing contextDidn't read package.json before running npm commands
Tool misuseUsed cat instead of Read tool
Wrong fileEdited the test file instead of the source file
Stale knowledgeUsed deprecated API method
Ordering errorRan 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
- Prevention: Before writing Python code, check version requirements

Rules:

  • Only log errors likely to recur
  • Include the prevention step — that's the value
  • After 30 days with no recurrence, consider archiving

4. User Preference Signals

Capture implicit preferences revealed through behavior and corrections.

Signal types:

  • Coding style: tabs vs spaces, quotes, naming conventions
  • Communication style: prefers short answers, likes/dislikes emojis
  • Tool choices: package manager, test framework, linter
  • Workflow patterns: commits frequently vs batches, reviews diffs vs trusts agent

Write to: preferences.md in the project memory directory

Rules:

  • Only record preferences confirmed by 2+ instances or explicit statement
  • Don't duplicate what's already in CLAUDE.md or project config
  • Project config wins over inferred preferences

5. Memory Synthesis

Write confirmed learnings to persistent memory files.

What qualifies:

  • Pattern observed 2+ times this session
  • Explicit user instruction ("always do X", "never do Y")
  • Error with a clear prevention rule
  • Stable permission pattern

What doesn't qualify:

  • Speculation or single observations
  • Anything already in project docs
  • Session-specific context
  • Sensitive data

Process:

  1. Check if a relevant topic file exists (permissions.md, errors.md, preferences.md)
  2. If yes: update existing entries, add new ones, remove outdated ones
  3. If no: create the topic file
  4. Update MEMORY.md if it needs a link to a new topic file (keep under 200 lines)

6. Friction Audit

Identify moments where the experience could be smoother.

Look for:

  • User had to repeat themselves
  • User had to correct a misunderstanding
  • User provided context that should have been known
  • A task took multiple rounds when one would suffice

Output format:

## Friction Audit — [date]
- User corrected package manager twice -> saved to preferences.md
- Had to re-read config file I should have cached -> read it first next time

For each friction point, identify if there's a systemic fix and apply it.

Memory File Hygiene

  • Every entry gets a "last updated" date
  • During reflection, flag entries older than 90 days for review
  • If a preference contradicts recent behavior, update or remove it
  • Each topic file: aim for under 100 lines
  • MEMORY.md: must stay under 200 lines
  • Archive old entries when files grow too large

Key Principles

  1. Less is more. A few high-quality entries beat a bloated log.
  2. Edit, don't append. Keep files clean by updating existing entries.
  3. Confirm before persisting. Save observed facts, not assumptions.
  4. Privacy first. Never persist secrets, tokens, or personal data.
  5. Respect existing docs. Don't duplicate CLAUDE.md or project config.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.