✨ SkillClaw: Let Skills Evolve Collectively with Agentic Evolver ✨

Evolve distributed AI agent clusters in production — just talk.
Experience auto-distilled. Skills keep growing. Collective intelligence shared in real time.

🚀 Quick Install	💬 Just Chat	🔌 Broad Compatibility	🧬 Collective Skill Evolution

From Experience Silos to Collective Evolution

How a Skill Evolves

N users, one Skill, continuous evolution. Every conversation compounds. Every user contributes.

News

• 2026/04/14 — WeChat discussion group is live! Join the group to chat with us.
• 2026/04/14 — Seamless integration with Hermes is now available.
• 2026/04/12 — Active discussion with Deer-Flow on cross-framework skill sharing.
• 2026/04/11 — SkillClaw ranked #2 Paper of the Day on Hugging Face Daily Papers!
• 2026/04/10 — SkillClaw is now open source! Code released on GitHub.

Overview

SkillClaw makes LLM agents progressively better by evolving reusable skills from real session data and sharing them across a group of agents.

The system has two components:

1. Client Proxy — A local API proxy (/v1/chat/completions, /v1/messages) that intercepts agent requests, records session artifacts, and syncs skills with shared storage.

2. Evolve Server (evolve_server) — A single evolve service that reads session data from shared storage, evolves or creates skills, and writes them back. It supports two engines:

   • workflow: fixed 3-stage LLM pipeline (Summarize → Aggregate → Execute)
   • agent: OpenClaw-driven agent workspace with direct skill editing

Both components share the same storage layer (Alibaba OSS / S3 / local filesystem) and skill format (SKILL.md).

Deployment Model

Think of SkillClaw as "per-user client, per-group evolver":

1. Every user runs a local skillclaw client proxy on their own machine.
2. One shared group usually runs one skillclaw-evolve-server.
3. The client side and server side only meet through shared storage (local, oss, or s3).

This separation is the key beginner mental model:

• If you only want to use SkillClaw yourself, install the client first. You can add an evolve server later.
• If you want to join an existing team, you still install only the client. You do not run the evolve server unless you are operating the shared group.
• The evolve server can run on the same laptop, a remote VM, or any machine that can access the shared storage and upstream LLM endpoint.

User Guide

If this is your first time, start with Path A. It proves the client-side install and usage first, without mixing in shared deployment concerns.

Prerequisites

• macOS, Linux, or Windows
• Python >= 3.10
• A provider account that exposes an OpenAI-compatible API, or AWS Bedrock
• Install openclaw only if you intentionally choose the openclaw CLI integration or the server agent engine

The beginner path below is locally smoke-tested on macOS.

Path A: Run SkillClaw for yourself on one machine

1. Install SkillClaw from this repository. If you already have the source checkout, skip git clone.

macOS / Linux:

git clone https://github.com/AMAP-ML/SkillClaw.git && cd SkillClaw
bash scripts/install_skillclaw.sh
source .venv/bin/activate

Windows PowerShell (manual install because the repository does not currently ship a native .ps1 installer):

git clone https://github.com/AMAP-ML/SkillClaw.git
Set-Location SkillClaw
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -U pip
python -m pip install -e ".[evolve,sharing,server]"

1. Generate a local config.

skillclaw setup

The setup wizard prompts for the provider, model, local skills directory, PRM settings, optional CLI agent integration, and optional shared storage.

For a minimal first run:

• choose none for the CLI agent if you do not want SkillClaw to auto-configure an external agent yet
• local skills at ~/.skillclaw/skills
• disable shared storage if you only want to use the local proxy first
• enable local shared storage only if you want to add the evolve server later on the same machine, and use a dedicated root such as ~/.skillclaw/local-share
• disable PRM if you want the cheapest first pass

1. Start the client proxy and verify that it is healthy.

skillclaw start --daemon
skillclaw status
PROXY_PORT="$(skillclaw config proxy.port | awk '{print $2}')"
curl "http://127.0.0.1:${PROXY_PORT}/healthz"

The default proxy port is 30000, but the health check should follow your configured proxy.port. Use skillclaw config show to inspect the active upstream model, proxy port, and sharing target.

At this point SkillClaw is already usable as a single-user local proxy. You do not need to run an evolve server just to use the client.

If you later want automatic skill evolution for yourself, keep the same client install and continue with Server Guide.

Hermes Integration

If you already use Hermes, the client-side path is:

1. Install Hermes first.
2. Run skillclaw setup and choose hermes for CLI agent to configure.
3. Keep Proxy model name exposed to agents as skillclaw-model unless you have a specific reason to change it.
4. Start SkillClaw. On startup, SkillClaw rewrites ~/.hermes/config.yaml to point Hermes at the local proxy.

Minimal verification:

skillclaw start --daemon
hermes chat -Q -m skillclaw-model -q "Reply with exactly HERMES_SKILLCLAW_OK and nothing else."

Path B: Join an existing shared group

Install the same client as in Path A, then point your local client at the group's shared storage. The easiest beginner route is to rerun skillclaw setup, enable shared storage, and fill in the values your server operator gives you.

You can also set the keys directly. Example for OSS:

skillclaw config sharing.enabled true
skillclaw config sharing.backend oss
skillclaw config sharing.endpoint https://oss-cn-hangzhou.aliyuncs.com
skillclaw config sharing.bucket my-skillclaw-bucket
skillclaw config sharing.access_key_id "$OSS_ACCESS_KEY_ID"
skillclaw config sharing.secret_access_key "$OSS_ACCESS_KEY_SECRET"
skillclaw config sharing.group_id my-group
skillclaw config sharing.user_alias alice
skillclaw config sharing.auto_pull_on_start true

skillclaw start --daemon
skillclaw skills pull

If your team uses a mounted local shared directory instead of OSS/S3, use sharing.backend local plus sharing.local_root /path/to/shared/root instead of the remote storage keys.

When you join a shared group:

• you still run only the local client proxy on your machine
• you do not run skillclaw-evolve-server unless you are also operating the shared group
• moving from single-user to multi-user is mostly a sharing-config change on the client side

Optional: turn one client into a background validation worker

This mode is optional and disabled by default. It is meant for groups that want a second review step before a workflow-generated skill is published.

What it does:

• the server stages a candidate skill as a validation job instead of publishing it immediately
• an opted-in client picks up jobs only when its local proxy is idle
• the client validates the candidate skill in the background and writes back a result
• a later evolve cycle publishes the candidate only after the configured thresholds are met

If validation.enabled stays false, normal client usage is unchanged.

Minimal client-side setup:

skillclaw config validation.enabled true
skillclaw config validation.idle_after_seconds 300
skillclaw config validation.poll_interval_seconds 60
skillclaw config validation.max_jobs_per_day 5

skillclaw validation status
skillclaw validation run-once --force

skillclaw start --daemon will automatically run the background validator afterward. run-once --force is the quickest way to test the path without waiting for the idle timer.

Server Guide

The evolve server is the shared backend for one user or many users. It can run locally for a personal setup, or remotely for a team setup.

Run one evolve server for a single-user local loop

This is the smallest full closed loop: one user, one machine, one local shared root, one evolve server.

This step assumes your client config already enabled local shared storage during skillclaw setup.

skillclaw-evolve-server --use-skillclaw-config --interval 300 --port 8787

Optional: inspect the shared skill store afterward.

skillclaw skills list-remote

What this gives you:

• one user
• one machine
• no OSS/S3 account
• the full loop: session capture -> skill evolution -> local skill reuse

Run one evolve server for a shared group on OSS or S3

Run this on any machine that can reach the shared storage and the upstream LLM API. It does not need to be an end-user laptop.

macOS / Linux:

git clone https://github.com/AMAP-ML/SkillClaw.git && cd SkillClaw
bash scripts/install_skillclaw_server.sh
source .venv-server/bin/activate
cp evolve_server/evolve_server.env.example evolve_server/.env

Windows PowerShell (manual install because the repository does not currently ship a native .ps1 installer):

git clone https://github.com/AMAP-ML/SkillClaw.git
Set-Location SkillClaw
python -m venv .venv-server
.\.venv-server\Scripts\Activate.ps1
python -m pip install -U pip
python -m pip install -e ".[server]"
Copy-Item .\evolve_server\evolve_server.env.example .\evolve_server\.env

Then fill in evolve_server/.env, or pass the same values on the CLI. Example for the default workflow engine:

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

By default, the workflow engine uploads accepted evolution outputs directly to the shared skill store at {group_id}/skills/<name>/SKILL.md.

If you want a staged publish flow where opted-in clients review candidates before they reach skills/, switch the server to validated publish mode:

EVOLVE_PUBLISH_MODE=validated \
EVOLVE_VALIDATION_REQUIRED_RESULTS=1 \
EVOLVE_VALIDATION_REQUIRED_APPROVALS=1 \
EVOLVE_VALIDATION_MIN_MEAN_SCORE=0.75 \
EVOLVE_VALIDATION_MAX_REJECTIONS=1 \
skillclaw-evolve-server --port 8787 --interval 300 \
  --storage-backend oss \
  --oss-endpoint "$EVOLVE_STORAGE_ENDPOINT" \
  --oss-bucket "$EVOLVE_STORAGE_BUCKET" \
  --group-id my-group

If you want the agent engine on the server side, install openclaw there and then run:

npm install -g openclaw

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

Only the server operator needs openclaw for --engine agent.

Quick Reference

Operational model — Every user has their own skillclaw process and ~/.skillclaw/config.yaml. Each group maps to a group_id; one evolve server watches that namespace, turns sessions into skills, and writes them back. Joining a group only requires the correct sharing config on the client side.

First-run checks

Skill management

skillclaw skills pull          # download shared skills
skillclaw skills push          # upload local skills
skillclaw skills sync          # bidirectional
skillclaw skills list-remote   # browse shared skills

Config reference

• Client config: ~/.skillclaw/config.yaml (created by skillclaw setup)
• Server template: evolve_server/evolve_server.env.example (copy to .env to use)
• Inspect / update config: skillclaw config show | skillclaw config <key> <value>
• Repo entry points for contributors: skillclaw/ (client), evolve_server/ (backend), scripts/ (installers)

Acknowledgement

The repo is built upon these open-source repos.

MetaClaw - Just talk to your agent — it learns and evolves

WildClawBench - Can an AI agent do real work, end-to-end, without hand-holding

OpenClaw-RL - Train a personalized agent simply by talking to it

Contributing

SkillClaw is a community-driven project. We welcome contributions of all kinds — bug reports, feature requests, new skills, documentation improvements, and more. Feel free to open an issue or submit a pull request!

Citation

If you find SkillClaw useful in your research, please consider citing our paper:

@article{ma2026skillclaw,
  title={SkillClaw: Let Skills Evolve Collectively with Agentic Evolver},
  author={Ma, Ziyu and Yang, Shidong and Ji, Yuxiang and Wang, Xucong and Wang, Yong and Hu, Yiming and Huang, Tongwen and Chu, Xiangxiang},
  journal={arXiv preprint arXiv:2604.08377},
  year={2026}
}

License

See LICENSE for details.