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
- l-gevity/l-gevity-skillstheir own version, first seen Nov 14, 2026
- BurakD/ai-engineering-harnesstheir own version, first seen Nov 1, 2026
- Abdox-menara/guard-skillstheir own version, first seen Aug 24, 2026
- kaka-ruto/skillstheir own version, first seen Apr 23, 2026
- muyen/vibe-to-prodtheir own version, first seen Jan 3, 2026
Other versions5 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 5
- l-gevity/l-gevity-skills★ 88same name
- muyen/vibe-to-prod★ 34same name
- kaka-ruto/skills★ 4same name
- BurakD/ai-engineering-harness★ 1same name
- 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.
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
- Distinctive: line 13
Before writing code or taking action:
- Distinctive: line 19
If you can't answer these, research first.
- Distinctive: line 32
Never report completion until you've checked actual output
- Distinctive: line 33
If you want to "also quickly add" something — stop.
- Distinctive: line 82
Always exactly 3 items, ranked.
- Distinctive: line 83
All 3 must be distinct directions — do not pad with rephrases of #1.
- Very specific: line 84
If fewer than 3 real moves exist, fill remaining slots with None — goal met from this angle.
- Very specific: line 85
If the goal is fully met across all angles, write 1.
- Distinctive: line 91
Never: add features before fixing bugs, make multiple untested changes, "improve" working code while the task is incomplete.
- Distinctive: line 103
If the user corrects you, the instinct weakens.
- Distinctive: line 126
If you're skipping a step, that's the step you need most.
- Very specific: line 142
To enable always-on: Create ~/.claude/instincts/<hash>/config.yaml with always_on: true.
- Distinctive: line 148
When analysis is triggered (on-demand, weekly, or always-on), determine level:
- Very specific: line 150
Find project hash: Run git rev-parse --show-toplevel 2>/dev/null, then SHA-256 first 12 chars of the path
- Very specific: line 165
When triggered by /continuous-improvement analyze, weekly schedule, or always-on mode:
- Very specific: line 167
Read observations.jsonl (last 500 lines)
- Very specific: line 168
Read existing instincts (project + global *.yaml files)
- Distinctive: line 174
Create/update instinct YAML files in the project directory
- Very specific: line 228
Run /continuous-improvement when you want to reflect and learn — not every session.
- Distinctive: line 242
Use this workflow only when the user explicitly asks for persistent, file-based planning or asks to use Planning-With-Files.
- Distinctive: line 245
Create and maintain three project-root files:
- Very specific: line 249
Default phases in task_plan.md: Research, Plan, Execute, Verify, Reflect
- Distinctive: line 250
Never create these files automatically for normal work.
- Distinctive: line 251
Never overwrite existing planning files unless the user explicitly asks to reset or replace them.
- Distinctive: line 253
When resuming work, read the three files before making major decisions so context survives long tasks and new sessions.
“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.
Files
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 hereRun vitest/Run tsc→ that is verification (Law 4), already done before reportingDeploy 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 cmdletpermission_block— sandbox / harness blocked, Permission deniedwrong_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 → IterateIf 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.
| Mode | When it runs | Token cost |
| On-demand (default) | Only when user runs /continuous-improvement or /dashboard | Zero overhead per session |
| Weekly | User schedules via /loop 7d /continuous-improvement analyze or cron | One analysis per week |
| Always-on (opt-in) | Set always_on: true in project instinct config | Runs 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:
- Find project hash: Run
git rev-parse --show-toplevel 2>/dev/null, then SHA-256 first 12 chars of the path - Check observations: Count lines in
~/.claude/instincts/<hash>/observations.jsonl - Check instincts: List
*.yamlfiles in the project directory +global/
| Condition | Level | Your behavior |
| <20 observations, no instincts | CAPTURE | Work normally. Hooks are capturing silently. |
| 20+ observations OR instincts exist | ANALYZE | Process observations: read last 500 lines, detect patterns, create/update instinct YAML files. Then load instincts. |
| Any instinct at 0.5–0.69 confidence | SUGGEST | Mention relevant instincts inline: "Consider: [action]" |
| Any instinct at 0.7+ confidence | AUTO-APPLY | Apply 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:
- Read
observations.jsonl(last 500 lines) - Read existing instincts (project + global
*.yamlfiles) - 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"
- Create/update instinct YAML files in the project directory
- 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
| Range | Behavior |
| 0.0–0.49 | Silent — stored, not surfaced |
| 0.5–0.69 | Suggest — mention inline when relevant |
| 0.7–0.9 | Auto-apply — apply automatically |
Confidence Changes
| Event | Change |
| 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.
- Reflect — Generate Law 5 reflection
- Analyze — Process pending observations into instincts
- 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, errorsfindings.md— research notes, sources, synthesized discoveriesprogress.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.
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.

