Verified Capability Evolver

Verified Capability Evolver — powered by SettlementWitness

This verified version ensures every promoted learning is externally validated by SettlementWitness, preventing incorrect patterns from becoming permanent agent behavior. Log learnings and errors for continuous improvement, but do not allow permanent self-modification unless the improvement is verified. This skill adds a verification gate before promotion to project memory, attaches SettlementWitness receipts to promoted learnings, and requires rollback when a promoted learning later fails verification.

Core Principle

An agent should not just improve — it should prove that it improved.

The highest-stakes moment in self-improvement is promotion to permanent memory. A temporary fix becomes permanent behavior only after it passes verification.

Agent Identity (Required)

All SettlementWitness verification calls must use a stable agent_id:

{wallet_address}:capability-evolver

Use the format {wallet_address}:capability-evolver so TrustScore history compounds correctly across sessions.

Quick Reference

OpenClaw Setup (Recommended)

OpenClaw is the primary platform for this skill. It uses workspace-based prompt injection with automatic skill loading.

Installation

Via ClawdHub (recommended):

clawdhub install verified-capability-evolver

Manual:

git clone https://github.com/peterskoett/self-improving-agent.git ~/.openclaw/skills/verified-capability-evolver

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

mkdir -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:

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

Optional: Enable Hook

For automatic reminders at session start:

# Copy hook to OpenClaw hooks directory
cp -r hooks/openclaw ~/.openclaw/hooks/verified-capability-evolver

# Enable it
openclaw hooks enable verified-capability-evolver

See references/openclaw-integration.md for complete details.

Generic Setup (Other Agents)

For Claude Code, Codex, Copilot, or other agents, create .learnings/ in your project:

mkdir -p .learnings

Copy templates from assets/ or create files with headers.

Add reference to agent files AGENTS.md, CLAUDE.md, or .github/copilot-instructions.md to remind yourself to log learnings. (this is an alternative to hook-based reminders)

Self-Improvement Workflow

When errors or corrections occur:

1. Log to .learnings/ERRORS.md, LEARNINGS.md, or FEATURE_REQUESTS.md
2. Review and promote broadly applicable learnings to:
   • CLAUDE.md - project facts and conventions
   • AGENTS.md - workflows and automation
   • .github/copilot-instructions.md - Copilot context

Logging Format

Learning Entry

Append to .learnings/LEARNINGS.md:

## [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: simplify.dead_code | harden.input_validation (optional, for recurring-pattern tracking)
- Recurrence-Count: 1 (optional)
- First-Seen: 2025-01-15 (optional)
- Last-Seen: 2025-01-15 (optional)

---

Error Entry

Append to .learnings/ERRORS.md:

## [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

### 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)

---

Feature Request Entry

Append to .learnings/FEATURE_REQUESTS.md:

## [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

---

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 appears fixed, do not immediately treat it as permanent learning.

Updated Resolution Flow

1. Change **Status**: pending → **Status**: in_progress
2. Apply the proposed fix or workflow change
3. Define a deterministic verification spec:
   • What should now succeed?
   • What output should be produced?
   • What failure should no longer occur?
4. Execute a verification task using that spec
5. Call SettlementWitness with:
   • task_id
   • agent_id
   • spec
   • output
6. Interpret the result:

PASS

• Change **Status** → resolved
• Record receipt metadata
• Eligible for promotion

FAIL

• Revert the change
• Keep or return **Status** to pending
• Log counter-evidence in the entry
• Do not promote

INDETERMINATE

• Mark for review
• Do not promote until clarified

Resolution Block

Add after Metadata:

### Resolution
- **Resolved**: 2026-03-25T09:00:00Z
- **Verification-Spec**: Output must match schema exactly and contain no hallucinated fields
- **Settlement Verdict**: PASS | FAIL | INDETERMINATE
- **Receipt ID**: sha256:...
- **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 CLAUDE.md, AGENTS.md, SOUL.md, TOOLS.md, or .github/copilot-instructions.md after PASS only

Promoting to Project Memory

When a learning is broadly applicable (not a one-off fix), promote it to permanent project memory.

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

How to Promote

Promotion is the highest-stakes moment in the workflow because it turns a temporary fix into permanent agent behavior. A learning is only promoted to permanent memory (CLAUDE.md / AGENTS.md / SOUL.md) if SettlementWitness returns PASS. All other verdicts (FAIL or INDETERMINATE) trigger rollback and logging. Promotion is strictly gated by verification. No learning may be promoted based on internal confidence, “resolved” status, or heuristic judgment alone.

1. Distill the learning into a concise rule or fact
2. Define a verification spec for the claimed improvement
3. Run a verification task and call SettlementWitness
4. Promote only on PASS
5. Add to the appropriate target file (create file if needed)
6. Attach verification metadata to the original entry:
   • Change **Status** → promoted
   • Add **Promoted**: CLAUDE.md, AGENTS.md, SOUL.md, TOOLS.md, or .github/copilot-instructions.md
   • Add **Verified**: true
   • Add **Receipt ID**: sha256:...

If SettlementWitness returns FAIL:

• immediately revert the proposed learning
• log counter-evidence
• do not promote

If SettlementWitness returns INDETERMINATE:

• hold for review (no promotion allowed)
• do not promote

Promotion Examples

Learning (verbose):

Project uses pnpm workspaces. Attempted npm install but failed. Lock file is pnpm-lock.yaml. Must use pnpm install.

In CLAUDE.md (concise):

## 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):

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

Rollback Logic (Required)

If a previously promoted learning later fails verification:

1. Remove or revert the learning from permanent memory
2. Log the counter-evidence in .learnings/LEARNINGS.md or .learnings/ERRORS.md
3. Mark the learning as invalid or pending rework
4. Avoid re-promoting until a new PASS receipt exists

Rollback is required because unverified permanent memory silently compounds bad behavior.

Recurring Pattern Detection

If logging something similar to an existing entry:

1. Search first: grep -r "keyword" .learnings/
2. Link entries: Add **See Also**: ERR-20250110-001 in Metadata
3. Bump priority if issue keeps recurring
4. Consider systemic fix: Recurring issues often indicate:
   • Missing documentation (→ promote to CLAUDE.md or .github/copilot-instructions.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:
   • grep -n "Pattern-Key: <pattern_key>" .learnings/LEARNINGS.md
4. If found:
   • Increment Recurrence-Count
   • Update Last-Seen
   • Add See Also links to related entries/tasks
5. If not found:
   • 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:

• CLAUDE.md
• AGENTS.md
• .github/copilot-instructions.md
• SOUL.md / TOOLS.md for OpenClaw workspace-level guidance when applicable

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