# self-improving-agent

Adopt this skill: https://proskills.md/skills/other/jamebobob-openclaw-self-improving-agent

Page: https://proskills.md/skills/other/jamebobob-openclaw-self-improving-agent
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 7225
upstream: https://github.com/jamebobob/openclaw-self-improving-agent/blob/HEAD/SKILL.md

````text
---
name: self-improving-agent
description: "Structured logging for recurring mistakes, corrections, and knowledge gaps. Use when the same type of error happens twice, or when you discover a better approach to something you've done before. NOT for one-off fixes or daily notes."
---

# Self-Improvement Skill

Log recurring mistakes, corrections, and knowledge gaps to structured files inside `memory/learnings/`. These files are indexed by the native memory search and complement daily notes (`memory/YYYY-MM-DD.md`) without duplicating them.

## Write Targets

All writes go to `memory/learnings/` only. Four files:

| File | Purpose |
|------|---------|
| `memory/learnings/LEARNINGS.md` | Corrections, knowledge gaps, best practices |
| `memory/learnings/ERRORS.md` | Command failures, tool errors, exceptions |
| `memory/learnings/FEATURE_REQUESTS.md` | Capabilities the maintainer has requested |
| `memory/learnings/PROMOTIONS.md` | Proposals for promoting patterns to boot files |

No other write targets exist. This skill does not write to boot files, config files, or any location outside `memory/learnings/`.

## When to Log

Log when you notice a **pattern**, not a one-off event.

**Detection triggers:**

| Signal | Entry Type | Category |
|--------|-----------|----------|
| The maintainer corrects you ("No, that's wrong...", "Actually...") | Learning | `correction` |
| Your knowledge was outdated or incorrect | Learning | `knowledge_gap` |
| You discover a better approach to a recurring task | Learning | `best_practice` |
| Command/tool returns an error you have seen before | Error | (by tool name) |
| API or external service fails repeatedly | Error | (by service name) |
| The maintainer requests a capability that does not exist | Feature Request | (by capability) |

**When NOT to log:**
- One-off fixes that will not recur
- Facts that belong in daily notes (`memory/YYYY-MM-DD.md`)
- Context that belongs in SESSION-STATE.md
- Anything already captured in a daily note from this session
- Information that belongs in a boot file (route it there instead)

**Workflow interruption rule:** Finish the active task first. Log at natural breakpoints (after a task completes, after a conversation topic changes), not mid-action. Never chain more than 2 tool calls for logging in a single turn.

## How to Log

### Step 1: Search Before Writing

Before adding a new entry, search `memory/learnings/` for similar entries:

```
memory_search("keyword from the issue")
```

Or grep directly:

```
grep -r "keyword" memory/learnings/
```

If a match exists: bump its Priority if warranted, increment Recurrence-Count, update Last-Seen, add a See Also cross-reference. Do NOT create a duplicate.

### Step 2: Write the Entry

Append to the appropriate file. Templates are in this skill's `assets/` directory. Full field reference is in `references/entry-format-reference.md`.

**Entry ID format:** `TYPE-YYYYMMDD-XXX`
- TYPE: `LRN` (learning), `ERR` (error), `FEAT` (feature request), `PROMO` (promotion)
- YYYYMMDD: Today's date
- XXX: Sequential number (001, 002) or random 3 chars (A7B)

**Minimal required fields:**

```markdown
## [LRN-YYYYMMDD-XXX] category

**Logged**: ISO-8601 timestamp
**Priority**: low | medium | high | critical
**Status**: pending
**Area**: (freeform tag)

### Summary
One-line description

### Details
What happened, what was wrong, what is correct

### Metadata
- Source: conversation | error | user_feedback
- Related Files: path/to/file
```

### Step 3: Cross-Reference Daily Notes

If the learning relates to something in today's daily note, add a Related Files link to that note. Do not copy daily note content into the learning.

## Area Tags

Freeform convention list (not a fixed enum): `operations`, `writing`, `research`, `social`, `memory`, `privacy`, `build-process`. Use whatever tag fits. Multiple tags are fine.

## Priority Guidelines

| Priority | When to Use |
|----------|-------------|
| `critical` | Blocks core functionality, data loss risk, security issue |
| `high` | Significant impact, affects common workflows, recurring |
| `medium` | Moderate impact, workaround exists |
| `low` | Minor inconvenience, edge case |

## Entry Lifecycle

### Statuses

`pending` > `in_progress` > `resolved` | `wont_fix` | `promoted` | `archived`

### Resolving an Entry

When fixed, update the entry:

1. Change `**Status**: pending` to `**Status**: resolved`
2. Add a Resolution block:

```markdown
### Resolution
- **Resolved**: ISO-8601 timestamp
- **Notes**: Brief description of what was done
```

## Recurring Pattern Detection

When logging something similar to an existing entry:

1. Link entries with See Also in Metadata
2. Bump priority if the issue keeps recurring
3. If a pattern recurs **3+ times across 2+ distinct tasks**, it qualifies for promotion

## Promotion Workflow

Promotion means proposing that a recurring pattern become a permanent rule. This skill never writes to boot files directly.

**Off-limits targets:** Identity and personality files are off-limits for promotion. Route identity-related insights through your agent's existing identity review process, not through this skill.

### When to Propose

All three conditions must be true:
- Recurrence-Count >= 3
- Seen across at least 2 distinct tasks
- Occurred within a 30-day window

### How to Propose

1. Draft a proposal in `memory/learnings/PROMOTIONS.md` using the template in `assets/PROMOTIONS-TEMPLATE.md`
2. Set the source entry status to `promoted`
3. Notify the maintainer through your preferred direct channel (not group chats) with the proposal title and a one-sentence summary
4. Wait for the maintainer's explicit written approval before any changes are made elsewhere

The maintainer applies changes manually. The proposal is a recommendation, not an action.

## Periodic Review

During your regular review cycle, also review `memory/learnings/` for:
- Resolved entries that can be archived
- Pending entries that are stale (>30 days with no activity)
- Patterns across entries that warrant a promotion proposal
- Entries that duplicate daily note content (delete the duplicate)

One pass through the four files is sufficient. Note findings in the daily note under the review section.

## Archiving

When total file size across `memory/learnings/` (excluding archive/) exceeds 10,000 characters:

1. Move resolved and wont_fix entries older than 30 days to `memory/learnings/archive/YYYY-MM/`
2. Set their status to `archived`
3. Preserve the entry ID so cross-references remain valid

## Memory Layer Boundary

| Layer | Location | Contains | Format |
|-------|----------|----------|--------|
| Daily notes | `memory/YYYY-MM-DD.md` | Raw chronological log | Timestamped narrative |
| Learnings | `memory/learnings/` | Structured patterns | ID'd entries with metadata |
| Long-term | `MEMORY.md` | Curated current state | Prose summaries |

Daily notes record what happened. Learnings record what to do differently. Cross-reference via Related Files. Never duplicate content across layers.

## References

- Entry templates: `assets/` directory in this skill
- Full field descriptions: `references/entry-format-reference.md`
- Worked examples: `references/examples.md`
````

## File: README.md
upstream: https://github.com/jamebobob/openclaw-self-improving-agent/blob/HEAD/README.md

````text
> **Archived April 2026.** Built on [OpenClaw](https://github.com/openclaw/openclaw) and moved off of it when the active work migrated to [Hermes](https://github.com/hermes-agent/hermes-agent). The design ideas in this repo might still be useful. The platform wiring is obsolete.

# openclaw-self-improving-agent

Structured logging for recurring mistakes, corrections, and knowledge gaps. Designed for non-coding OpenClaw agents: operations assistants, writing agents, social agents, research agents.

Use when the same type of error happens twice, or when you discover a better approach to something you've done before. NOT for one-off fixes or daily notes.

## What It Does

Four structured log files in `memory/learnings/`:

| File | Purpose |
|------|---------|
| `LEARNINGS.md` | Corrections, knowledge gaps, best practices |
| `ERRORS.md` | Command failures, tool errors, exceptions |
| `FEATURE_REQUESTS.md` | Capabilities requested by the maintainer |
| `PROMOTIONS.md` | Proposals for promoting patterns to boot files |

Files live inside `memory/` so the native OpenClaw memory indexer picks them up automatically. No `extraPaths` config needed, no separate indexing step.

### Key behaviors

- **Search before write.** Before adding a new entry, search for similar existing entries. Bump recurrence count instead of duplicating.
- **Finish the task first.** Log at natural breakpoints, not mid-action. Never chain more than 2 tool calls for logging in a single turn.
- **Promotion requires approval.** When a pattern recurs 3+ times across 2+ tasks, the agent drafts a proposal. The maintainer reviews and applies changes manually. The agent never writes to boot files directly.
- **Identity files are off-limits.** Identity and personality files are never valid promotion targets. Identity-related insights follow the agent's existing identity review process.

## Who It's For

Agents that aren't primarily coding but still need structured self-improvement:

- **Operations agents** managing servers, crons, deployments
- **Writing agents** publishing blog posts, social content
- **Social agents** participating in group chats
- **Research agents** scouting and analyzing information

The upstream skill ([peterskoett/self-improving-agent](https://github.com/peterskoett/self-improving-agent)) is designed for coding workflows with hooks, shell scripts, and code-centric area tags. This is a clean rewrite for agents that operate, write, and communicate rather than code.

## What's Different from Upstream

This is a clean rewrite, not a fork. Inspired by [peterskoett/self-improving-agent](https://github.com/peterskoett/self-improving-agent) (MIT-0).

### Issues addressed

| Upstream issue | Fix |
|---------------|-----|
| [#5](https://github.com/peterskoett/self-improving-agent/issues/5): Infinite tool call loops from broad triggers and "promote aggressively" | Max 2 tool calls per logging turn, "finish the task first" rule, promotion requires 3+ recurrences |
| [#9](https://github.com/peterskoett/self-improving-agent/issues/9): Hook installation fails | Zero hooks, zero scripts, zero executable files |
| Boot file writes via promotion | Promotion drafts proposals only; maintainer applies changes manually; identity files permanently off-limits |
| `.learnings/` not indexed by native memory search | Files in `memory/learnings/` (inside the indexed tree, not dot-prefixed) |

### What's kept

Entry ID format (`TYPE-YYYYMMDD-XXX`), all metadata fields (Priority, Status, Area, See Also, Pattern-Key, Recurrence-Count, First-Seen, Last-Seen), resolution workflow, recurring pattern detection, detection triggers, priority guidelines.

### What's removed

Hook system (buggy, caused loops), shell scripts (security risk), skill extraction workflow (over-engineered for non-coding agents), multi-platform support sections, "promote aggressively" directive, coding-centric area tags.

### What's added

PROMOTIONS.md (fourth log file with approval gate), archiving workflow, memory layer boundary documentation, freeform area tags for non-coding domains.

## Installation

### 1. Copy to your workspace skills directory

```bash
git clone https://github.com/jamebobob/openclaw-self-improving-agent.git
cp -r openclaw-self-improving-agent ~/.openclaw/workspace/skills/self-improving-agent
```

### 2. Create the learnings directory

```bash
mkdir -p ~/.openclaw/workspace/memory/learnings
```

### 3. Verify the skill loads

Restart your OpenClaw gateway, then check that the skill appears:

```bash
openclaw status
```

The skill description should show in the loaded skills list.

## File Tree

```
self-improving-agent/
  SKILL.md                          # Core skill (loaded by OpenClaw)
  assets/
    LEARNINGS-TEMPLATE.md           # Entry template for learnings
    ERRORS-TEMPLATE.md              # Entry template for errors
    FEATURE-REQUESTS-TEMPLATE.md    # Entry template for feature requests
    PROMOTIONS-TEMPLATE.md          # Entry template for promotion proposals
  references/
    examples.md                     # Worked examples of well-formatted entries
    entry-format-reference.md       # Complete field descriptions
```

## How It Works

1. **Detection:** The agent notices a pattern (correction, recurring error, knowledge gap, feature request)
2. **Search:** Checks `memory/learnings/` for existing entries on the same topic
3. **Log or bump:** Creates a new entry or increments Recurrence-Count on an existing one
4. **Review:** During regular review cycles, the agent checks for stale entries, patterns worth promoting, and entries to archive
5. **Promote:** When a pattern hits 3+ occurrences across 2+ tasks, the agent drafts a proposal and notifies the maintainer
6. **Apply:** The maintainer reviews the proposal and manually applies changes to boot files

## Design Decisions

**1,023 words in SKILL.md.** OpenClaw injects SKILL.md into the system prompt when the skill is invoked. Every word costs tokens. Operational instructions only. Examples and field reference moved to `references/`.

**`memory/learnings/` path.** The native memory indexer scans `memory/**/*.md`. Placing learnings inside `memory/` means they're indexed automatically with no config change. The upstream's `.learnings/` (dot-prefixed, at workspace root) falls outside the indexed path.

**Four files, not three.** PROMOTIONS.md is this skill's addition. It replaces the upstream's direct boot-file writes with an approval-gated proposal queue. The maintainer reviews and applies changes, not the agent.

**No hooks, no scripts.** Zero executable files. The upstream's hook system caused infinite tool call loops ([#5](https://github.com/peterskoett/self-improving-agent/issues/5)) and failed to install ([#9](https://github.com/peterskoett/self-improving-agent/issues/9)). Detection is prompt-driven, not hook-driven.

## License

MIT-0. See [LICENSE](LICENSE).

## Lineage

Inspired by [peterskoett/self-improving-agent](https://github.com/peterskoett/self-improving-agent) (MIT-0). Clean rewrite, not a fork. Entry formats and metadata fields are compatible with the upstream.
````
