| name | improve-system |
| description | Capture a lesson from the current conversation and patch the setup so the same mistake never recurs — add a Gotchas section to the relevant skill, tighten CLAUDE.md/instructions, fix an agent prompt, or write a memory. Use proactively right after the user corrects your output or course-corrects you, and when wrapping up a substantial session. Invoke directly with /improve-system. |
Improve System
The feedback loop that makes the setup compound. Most AI output stops at "good enough" and the lesson evaporates. This skill turns a correction you just made into a durable change, so the next run starts smarter instead of repeating the mistake.
When to run
- The user corrected your output, repeated an instruction, or said "no, do it like X".
- You hit a gotcha — an edge case, a wrong assumption, a format that needed rework.
- End of a substantial session (offer it).
- The user types /improve-system.
The loop
-
Find the lesson. From the CURRENT conversation, list the specific corrections, frictions, and gotchas: what went wrong, what the user actually wanted, and the rule that would have prevented it. Quote the moment it happened. If nothing real surfaced, say so and stop — never invent lessons to look productive.
-
Pick the right home — the most specific place that fits, mirroring the context hierarchy:
| Lesson type | Home |
|---|
| Quirk / edge case of a specific skill | a ## Gotchas section in that skill's SKILL.md |
| A reusable workflow that doesn't exist yet | a new skill |
| Cross-project rule (naming, safety, style) | ~/.claude/instructions.md or CLAUDE.md |
| An agent behaving wrong | that agent's .md system prompt |
| A durable fact/preference about the user or a project | a memory file |
-
Write the Gotchas entry — the highest-leverage move. Append to the relevant skill:
## Gotchas
- <symptom> → <rule that prevents it>. (learned <date>)
One line per gotcha. Lead with the symptom so future-you recognizes the situation before repeating it.
-
Propose before you persist. CLAUDE.md, instructions.md, and every global skill/agent load into future sessions — show the exact change and get an explicit yes before editing them. Project-local docs and memory writes can proceed without asking.
-
Keep it minimal. One lesson → one home. Don't refactor the file; append the smallest change that captures the lesson.
Verification
- Re-read the patched file and confirm the lesson is phrased so it would actually fire next time (concrete symptom, concrete rule).
- If you edited a skill / agent / instructions that lives in the reusable workspace template, note it so it can be re-synced (see TEMPLATE.md).
Gotchas
- A "lesson" with no concrete correction behind it is noise → only capture what the user actually pushed back on. (learned 2026-06-16)
