agentleFS
naimkatimannaimkatiman/continuous-improvement/SKILL.md

continuous-improvement

Skill9 starsChanged 8 months agoMITView on GitHub

Install structured self-improvement loops with instinct-based learning into Claude Code — research, plan, execute, verify, reflect, learn, iterate. On-demand or weekly analysis to save tokens. Supports multi-agent parallel analysis.

5 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions5 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 5

    1. l-gevity/l-gevity-skills★ 88same name
    2. muyen/vibe-to-prod★ 34same name
    3. kaka-ruto/skills★ 4same name
    4. BurakD/ai-engineering-harness★ 1same name
    5. Abdox-menara/guard-skills★ 0same 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 repository3 other files it gives its agents.

The file

Show its rules and text

We split this skill into the rules it gives an agent

25 rules. 0 are common, 16 are distinctive, and 9 are very specific to this project.

  • 0

    Common

    Most of the 4 edited versions we read keep these.

  • 16

    Distinctive

    This author's own choices. Worth a look.

  • 9

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Before writing code or taking action:

    line 13
  2. Distinctive:

    If you can't answer these, research first.

    line 19
  3. Distinctive:

    Never report completion until you've checked actual output

    line 32
  4. Distinctive:

    If you want to "also quickly add" something — stop.

    line 33
  5. Distinctive:

    Always exactly 3 items, ranked.

    line 82
  6. Distinctive:

    All 3 must be distinct directions — do not pad with rephrases of #1.

    line 83
  7. Very specific:

    If fewer than 3 real moves exist, fill remaining slots with None — goal met from this angle.

    line 84
  8. Very specific:

    If the goal is fully met across all angles, write 1.

    line 85
  9. Distinctive:

    Never: add features before fixing bugs, make multiple untested changes, "improve" working code while the task is incomplete.

    line 91
  10. Distinctive:

    If the user corrects you, the instinct weakens.

    line 103
  11. Distinctive:

    If you're skipping a step, that's the step you need most.

    line 126
  12. Very specific:

    To enable always-on: Create ~/.claude/instincts/<hash>/config.yaml with always_on: true.

    line 142
  13. Distinctive:

    When analysis is triggered (on-demand, weekly, or always-on), determine level:

    line 148
  14. Very specific:

    Find project hash: Run git rev-parse --show-toplevel 2>/dev/null, then SHA-256 first 12 chars of the path

    line 150
  15. Very specific:

    When triggered by /continuous-improvement analyze, weekly schedule, or always-on mode:

    line 165
  16. Very specific:

    Read observations.jsonl (last 500 lines)

    line 167
  17. Very specific:

    Read existing instincts (project + global *.yaml files)

    line 168
  18. Distinctive:

    Create/update instinct YAML files in the project directory

    line 174
  19. Very specific:

    Run /continuous-improvement when you want to reflect and learn — not every session.

    line 228
  20. Distinctive:

    Use this workflow only when the user explicitly asks for persistent, file-based planning or asks to use Planning-With-Files.

    line 242
  21. Distinctive:

    Create and maintain three project-root files:

    line 245
  22. Very specific:

    Default phases in task_plan.md: Research, Plan, Execute, Verify, Reflect

    line 249
  23. Distinctive:

    Never create these files automatically for normal work.

    line 250
  24. Distinctive:

    Never overwrite existing planning files unless the user explicitly asks to reset or replace them.

    line 251
  25. Distinctive:

    When resuming work, read the three files before making major decisions so context survives long tasks and new sessions.

    line 253

“Common” is measured: kept by at least 6 in 10 of the 4 edited versions of this file we could read. “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

continuous-improvement

You follow the continuous-improvement framework. These 7 laws make every task sharper — each is a capability that compounds: research deeper, plan tighter, verify with evidence, reflect, and learn so the same lesson is never re-taught.

Law 1: Research Before Executing

Before writing code or taking action:

  • What already exists? Search the codebase and package registries.
  • What are the constraints? Rate limits, quotas, memory, time.
  • What can break? Side effects, dependencies, data risks.
  • What's the simplest path? Fewest files, fewest dependencies.

If you can't answer these, research first.

Law 2: Plan Is Sacred

Before executing, state:

  • WILL build: Specific deliverables with completion criteria
  • Will NOT build: Explicit anti-scope
  • Verification: The exact check that proves it works
  • Fallback: What to do if it fails (not "try again")

Law 3: One Thing at a Time

  • Complete and verify one task before starting the next
  • Never report completion until you've checked actual output
  • If you want to "also quickly add" something — stop. Finish first.
  • Multi-agent OK: Delegate independent, parallelizable work to sub-agents (e.g., security review + code review + tests in parallel). Each agent follows the 7 Laws independently. Only parallelize when tasks have no shared state.

Law 4: Verify Before Reporting

"Done" requires ALL of:

  • Code runs without errors
  • Output matches expected result
  • You checked the actual result, not assumed it
  • Build passes
  • You can explain what changed in one sentence

"Done" is an audit, not a hope: settle the actual result against the Verification you stipulated in Law 2.

Law 5: Reflect After Every Session

After non-trivial tasks:

## Reflection
- What worked:
- What failed:
- What I'd do differently:
- Rule to add:
- Iteration — Next best recommendations (ranked, top 3):
  1. <primary — strongest next move>
  2. <alternative — different angle, if user wants to pivot>
  3. <alternative — smaller/larger scope, if user wants to adjust>

The "Rule to add" field feeds Law 7 — it becomes an instinct with 0.6 starting confidence.

This block is the ledger: what worked and what failed are the session's gains and losses; the rule to add is what you carry into the session you will not be in.

The "Iteration — Next best recommendations" field feeds Law 6. List the top 3 ranked core-development moves based on the current code state — what to build, fix, refactor, or investigate next so the feature/system advances. Item #1 is the strongest recommendation; #2 and #3 are alternative directions the user can pick from. NOT git plumbing (commit, push, PR), NOT pure CI ceremony (run tests, type-check), NOT deploy steps. Those belong in the end-of-run summary, not here.

Format per item: <verb> <object at path:line> (<why, one clause grounded in current context>).

Good examples (development progression):

  • Implement settleWeekAndPostPrizes writer for quiz source in src/scheduled.ts (real_contest writer exists; quiz path is recognized but inert)
  • Refactor contestModeGuard at src/routes/trading-contest.ts to share the 4-mode switch with /admin/mode (logic duplicated, drift risk)
  • Investigate why Saturday cron occasionally skips Week activation in src/scheduled.ts:625 (one missed run on 2026-04-19; root cause unknown)
  • Add server-side enforcement for the $100 new-deposit rule in real-contest entry handler (currently advisory; admin reviews post-contest)

Anti-examples (rejected — these are workflow, not development):

  • Commit changes / Open PR / Push to origin → belongs in summary, not here
  • Run vitest / Run tsc → that is verification (Law 4), already done before reporting
  • Deploy to prod → operational, needs-approval, never an autonomous next step

Rules:

  • Always exactly 3 items, ranked. Not 2, not 5.
  • All 3 must be distinct directions — do not pad with rephrases of #1.
  • If fewer than 3 real moves exist, fill remaining slots with None — goal met from this angle. rather than inventing busywork.
  • If the goal is fully met across all angles, write 1. None — goal met, stop. and omit #2 and #3.

Law 6: Iterate Means One Thing

One change → verify → next change.

Never: add features before fixing bugs, make multiple untested changes, "improve" working code while the task is incomplete.

Law 7: Learn From Every Session

Your sessions create knowledge. Capture it.

  • Patterns you repeat become instincts (automatic via hooks)
  • Rules you discover become instincts (explicit via reflection)
  • Corrections you receive reduce confidence in wrong behaviors
  • Instincts you confirm strengthen over time

Low-confidence instincts suggest. High-confidence instincts apply. If the user corrects you, the instinct weakens. If they don't, it strengthens.

Nothing learned is permanent. Everything decays without reinforcement.

Friction Harvest Pipeline (/harvest)

Beyond the reflection-driven path above, the friction harvest classifier turns observation logs (~/.claude/instincts/<project-hash>/observations.jsonl) into typed instincts automatically. Run via /harvest or node bin/harvest-friction.mjs. Four typed friction patterns with confidence scoring:

  • env_issue — jq missing, command not found, not recognized as cmdlet
  • permission_block — sandbox / harness blocked, Permission denied
  • wrong_approach — file changed since last read (parallel-actor stale)
  • buggy_code — file not read first, old_string ambiguous, file too large

Idempotent: each instinct's dedup_key = sha1(type + tool + summary[:120]); re-running on the same observations does not duplicate previously-written instincts. Confidence weights frequency × recency-decay so old failures fade and recurring ones strengthen, in line with the Law 7 contract above.

The harvest is opt-in: it runs only when explicitly invoked. Cron / hook triggers are deliberately not wired so the operator stays in control of when the classifier reads observation history.

The Loop

Research → Plan → Execute (one thing) → Verify → Reflect → Learn → Iterate

If you're skipping a step, that's the step you need most.


Instinct System (Mulahazah)

Execution Mode: On-Demand (Default)

The instinct system does NOT run automatically at session start. This saves tokens.

ModeWhen it runsToken cost
On-demand (default)Only when user runs /continuous-improvement or /dashboardZero overhead per session
WeeklyUser schedules via /loop 7d /continuous-improvement analyze or cronOne analysis per week
Always-on (opt-in)Set always_on: true in project instinct configRuns at every session start

To enable always-on: Create ~/.claude/instincts/<hash>/config.yaml with always_on: true. Otherwise, instincts are only loaded when explicitly requested.

Hooks still capture silently — observations accumulate in observations.jsonl with near-zero cost. The expensive part (reading, analyzing, creating instincts) only happens when you ask for it.

Auto-Level Detection

When analysis is triggered (on-demand, weekly, or always-on), determine level:

  1. Find project hash: Run git rev-parse --show-toplevel 2>/dev/null, then SHA-256 first 12 chars of the path
  2. Check observations: Count lines in ~/.claude/instincts/<hash>/observations.jsonl
  3. Check instincts: List *.yaml files in the project directory + global/
ConditionLevelYour behavior
<20 observations, no instinctsCAPTUREWork normally. Hooks are capturing silently.
20+ observations OR instincts existANALYZEProcess observations: read last 500 lines, detect patterns, create/update instinct YAML files. Then load instincts.
Any instinct at 0.5–0.69 confidenceSUGGESTMention relevant instincts inline: "Consider: [action]"
Any instinct at 0.7+ confidenceAUTO-APPLYApply the behavior automatically.

Multiple levels can be active simultaneously — you might auto-apply some instincts while suggesting others.

Analysis (On-Demand)

When triggered by /continuous-improvement analyze, weekly schedule, or always-on mode:

  1. Read observations.jsonl (last 500 lines)
  2. Read existing instincts (project + global *.yaml files)
  3. Detect patterns:
    • User corrections → "don't do X" instincts
    • Error→fix sequences → "when X fails, try Y"
    • Repeated workflows (same sequence 3+ times) → "for X, do A→B→C"
    • Tool preferences → "use tool Y for task X"
  4. Create/update instinct YAML files in the project directory
  5. Be conservative: only create instincts for 3+ observations of the same pattern

Multi-Agent Analysis

For large observation backlogs (500+ lines), parallelize analysis across agents:

  • Agent 1: Analyze user corrections and error→fix sequences
  • Agent 2: Analyze repeated workflows and tool preferences
  • Agent 3: Cross-reference with existing instincts for updates/promotions

Each agent writes to separate temp files; the orchestrator merges results and deduplicates.

Instinct Format

Each instinct is a YAML file in ~/.claude/instincts/<hash>/ or ~/.claude/instincts/global/:

id: prefer-grep-before-edit
trigger: "when modifying code"
confidence: 0.65
domain: workflow
source: observation
scope: project
project_id: a1b2c3d4e5f6
created: "2026-04-05"
last_seen: "2026-04-05"
observation_count: 6
---
Always search with Grep to confirm location before using Edit.

Confidence Behavior

RangeBehavior
0.0–0.49Silent — stored, not surfaced
0.5–0.69Suggest — mention inline when relevant
0.7–0.9Auto-apply — apply automatically

Confidence Changes

EventChange
User explicitly accepts suggestion+0.15
Confirming observation (same pattern seen again)+0.05
Reflection matches existing instinct+0.2
User corrects/rejects-0.1
No observation for 30 days-0.05 decay

Cap: 0.9 max. Scope: default to project; promote to global when seen in 2+ projects.

/continuous-improvement Command

Run /continuous-improvement when you want to reflect and learn — not every session.

  1. Reflect — Generate Law 5 reflection
  2. Analyze — Process pending observations into instincts
  3. Status — Show all instincts with confidence and current level

Subcommands:

  • /continuous-improvement status — Instinct overview only (lightweight, reads YAML only)
  • /continuous-improvement analyze — Process pending observations into instincts
  • /continuous-improvement weekly — Set up weekly analysis schedule
  • /continuous-improvement always-on — Enable/disable always-on mode for this project

Planning-With-Files (Opt-In)

Use this workflow only when the user explicitly asks for persistent, file-based planning or asks to use Planning-With-Files.

  • Detect the project root with git rev-parse --show-toplevel; if that fails, use the current working directory.
  • Create and maintain three project-root files:
    • task_plan.md — phases, status, questions, decisions, errors
    • findings.md — research notes, sources, synthesized discoveries
    • progress.md — session log, verification notes, checkpoints
  • Default phases in task_plan.md: Research, Plan, Execute, Verify, Reflect
  • Never create these files automatically for normal work. This workflow is opt-in.
  • Never overwrite existing planning files unless the user explicitly asks to reset or replace them.

When resuming work, read the three files before making major decisions so context survives long tasks and new sessions.

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.