skillclaw-skill-evolution

# SkillClaw: Collective Skill Evolution for LLM Agents

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

SkillClaw is a framework that makes LLM agents progressively smarter by **evolving reusable skills** from real session data and sharing them across a group of agents. It intercepts OpenAI-compatible API calls via a local proxy, records session artifacts, and runs an evolve server that distills experience into `SKILL.md` files synced via cloud storage (OSS/S3/local).

## Architecture

```
User → OpenClaw Agent → SkillClaw Client Proxy → Upstream LLM API
                              ↓ records sessions
                        Shared Storage (OSS/S3/local)
                              ↑ reads sessions, writes skills
                        Evolve Server (workflow or agent)
```

Three components share the same storage layer and skill format:

1. **Client Proxy** — Local API proxy intercepting `/v1/chat/completions` and `/v1/messages`, syncing skills
2. **Workflow Evolve Server** (`evolve_server`) — Fixed 3-stage pipeline: Summarize → Aggregate → Execute
3. **Agent Evolve Server** (`agent_evolve_server`) — Autonomous OpenClaw agent that reads sessions and writes evolved skills

## Installation

### Client / Local Development

```bash
git clone <repo-url> SkillClaw && cd SkillClaw
bash scripts/install_skillclaw.sh
source .venv/bin/activate
```

### Server Deployment

```bash
bash scripts/install_skillclaw_server.sh
source .venv-server/bin/activate

# Required only for the agent evolve server
npm install -g openclaw
```

## Environment Configuration

Copy and populate credentials — never hardcode secrets:

```bash
# From example_env.sh
export OPENAI_BASE_URL="https://your-api-gateway/v1"
export OPENAI_API_KEY="$OPENAI_API_KEY"

# For OSS storage backend
export EVOLVE_STORAGE_ENDPOINT="$OSS_ENDPOINT"
export EVOLVE_STORAGE_BUCKET="$OSS_BUCKET"
export OSS_ACCESS_KEY_ID="$OSS_ACCESS_KEY_ID"
export OSS_ACCESS_KEY_SECRET="$OSS_ACCESS_KEY_SECRET"
```

Config file lives at `~/.skillclaw/config.yaml`. Inspect and modify:

```bash
skillclaw config show
skillclaw config <key> <value>
```

## CLI Reference

### Client Proxy Setup

```bash
skillclaw setup          # Initialize config and directories
skillclaw start          # Start the local proxy server
skillclaw stop           # Stop the proxy server
skillclaw status         # Show proxy status and config summary
skillclaw config show    # Dump full resolved config
```

### Skill Management

```bash
skillclaw skills pull          # Download shared skills from cloud storage
skillclaw skills push          # Upload local skills to cloud storage
skillclaw skills sync          # Bidirectional sync (pull + push)
skillclaw skills list-remote   # Browse skills available in shared storage
```

### Benchmarking

```bash
skillclaw benchmark --help     # List all benchmark subcommands
```

## Starting the Evolve Servers

### Workflow Evolve Server (Summarize → Aggregate → Execute)

```bash
skillclaw-evolve-server \
  --port 8787 \
  --interval 300 \
  --storage-backend oss \
  --oss-endpoint "$EVOLVE_STORAGE_ENDPOINT" \
  --oss-bucket "$EVOLVE_STORAGE_BUCKET" \
  --group-id my-group
```

### Agent Evolve Server (Autonomous OpenClaw agent)

```bash
skillclaw-agent-evolve-server \
  --port 8787 \
  --interval 300 \
  --no-fresh \
  --storage-backend oss \
  --oss-endpoint "$EVOLVE_STORAGE_ENDPOINT" \
  --oss-bucket "$EVOLVE_STORAGE_BUCKET" \
  --group-id my-group
```

Use `--no-fresh` to continue from existing evolved skills rather than starting from scratch each run.

### Local Filesystem Backend (for development)

```bash
skillclaw-evolve-server \
  --port 8787 \
  --interval 60 \
  --storage-backend local \
  --local-storage-path ./skill_storage \
  --group-id dev-group
```

## Key Configuration Options

| Option | Description | Default |
|---|---|---|
| `--port` | Server port | `8787` |
| `--interval` | Seconds between evolution cycles | `300` |
| `--storage-backend` | `oss`, `s3`, or `local` | `local` |
| `--group-id` | Identifier for your agent cluster | required |
| `--no-fresh` | Resume from existing skills | flag |
| `--oss-endpoint` | OSS endpoint URL | env var |
| `--oss-bucket` | OSS bucket name | env var |

## Skill Format (SKILL.md)

Skills are Markdown files with YAML frontmatter. The evolve server reads session data and writes or updates these files:

```markdown
---
name: my-skill-name
description: What this skill does
version: 1.0.0
tags: [web, scraping]
---

# Skill Name

## When to Use
...

## Instructions
Step-by-step instructions the agent follows.

## Examples
\`\`\`python
# working code example
\`\`\`
```

## WildClawBench Experiment

Run the main iterative evolution experiment:

```bash
python scripts/run_wildclawbench_iterative_evolve_agent.py \
  --group-id wildclawbench-test \
  --storage-backend local \
  --local-storage-path ./wb_storage \
  --num-iterations 3
```

This evaluates skill evolution on real-world agent tasks from [WildClawBench](https://github.com/InternLM/WildClawBench).

## Python API Usage

### Programmatic Skill Sync

```python
from skillclaw.skill_manager import SkillManager
from skillclaw.skill_hub import SkillHub

# Initialize with local backend
manager = SkillManager(storage_backend="local", local_path="./skills")

# Pull skills from shared storage
manager.pull()

# List available skills
skills = manager.list_local()
for skill in skills:
    print(f"{skill.name}: {skill.description}")

# Push a new skill
manager.push("path/to/SKILL.md")
```

### Launching the Proxy Programmatically

```python
from skillclaw.launcher import SkillClawLauncher
from skillclaw.config import SkillClawConfig

config = SkillClawConfig(
    upstream_base_url="https://api.openai.com/v1",
    upstream_api_key="$OPENAI_API_KEY",   # loaded from env at runtime
    proxy_port=8080,
    storage_backend="local",
    local_storage_path="./skillclaw_data",
    group_id="my-agents",
)

launcher = SkillClawLauncher(config)
launcher.start()
# Agents now point to http://localhost:8080/v1
```

### Using the Evolve Server API

```python
import httpx

# Trigger an immediate evolution cycle
response = httpx.post("http://localhost:8787/evolve")
print(response.json())  # {"status": "ok", "skills_evolved": 3}

# Check server status
status = httpx.get("http://localhost:8787/status")
print(status.json())
```

### Evolve Server Config (`.env.example`)

```bash
# evolve_server/.env.example
OPENAI_BASE_URL="https://your-api-gateway/v1"
OPENAI_API_KEY="$OPENAI_API_KEY"

STORAGE_BACKEND=oss
OSS_ENDPOINT="$EVOLVE_STORAGE_ENDPOINT"
OSS_BUCKET="$EVOLVE_STORAGE_BUCKET"
OSS_ACCESS_KEY_ID="$OSS_ACCESS_KEY_ID"
OSS_ACCESS_KEY_SECRET="$OSS_ACCESS_KEY_SECRET"

GROUP_ID=production-cluster
EVOLVE_INTERVAL=300
```

## Supported Frameworks

SkillClaw natively integrates with these OpenClaw-compatible frameworks:

- **CoPaw** — collaborative agent framework
- **IronClaw** — robust task execution
- **PicoClaw** — lightweight agents
- **ZeroClaw** — zero-shot agents
- **NanoClaw** — minimal footprint
- **NemoClaw** — NVIDIA NeMo-based agents

Point any framework's OpenAI-compatible API calls at the SkillClaw proxy to start recording sessions.

## Deployment Pattern: Multi-User Cluster

```
User A → Agent (port 8080) ─┐
User B → Agent (port 8081) ─┼──→ Shared OSS Bucket ←── Evolve Server
User C → Agent (port 8082) ─┘         ↑
                                  Skills sync'd
                                  back to all agents
```

```bash
# Each user's machine runs:
skillclaw start --group-id production-cluster --port 8080

# One central server runs:
skillclaw-evolve-server \
  --storage-backend oss \
  --oss-bucket "$SHARED_BUCKET" \
  --group-id production-cluster \
  --interval 300
```

## Troubleshooting

**Proxy won't start:**
```bash
skillclaw status        # Check if already running
skillclaw stop && skillclaw start   # Restart
skillclaw config show   # Verify OPENAI_BASE_URL is set
```

**Skills not syncing:**
```bash
skillclaw skills list-remote   # Verify storage connection
skillclaw config show          # Check storage backend config
# Confirm env vars are exported: echo $OSS_ACCESS_KEY_ID
```

**Evolve server not processing sessions:**
```bash
# Check server logs for cycle output
# Verify --group-id matches the client proxy group-id
# Try --storage-backend local for debugging
skillclaw-evolve-server --storage-backend local --local-storage-path ./debug_storage --group-id debug
```

**Agent evolve server fails to start:**
```bash
which openclaw          # Must be in PATH
npm install -g openclaw # Install if missing
# Verify OPENAI_BASE_URL and OPENAI_API_KEY are set for the agent's LLM
```

**Port already in use:**
```bash
skillclaw stop
lsof -i :8787 | grep LISTEN   # Find conflicting process
skillclaw-evolve-server --port 8788 ...
```

## Project Structure Reference

```
SkillClaw/
├── skillclaw/               # Client proxy, CLI, config
│   ├── cli.py               # All `skillclaw` CLI commands
│   ├── api_server.py        # Proxy server implementation
│   ├── launcher.py          # Process management
│   ├── skill_manager.py     # Local skill CRUD
│   ├── skill_hub.py         # Cloud sync logic
│   └── experiments/         # Benchmark runners
├── evolve_server/           # Workflow evolve server
│   ├── summarizer.py        # Stage 1: session → summary
│   ├── aggregation.py       # Stage 2: summaries → patterns
│   ├── execution.py         # Stage 3: patterns → SKILL.md
│   └── skill_registry.py    # Skill dedup and versioning
├── agent_evolve_server/     # OpenClaw-based evolve server
│   ├── workspace.py         # Session/skill file workspace
│   ├── openclaw_runner.py   # Agent execution harness
│   └── EVOLVE_AGENTS.md     # Agent prompt and tool config
└── scripts/
    ├── install_skillclaw.sh
    ├── install_skillclaw_server.sh
    └── run_wildclawbench_iterative_evolve_agent.py
```