Skill: rangeking/self-evo-agent (version 1.1.0)

--- name: self-evolving-agent description: Build a goal-driven self-learning loop for OpenClaw and coding agents. Use when the agent should not only log mistakes, but diagnose capability gaps, maintain a capability map and learning agenda, generate training units, evaluate progress, validate transfer, and promote only proven strategies into long-term behavior. Also use before major tasks to retrieve relevant learnings, inspect capability risks, and choose safer execution strategies. metadata: short-description: Capability evolution for agents --- # Self-Evolving Agent `self-evolving-agent` upgrades passive self-improvement into an explicit capability evolution system. Use this skill when any of the following is true: - A task is difficult, novel, high-stakes, or long-horizon. - An error, correction, or near-miss reveals a deeper capability weakness. - The same failure pattern appears more than once. - A useful tactic might deserve promotion into long-term context, but has not been validated yet. - You want to understand not just what went wrong, but what the agent can do now, what it still cannot do, and what it should train next. Default to the light loop first. Escalate into the full capability-evolution loop only when the task or evidence justifies the extra cost. ## Core Principle Do not treat logging as learning. This skill separates six states of progress: 1. `recorded` 2. `understood` 3. `practiced` 4. `passed` 5. `generalized` 6. `promoted` A lesson only becomes long-term policy after it survives training and transfer. ## What This Skill Preserves From Classic Self-Improvement Keep the original strengths as the memory layer: - Log errors, corrections, learnings, and feature requests. - Detect recurring patterns. - Review prior learnings before major work. - Promote only high-value guidance into long-term context. - Use workspace files and hooks to keep memory persistent across sessions. ## What This Skill Adds This skill adds an active learning layer: - Capability map with levels, failure modes, and upgrade criteria - Proactive learning agenda that selects the next 1-3 capabilities to train - Task-level diagnosis of root causes - Training unit generation for recurring weaknesses - Evaluation gates that separate recording from mastery - Transfer checks on new tasks before promotion - Reflection routines that force self-explanation and counterexamples ## Closed Loop Run the following loop, in order: 1. Classify the task. 2. Retrieve relevant learnings and related capabilities. 3. Run a pre-task risk diagnosis. 4. Choose an execution strategy. 5. Perform the task. 6. Run post-task reflection. 7. Update the capability map. 8. Generate a training unit if weakness or recurrence is detected. 9. Evaluate learning progress. 10. Promote only validated strategies. ## Effort Modes ### Light loop Use the lightweight pass when all of the following are true: - The task is familiar. - Consequence is low. - Horizon is short. - No active agenda focus is central to the task. - No failure, near-miss, or user rescue exposed a deeper weakness. - No learning needs training, evaluation, or promotion. In the light loop: 1. Retrieve only the most relevant 1-3 memory items. 2. Name the single most likely risk and one verification check. 3. Do the work. 4. Log only unusually reusable lessons. 5. Stop unless an escalation trigger fires. ### Full loop Run the full loop when any of the following is true: - The task is mixed or unfamiliar. - Consequence is medium or high and failure would matter. - Horizon is medium or long with many dependencies. - An active agenda focus is relevant. - A failure, near-miss, or user correction suggests a reusable weakness. - A similar issue repeated, transfer failed, or promotion is under consideration. - The task itself is deliberate practice, evaluation, or promotion review. ### Escalation triggers Escalate from light to full when any of the following appears during execution: - non-trivial rework - verification catches a real defect - the user had to rescue or redirect the task - a missed retrieval or repeated pattern appears - the learning looks broad enough to affect future policy ## Control Loop Outside the 10-step task loop, maintain an explicit learning agenda. Run an agenda review when any of the following is true: - The workspace is new and no calibrated capability map exists. - Five meaningful cycles have passed since the last review. - A `structural_gap` or failed transfer was detected. - A long-horizon or unfamiliar task is about to begin. During agenda review: - choose the top 1-3 capabilities to train next - defer lower-leverage weaknesses instead of training everything at once - define what evidence would retire or advance each focus - link each focus to existing or new training units ## File Map - Main orchestration: `system/coordinator.md` - Learning agenda and review cycle: `modules/learning-agenda.md` - Diagnosis: `modules/diagnose.md` - Capability definitions and update rules: `modules/capability-map.md` - Training unit design: `modules/curriculum.md` - Learning evaluation ladder: `modules/evaluator.md` - Promotion gate: `modules/promotion.md` - Reflection protocol: `modules/reflection.md` Assets and ledgers: - `assets/LEARNINGS.md` - `assets/ERRORS.md` - `assets/FEATURE_REQUESTS.md` - `assets/CAPABILITIES.md` - `assets/LEARNING_AGENDA.md` - `assets/TRAINING_UNITS.md` - `assets/EVALUATIONS.md` ## Operating Rules ### During migration from self-improving-agent - Treat `.evolution/legacy-self-improving/` as a read-only memory layer. - Search the legacy files during retrieval if they exist. - Do not bulk-convert every old entry into the new schema on day one. - Normalize a legacy learning into `.evolution` only when it is reused, agenda-worthy, or needed for evaluation. ### Before a substantial task - Read `system/coordinator.md`. - Check whether `assets/LEARNING_AGENDA.md` requires a review cycle. - Retrieve relevant entries from `LEARNINGS`, `ERRORS`, `CAPABILITIES`, and `TRAINING_UNITS`. - Identify the top 1-3 risk capabilities for this task. ### After every meaningful task - Log incident-level observations in the memory files. - Diagnose the weakest capability involved. - Update the capability map with evidence, not vibes. - Refresh the learning agenda if a focus should change. - If the issue is recurring or high-leverage, create or revise a training unit. - Record evaluation status using the six-state ladder. ### Before promotion - Read `modules/evaluator.md` and `modules/promotion.md`. - Confirm the strategy has passed training and succeeded in at least one transfer scenario. - Promote the smallest stable rule that explains the success. ## When Not To Use Heavyweight Evaluation Use a lightweight pass when all of the following are true: - The task was trivial. - No real uncertainty or failure occurred. - No new behavior should be generalized. In that case, log the learning only if it is unusually reusable. ## Output Contracts When this skill is active, prefer producing these artifacts: - A learning agenda review when triggers fire - A short pre-task risk diagnosis - A post-task capability diagnosis - A `TRAINING_UNIT` when recurrence or weakness appears - An `EVALUATION` entry when progress is tested - A promotion decision with explicit evidence ## Recommended Workflow 1. Read `system/coordinator.md`. 2. Load only the modules needed for the current step. 3. Use the asset templates as the canonical output format. 4. Keep long-term memory strict: only promote validated patterns.

path: CHANGELOG.md
content: # Changelog

All notable changes to this project will be documented in this file.

The format is inspired by Keep a Changelog and uses calendar-aware project notes rather than strict semver release automation.

## [Unreleased]

### Added

- Repository governance files: `LICENSE`, `CONTRIBUTING.md`, `SECURITY.md`
- GitHub issue templates and pull request template
- GitHub Actions CI workflow for structural validation and bootstrap smoke testing

## [0.1.0] - 2026-03-18

### Added

- Initial `self-evolving-agent` skill architecture
- Capability map, diagnosis, curriculum, evaluator, reflection, promotion, and coordinator modules
- Bootstrap capability baseline and learning agenda
- English and Chinese README files
- Model-in-the-loop benchmark harness and structural evaluation script
- Demo conversations, hooks, workspace assets, and installation guidance


path: install.md
content: # Install self-evolving-agent

## OpenClaw Installation

### Option 1: Install from ClawHub

ClawHub is the public skill registry for OpenClaw. Install the CLI, then install this skill by its registry slug:

```bash
npm i -g clawhub
# or
pnpm add -g clawhub

clawhub install RangeKing/self-evo-agent
```

OpenClaw will pick up the new workspace skill on the next session start.

Registry slug and local install directory use `self-evo-agent`.
The skill name and hook name remain `self-evolving-agent`.

If you already use `self-improving-agent`, keep it installed for the moment. Migrate the old `.learnings/` history first, then disable the old hook so you do not get duplicate reminders.

### Option 2: Let OpenClaw fetch it from GitHub

Ask your OpenClaw agent to install the repository directly into the shared skills directory:

```text
Install the OpenClaw skill from https://github.com/RangeKing/self-evolving-agent into ~/.openclaw/skills/self-evo-agent, inspect the scripts before enabling hooks, and then bootstrap ~/.openclaw/workspace/.evolution.
```

This is useful when you want OpenClaw itself to download and inspect the skill before use.

### Option 3: Copy into the skills directory

```bash
cp -r self-evolving-agent ~/.openclaw/skills/self-evo-agent
```

### Option 4: Clone directly

```bash
git clone https://github.com/RangeKing/self-evolving-agent.git ~/.openclaw/skills/self-evo-agent
```

## Workspace Setup

Create a persistent workspace memory area:

```bash
mkdir -p ~/.openclaw/workspace/.evolution
```

Seed the workspace ledgers with the bootstrap script:

```bash
~/.openclaw/skills/self-evo-agent/scripts/bootstrap-workspace.sh ~/.openclaw/workspace/.evolution
```

If you are migrating from `self-improving-agent`, import the legacy `.learnings/` directory at the same time:

```bash
~/.openclaw/skills/self-evo-agent/scripts/bootstrap-workspace.sh \
  ~/.openclaw/workspace/.evolution \
  --migrate-from ~/.openclaw/workspace/.learnings
```

This migration is lossless:

- it copies the original `.learnings/` files into `.evolution/legacy-self-improving/`
- it leaves the original files untouched
- it avoids rewriting old entries into the new schema before they are needed

After import, verify `.evolution/legacy-self-improving/IMPORT_INDEX.md`.

## Recommended Workspace Convention

```text
~/.openclaw/workspace/
├── AGENTS.md
├── SOUL.md
├── TOOLS.md
├── MEMORY.md
└── .evolution/
    ├── LEARNINGS.md
    ├── ERRORS.md
    ├── FEATURE_REQUESTS.md
    ├── CAPABILITIES.md
    ├── LEARNING_AGENDA.md
    ├── TRAINING_UNITS.md
    └── EVALUATIONS.md
```

## Optional Hook

Copy the OpenClaw hook:

```bash
cp -r ~/.openclaw/skills/self-evo-agent/hooks/openclaw ~/.openclaw/hooks/self-evolving-agent
```

Enable it:

```bash
openclaw hooks enable self-evolving-agent
```

If you previously enabled the old hook, disable it after verifying the import:

```bash
openclaw hooks disable self-improvement
```

## Optional Generic Agent Hooks

If your agent environment supports shell hooks, you can use:

- `scripts/activator.sh` for bootstrap reminders
- `scripts/error-detector.sh` for command-error reminders
- `scripts/run-evals.py` for repeatable local compliance checks
- `scripts/run-benchmark.py` for model-in-the-loop benchmark runs

## Promotion Targets

Only promote validated strategies into durable context:

- `AGENTS.md` for workflow rules
- `TOOLS.md` for tool-specific constraints
- `SOUL.md` for behavioral policies
- `MEMORY.md` for durable project or operator facts

## Minimum Operating Routine

Default to the light loop. Only pay the cost of the full loop when the task or evidence warrants it.

Before major tasks:

1. Review `LEARNING_AGENDA` to see what the agent is actively training.
2. Review relevant entries from `LEARNINGS`, `ERRORS`, and `CAPABILITIES`.
3. Identify the most likely failure mode.
4. Choose an execution strategy that reduces that risk.

After major tasks:

1. Log incidents and learnings.
2. Diagnose the weakest capability involved.
3. Refresh the learning agenda if priorities changed.
4. Create or update a training unit if recurrence appears.
5. Record evaluation status.
6. Promote only after validated transfer.

For familiar, low-consequence, short tasks, use the light loop instead:

1. Retrieve only the 1-3 most relevant prior items.
2. Name one likely risk and one verification check.
3. Do the work.
4. Log only if the lesson is unusually reusable.
5. Escalate into the full loop only if a real defect, user rescue, recurrence, or transfer-worthy lesson appears.

## Validation

Run the repeatable local compliance suite:

```bash
python3 ~/.openclaw/skills/self-evo-agent/scripts/run-evals.py ~/.openclaw/skills/self-evo-agent
```

Run the model-in-the-loop benchmark:

```bash
python3 ~/.openclaw/skills/self-evo-agent/scripts/run-benchmark.py --skill-dir ~/.openclaw/skills/self-evo-agent
```

## Security Note

Whether you install from ClawHub or GitHub, inspect the skill files before enabling hooks or running scripts that modify your OpenClaw workspace.


path: CONTRIBUTING.md
content: # Contributing

Thanks for contributing to `self-evolving-agent`.

## Principles

- Keep the skill clearly stronger than passive self-improvement systems.
- Prefer concrete workflow improvements over abstract theory.
- Preserve the memory layer while strengthening capability evolution.
- Treat benchmark quality as part of the product, not as an afterthought.

## Branch Convention

The default branch is `main`. Please branch from `main` and target `main` in pull requests.

## Development Setup

```bash
git clone https://github.com/RangeKing/self-evolving-agent.git
cd self-evolving-agent
python3 scripts/run-evals.py .
./scripts/bootstrap-workspace.sh /tmp/self-evolving-agent-dev --force
```

Optional model-in-the-loop smoke test:

```bash
python3 scripts/run-benchmark.py \
  --skill-dir . \
  --candidate-model gpt-5.4-mini \
  --judge-model gpt-5.4-mini \
  --max-scenarios 1 \
  --timeout-seconds 90
```

## What Good Changes Look Like

- New modules or assets improve diagnosis, training, evaluation, transfer, or promotion quality.
- README and docs stay aligned with the actual repository behavior.
- Benchmarks become more discriminating, not more vague.
- Long-term memory stays strict: recording is not treated as mastery.

## Pull Request Checklist

- Update docs when behavior or structure changes.
- Run `python3 scripts/run-evals.py .`
- Run a benchmark smoke test when the change affects benchmarked behavior or evaluation logic.
- Keep generated benchmark outputs out of Git.
- Add or update changelog notes in [CHANGELOG.md](./CHANGELOG.md).

## Scope Guidance

### Great contributions

- Better benchmark scenarios
- Better curriculum or evaluator rubrics
- Clearer capability taxonomy
- More reusable demos
- Better installation and workflow ergonomics

### Usually not a fit

- Purely cosmetic changes with no usability benefit
- Weaker promotion rules
- Benchmark shortcuts that reduce evaluation integrity
- Large unrelated refactors without a clear repository payoff

## Commit and PR Style

- Use clear, descriptive titles.
- Explain the user-facing outcome, not only the file diff.
- Call out risks, follow-ups, and assumptions explicitly.

## Questions

Open an issue for product or design discussion. For security-sensitive concerns, follow [SECURITY.md](./SECURITY.md).


path: SECURITY.md
content: # Security Policy

## Supported Versions

Security fixes are currently prioritized for the latest state of the default branch.

| Version | Supported |
| --- | --- |
| Latest `main` | Yes |
| Older snapshots and forks | Best effort |

## Reporting a Vulnerability

Please do not open a public issue for security-sensitive findings.

Preferred reporting paths:

1. Use GitHub private vulnerability reporting if it is enabled for this repository.
2. If private reporting is unavailable, contact the maintainer privately through GitHub: [@RangeKing](https://github.com/RangeKing).

Please include:

- a concise description of the issue
- affected files or workflow areas
- reproduction steps or proof of concept
- impact assessment
- any suggested mitigation

You can expect an acknowledgment as soon as practical, followed by triage and a remediation plan if the issue is confirmed.


path: assets/FEATURE_REQUESTS.md
content: # Feature Requests Ledger

Use this ledger for requested capabilities the agent does not yet possess or does not perform reliably enough.

```markdown
## [FEAT-YYYYMMDD-XXX] capability_request

**Logged**: ISO-8601 timestamp
**Priority**: low | medium | high | critical
**Status**: open | triaged | planned | satisfied | declined
**Related Capability**: research | planning | tool-use | verification | synthesis | communication | coding | execution discipline | memory retrieval | long-horizon task handling

### Requested Capability
What the user wanted the agent to do.

### User Context
Why this matters and what job the user was trying to get done.

### Current Limitation
What the agent could not yet do well.

### Evolution Path
How this might become training, tooling, or a new stable policy.

### Linked Records
- CAP-...
- TRN-...
- EVL-...
- AGD-...

---
```


path: assets/ERRORS.md
content: # Error Ledger

Use this ledger for failures, near-misses, and diagnostic evidence.

````markdown
## [ERR-YYYYMMDD-XXX] incident_title

**Logged**: ISO-8601 timestamp
**Priority**: low | medium | high | critical
**Status**: open | investigated | resolved | archived
**Primary Capability**: research | planning | tool-use | verification | synthesis | communication | coding | execution discipline | memory retrieval | long-horizon task handling

### Summary
Short description of the failure.

### Error
```text
Exact error text or concise failure output.
```

### Context
- Task:
- Command or action:
- Environment:

### Diagnostic Hypothesis
Initial best guess at root cause.

### Recurrence Signal
first_time | similar_before | recurring_pattern

### Suggested Next Step
log_only | diagnose | create_training_unit | evaluate

### Linked Records
- LRN-...
- CAP-...
- TRN-...
- AGD-...

---
````


path: agents/openai.yaml
content: interface:
  display_name: "Self-Evolving Agent"
  short_description: "Capability evolution with light/full learning modes"
  default_prompt: "Use $self-evolving-agent to choose a light or full learning loop, preserve legacy self-improving-agent logs, diagnose capability gaps, and promote only validated strategies."


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)