repository·main·Indexed 24 days ago
https://github.com/amap-ml/skillclawA system for collective skill evolution in AI agents that intercepts interactions to automatically extract, deduplicate, and improve reusable skills stored as SKILL.md. It features a Client Proxy for intercepting requests and an optional Evolve Server for automating skill creation via workflow or agent engines. SkillClaw supports shared storage (OSS, S3, local) for team collaboration and integrates with frameworks like Hermes, Codex, Claude Code, and any OpenAI-compatible API.
SkillClaw is designed for broad compatibility and natively integrates with several agent frameworks and OpenAI-compatible APIs, including:
The SkillClaw workspace is a structured environment where agent session data is analyzed to evolve a skill library. All file operations must stay within this directory.
sessions/: Contains JSON files of pre-processed agent sessions (input).skills/: The skill library containing skill bundles (input/output).SKILL.md: The entrypoint for a skill.references/, scripts/, assets/: Optional supporting files.history/: Persistent snapshots of previous skill versions and evidence.manifest.json: Read-only reference for the current skill manifest.skill_registry.json: Read-only reference for skill IDs and versions.workspace/
├── EVOLVE_AGENTS.md ← this file (read-only)
├── sessions/ ← input: agent session JSON files to analyze
│ └── <session_id>.json
├── skills/ ← input+output: current skill library
│ └── <skill-name>/
│ ├── SKILL.md ← current version
│ ├── references/ ← optional reference docs / prompts / notes
│ ├── scripts/ ← optional helper scripts / tooling
│ ├── assets/ ← optional templates / binaries / other assets
│ └── history/ ← persistent across rounds
│ ├── v1.md ← previous SKILL.md snapshot
│ └── v1_evidence.md
├── manifest.json ← current skill manifest (read-only)
└── skill_registry.json ← skill ID & version info (read-only)SkillClaw operates using two main components that interact via a shared storage layer (Alibaba OSS, S3, or local filesystem):
/v1/chat/completions and /v1/messages) that intercepts agent requests, records session artifacts, and manages your local skill library. This is the primary component required for basic usage.evolve_server): An optional service that automates skill evolution. It reads session data from shared storage, evolves or creates skills, and writes them back. It supports two engines:workflow: A fixed 3-stage LLM pipeline (Summarize → Aggregate → Execute).agent: An OpenClaw-driven agent workspace that allows for direct skill editing.Deployment Strategies:
skillclaw-evolve-server is run for the group to create a collective evolution loop.When evolving skills, follow these core principles to ensure stability and utility:
improve_skill)SKILL.md as the source of truth, not a draft.create_skill)manifest.json.description field as the main triggering mechanism, including explicit exclusion conditions (e.g., "NOT for: ...").SkillClaw consists of two main components that interact via a shared storage layer (supporting local, oss, or s3):
/v1/chat/completions and /v1/messages) that intercepts Agent requests, records session outputs, and manages your local skill library. This is the minimum requirement to use SkillClaw.evolve_server): An optional service that automates skill evolution by reading session data from shared storage, evolving/creating skills, and writing them back. It supports two engines:workflow: A fixed three-stage LLM process (Summarize $\rightarrow$ Aggregate $\rightarrow$ Execute).agent: An autonomous agent workspace based on OpenClaw that directly edits skill files.skillclaw-evolve-server. All members' experiences contribute to a single evolution loop.SkillClaw operates on a decentralized client-server model designed for collective skill evolution:
skillclaw process and maintains a local configuration at ~/.skillclaw/config.yaml. Users belong to groups identified by a group_id.evolve_server watches specific namespaces (groups). It monitors user sessions, converts them into reusable skills, and writes them back to the shared namespace.Once configured, start the client proxy in daemon mode and verify its health using the configured port.
skillclaw start --daemonskillclaw statusPROXY_PORT="$(skillclaw config proxy.port | awk '{print $2}')"
curl "http://127.0.0.1:${PROXY_PORT}/healthz"Note: The default port is 30000. You can inspect active settings with skillclaw config show.
skillclaw start --daemon
skillclaw statusTo use SkillClaw as a local proxy for your agent, install it from the repository. Choose the command based on your operating system.
git clone https://github.com/AMAP-ML/SkillClaw.git && cd SkillClaw
bash scripts/install_skillclaw.sh
source .venv/bin/activateSince there is no native .ps1 script, perform a manual installation:
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]"bash
git clone https://github.com/AMAP-ML/SkillClaw.git && cd SkillClaw
bash scripts/install_skillclaw.sh
source .venv/bin/activateRun the skillclaw setup command to initialize your configuration. The wizard will prompt you for:
~/.skillclaw/skills. Note that if using Hermes, Codex, or Claude Code, the default changes to ~/.hermes/skills, ~/.codex/skills, or ~/.claude/skills respectively.local shared storage if you plan to run an evolve server on the same machine (e.g., using ~/.skillclaw/local-share).skillclaw setupYou can optionally turn your client into a background validation node. This allows the group to use a "validated" publishing mode where candidate skills are reviewed by clients before being officially added to the shared directory.
Configuration:
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 5Commands:
skillclaw validation status: Check validation status.skillclaw validation run-once --force: Manually trigger a validation run immediately.Once configured, the validator runs automatically when you execute skillclaw start --daemon and the client is idle.
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 --forceEvery action taken to evolve a skill (create_skill, improve_skill, or optimize_description) must leave a history trail in the skills/<skill-name>/history/ directory. This acts as an evolution ledger to prevent reverting past improvements or contradicting previous evidence-based decisions.
improve_skill and optimize_description:skills/<skill-name>/history/. If it exists, you must read every v*.md and v*_evidence.md file to understand the full change trajectory.SKILL.md content verbatim to history/v<N>.md (where N is the current round number).history/v<N>_evidence.md documenting the decision drivers (session IDs, PRM scores, failure patterns, etc.).SKILL.md file.create_skill:history/v0_evidence.md explaining the motivation for creation (session IDs, failure patterns, and why no existing skill covers this pattern).SKILL.md.v<N>.md and v<N>_evidence.md.2026-04-04.md or notes.md).v1.md and its evidence is v1_evidence.md.skills/<skill-name>/history/
├── v0_evidence.md ← why this skill was created (for create_skill)
├── v1.md ← SKILL.md snapshot before round 1 edit
├── v1_evidence.md ← sessions/feedback that drove the v1→v2 change
├── v2.md ← SKILL.md snapshot before round 2 edit
├── v2_evidence.md
└── ...SkillClaw provides a shell installer for macOS and Linux. For Windows users, a manual Python installation path is required. After installation, you must initialize the setup and start the daemon to begin intercepting agent requests.
To get started, run:
skillclaw setup
skillclaw start --daemon