技能/ #agents/ #self-improvement

self-improving agent

Captures learnings, errors, and corrections to enable continuous improvement for the agent.

pskoett@pskoett

安装

针对本地咔咔镜像运行此命令。

请从本地咔咔镜像安装 self-improving-agent,注册表地址为 http://localhost:13001。安装后先检查 README、清单和权限,再在当前工作区使用。下载

说明

--- name: self-improving-agent description: "Captures learnings, errors, and corrections to enable continuous improvement. Use when: (1) A command or operation fails unexpectedly, (2) User corrects Claude ('No, that's wrong...', 'Actually...'), (3) User requests a capability that doesn't exist, (4) An external API or tool fails, (5) Claude realizes its knowledge is outdated or incorrect, (6) A better approach is discovered for a recurring task. Also review learnings before major tasks." version: "4.0.0" metadata: ---

Self-Improvement Skill

Log learnings and errors to markdown files for continuous improvement. Agents can later process these into fixes, and important learnings get promoted to workspace memory. This version of the skill is built for OpenClaw only — for other agents, see the original multi-agent version at https://github.com/pskoett/pskoett-ai-skills.

First-Use Initialisation

Before logging anything, ensure the `.learnings/` directory and files exist in the project or workspace root. If any are missing, create them:

bashmkdir -p .learnings
[ -f .learnings/LEARNINGS.md ] || printf "# Learnings\n\nCorrections, insights, and knowledge gaps captured during development.\n\n**Categories**: correction | insight | knowledge_gap | best_practice\n\n---\n" > .learnings/LEARNINGS.md
[ -f .learnings/ERRORS.md ] || printf "# Errors\n\nCommand failures and integration errors.\n\n---\n" > .learnings/ERRORS.md
[ -f .learnings/FEATURE_REQUESTS.md ] || printf "# Feature Requests\n\nCapabilities requested by the user.\n\n---\n" > .learnings/FEATURE_REQUESTS.md

Never overwrite existing files. This is a no-op if `.learnings/` is already initialised.

Do not log secrets, tokens, private keys, environment variables, or full source/config files unless the user explicitly asks for that level of detail. Prefer short summaries or redacted excerpts over raw command output or full transcripts.

If you want automatic reminders and session-end error detection, enable the opt-in hook described in [Optional: Enable Hook](#optional-enable-hook).

Quick Reference

| Situation | Action | |-----------|--------| | Command/operation fails | Log to `.learnings/ERRORS.md` | | User corrects you | Log to `.learnings/LEARNINGS.md` with category `correction` | | User wants missing feature | Log to `.learnings/FEATURE_REQUESTS.md` | | API/external tool fails | Log to `.learnings/ERRORS.md` with integration details | | Knowledge was outdated | Log to `.learnings/LEARNINGS.md` with category `knowledge_gap` | | Found better approach | Log to `.learnings/LEARNINGS.md` with category `best_practice` | | Simplify/Harden recurring patterns | Log/update `.learnings/LEARNINGS.md` with `Source: simplify-and-harden` and a stable `Pattern-Key` | | Similar to existing entry | Grep by `Pattern-Key` first, link with `**See Also**`, bump `Recurrence-Count` | | Workflow improvements | Promote to `AGENTS.md` (workspace) | | Tool gotchas | Promote to `TOOLS.md` (workspace) | | Behavioral patterns | Promote to `SOUL.md` (workspace) |

OpenClaw Setup

OpenClaw uses workspace-based prompt injection with automatic skill loading.

Installation

**Via ClawdHub (recommended):**

bashclawdhub install self-improving-agent

**Manual** (the skill lives in the repo's `self-improving-agent/` subfolder; copy that folder, not the repo root):

bashgit clone https://github.com/peterskoett/self-improving-agent.git /tmp/self-improving-agent-repo
cp -r /tmp/self-improving-agent-repo/self-improving-agent ~/.openclaw/skills/self-improving-agent

Remade for openclaw from original repo : https://github.com/pskoett/pskoett-ai-skills - https://github.com/pskoett/pskoett-ai-skills/tree/main/skills/self-improvement

Workspace Structure

OpenClaw injects these files into every session:

~/.openclaw/workspace/ ├── AGENTS.md # Multi-agent workflows, delegation patterns ├── SOUL.md # Behavioral guidelines, personality, principles ├── TOOLS.md # Tool capabilities, integration gotchas ├── MEMORY.md # Long-term memory (main session only) ├── memory/ # Daily memory files │ └── YYYY-MM-DD.md └── .learnings/ # This skill's log files ├── LEARNINGS.md ├── ERRORS.md └── FEATURE_REQUESTS.md

Create Learning Files

bashmkdir -p ~/.openclaw/workspace/.learnings

Then create the log files (or copy from `assets/`):

  • `LEARNINGS.md` — corrections, knowledge gaps, best practices
  • `ERRORS.md` — command failures, exceptions
  • `FEATURE_REQUESTS.md` — user-requested capabilities

Promotion Targets

When learnings prove broadly applicable, promote them to workspace files:

| Learning Type | Promote To | Example | |---------------|------------|---------| | Behavioral patterns | `SOUL.md` | "Be concise, avoid disclaimers" | | Workflow improvements | `AGENTS.md` | "Spawn sub-agents for long tasks" | | Tool gotchas | `TOOLS.md` | "Git push needs auth configured first" |

Inter-Session Communication

OpenClaw provides tools to share learnings across sessions:

  • **sessions_list** — View active/recent sessions
  • **sessions_history** — Read another session's transcript
  • **sessions_send** — Send a learning to another session
  • **sessions_spawn** — Spawn a sub-agent for background work

Use these only in trusted environments and only when the user explicitly wants cross-session sharing. Prefer sending a short sanitized summary and relevant file paths, not raw transcripts, secrets, or full command output.

Optional: Enable Hook

For automatic reminders at session start and error detection at session end:

bashcp -r ~/.openclaw/skills/self-improving-agent/hooks/openclaw ~/.openclaw/hooks/self-improvement
openclaw hooks enable self-improvement

Fires on `agent:bootstrap` (injects the reminder, plus a pending-triage note when auto-detected errors await review) and on `command:new`/`command:reset` (sweeps the ended session's transcript for error patterns into `<workspace>/.learnings/ERRORS.md`; opt-in — runs only when `.learnings/` exists). OpenClaw has no per-tool-call hook event, so error detection happens at session end. See `references/openclaw-integration.md` for details and sweep limitations.

Logging Format

Learning Entry

Append to `.learnings/LEARNINGS.md`:

markdown## [LRN-YYYYMMDD-XXX] category

**Logged**: ISO-8601 timestamp
**Priority**: low | medium | high | critical
**Status**: pending
**Area**: frontend | backend | infra | tests | docs | config

### Summary
One-line description of what was learned

### Details
Full context: what happened, what was wrong, what's correct

### Suggested Action
Specific fix or improvement to make

### Metadata
- Source: conversation | error | user_feedback
- Related Files: path/to/file.ext
- Tags: tag1, tag2
- See Also: LRN-20250110-001 (if related to existing entry)
- Pattern-Key: area.symptom (recommended; e.g. deps.module-not-found, simplify.dead_code — see Pattern-Key Taxonomy)
- Recurrence-Count: 1 (optional)
- First-Seen: 2025-01-15 (optional)
- Last-Seen: 2025-01-15 (optional)

---

Error Entry

Append to `.learnings/ERRORS.md`:

markdown## [ERR-YYYYMMDD-XXX] skill_or_command_name

**Logged**: ISO-8601 timestamp
**Priority**: high
**Status**: pending
**Area**: frontend | backend | infra | tests | docs | config

### Summary
Brief description of what failed

### Error

Actual error message or output

Context

  • Command/operation attempted
  • Input or parameters used
  • Environment details if relevant
  • Summary or redacted excerpt of relevant output (avoid full transcripts and secret-bearing data by default)

Suggested Fix

If identifiable, what might resolve this

Metadata

  • Reproducible: yes | no | unknown
  • Related Files: path/to/file.ext
  • See Also: ERR-20250110-001 (if recurring)
  • Pattern-Key: area.symptom (recommended; e.g. net.connection-refused — see Pattern-Key Taxonomy)
  • Recurrence-Count: 1 (optional)
  • First-Seen: 2025-01-15 (optional)
  • Last-Seen: 2025-01-15 (optional)

---

Feature Request Entry

Append to `.learnings/FEATURE_REQUESTS.md`:

markdown## [FEAT-YYYYMMDD-XXX] capability_name

**Logged**: ISO-8601 timestamp
**Priority**: medium
**Status**: pending
**Area**: frontend | backend | infra | tests | docs | config

### Requested Capability
What the user wanted to do

### User Context
Why they needed it, what problem they're solving

### Complexity Estimate
simple | medium | complex

### Suggested Implementation
How this could be built, what it might extend

### Metadata
- Frequency: first_time | recurring
- Related Features: existing_feature_name
- Pattern-Key: area.symptom (optional — features usually dedupe by capability name; use a key only for recurring themes, e.g. api.missing-endpoint)

---

ID Generation

Format: `TYPE-YYYYMMDD-XXX`

  • TYPE: `LRN` (learning), `ERR` (error), `FEAT` (feature)
  • YYYYMMDD: Current date
  • XXX: Sequential number or random 3 chars (e.g., `001`, `A7B`)

Examples: `LRN-20250115-001`, `ERR-20250115-A3F`, `FEAT-20250115-002`

Resolving Entries

When an issue is fixed, update the entry:

1. Change `**Status**: pending` → `**Status**: resolved` 2. Add resolution block after Metadata:

markdown### Resolution
- **Resolved**: 2025-01-16T09:00:00Z
- **Commit/PR**: abc123 or #42
- **Notes**: Brief description of what was done

Other status values:

  • `in_progress` - Actively being worked on
  • `wont_fix` - Decided not to address (add reason in Resolution notes)
  • `promoted` - Elevated to a workspace file (`SOUL.md`, `TOOLS.md`, `AGENTS.md`)

Promoting to Workspace Memory

When a learning is broadly applicable (not a one-off fix), promote it to a workspace file so every session inherits it.

When to Promote

  • Learning applies across multiple files/features
  • Knowledge any contributor (human or AI) should know
  • Prevents recurring mistakes
  • Documents project-specific conventions

Promotion Targets

| Target | What Belongs There | |--------|-------------------| | `SOUL.md` | Behavioral guidelines, communication style, principles | | `TOOLS.md` | Tool capabilities, usage patterns, integration gotchas | | `AGENTS.md` | Workflows, delegation patterns, automation rules |

When the learning is specific to a project repo you work in (not the workspace), promote to that project's own agent file (e.g. its `AGENTS.md`) instead.

How to Promote

1. **Distill** the learning into a concise rule or fact 2. **Add** to appropriate section in target file (create file if needed) 3. **Update** original entry:

  • Change `**Status**: pending` → `**Status**: promoted`
  • Add `**Promoted**: SOUL.md`, `TOOLS.md`, or `AGENTS.md`

Promotion Examples

**Learning** (verbose): > Project uses pnpm workspaces. Attempted `npm install` but failed. > Lock file is `pnpm-lock.yaml`. Must use `pnpm install`.

**In TOOLS.md** (concise):

markdown## Build & Dependencies
- Package manager: pnpm (not npm) - use `pnpm install`

**Learning** (verbose): > When modifying API endpoints, must regenerate TypeScript client. > Forgetting this causes type mismatches at runtime.

**In AGENTS.md** (actionable):

markdown## After API Changes
1. Regenerate client: `pnpm run generate:api`
2. Check for type errors: `pnpm tsc --noEmit`

Pattern-Key Taxonomy

`Pattern-Key` is the stable dedup and recurrence key for entries in all three log files: keyword grep misses semantically identical but differently-worded entries, a shared key does not — and reliable keys are what make `Recurrence-Count` and the promotion rule work.

**Format**: `area.symptom` — exactly two levels, lowercase, hyphenated (e.g. `deps.module-not-found`). Keep symptoms generic enough to recur: no file names, versions, or hostnames in keys.

| Area | Scope | Example Keys | |------|-------|--------------| | `api` | External API/service behavior | `api.rate-limit`, `api.schema-mismatch`, `api.missing-endpoint` | | `auth` | Credentials, tokens, scopes | `auth.token-expired`, `auth.missing-scope` | | `build` | Compilation, bundling, CI | `build.type-error`, `build.missing-artifact` | | `config` | Config files, env vars, settings | `config.missing-env`, `config.invalid-json` | | `deps` | Package managers, dependencies | `deps.module-not-found`, `deps.npm-error`, `deps.version-conflict` | | `fs` | Filesystem | `fs.no-such-file`, `fs.permission-denied` | | `net` | Network connectivity | `net.connection-refused`, `net.timeout` | | `runtime` | Language/runtime errors not covered above | `runtime.type-error`, `runtime.python-exception` | | `shell` | Shell/CLI mechanics | `shell.command-not-found`, `shell.nonzero-exit` | | `vcs` | Git and other version control | `vcs.fatal-error`, `vcs.merge-conflict` | | `simplify` / `harden` | Code-quality patterns from the simplify-and-harden feed | `simplify.dead_code`, `harden.input_validation` |

**Rules:**

1. **Reuse before minting**: `grep -rh "Pattern-Key:" .learnings/ | sort -u` — a near-match beats a new key. 2. **One key per manual entry**; auto-swept OpenClaw entries may carry several — reduce to one when triaging. 3. **Mint new areas sparingly** — only when several entries would share one. 4. **Generic sweep keys** (`runtime.error`, `runtime.failure`) mean "unclassified" — replace with a specific key during triage.

Recurring Pattern Detection

If logging something similar to an existing entry:

1. **Search by key first**: `grep -n "Pattern-Key: area.symptom" .learnings/*.md` — this is the default dedup check and catches rewordings that keyword search misses 2. **Fallback keyword search**: `grep -ri "keyword" .learnings/` for entries logged without a key 3. **Fold, don't duplicate**: on a hit, update the existing entry — bump `Recurrence-Count`, set `Last-Seen`, add `**See Also**` — instead of creating a new one 4. **Bump priority** if issue keeps recurring 5. **Consider systemic fix**: Recurring issues often indicate:

  • Missing knowledge (→ promote to `TOOLS.md` or `SOUL.md`)
  • Missing automation (→ add to `AGENTS.md`)
  • Architectural problem (→ create tech debt ticket)

Simplify & Harden Feed

Use this workflow to ingest recurring patterns from the `simplify-and-harden` skill and turn them into durable prompt guidance.

Ingestion Workflow

1. Read `simplify_and_harden.learning_loop.candidates` from the task summary. 2. For each candidate, use `pattern_key` as the stable dedupe key. 3. Search `.learnings/LEARNINGS.md` for an existing entry with that key:

4. If found:

5. If not found:

  • `grep -n "Pattern-Key: <pattern_key>" .learnings/LEARNINGS.md`
  • Increment `Recurrence-Count`
  • Update `Last-Seen`
  • Add `See Also` links to related entries/tasks
  • Create a new `LRN-...` entry
  • Set `Source: simplify-and-harden`
  • Set `Pattern-Key`, `Recurrence-Count: 1`, and `First-Seen`/`Last-Seen`

Promotion Rule (System Prompt Feedback)

Promote recurring patterns into agent context/system prompt files when all are true:

  • `Recurrence-Count >= 3`
  • Seen across at least 2 distinct tasks
  • Occurred within a 30-day window

Promotion targets: `SOUL.md`, `TOOLS.md`, or `AGENTS.md` (workspace), or the project's own agent file when the pattern is project-specific.

Write promoted rules as short prevention rules (what to do before/while coding), not long incident write-ups.

Periodic Review

Review `.learnings/` at natural breakpoints:

When to Review

  • Before starting a new major task
  • After completing a feature
  • When working in an area with past learnings
  • Weekly during active development

Quick Status Check

bash# Count pending items
grep -h "Status\*\*: pending" .learnings/*.md | wc -l

# List pending high-priority items
grep -B5 "Priority\*\*: high" .learnings/*.md | grep "^## \["

# Find learnings for a specific area
grep -l "Area\*\*: backend" .learnings/*.md

Review Actions

  • Resolve fixed items
  • Promote applicable learnings
  • Link related entries
  • Escalate recurring issues

Detection Triggers

Automatically log when you notice:

**Corrections** (→ learning with `correction` category):

  • "No, that's not right..."
  • "Actually, it should be..."
  • "You're wrong about..."
  • "That's outdated..."

**Feature Requests** (→ feature request):

  • "Can you also..."
  • "I wish you could..."
  • "Is there a way to..."
  • "Why can't you..."

**Knowledge Gaps** (→ learning with `knowledge_gap` category):

  • User provides information you didn't know
  • Documentation you referenced is outdated
  • API behavior differs from your understanding

**Errors** (→ error entry):

  • Command returns non-zero exit code
  • Exception or stack trace
  • Unexpected output or behavior
  • Timeout or connection failure

Priority Guidelines

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

Area Tags

Use to filter learnings by codebase region:

| Area | Scope | |------|-------| | `frontend` | UI, components, client-side code | | `backend` | API, services, server-side code | | `infra` | CI/CD, deployment, Docker, cloud | | `tests` | Test files, testing utilities, coverage | | `docs` | Documentation, comments, READMEs | | `config` | Configuration files, environment, settings |

Best Practices

1. **Log immediately** - context is freshest right after the issue 2. **Be specific** - future agents need to understand quickly 3. **Include reproduction steps** - especially for errors 4. **Link related files** - makes fixes easier 5. **Suggest concrete fixes** - not just "investigate" 6. **Use consistent categories** - enables filtering 7. **Promote aggressively** - if in doubt, add to `TOOLS.md` or `SOUL.md` 8. **Review regularly** - stale learnings lose value

Gitignore Options

**Keep learnings local** (per-developer):

gitignore.learnings/

This repo uses that default to avoid committing sensitive or noisy local logs by accident.

**Track learnings in repo** (team-wide): Don't add to .gitignore - learnings become shared knowledge.

**Hybrid** (track templates, ignore entries):

gitignore.learnings/*.md
!.learnings/.gitkeep

Upgrading & Uninstalling

Read `CHANGELOG.md` before upgrading — it carries per-version notes, and hook changes require re-copying the hook and restarting the gateway. To disable or remove the skill, follow `references/uninstall.md`: `.learnings/` is user data (review before deleting), and content promoted to `SOUL.md`/`TOOLS.md`/`AGENTS.md` stays until removed manually.

Automatic Skill Extraction

When a learning is valuable enough to become a reusable skill, extract it using the provided helper.

Skill Extraction Criteria

A learning qualifies for skill extraction when ANY of these apply:

| Criterion | Description | |-----------|-------------| | **Recurring** | Has `See Also` links to 2+ similar issues | | **Verified** | Status is `resolved` with working fix | | **Non-obvious** | Required actual debugging/investigation to discover | | **Broadly applicable** | Not project-specific; useful across codebases | | **User-flagged** | User says "save this as a skill" or similar |

Extraction Workflow

1. **Identify candidate**: Learning meets extraction criteria 2. **Run helper** (or create manually):

bash   ~/.openclaw/skills/self-improving-agent/scripts/extract-skill.sh skill-name --dry-run
   ~/.openclaw/skills/self-improving-agent/scripts/extract-skill.sh skill-name

3. **Customize SKILL.md**: Fill in template with learning content 4. **Update learning**: Set status to `promoted_to_skill`, add `Skill-Path` 5. **Verify**: Read skill in fresh session to ensure it's self-contained

Manual Extraction

If you prefer manual creation:

1. Create `skills/<skill-name>/SKILL.md` 2. Use template from `assets/SKILL-TEMPLATE.md` 3. Follow [Agent Skills spec](https://agentskills.io/specification):

  • YAML frontmatter with `name` and `description`
  • Name must match folder name
  • No README.md inside skill folder

Extraction Detection Triggers

Watch for these signals that a learning should become a skill:

**In conversation:**

  • "Save this as a skill"
  • "I keep running into this"
  • "This would be useful for other projects"
  • "Remember this pattern"

**In learning entries:**

  • Multiple `See Also` links (recurring issue)
  • High priority + resolved status
  • Category: `best_practice` with broad applicability
  • User feedback praising the solution

Skill Quality Gates

Before extraction, verify:

  • [ ] Solution is tested and working
  • [ ] Description is clear without original context
  • [ ] Code examples are self-contained
  • [ ] No project-specific hardcoded values
  • [ ] Follows skill naming conventions (lowercase, hyphens)

安装解析

{
  "artifact": {
    "downloadUrl": "/api/v1/download?slug=self-improving-agent&version=4.0.1&ownerHandle=pskoett",
    "format": "zip",
    "generated": true,
    "kind": "skillArchive",
    "sha256": "6980664729dfd1c7fdda7eb05d458ccc94814b086d11d2fde714028a3c149d7e",
    "size": 22330
  },
  "owner": {
    "displayName": "pskoett",
    "handle": "pskoett",
    "id": "87a218b0-a0d3-4a0a-99b4-347a4b9c0150",
    "verified": false
  },
  "skill": {
    "displayName": "self-improving agent",
    "latestVersion": "4.0.1",
    "license": "MIT-0",
    "name": "self-improving-agent",
    "ownerHandle": "pskoett",
    "slug": "self-improving-agent",
    "stats": {
      "downloads": 465851,
      "installs": 18337,
      "stars": 3890
    },
    "summary": "Captures learnings, errors, and corrections to enable continuous improvement for the agent.",
    "tags": [
      "agents",
      "self-improvement"
    ],
    "type": "skill",
    "updatedAt": "2026-07-06T10:48:11.423Z"
  },
  "sourceHandoff": null,
  "version": {
    "checksum": null,
    "checksumAlgorithm": null,
    "id": "73a8618b-913d-4475-879e-93a778d2978f",
    "publishedAt": "2026-07-05T13:28:03.853Z",
    "size": null,
    "version": "4.0.1",
    "artifactStorageKey": null,
    "changelog": "**Automatic error detection**: the hook now sweeps each ended session's\n  transcript (`/new` / `/reset`) for error patterns and logs pending,\n  redacted entries to `.learnings/ERRORS.md` — no agent discipline needed.\n  Opt-in: create `~/.openclaw/workspace/.learnings` to enable.\n- **Pattern-Key dedup**: every entry carries a stable `area.symptom` key\n  (e.g. `deps.module-not-found`) under a controlled taxonomy; auto-detected\n  errors are stamped automatically, making recurrence counting and\n  promotion (to `SOUL.md` / `TOOLS.md` / `AGENTS.md`) reliable.\n- **Triage loop**: the bootstrap reminder flags auto-detected errors\n  awaiting review at the start of each session.\n- **Now OpenClaw-only**: leaner skill prompt; for Claude Code/Codex/Copilot\n  use the original multi-agent version (pskoett/pskoett-ai-skills).\n- Added versioned CHANGELOG with upgrade notes, uninstall guide, test\n  suite + CI, and a clean skill package layout for ClawdHub.\n\n**Upgrading**: re-copy the hook\n(`cp -r ~/.openclaw/skills/self-improving-agent/hooks/openclaw ~/.openclaw/hooks/self-improvement`)\nand restart the gateway. `.learnings/` data is never touched by upgrades.",
    "manifest": {
      "clawhub": {
        "tags": {
          "latest": "4.0.1"
        },
        "owner": "pskoett",
        "stats": {
          "stars": 3890,
          "comments": 53,
          "installs": 18337,
          "versions": 38,
          "downloads": 465851
        },
        "topics": [
          "self-improvement"
        ],
        "categories": [
          "agents"
        ]
      },
      "install": "openclaw skills install @pskoett/self-improving-agent"
    },
    "readme": "---\nname: self-improving-agent\ndescription: \"Captures learnings, errors, and corrections to enable continuous improvement. Use when: (1) A command or operation fails unexpectedly, (2) User corrects Claude ('No, that's wrong...', 'Actually...'), (3) User requests a capability that doesn't exist, (4) An external API or tool fails, (5) Claude realizes its knowledge is outdated or incorrect, (6) A better approach is discovered for a recurring task. Also review learnings before major tasks.\"\nversion: \"4.0.0\"\nmetadata:\n---\n\n# Self-Improvement Skill\n\nLog learnings and errors to markdown files for continuous improvement. Agents can later process these into fixes, and important learnings get promoted to workspace memory. This version of the skill is built for OpenClaw only — for other agents, see the original multi-agent version at https://github.com/pskoett/pskoett-ai-skills.\n\n## First-Use Initialisation\n\nBefore logging anything, ensure the `.learnings/` directory and files exist in the project or workspace root. If any are missing, create them:\n\n```bash\nmkdir -p .learnings\n[ -f .learnings/LEARNINGS.md ] || printf \"# Learnings\\n\\nCorrections, insights, and knowledge gaps captured during development.\\n\\n**Categories**: correction | insight | knowledge_gap | best_practice\\n\\n---\\n\" > .learnings/LEARNINGS.md\n[ -f .learnings/ERRORS.md ] || printf \"# Errors\\n\\nCommand failures and integration errors.\\n\\n---\\n\" > .learnings/ERRORS.md\n[ -f .learnings/FEATURE_REQUESTS.md ] || printf \"# Feature Requests\\n\\nCapabilities requested by the user.\\n\\n---\\n\" > .learnings/FEATURE_REQUESTS.md\n```\n\nNever overwrite existing files. This is a no-op if `.learnings/` is already initialised.\n\nDo not log secrets, tokens, private keys, environment variables, or full source/config files unless the user explicitly asks for that level of detail. Prefer short summaries or redacted excerpts over raw command output or full transcripts.\n\nIf you want automatic reminders and session-end error detection, enable the opt-in hook described in [Optional: Enable Hook](#optional-enable-hook).\n\n## Quick Reference\n\n| Situation | Action |\n|-----------|--------|\n| Command/operation fails | Log to `.learnings/ERRORS.md` |\n| User corrects you | Log to `.learnings/LEARNINGS.md` with category `correction` |\n| User wants missing feature | Log to `.learnings/FEATURE_REQUESTS.md` |\n| API/external tool fails | Log to `.learnings/ERRORS.md` with integration details |\n| Knowledge was outdated | Log to `.learnings/LEARNINGS.md` with category `knowledge_gap` |\n| Found better approach | Log to `.learnings/LEARNINGS.md` with category `best_practice` |\n| Simplify/Harden recurring patterns | Log/update `.learnings/LEARNINGS.md` with `Source: simplify-and-harden` and a stable `Pattern-Key` |\n| Similar to existing entry | Grep by `Pattern-Key` first, link with `**See Also**`, bump `Recurrence-Count` |\n| Workflow improvements | Promote to `AGENTS.md` (workspace) |\n| Tool gotchas | Promote to `TOOLS.md` (workspace) |\n| Behavioral patterns | Promote to `SOUL.md` (workspace) |\n\n## OpenClaw Setup\n\nOpenClaw uses workspace-based prompt injection with automatic skill loading.\n\n### Installation\n\n**Via ClawdHub (recommended):**\n```bash\nclawdhub install self-improving-agent\n```\n\n**Manual** (the skill lives in the repo's `self-improving-agent/` subfolder;\ncopy that folder, not the repo root):\n```bash\ngit clone https://github.com/peterskoett/self-improving-agent.git /tmp/self-improving-agent-repo\ncp -r /tmp/self-improving-agent-repo/self-improving-agent ~/.openclaw/skills/self-improving-agent\n```\n\nRemade for openclaw from original repo : https://github.com/pskoett/pskoett-ai-skills - https://github.com/pskoett/pskoett-ai-skills/tree/main/skills/self-improvement\n\n### Workspace Structure\n\nOpenClaw injects these files into every session:\n\n```\n~/.openclaw/workspace/\n├── AGENTS.md          # Multi-agent workflows, delegation patterns\n├── SOUL.md            # Behavioral guidelines, personality, principles\n├── TOOLS.md           # Tool capabilities, integration gotchas\n├── MEMORY.md          # Long-term memory (main session only)\n├── memory/            # Daily memory files\n│   └── YYYY-MM-DD.md\n└── .learnings/        # This skill's log files\n    ├── LEARNINGS.md\n    ├── ERRORS.md\n    └── FEATURE_REQUESTS.md\n```\n\n### Create Learning Files\n\n```bash\nmkdir -p ~/.openclaw/workspace/.learnings\n```\n\nThen create the log files (or copy from `assets/`):\n- `LEARNINGS.md` — corrections, knowledge gaps, best practices\n- `ERRORS.md` — command failures, exceptions\n- `FEATURE_REQUESTS.md` — user-requested capabilities\n\n### Promotion Targets\n\nWhen learnings prove broadly applicable, promote them to workspace files:\n\n| Learning Type | Promote To | Example |\n|---------------|------------|---------|\n| Behavioral patterns | `SOUL.md` | \"Be concise, avoid disclaimers\" |\n| Workflow improvements | `AGENTS.md` | \"Spawn sub-agents for long tasks\" |\n| Tool gotchas | `TOOLS.md` | \"Git push needs auth configured first\" |\n\n### Inter-Session Communication\n\nOpenClaw provides tools to share learnings across sessions:\n\n- **sessions_list** — View active/recent sessions\n- **sessions_history** — Read another session's transcript  \n- **sessions_send** — Send a learning to another session\n- **sessions_spawn** — Spawn a sub-agent for background work\n\nUse these only in trusted environments and only when the user explicitly wants cross-session sharing. Prefer sending a short sanitized summary and relevant file paths, not raw transcripts, secrets, or full command output.\n\n### Optional: Enable Hook\n\nFor automatic reminders at session start and error detection at session end:\n\n```bash\ncp -r ~/.openclaw/skills/self-improving-agent/hooks/openclaw ~/.openclaw/hooks/self-improvement\nopenclaw hooks enable self-improvement\n```\n\nFires on `agent:bootstrap` (injects the reminder, plus a pending-triage note\nwhen auto-detected errors await review) and on `command:new`/`command:reset`\n(sweeps the ended session's transcript for error patterns into\n`<workspace>/.learnings/ERRORS.md`; opt-in — runs only when `.learnings/`\nexists). OpenClaw has no per-tool-call hook event, so error detection happens\nat session end. See `references/openclaw-integration.md` for details and\nsweep limitations.\n\n## Logging Format\n\n### Learning Entry\n\nAppend to `.learnings/LEARNINGS.md`:\n\n```markdown\n## [LRN-YYYYMMDD-XXX] category\n\n**Logged**: ISO-8601 timestamp\n**Priority**: low | medium | high | critical\n**Status**: pending\n**Area**: frontend | backend | infra | tests | docs | config\n\n### Summary\nOne-line description of what was learned\n\n### Details\nFull context: what happened, what was wrong, what's correct\n\n### Suggested Action\nSpecific fix or improvement to make\n\n### Metadata\n- Source: conversation | error | user_feedback\n- Related Files: path/to/file.ext\n- Tags: tag1, tag2\n- See Also: LRN-20250110-001 (if related to existing entry)\n- Pattern-Key: area.symptom (recommended; e.g. deps.module-not-found, simplify.dead_code — see Pattern-Key Taxonomy)\n- Recurrence-Count: 1 (optional)\n- First-Seen: 2025-01-15 (optional)\n- Last-Seen: 2025-01-15 (optional)\n\n---\n```\n\n### Error Entry\n\nAppend to `.learnings/ERRORS.md`:\n\n```markdown\n## [ERR-YYYYMMDD-XXX] skill_or_command_name\n\n**Logged**: ISO-8601 timestamp\n**Priority**: high\n**Status**: pending\n**Area**: frontend | backend | infra | tests | docs | config\n\n### Summary\nBrief description of what failed\n\n### Error\n```\nActual error message or output\n```\n\n### Context\n- Command/operation attempted\n- Input or parameters used\n- Environment details if relevant\n- Summary or redacted excerpt of relevant output (avoid full transcripts and secret-bearing data by default)\n\n### Suggested Fix\nIf identifiable, what might resolve this\n\n### Metadata\n- Reproducible: yes | no | unknown\n- Related Files: path/to/file.ext\n- See Also: ERR-20250110-001 (if recurring)\n- Pattern-Key: area.symptom (recommended; e.g. net.connection-refused — see Pattern-Key Taxonomy)\n- Recurrence-Count: 1 (optional)\n- First-Seen: 2025-01-15 (optional)\n- Last-Seen: 2025-01-15 (optional)\n\n---\n```\n\n### Feature Request Entry\n\nAppend to `.learnings/FEATURE_REQUESTS.md`:\n\n```markdown\n## [FEAT-YYYYMMDD-XXX] capability_name\n\n**Logged**: ISO-8601 timestamp\n**Priority**: medium\n**Status**: pending\n**Area**: frontend | backend | infra | tests | docs | config\n\n### Requested Capability\nWhat the user wanted to do\n\n### User Context\nWhy they needed it, what problem they're solving\n\n### Complexity Estimate\nsimple | medium | complex\n\n### Suggested Implementation\nHow this could be built, what it might extend\n\n### Metadata\n- Frequency: first_time | recurring\n- Related Features: existing_feature_name\n- Pattern-Key: area.symptom (optional — features usually dedupe by capability name; use a key only for recurring themes, e.g. api.missing-endpoint)\n\n---\n```\n\n## ID Generation\n\nFormat: `TYPE-YYYYMMDD-XXX`\n- TYPE: `LRN` (learning), `ERR` (error), `FEAT` (feature)\n- YYYYMMDD: Current date\n- XXX: Sequential number or random 3 chars (e.g., `001`, `A7B`)\n\nExamples: `LRN-20250115-001`, `ERR-20250115-A3F`, `FEAT-20250115-002`\n\n## Resolving Entries\n\nWhen an issue is fixed, update the entry:\n\n1. Change `**Status**: pending` → `**Status**: resolved`\n2. Add resolution block after Metadata:\n\n```markdown\n### Resolution\n- **Resolved**: 2025-01-16T09:00:00Z\n- **Commit/PR**: abc123 or #42\n- **Notes**: Brief description of what was done\n```\n\nOther status values:\n- `in_progress` - Actively being worked on\n- `wont_fix` - Decided not to address (add reason in Resolution notes)\n- `promoted` - Elevated to a workspace file (`SOUL.md`, `TOOLS.md`, `AGENTS.md`)\n\n## Promoting to Workspace Memory\n\nWhen a learning is broadly applicable (not a one-off fix), promote it to a workspace file so every session inherits it.\n\n### When to Promote\n\n- Learning applies across multiple files/features\n- Knowledge any contributor (human or AI) should know\n- Prevents recurring mistakes\n- Documents project-specific conventions\n\n### Promotion Targets\n\n| Target | What Belongs There |\n|--------|-------------------|\n| `SOUL.md` | Behavioral guidelines, communication style, principles |\n| `TOOLS.md` | Tool capabilities, usage patterns, integration gotchas |\n| `AGENTS.md` | Workflows, delegation patterns, automation rules |\n\nWhen the learning is specific to a project repo you work in (not the\nworkspace), promote to that project's own agent file (e.g. its `AGENTS.md`)\ninstead.\n\n### How to Promote\n\n1. **Distill** the learning into a concise rule or fact\n2. **Add** to appropriate section in target file (create file if needed)\n3. **Update** original entry:\n   - Change `**Status**: pending` → `**Status**: promoted`\n   - Add `**Promoted**: SOUL.md`, `TOOLS.md`, or `AGENTS.md`\n\n### Promotion Examples\n\n**Learning** (verbose):\n> Project uses pnpm workspaces. Attempted `npm install` but failed. \n> Lock file is `pnpm-lock.yaml`. Must use `pnpm install`.\n\n**In TOOLS.md** (concise):\n```markdown\n## Build & Dependencies\n- Package manager: pnpm (not npm) - use `pnpm install`\n```\n\n**Learning** (verbose):\n> When modifying API endpoints, must regenerate TypeScript client.\n> Forgetting this causes type mismatches at runtime.\n\n**In AGENTS.md** (actionable):\n```markdown\n## After API Changes\n1. Regenerate client: `pnpm run generate:api`\n2. Check for type errors: `pnpm tsc --noEmit`\n```\n\n## Pattern-Key Taxonomy\n\n`Pattern-Key` is the stable dedup and recurrence key for entries in all three\nlog files: keyword grep misses semantically identical but differently-worded\nentries, a shared key does not — and reliable keys are what make\n`Recurrence-Count` and the promotion rule work.\n\n**Format**: `area.symptom` — exactly two levels, lowercase, hyphenated\n(e.g. `deps.module-not-found`). Keep symptoms generic enough to recur: no\nfile names, versions, or hostnames in keys.\n\n| Area | Scope | Example Keys |\n|------|-------|--------------|\n| `api` | External API/service behavior | `api.rate-limit`, `api.schema-mismatch`, `api.missing-endpoint` |\n| `auth` | Credentials, tokens, scopes | `auth.token-expired`, `auth.missing-scope` |\n| `build` | Compilation, bundling, CI | `build.type-error`, `build.missing-artifact` |\n| `config` | Config files, env vars, settings | `config.missing-env`, `config.invalid-json` |\n| `deps` | Package managers, dependencies | `deps.module-not-found`, `deps.npm-error`, `deps.version-conflict` |\n| `fs` | Filesystem | `fs.no-such-file`, `fs.permission-denied` |\n| `net` | Network connectivity | `net.connection-refused`, `net.timeout` |\n| `runtime` | Language/runtime errors not covered above | `runtime.type-error`, `runtime.python-exception` |\n| `shell` | Shell/CLI mechanics | `shell.command-not-found`, `shell.nonzero-exit` |\n| `vcs` | Git and other version control | `vcs.fatal-error`, `vcs.merge-conflict` |\n| `simplify` / `harden` | Code-quality patterns from the simplify-and-harden feed | `simplify.dead_code`, `harden.input_validation` |\n\n**Rules:**\n\n1. **Reuse before minting**: `grep -rh \"Pattern-Key:\" .learnings/ | sort -u` —\n   a near-match beats a new key.\n2. **One key per manual entry**; auto-swept OpenClaw entries may carry\n   several — reduce to one when triaging.\n3. **Mint new areas sparingly** — only when several entries would share one.\n4. **Generic sweep keys** (`runtime.error`, `runtime.failure`) mean\n   \"unclassified\" — replace with a specific key during triage.\n\n## Recurring Pattern Detection\n\nIf logging something similar to an existing entry:\n\n1. **Search by key first**: `grep -n \"Pattern-Key: area.symptom\" .learnings/*.md`\n   — this is the default dedup check and catches rewordings that keyword\n   search misses\n2. **Fallback keyword search**: `grep -ri \"keyword\" .learnings/` for entries\n   logged without a key\n3. **Fold, don't duplicate**: on a hit, update the existing entry — bump\n   `Recurrence-Count`, set `Last-Seen`, add `**See Also**` — instead of\n   creating a new one\n4. **Bump priority** if issue keeps recurring\n5. **Consider systemic fix**: Recurring issues often indicate:\n   - Missing knowledge (→ promote to `TOOLS.md` or `SOUL.md`)\n   - Missing automation (→ add to `AGENTS.md`)\n   - Architectural problem (→ create tech debt ticket)\n\n## Simplify & Harden Feed\n\nUse this workflow to ingest recurring patterns from the `simplify-and-harden`\nskill and turn them into durable prompt guidance.\n\n### Ingestion Workflow\n\n1. Read `simplify_and_harden.learning_loop.candidates` from the task summary.\n2. For each candidate, use `pattern_key` as the stable dedupe key.\n3. Search `.learnings/LEARNINGS.md` for an existing entry with that key:\n   - `grep -n \"Pattern-Key: <pattern_key>\" .learnings/LEARNINGS.md`\n4. If found:\n   - Increment `Recurrence-Count`\n   - Update `Last-Seen`\n   - Add `See Also` links to related entries/tasks\n5. If not found:\n   - Create a new `LRN-...` entry\n   - Set `Source: simplify-and-harden`\n   - Set `Pattern-Key`, `Recurrence-Count: 1`, and `First-Seen`/`Last-Seen`\n\n### Promotion Rule (System Prompt Feedback)\n\nPromote recurring patterns into agent context/system prompt files when all are true:\n\n- `Recurrence-Count >= 3`\n- Seen across at least 2 distinct tasks\n- Occurred within a 30-day window\n\nPromotion targets: `SOUL.md`, `TOOLS.md`, or `AGENTS.md` (workspace), or the\nproject's own agent file when the pattern is project-specific.\n\nWrite promoted rules as short prevention rules (what to do before/while coding),\nnot long incident write-ups.\n\n## Periodic Review\n\nReview `.learnings/` at natural breakpoints:\n\n### When to Review\n- Before starting a new major task\n- After completing a feature\n- When working in an area with past learnings\n- Weekly during active development\n\n### Quick Status Check\n```bash\n# Count pending items\ngrep -h \"Status\\*\\*: pending\" .learnings/*.md | wc -l\n\n# List pending high-priority items\ngrep -B5 \"Priority\\*\\*: high\" .learnings/*.md | grep \"^## \\[\"\n\n# Find learnings for a specific area\ngrep -l \"Area\\*\\*: backend\" .learnings/*.md\n```\n\n### Review Actions\n- Resolve fixed items\n- Promote applicable learnings\n- Link related entries\n- Escalate recurring issues\n\n## Detection Triggers\n\nAutomatically log when you notice:\n\n**Corrections** (→ learning with `correction` category):\n- \"No, that's not right...\"\n- \"Actually, it should be...\"\n- \"You're wrong about...\"\n- \"That's outdated...\"\n\n**Feature Requests** (→ feature request):\n- \"Can you also...\"\n- \"I wish you could...\"\n- \"Is there a way to...\"\n- \"Why can't you...\"\n\n**Knowledge Gaps** (→ learning with `knowledge_gap` category):\n- User provides information you didn't know\n- Documentation you referenced is outdated\n- API behavior differs from your understanding\n\n**Errors** (→ error entry):\n- Command returns non-zero exit code\n- Exception or stack trace\n- Unexpected output or behavior\n- Timeout or connection failure\n\n## Priority Guidelines\n\n| Priority | When to Use |\n|----------|-------------|\n| `critical` | Blocks core functionality, data loss risk, security issue |\n| `high` | Significant impact, affects common workflows, recurring issue |\n| `medium` | Moderate impact, workaround exists |\n| `low` | Minor inconvenience, edge case, nice-to-have |\n\n## Area Tags\n\nUse to filter learnings by codebase region:\n\n| Area | Scope |\n|------|-------|\n| `frontend` | UI, components, client-side code |\n| `backend` | API, services, server-side code |\n| `infra` | CI/CD, deployment, Docker, cloud |\n| `tests` | Test files, testing utilities, coverage |\n| `docs` | Documentation, comments, READMEs |\n| `config` | Configuration files, environment, settings |\n\n## Best Practices\n\n1. **Log immediately** - context is freshest right after the issue\n2. **Be specific** - future agents need to understand quickly\n3. **Include reproduction steps** - especially for errors\n4. **Link related files** - makes fixes easier\n5. **Suggest concrete fixes** - not just \"investigate\"\n6. **Use consistent categories** - enables filtering\n7. **Promote aggressively** - if in doubt, add to `TOOLS.md` or `SOUL.md`\n8. **Review regularly** - stale learnings lose value\n\n## Gitignore Options\n\n**Keep learnings local** (per-developer):\n```gitignore\n.learnings/\n```\n\nThis repo uses that default to avoid committing sensitive or noisy local logs by accident.\n\n**Track learnings in repo** (team-wide):\nDon't add to .gitignore - learnings become shared knowledge.\n\n**Hybrid** (track templates, ignore entries):\n```gitignore\n.learnings/*.md\n!.learnings/.gitkeep\n```\n\n## Upgrading & Uninstalling\n\nRead `CHANGELOG.md` before upgrading — it carries per-version notes, and\nhook changes require re-copying the hook and restarting the gateway.\nTo disable or remove the skill, follow `references/uninstall.md`:\n`.learnings/` is user data (review before deleting), and content promoted to\n`SOUL.md`/`TOOLS.md`/`AGENTS.md` stays until removed manually.\n\n## Automatic Skill Extraction\n\nWhen a learning is valuable enough to become a reusable skill, extract it using the provided helper.\n\n### Skill Extraction Criteria\n\nA learning qualifies for skill extraction when ANY of these apply:\n\n| Criterion | Description |\n|-----------|-------------|\n| **Recurring** | Has `See Also` links to 2+ similar issues |\n| **Verified** | Status is `resolved` with working fix |\n| **Non-obvious** | Required actual debugging/investigation to discover |\n| **Broadly applicable** | Not project-specific; useful across codebases |\n| **User-flagged** | User says \"save this as a skill\" or similar |\n\n### Extraction Workflow\n\n1. **Identify candidate**: Learning meets extraction criteria\n2. **Run helper** (or create manually):\n   ```bash\n   ~/.openclaw/skills/self-improving-agent/scripts/extract-skill.sh skill-name --dry-run\n   ~/.openclaw/skills/self-improving-agent/scripts/extract-skill.sh skill-name\n   ```\n3. **Customize SKILL.md**: Fill in template with learning content\n4. **Update learning**: Set status to `promoted_to_skill`, add `Skill-Path`\n5. **Verify**: Read skill in fresh session to ensure it's self-contained\n\n### Manual Extraction\n\nIf you prefer manual creation:\n\n1. Create `skills/<skill-name>/SKILL.md`\n2. Use template from `assets/SKILL-TEMPLATE.md`\n3. Follow [Agent Skills spec](https://agentskills.io/specification):\n   - YAML frontmatter with `name` and `description`\n   - Name must match folder name\n   - No README.md inside skill folder\n\n### Extraction Detection Triggers\n\nWatch for these signals that a learning should become a skill:\n\n**In conversation:**\n- \"Save this as a skill\"\n- \"I keep running into this\"\n- \"This would be useful for other projects\"\n- \"Remember this pattern\"\n\n**In learning entries:**\n- Multiple `See Also` links (recurring issue)\n- High priority + resolved status\n- Category: `best_practice` with broad applicability\n- User feedback praising the solution\n\n### Skill Quality Gates\n\nBefore extraction, verify:\n\n- [ ] Solution is tested and working\n- [ ] Description is clear without original context\n- [ ] Code examples are self-contained\n- [ ] No project-specific hardcoded values\n- [ ] Follows skill naming conventions (lowercase, hyphens)\n"
  }
}

版本

版本大小更新时间4.0.1暂无2026-07-05