# Self Improve

> Use only when the user explicitly invokes one of the slash commands: `/self-improve capture`, `/self-improve promote`, `/self-improve prune`, `/self-improve review`. Never trigger during code review, normal coding, or end-of-session summaries.

- Skill: `cosmtrek/self-improve` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add cosmtrek/self-improve`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cosmtrek/self-improve/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: cosmtrek (https://skillmd.com/u/cosmtrek)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/cosmtrek/self-improve

---


# Self-Improvement Loop

A cross-agent self-improvement system. Works with Claude Code, Codex, Cursor,
and any agent that reads SKILL.md.

Core loop: **Capture → Promote → Prune → Review**.

## Three-Tier Architecture

```
NOTES.md          Tier 0   raw observations, quick captures
LESSONS.md        Tier 1   validated patterns, domain-specific playbook
AGENTS.md         Tier 2   hard rules, always loaded, ≤100 lines
```

Promotion direction: NOTES → LESSONS → AGENTS.
Each tier is more selective, more abstract, and higher priority.

## Setup

File layout:

```
project-root/
├── AGENTS.md                          # Tier 2: always loaded
└── .agents/self-improve/
    ├── LESSONS.md                     # Tier 1: read on demand
    └── NOTES.md                       # Tier 0: staging area
```

The `.agents/self-improve/` directory is owned by this skill. On first
invocation, create it if missing, plus any missing files inside it with
a one-line heading. No fingerprint is needed for these files — the path
itself is the ownership marker.

Throughout this document, **NOTES.md** and **LESSONS.md** refer to their
fixed paths inside `.agents/self-improve/`.

Each tier has its own structural scope. The skill only reads and writes
content that matches its tier's format:

- **NOTES.md** — entries matching the Phase 1 capture format
  (`### [observe|promote] ...` with a `<!-- captured: YYYY-MM-DD -->`
  footer).
- **LESSONS.md** — bullet points (`- ...`) under `##` section headings
  (Code Style, Testing, API, etc.).

Anything that does not match these shapes — prose, comments, headings
outside the skill's format — is never parsed, moved, or deleted.

### AGENTS.md

AGENTS.md lives at the project root and is never owned as a whole by this
skill. The skill only touches a single fingerprinted block:

```markdown
## Self-Improve
<!-- managed-by: self-improve -->
See `.agents/self-improve/LESSONS.md` for domain-specific patterns.

- <promoted rule 1>
- <promoted rule 2>
```

Rules for this block:

- **Identified by block fingerprint, not heading text.** A project's own
  `## Self-Improve` heading without the fingerprint is out of scope —
  never touched.
- **The only place Phase 2 writes promoted rules and Phase 3 prunes them.**
- **Created on first promotion** with a separate user confirmation. If
  AGENTS.md does not exist, Phase 2 also asks before creating it.
- **Everything else in AGENTS.md is project-owned and read-only.** If a
  promotion candidate overlaps with a project-owned rule outside the block,
  see the merge procedure in Phase 2.

Mirror files (`CLAUDE.md`, `.cursorrules`, `copilot-instructions.md`, …)
are never written to. AGENTS.md is the single source of truth.

---

## Phase 1: Capture → NOTES.md

**Trigger**: `/self-improve capture`.

1. One sentence: **what happened**
2. One sentence: **root cause** (ask "why", not "what")
3. Decide: **record** or **dismiss**?
   - **dismiss** — one-off, not a pattern. Tell user why, do not write
     to NOTES.md, stop here.
   - **record** — continue to step 4.
4. Tag the entry:
   - `[promote]` — clear pattern, recommend moving to LESSONS.md in Phase 2
   - `[observe]` — might be a pattern, keep for now
5. Append to `NOTES.md` with date stamp

Entry format:

```markdown
### [observe] Database calls must be awaited
- **Symptom**: Missing await in userService.ts caused silent failure
- **Root cause**: No lint rule enforcing consumption of async return values
- **Scope**: `src/services/**`
<!-- captured: YYYY-MM-DD -->
```

Constraints:
- Max 5 lines per entry
- Write **behavioral directives** ("must X", "never Y"), not narratives
- Record glob scope when determinable

---

## Phase 2: Promote

**Trigger**: `/self-improve promote`.

Promotion **moves** entries between tiers. Do not leave breadcrumbs like
`[promoted → ...]` in the source file — `git log` is the audit trail.

Two promotion paths, evaluated independently.

### NOTES.md → LESSONS.md

1. Read `NOTES.md`
2. Gather candidates: `[promote]`-tagged entries, plus `[observe]` entries
   with 2+ similar occurrences
3. Abstract: from specific incidents to general principle
4. Present candidates to user, ask for each:

| Action | When |
|--------|------|
| Promote to `LESSONS.md` | Pattern confirmed, domain-specific |
| Stay in notes | Needs more observation |
| Dismiss | Turned out to be noise |

5. On confirm: append to the correct section in `LESSONS.md` (Code Style,
   Testing, API, …), creating the section if it does not yet exist,
   and **delete the entry from NOTES.md**.

### LESSONS.md → AGENTS.md

1. Read `LESSONS.md`
2. Find lessons that apply across the whole project
3. Compression test: **can it be stated in one line?** If yes → candidate
4. Present candidates to user:

| Action | When |
|--------|------|
| Promote to AGENTS.md | Universal, high-impact, one-liner |
| Stay in lessons | Domain-specific or needs context |
| Extract to a skill | Complex enough to be a standalone workflow |
| Merge into existing rule | Says the same thing as an existing rule |

5. On confirm: append the rule to the `## Self-Improve` block in AGENTS.md
   and **delete the entry from LESSONS.md**.

### Merge procedure

When a candidate overlaps with an existing rule, the destination action
depends on where the duplicate lives.

1. **Duplicate in skill-managed space** (LESSONS.md, or the
   `## Self-Improve` block in AGENTS.md). Show both wordings
   side-by-side and ask the user: **keep existing**, **replace with
   candidate**, or **combine**. Apply the choice to the destination,
   then delete the source entry (move semantics).
2. **Duplicate in project-owned AGENTS.md content.** Tell the user the
   rule already exists outside the skill's managed area and recommend
   they update the project-owned rule themselves. Never auto-edit
   project-owned content. **Keep the source entry in place** — the
   skill cannot verify the destination was updated, so deleting it
   would risk silent loss. Offer an explicit **dismiss** action if the
   user wants to drop the source anyway.

---

## Phase 3: Prune

**Trigger**: `/self-improve prune`.

Prune each tier independently.

### AGENTS.md (Tier 2)

Scope: the `## Self-Improve` block only. Never touch content outside it,
even if a rule elsewhere looks redundant or stale. Hard constraint:
≤100 lines inside the block.

| Check | Condition | Action |
|-------|-----------|--------|
| Redundant | Removing it would not cause mistakes | Delete from block |
| Over-detailed | Needs examples to understand | Demote to LESSONS.md |
| Duplicate | Another block rule says the same thing | Merge in place |

### LESSONS.md (Tier 1)

No hard line limit, but each section must earn its place.

| Check | Condition | Action |
|-------|-----------|--------|
| Obsolete | Codebase has changed, no longer applies | Delete |
| Section bloat | One section dominates | Split into a skill |

### NOTES.md (Tier 0)

Aggressive cleanup — this is a staging area, not an archive.

| Check | Condition | Action |
|-------|-----------|--------|
| Stale observe | > 14 days, no second occurrence | Dismiss |

Present the pruning plan, wait for user confirmation, execute,
and report line counts before vs after for all three files.

---

## Phase 4: Review

**Trigger**: `/self-improve review`.

1. Scan the current session for:
   - Corrections the user made
   - Dead ends that required backtracking
   - Repeated attempts before success
2. Run Phase 1 (Capture) on each finding → NOTES.md
3. If NOTES.md has ≥ 2 similar `[observe]` entries, suggest Promote
4. Output summary: N new notes captured, M ready for promotion

---

## Constraints

- NOTES.md entries: ≤ 5 lines each
- AGENTS.md: ≤ 100 lines inside the `## Self-Improve` block (project-owned
  content elsewhere is out of scope and uncounted)
- Every entry must have a date: `<!-- captured: YYYY-MM-DD -->`
- Date stamps use the harness-provided current date (e.g., Claude Code's
  `currentDate` context). If unavailable, ask the user for today's date
  before writing. Never guess or fabricate.
- **All file modifications require user confirmation**
- Write behavioral directives, not narratives
- When promoting to AGENTS.md, compress to one line;
  if impossible, it belongs in LESSONS.md