skillclaw-skill-evolution

SkillClaw: Collective Skill Evolution for LLM Agents

Skill by 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

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

Server Deployment

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:

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

skillclaw config show
skillclaw config <key> <value>

CLI Reference

Client Proxy Setup

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

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

skillclaw benchmark --help     # List all benchmark subcommands

Starting the Evolve Servers

Workflow Evolve Server (Summarize → Aggregate → Execute)

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)

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)

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:

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

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.

Python API Usage

Programmatic Skill Sync

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

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

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)

# 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

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

skillclaw status        # Check if already running
skillclaw stop && skillclaw start   # Restart
skillclaw config show   # Verify OPENAI_BASE_URL is set

Skills not syncing:

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:

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

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:

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