<!-- Line count target: keep SKILL.md body under 400 lines (hard limit: 500). --> <!-- Run: wc -l SKILL.md to check. Move overflow sections to references/ with links below. -->

Self-Improving Agent

Behavioral-rules layer that complements the recall plugin. Recall stores facts and context; self-improving stores correction-derived behavioral rules. Data lives in ~/self-improving/ (not in the skill directory, not in recall's memory/). Three tier files: rules.md (new/unconfirmed rules), hot.md (confirmed 3+ times in 7 days), cold.md (archived 30+ days unused). Reflection sessions saved in ~/self-improving/reflections/YYYY-MM-DD.md. Rule metadata tracked in ~/self-improving/meta.json. Full algorithm details in references/.

First Use

On any self-improving action, check if ~/self-improving/ exists. If not:

• Create ~/self-improving/rules.md with content: # Rules\n\n
• Create ~/self-improving/hot.md with content: # Hot Rules\n\n
• Create ~/self-improving/cold.md with content: # Cold Rules\n\n
• Create directory ~/self-improving/reflections/
• Create ~/self-improving/meta.json with content: {}
• Confirm: "Created ~/self-improving/ with empty files. Ready to use."

Then load ~/self-improving/hot.md to apply active rules immediately.

Reflection Protocol

Triggers: "reflect", "reflect on that", "reflect deeply", "what did I learn", "self-assess". Do NOT trigger on "evening reflection", "end of day", "what did I do today" — those belong to the productivity skill's Evening Reflection workflow.

Steps:

1. Check ~/self-improving/ exists (create if missing — see First Use)
2. Load ~/self-improving/hot.md and ~/self-improving/rules.md to surface relevant rules
3. Brief mode (default — any "reflect" trigger): produce 3-section structured output:

# Reflection: YYYY-MM-DD [HH:MM]

## What Went Well
[1-3 sentences]

## What Went Poorly
[1-3 sentences]

## Lesson
[One reusable takeaway — generalized from the specific task]

*Task context: [brief description of what was being done]*

4. Detailed mode ("reflect deeply" or user-requested): add sections — Root Cause Analysis, Rule Candidates, Pattern History
5. Save output to ~/self-improving/reflections/YYYY-MM-DD.md (append if file exists for today, with timestamp header)
6. If reflection surfaces a clear lesson, ask: "Want me to capture this as a rule?"

Correction Capture

Triggers:

• Explicit: user says "correction: ..." — ALWAYS capture immediately, no prompt needed
• Conversational: user says "no", "not that", "I prefer X", "do it differently", "stop doing that", "don't do X" — prompt: "Want me to remember this preference?"

Steps for every capture:

1. Check ~/self-improving/ exists (First Use if missing)
2. Read ~/self-improving/meta.json
3. Recall duplicate check: Check if memory/ directory exists in the project root. If yes: grep memory/registers/ and CLAUDE.local.md for key terms from the correction. If similar content found: "Recall already has a similar entry in [file]. Store as behavioral rule in ~/self-improving/rules.md anyway?" If memory/ not found: skip check — recall not installed, degrade gracefully.
4. Generalize:
   • Explicit corrections ("correction: ..."): auto-generalize — infer the pattern, state it in the same message: "Capturing rule: [inferred pattern]. Sound right?"
   • Conversational corrections: ask "Is this a general preference or one-off?" before storing
5. Generate rule ID: 8-char hex, prefix with "rule-" (e.g., rule-a1b2c3d4)
6. Write rule block to ~/self-improving/rules.md (append):

## Rule: [short human-readable title]

**ID:** rule-[8-char hex]
**Trigger:** [situation that causes this to matter]
**Action:** [what to do (or avoid) in that situation]
**Source:** [verbatim correction or "reflection YYYY-MM-DD"]
**Created:** YYYY-MM-DD

7. Update meta.json: add entry { "created_at": today, "last_used": today, "use_count": 0, "tier": "rules" }
8. Confirm: "Rule captured: '[title]'. Stored in ~/self-improving/rules.md."

Applying Rules (When a Rule Fires)

When a rule from hot.md or rules.md influences a response:

1. Note the rule ID
2. Read ~/self-improving/meta.json
3. Increment use_count, set last_used to today
4. Check promotion: if tier is "rules" AND use_count >= 3 AND (today - created_at) <= 7 days:
   • Move rule block from rules.md to hot.md
   • Update meta.json: tier → "hot"
   • Inform user: "Rule '[title]' promoted to hot tier (used 3x in 7 days)"
5. Write updated meta.json

Silent acceptance counts as confirmation. If user explicitly corrects a rule, do NOT increment — that correction may spawn a new rule instead.

Full algorithm detail: see references/tier-algorithm.md

Memory Audit

Triggers: "audit memory", "audit rules", "review my rules".

Steps:

1. Read ~/self-improving/meta.json
2. Read ~/self-improving/hot.md and ~/self-improving/rules.md
3. Detect stale hot rules: tier = "hot" AND last_used > 30 days ago
4. Detect orphan entries: meta.json IDs not present in any tier file — flag as orphans
5. Present stale hot rules list (see references/audit-format.md for format)
6. Ask: "Demote to cold? [yes / review each / skip]"
   • "yes": move all stale rule blocks from hot.md to cold.md, update meta.json tier → "cold", confirm count
   • "review each": present one rule at a time with [demote / keep / delete] options
   • "skip": no changes, no file writes
7. If orphans found: "Found [N] orphan entries in meta.json (rules no longer in any file). Clean up? [yes / skip]"
8. Write final meta.json state

Every tier change is reported to the user — no silent moves between files.

Storage Boundary

Write ONLY to ~/self-improving/ files: rules.md, hot.md, cold.md, meta.json, reflections/*.md. NEVER write to memory/, CLAUDE.local.md, or any recall-managed path. Read memory/ only for duplicate check (grep, read-only). Degrade gracefully if memory/ absent.

References

• See references/rule-schema.md for full rule markdown format and meta.json schema details
• See references/tier-algorithm.md for promotion/demotion logic and edge cases
• See references/audit-format.md for memory audit output template and orphan detection