# Self Improving Agent

> Low-noise self-improvement skill. Captures learnings, errors, and corrections into a local `.learnings/` cache layer. Never auto-promotes to long-term memory files (SOUL.md, MEMORY.md, AGENTS.md, TOOLS.md). Promotion requires explicit user approval after repeated validation.

- Skill: `yishu5/self-improving-agent` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add yishu5/self-improving-agent`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yishu5/self-improving-agent/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: YiShu5 (https://skillmd.com/u/yishu5)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/yishu5/self-improving-agent

---


# Self-Improving Agent (Low-Noise Edition)

A conservative self-improvement system that treats `.learnings/` as a write-first
cache layer. Nothing reaches the main system files without human review.

## Quick Reference

| Action | Target | Auto? |
|--------|--------|-------|
| Log a learning | `.learnings/LEARNINGS.md` | Yes |
| Log an error | `.learnings/ERRORS.md` | Yes |
| Log a feature gap | `.learnings/FEATURE_REQUESTS.md` | Yes |
| Promote to MEMORY.md | Requires user approval | No |
| Promote to SOUL.md | Requires user approval + review | No |
| Promote to AGENTS.md | Requires user approval | No |
| Promote to TOOLS.md | Requires user approval | No |

## Core Principles

1. **Write to cache first.** All observations go to `.learnings/`. No exceptions.
2. **Never auto-promote.** The cache is not the system. Promotion is a deliberate act.
3. **SOUL.md is sacred.** Modifications require explicit human review every time.
4. **MEMORY.md is for stable truths.** Only long-term preferences, decisions, and goals belong there.
5. **Errors and learnings stay separate.** Different logs, different purposes.
6. **Silence is better than noise.** If unsure whether something is worth logging, don't log it.
7. **No cross-session broadcasting of raw learnings.** Only promote distilled, verified content.

## Logging Format

### Learning Entry

```markdown
## [YYYY-MM-DD] Category: brief title

- **Type**: correction | knowledge_gap | best_practice
- **Context**: What was happening
- **Learning**: What was learned
- **Confidence**: low | medium | high
- **Promote?**: no (default) | candidate | promoted
```

### Error Entry

```markdown
## [YYYY-MM-DD] brief description

- **Command/Tool**: What failed
- **Error**: The error message or symptom
- **Root Cause**: What actually went wrong
- **Resolution**: How it was fixed
- **Recurrence**: first | repeated
```

### Feature Request Entry

```markdown
## [YYYY-MM-DD] brief description

- **Gap**: What capability is missing
- **User Need**: Why it matters
- **Priority**: low | medium | high
```

## Promotion Gates

A cached item may be promoted to a system file **only** when ALL of these are true:

1. **Repeated** — The same insight has appeared in 2+ separate sessions
2. **Verified** — The insight was confirmed correct (not a one-off misunderstanding)
3. **User-approved** — The user explicitly agrees to promote it
4. **Relevant long-term** — It's not a temporary workaround or context-specific hack

### Promotion Targets

| Content Type | Target File | Extra Requirement |
|---|---|---|
| User preference / long-term decision | MEMORY.md | Stable across sessions |
| Identity / behavior guideline | SOUL.md | **Human review mandatory** |
| Agent capability / role definition | AGENTS.md | Verified in practice |
| Tool usage pattern / integration | TOOLS.md | Tested and confirmed |

### Promotion Process

1. Agent proposes promotion with rationale
2. User reviews the exact content to be written
3. User explicitly approves
4. Agent writes to target file
5. Agent marks the cached entry as `Promote?: promoted`

## Best Practices (Low-Noise)

- Don't log obvious things. "Python needs indentation" is not a learning.
- Don't log things already in the codebase or docs.
- One entry per insight. No walls of text.
- Prefer updating an existing entry over creating a duplicate.
- Review `.learnings/` periodically. Prune stale entries.
- When in doubt, skip the log. You can always add it later.

## OpenClaw Integration

See `references/openclaw-integration.md` for how this skill fits into the
OpenClaw workspace architecture.

### Key Boundaries

```
┌─────────────────────────────────────┐
│  Main System Layer (protected)      │
│  SOUL.md · MEMORY.md · AGENTS.md   │
│  TOOLS.md                           │
│  ← promotion requires approval →    │
├─────────────────────────────────────┤
│  Cache Layer (free-write)           │
│  .learnings/LEARNINGS.md            │
│  .learnings/ERRORS.md               │
│  .learnings/FEATURE_REQUESTS.md     │
└─────────────────────────────────────┘
```