### Install SkillClaw and Setup Wizard

Source: https://context7.com/amap-ml/skillclaw/llms.txt

Installs SkillClaw from source and runs an interactive setup wizard to generate a local configuration file.

```bash
# macOS / Linux — quick install
git clone https://github.com/AMAP-ML/SkillClaw.git && cd SkillClaw
bash scripts/install_skillclaw.sh
source .venv/bin/activate

# Windows PowerShell — manual install
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]"

# Configure interactively — prompts for provider, model, skills dir, sharing, PRM
skillclaw setup

# Start the proxy as a background daemon and verify health
skillclaw start --daemon
skillclaw status
curl http://127.0.0.1:30000/healthz
# {"ok": true}
```

--------------------------------

### Install and Start SkillClaw Server with Default Workflow Engine

Source: https://context7.com/amap-ml/skillclaw/llms.txt

Installs server dependencies, sets up the environment, and starts the SkillClaw server with the default 3-stage workflow engine. Requires OSS credentials for storage.

```bash
bash scripts/install_skillclaw_server.sh
source .venv-server/bin/activate
cp evolve_server/evolve_server.env.example evolve_server/.env
# Edit .env with storage credentials

# Start with default workflow engine (3-stage: 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-team
```

--------------------------------

### Setup SkillClaw Configuration

Source: https://github.com/amap-ml/skillclaw/blob/main/README.md

Runs the SkillClaw setup wizard to configure provider, model, storage, and other settings. Follow the prompts for a minimal or customized setup.

```bash
skillclaw setup
```

--------------------------------

### Run SkillClaw Evolve Server (Agent Engine)

Source: https://github.com/amap-ml/skillclaw/blob/main/README.md

Starts the SkillClaw evolve server using the 'agent' engine. This requires installing `openclaw` globally on the server. Configure `.env` or use CLI arguments for storage, group ID, and other parameters.

```bash
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
```

--------------------------------

### Start SkillClaw Server with Agent Engine

Source: https://context7.com/amap-ml/skillclaw/llms.txt

Starts the SkillClaw server using the 'agent' engine, which requires OpenClaw to be installed on the server. Uses OSS for storage and does not perform a fresh data pull.

```bash
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-team
```

--------------------------------

### SkillClaw Setup

Source: https://context7.com/amap-ml/skillclaw/llms.txt

The `skillclaw setup` command initiates an interactive wizard for configuring SkillClaw, including LLM provider, API details, skills directory, and optional integrations.

```APIDOC
## CLI: `skillclaw setup`

Interactive first-time configuration wizard that generates `~/.skillclaw/config.yaml` and optionally auto-configures Hermes, Codex, or Claude Code to point at the local proxy.

```bash
# Run setup — answers the following prompts:
#   1. LLM provider (openai / openrouter / bedrock)
#   2. Upstream API base URL and model
#   3. Skills directory (default: ~/.skillclaw/skills or agent-specific)
#   4. CLI agent to integrate (none / hermes / codex / claude)
#   5. Shared storage (local / oss / s3 / none)
#   6. PRM scoring (enabled / disabled)
skillclaw setup

# After setup, inspect the generated config
skillclaw config show
# Config file: /Users/alice/.skillclaw/config.yaml
#
# proxy.port: 30000
# proxy.host: 0.0.0.0
# llm.provider: openai
# llm.api_base: https://api.openai.com/v1
# llm.model_id: gpt-4o
# skills.dir: /Users/alice/.skillclaw/skills
# sharing.enabled: false
```
```

--------------------------------

### SKILL.md Frontmatter and Content Example

Source: https://context7.com/amap-ml/skillclaw/llms.txt

An example of a SKILL.md file, showing the YAML frontmatter with name, description, and metadata, followed by markdown content detailing when to use the skill and its process.

```markdown
---
name: debug-systematically
description: "Use when diagnosing a bug or unexpected behavior. Gather evidence
before forming hypotheses. NOT for: simple typo fixes or greenfield code."
metadata:
  {
    "openclaw": { "emoji": "🔍" },
    "skillclaw": { "category": "coding" }
  }
---

# Debug Systematically

## When to use
Trigger this skill when you see an error message, unexpected output, or a failing
test and you are not immediately sure of the root cause.

## Process
1. **Reproduce** — confirm you can trigger the bug consistently.
2. **Isolate** — narrow the failure to the smallest possible input.
3. **Hypothesize** — form at most two hypotheses before looking at code.
4. **Verify** — add a targeted log or assertion to confirm or disprove each.
5. **Fix** — apply the minimal change that makes the test pass.

## Don'ts
- Do NOT start editing code before you can reproduce the bug.
- Do NOT add multiple changes in one commit when debugging.
```

--------------------------------

### Install SkillClaw on macOS/Linux

Source: https://github.com/amap-ml/skillclaw/blob/main/README.md

Installs SkillClaw from the repository and activates the virtual environment. Ensure you have Python 3.10+ and Git installed.

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

--------------------------------

### Install and Configure Hermes Integration

Source: https://context7.com/amap-ml/skillclaw/llms.txt

Steps to install SkillClaw, configure it with Hermes, and verify the integration.

```bash
skillclaw setup   # select "hermes" at "CLI agent to configure" prompt
```

```bash
skillclaw start --daemon
```

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

--------------------------------

### Install SkillClaw Server on macOS/Linux

Source: https://github.com/amap-ml/skillclaw/blob/main/README.md

Installs the SkillClaw server and its dependencies on macOS and Linux systems. Requires cloning the repository, running an install script, and activating a virtual environment.

```bash
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
```

--------------------------------

### SKILL.md File Structure Example

Source: https://context7.com/amap-ml/skillclaw/llms.txt

Demonstrates the canonical directory structure for a skill, including the required SKILL.md file and optional subdirectories for references, scripts, and assets.

```bash
# Valid skill directory structure
~/.skillclaw/skills/
└── debug-systematically/
    ├── SKILL.md           # required — YAML frontmatter + markdown body
    ├── references/        # optional — reference docs, API specs
    │   └── error-codes.md
    ├── scripts/           # optional — helper scripts
    │   └── repro.sh
    ├── assets/            # optional — templates, images
    └── history/           # maintained by evolve server
        ├── v1.md
        └── v1_evidence.md
```

--------------------------------

### Install SkillClaw Server on Windows PowerShell

Source: https://github.com/amap-ml/skillclaw/blob/main/README.md

Installs the SkillClaw server and its dependencies on Windows using PowerShell. This involves cloning the repository, setting up a Python virtual environment, installing dependencies, and copying the environment file.

```powershell
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
```

--------------------------------

### CLI: skillclaw setup

Source: https://context7.com/amap-ml/skillclaw/llms.txt

Runs the interactive first-time configuration wizard. It prompts for LLM provider, API details, skills directory, CLI agent integration, shared storage, and PRM scoring.

```bash
# Run setup — answers the following prompts:
#   1. LLM provider (openai / openrouter / bedrock)
#   2. Upstream API base URL and model
#   3. Skills directory (default: ~/.skillclaw/skills or agent-specific)
#   4. CLI agent to integrate (none / hermes / codex / claude)
#   5. Shared storage (local / oss / s3 / none)
#   6. PRM scoring (enabled / disabled)
skillclaw setup

# After setup, inspect the generated config
skillclaw config show
# Config file: /Users/alice/.skillclaw/config.yaml
#
# proxy.port: 30000
# proxy.host: 0.0.0.0
# llm.provider: openai
# llm.api_base: https://api.openai.com/v1
# llm.model_id: gpt-4o
# skills.dir: /Users/alice/.skillclaw/skills
# sharing.enabled: false
```

--------------------------------

### Run Evolve Server

Source: https://context7.com/amap-ml/skillclaw/llms.txt

Commands to start the `skillclaw-evolve-server` for personal or team use. Shows options for using SkillClaw config, setting interval and port, and inspecting the skill store.

```bash
# --- Personal use: single-user local loop ---
# Requires: client config already uses local shared storage
skillclaw-evolve-server --use-skillclaw-config --interval 300 --port 8787

# Inspect the resulting shared skill store
skillclaw skills list-remote

# --- Team use: OSS / S3 shared backend ---

```

--------------------------------

### History Directory Structure Example

Source: https://github.com/amap-ml/skillclaw/blob/main/evolve_server/engines/EVOLVE_AGENTS.md

Illustrates the expected file and directory structure for maintaining skill history. Each version of a skill is accompanied by an evidence file detailing the rationale for changes.

```bash
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
└── ...
```

--------------------------------

### Start SkillClaw Server with Staged Publish

Source: https://context7.com/amap-ml/skillclaw/llms.txt

Starts the SkillClaw server with staged publishing enabled, requiring client validation before publishing. Configures validation parameters for results, approvals, mean score, and rejections.

```bash
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-team
```

--------------------------------

### Run SkillClaw Evolve Server (Default Workflow)

Source: https://github.com/amap-ml/skillclaw/blob/main/README.md

Starts the SkillClaw evolve server using the default 'workflow' engine. This configuration uploads accepted evolution outputs directly to the shared skill store. Requires filling in the `.env` file or providing CLI arguments for storage and group ID.

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

--------------------------------

### Start and Check SkillClaw Client Proxy

Source: https://github.com/amap-ml/skillclaw/blob/main/README.md

Starts the SkillClaw client proxy as a daemon and checks its status. It then retrieves the proxy port and performs a health check using curl.

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

--------------------------------

### CLI: skillclaw start/stop/status

Source: https://context7.com/amap-ml/skillclaw/llms.txt

Manages the local proxy daemon. Use `start` to run it, `stop` to halt it, and `status` to check its health and operational details.

```bash
# Start the proxy in the foreground
skillclaw start

# Start as a background daemon (recommended for normal use)
skillclaw start --daemon

# Start on a non-default port for this session only
skillclaw start --daemon --port 30001

# Stop the running daemon
skillclaw stop

# Check health — reports PID, port, and proxy readiness
skillclaw status
# SkillClaw: running  (PID=12345, proxy=:30000)

# Environment variable: override the wait-for-ready timeout (default 15 s)
SKILLCLAW_DAEMON_READY_TIMEOUT_S=30 skillclaw start --daemon
```

--------------------------------

### Install SkillClaw on Windows PowerShell

Source: https://github.com/amap-ml/skillclaw/blob/main/README.md

Installs SkillClaw using Python's virtual environment and pip on Windows. Requires Python 3.10+ and Git.

```powershell
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]"
```

--------------------------------

### Chat Completions with Session Tracking

Source: https://context7.com/amap-ml/skillclaw/llms.txt

This example demonstrates sending explicit session tracking headers for requests. This is typically handled automatically by clients like OpenClaw and Hermes.

```bash
PROXY_PORT=30000

# With explicit session tracking (sent by OpenClaw and Hermes automatically)
curl -s http://127.0.0.1:${PROXY_PORT}/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-Session-Id: session-abc123" \
  -H "X-Turn-Type: main" \
  -d '{
    "model": "skillclaw-model",
    "stream": false,
    "messages": [
      {"role": "system", "content": "You are a coding assistant."},
      {"role": "user", "content": "Debug this Python error: AttributeError: ..."}
    ]
  }'
```

--------------------------------

### Run SkillClaw Evolve Server (Validated Publish Mode)

Source: https://github.com/amap-ml/skillclaw/blob/main/README.md

Starts the SkillClaw evolve server in 'validated' publish mode for a staged review flow. This requires setting environment variables for validation criteria before candidates reach the main skill store. Configure `.env` or use CLI arguments.

```bash
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
```

--------------------------------

### SkillClaw Start/Stop/Status

Source: https://context7.com/amap-ml/skillclaw/llms.txt

Commands to manage the SkillClaw proxy daemon, allowing users to start, stop, and check the status of the local proxy.

```APIDOC
## CLI: `skillclaw start` / `skillclaw stop` / `skillclaw status`

Start or stop the local proxy daemon; check whether it is running and healthy.

```bash
# Start the proxy in the foreground
skillclaw start

# Start as a background daemon (recommended for normal use)
skillclaw start --daemon

# Start on a non-default port for this session only
skillclaw start --daemon --port 30001

# Stop the running daemon
skillclaw stop

# Check health — reports PID, port, and proxy readiness
skillclaw status
# SkillClaw: running  (PID=12345, proxy=:30000)

# Environment variable: override the wait-for-ready timeout (default 15 s)
SKILLCLAW_DAEMON_READY_TIMEOUT_S=30 skillclaw start --daemon
```
```

--------------------------------

### Run SkillClaw Evolve Server for Single-User Local Loop

Source: https://github.com/amap-ml/skillclaw/blob/main/README.md

Run the SkillClaw evolve server for a single-user local setup. This command assumes local shared storage is already enabled in the client configuration.

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

--------------------------------

### Verify Hermes Integration with SkillClaw

Source: https://github.com/amap-ml/skillclaw/blob/main/README.md

Starts the SkillClaw client and then uses Hermes to send a query to the 'skillclaw-model'. This verifies that Hermes is correctly configured to use the SkillClaw proxy.

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

--------------------------------

### GET /v1/models

Source: https://context7.com/amap-ml/skillclaw/llms.txt

Lists the models served by the local proxy, used by agent frameworks to discover available models.

```APIDOC
## GET /v1/models

### Description
Lists the model served by the local proxy; used by agent frameworks to discover available models.

### Method
GET

### Endpoint
/v1/models

### Response Example
```json
{
  "object": "list",
  "data": [
    {
      "id": "skillclaw-model",
      "object": "model",
      "created": 0,
      "owned_by": "skillclaw"
    }
  ]
}
```

### Request Example
```bash
curl -s http://127.0.0.1:${PROXY_PORT}/v1/models | python3 -m json.tool
```
```

--------------------------------

### Configure SkillClaw Client for OSS Sharing

Source: https://context7.com/amap-ml/skillclaw/llms.txt

Configures the SkillClaw client to synchronize with an existing group's shared storage using OSS. This setup does not require an evolve server on the client side.

```bash
# Configure OSS sharing and join a group
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
# Pulling skills from oss storage (my-skillclaw-bucket/my-group) ...
# Done: 20 downloaded, 0 unchanged, 0 deleted, 20 total remote skills.
```

--------------------------------

### GET /healthz

Source: https://context7.com/amap-ml/skillclaw/llms.txt

A liveness probe endpoint for the SkillClaw local proxy. It returns `{"ok": true}` when the proxy is operational and ready to receive requests.

```APIDOC
## REST API: `GET /healthz`

Liveness probe for the local proxy; returns `{"ok": true}` when the proxy is ready to accept requests.

```bash
PROXY_PORT=30000

# Health check
curl http://127.0.0.1:${PROXY_PORT}/healthz
# {"ok":true}

# Also useful in CI or scripts to wait until the proxy is ready:
until curl -sf http://127.0.0.1:${PROXY_PORT}/healthz > /dev/null; do sleep 0.5; done
echo "Proxy ready"
```
```

--------------------------------

### REST API: GET /healthz

Source: https://context7.com/amap-ml/skillclaw/llms.txt

A liveness probe for the local proxy. It returns `{"ok": true}` when the proxy is ready to accept requests, useful for CI/CD pipelines or scripts to check readiness.

```bash
PROXY_PORT=30000

# Health check
curl http://127.0.0.1:${PROXY_PORT}/healthz
# {"ok":true}

# Also useful in CI or scripts to wait until the proxy is ready:
until curl -sf http://127.0.0.1:${PROXY_PORT}/healthz > /dev/null; do sleep 0.5; done
echo "Proxy ready"
```

--------------------------------

### Initialize and Use SkillHub

Source: https://context7.com/amap-ml/skillclaw/llms.txt

Demonstrates how to initialize SkillHub using either a SkillClaw configuration or direct parameters for OSS. Shows basic operations like pulling, pushing, and syncing skills.

```python
from skillclaw.skill_hub import SkillHub
from skillclaw.config_store import ConfigStore

# Build a hub from the active SkillClaw config
cfg = ConfigStore().to_skillclaw_config()
hub = SkillHub.from_config(cfg)

# Or construct directly for OSS
hub = SkillHub(
    backend="oss",
    endpoint="https://oss-cn-hangzhou.aliyuncs.com",
    bucket="my-skillclaw-bucket",
    access_key_id="AKIDxxx",
    secret_access_key="secretxxx",
    group_id="my-team",
    user_alias="alice",
)

# Pull all remote skills into a local directory (full mirror with backup + rollback)
result = hub.pull_skills("/Users/alice/.skillclaw/skills")
print(result)
# {
#   "downloaded": 5, "skipped": 10, "deleted": 1,
#   "total_remote": 15, "restored_from_backup": False, "backup_dir": "..."
# }

# Incremental pull (no local deletions)
result = hub.pull_skills("/Users/alice/.skillclaw/skills", mirror=False)

# Pull specific skills only
result = hub.pull_skills(
    "/Users/alice/.skillclaw/skills",
    include_names={"debug-systematically", "write-unit-tests"},
)

# Push local skills (with quality gate: min 5 injections, 0.3 effectiveness)
import json, os
stats_path = "/Users/alice/.skillclaw/skills/skill_stats.json"
stats = json.load(open(stats_path)) if os.path.exists(stats_path) else {}
result = hub.push_skills(
    "/Users/alice/.skillclaw/skills",
    skill_filter={"stats": stats, "min_injections": 5, "min_effectiveness": 0.3},
)
print(result)
# {"uploaded": 2, "skipped": 13, "filtered": 1, "total_local": 16}

# Bidirectional sync
result = hub.sync_skills("/Users/alice/.skillclaw/skills")
print(result["pull"], result["push"])

# List all remote skills
remote = hub.list_remote()
for s in remote:
    print(s["name"], s.get("description", ""))
```

--------------------------------

### GET /v1/responses/{response_id}

Source: https://context7.com/amap-ml/skillclaw/llms.txt

Retrieves a specific stored response from the API.

```APIDOC
## GET /v1/responses/{response_id}

### Description
Retrieve a stored response using its ID.

### Method
GET

### Endpoint
/v1/responses/{response_id}

### Request Example
```bash
curl -s http://127.0.0.1:${PROXY_PORT}/v1/responses/resp_abc123
```
```

--------------------------------

### Initialize SkillManager with Template Mode

Source: https://context7.com/amap-ml/skillclaw/llms.txt

Initializes the SkillManager for zero-latency, effectiveness-ranked skill retrieval.

```python
from skillclaw.skill_manager import SkillManager

# Initialize with template mode (zero-latency, effectiveness-ranked)
manager = SkillManager(
    skills_dir="/Users/alice/.skillclaw/skills",
    retrieval_mode="template",
)
```

--------------------------------

### Manage Skills: Pull, Push, and Sync

Source: https://context7.com/amap-ml/skillclaw/llms.txt

Commands for synchronizing local skills with cloud storage (OSS, S3). Use 'pull' to download, 'push' to upload, and 'sync' for bidirectional synchronization.

```bash
# Pull shared skills from cloud → overwrites local with the full remote snapshot
skillclaw skills pull
```

```bash
# Push local skills to cloud (applies effectiveness quality gate by default)
skillclaw skills push
```

```bash
# Push without quality gate
skillclaw skills push --no-filter
```

```bash
# Bidirectional sync (pull then push, incremental — no local deletes)
skillclaw skills sync
```

--------------------------------

### Get Skill Counts

Source: https://context7.com/amap-ml/skillclaw/llms.txt

Retrieves the total number of skills managed by the SkillManager.

```python
# Get skill counts
counts = manager.get_skill_count()
```

--------------------------------

### Build OpenClaw-Compatible Skill Catalog

Source: https://context7.com/amap-ml/skillclaw/llms.txt

Generates an XML-formatted skill catalog suitable for injection into agent system prompts.

```python
# Build an OpenClaw-compatible XML skill catalog for injection
prompt = manager.build_injection_prompt(max_chars=30_000)
# Returns:
# ## Skills (mandatory)
# Before replying: scan <available_skills> <description> entries.
# ...
# <available_skills>
#   <skill>
#     <name>debug-systematically</name>
#     <description>...</description>
#     <location>/Users/alice/.skillclaw/skills/debug-systematically/SKILL.md</location>
#   </skill>
# </available_skills>
```

--------------------------------

### List Available Models

Source: https://context7.com/amap-ml/skillclaw/llms.txt

This endpoint lists the models served by the local proxy, which is essential for agent frameworks to discover available models. Ensure the PROXY_PORT is set.

```bash
PROXY_PORT=30000

curl -s http://127.0.0.1:${PROXY_PORT}/v1/models | python3 -m json.tool
# {
#   "object": "list",
#   "data": [
#     {
#       "id": "skillclaw-model",
#       "object": "model",
#       "created": 0,
#       "owned_by": "skillclaw"
#     }
#   ]
# }
```

--------------------------------

### Workspace Layout

Source: https://github.com/amap-ml/skillclaw/blob/main/evolve_server/engines/EVOLVE_AGENTS.md

Illustrates the directory structure of the SkillClaw workspace, including input and output directories for agent sessions and skills.

```bash
workspace/
├── EVOLVE_AGENTS.md       ← this file (read-only)
├── sessions/              ← input: agent session JSON files to analyze (refreshed each round)
│   └── <session_id>.json
├── skills/                ← input+output: current skill library
│   └── <skill-name>/
│       ├── SKILL.md       ← current version (refreshed from storage each round)
│       ├── references/    ← optional reference docs / prompts / notes
│       ├── scripts/       ← optional helper scripts / tooling
│       ├── assets/        ← optional templates / binaries / other assets
│       └── history/       ← persistent across rounds only in `--no-fresh` mode
│           ├── v1.md      ← previous SKILL.md snapshot
│           ├── v1_evidence.md
│           ├── v2.md
│           ├── v2_evidence.md
│           └── ...
├── manifest.json          ← current skill manifest (read-only reference)
└── skill_registry.json    ← skill ID & version info (read-only reference)
```

--------------------------------

### Sync and Serve SkillClaw Dashboard

Source: https://github.com/amap-ml/skillclaw/blob/main/README.md

Synchronize the local SkillClaw snapshot and serve the dashboard for visualization. The dashboard helps inspect local skills, validation jobs, and shared skill history.

```bash
skillclaw dashboard sync
skillclaw dashboard serve
```

--------------------------------

### Configure SkillClaw Client for Local Sharing

Source: https://context7.com/amap-ml/skillclaw/llms.txt

Configures the SkillClaw client to synchronize with a shared group using a local directory as the storage backend. This is an alternative to using OSS/S3 for shared storage.

```bash
# For a local shared directory instead of OSS/S3
skillclaw config sharing.backend local
skillclaw config sharing.local_root /mnt/team-share
skillclaw config sharing.group_id my-group
```

--------------------------------

### Manage SkillClaw Dashboard

Source: https://context7.com/amap-ml/skillclaw/llms.txt

Commands for syncing the dashboard's SQLite database and serving the web UI. Includes options for custom host/port, skipping sync, and specifying sharing configurations.

```bash
# Sync the dashboard SQLite database from local + shared storage
skillclaw dashboard sync
# Dashboard snapshot synced: 15 skills, 42 sessions, 3 validation jobs.
# SQLite: /Users/alice/.skillclaw/dashboard.db

# Serve the dashboard UI (syncs on startup by default)
skillclaw dashboard serve
# Starting SkillClaw dashboard at http://127.0.0.1:3788 (db: ~/.skillclaw/dashboard.db)
# Open http://127.0.0.1:3788 in a browser

# Custom host/port and skip re-sync (use previously synced data)
skillclaw dashboard serve --host 0.0.0.0 --port 3791 --no-sync-on-start

# Use a local shared root and a specific group (useful for team deployments)
skillclaw dashboard sync \
  --sharing-local-root /path/to/shared/root \
  --sharing-group-id my-team \
  --sharing-user-alias alice

skillclaw dashboard serve \
  --host 127.0.0.1 \
  --port 3791 \
  --sharing-local-root /path/to/shared/root \
  --sharing-group-id my-team \
  --sharing-user-alias alice

# Then open: http://127.0.0.1:3791
```

--------------------------------

### POST /v1/chat/completions

Source: https://context7.com/amap-ml/skillclaw/llms.txt

OpenAI-compatible chat completions endpoint. It injects skills into the system prompt, forwards requests to the upstream LLM, and records the session turn. Accepts standard OpenAI request bodies and optional SkillClaw session headers.

```APIDOC
## POST /v1/chat/completions

### Description
OpenAI-compatible chat completions endpoint. The proxy injects skills into the system prompt, forwards the request to the upstream LLM, and records the session turn. Accepts standard OpenAI request bodies plus optional SkillClaw session headers.

### Method
POST

### Endpoint
/v1/chat/completions

### Request Example
```bash
curl -s http://127.0.0.1:${PROXY_PORT}/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "skillclaw-model",
    "messages": [
      {"role": "user", "content": "Write a Python function to parse JSON from a file"}
    ]
  }'
```

### Streaming Response Example
```bash
curl -sN http://127.0.0.1:${PROXY_PORT}/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "skillclaw-model", "stream": true,
       "messages": [{"role": "user", "content": "Hello"}]}'
```

### Session Management Example
```bash
# With explicit session tracking
curl -s http://127.0.0.1:${PROXY_PORT}/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-Session-Id: session-abc123" \
  -H "X-Turn-Type: main" \
  -d '{
    "model": "skillclaw-model",
    "stream": false,
    "messages": [
      {"role": "system", "content": "You are a coding assistant."},
      {"role": "user", "content": "Debug this Python error: AttributeError: ..."}
    ]
  }'

# Signal end of session
curl -s http://127.0.0.1:${PROXY_PORT}/v1/chat/completions \
  -H "X-Session-Id: session-abc123" \
  -H "X-Session-Done: true" \
  -H "Content-Type: application/json" \
  -d '{"model": "skillclaw-model", "messages": [{"role": "user", "content": "Thanks"}]}'
```
```

--------------------------------

### Configure SkillClaw for Local Shared Directory

Source: https://github.com/amap-ml/skillclaw/blob/main/README.md

Configure SkillClaw to use a local mounted directory for shared storage. Specify the root path for the shared directory.

```bash
skillclaw config sharing.backend local
skillclaw config sharing.local_root /path/to/shared/root
```

--------------------------------

### Initialize SkillManager with Embedding Mode

Source: https://context7.com/amap-ml/skillclaw/llms.txt

Initializes the SkillManager for skill retrieval using SentenceTransformer embeddings.

```python
# Initialize with embedding mode (cosine similarity using SentenceTransformer)
manager_emb = SkillManager(
    skills_dir="/Users/alice/.skillclaw/skills",
    retrieval_mode="embedding",
    embedding_model_path="Qwen/Qwen3-Embedding-0.6B",
)
```

--------------------------------

### Skill Management Commands

Source: https://github.com/amap-ml/skillclaw/blob/main/README.md

Provides essential commands for managing skills within the SkillClaw ecosystem. These include downloading, uploading, synchronizing, and listing skills from remote storage.

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

--------------------------------

### SkillClaw Hermes Diagnostics and Restore

Source: https://github.com/amap-ml/skillclaw/blob/main/README.md

Provides commands to diagnose the Hermes integration with SkillClaw and to restore the original Hermes configuration if needed. Use these for troubleshooting.

```bash
skillclaw doctor hermes
skillclaw restore hermes
```

--------------------------------

### Standard Chat Completions Request

Source: https://context7.com/amap-ml/skillclaw/llms.txt

Use this endpoint for standard chat completions. SkillClaw injects skills and records the turn transparently. Ensure the PROXY_PORT is set.

```bash
PROXY_PORT=30000

# Standard request — SkillClaw transparently injects skills and records the turn
curl -s http://127.0.0.1:${PROXY_PORT}/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "skillclaw-model",
    "messages": [
      {"role": "user", "content": "Write a Python function to parse JSON from a file"}
    ]
  }' | python3 -m json.tool
```

--------------------------------

### List Remote Skills

Source: https://github.com/amap-ml/skillclaw/blob/main/README.md

List remote skills available in the shared store. This command is useful for inspecting the shared skill repository after setting up the evolve server.

```bash
skillclaw skills list-remote
```

--------------------------------

### CLI: skillclaw config

Source: https://context7.com/amap-ml/skillclaw/llms.txt

Allows reading and writing individual configuration values directly via the command line, without manual YAML editing. Supports dot-path notation for nested keys.

```bash
# Show full config
skillclaw config show

# Read a single key
skillclaw config proxy.port
# proxy.port: 30000

# Set a value
skillclaw config proxy.port 30001
# Set proxy.port = 30001

# Key reference (dot-path notation)
skillclaw config llm.api_base https://openrouter.ai/api/v1
skillclaw config llm.model_id anthropic/claude-opus-4
skillclaw config llm.api_key sk-or-...

# Sharing config 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_KEY_ID"
skillclaw config sharing.secret_access_key "$OSS_SECRET"
skillclaw config sharing.group_id my-team
skillclaw config sharing.user_alias alice
skillclaw config sharing.auto_pull_on_start true
```

--------------------------------

### SKILL.md Frontmatter and Body Structure

Source: https://github.com/amap-ml/skillclaw/blob/main/evolve_server/engines/EVOLVE_AGENTS.md

Defines the required YAML frontmatter and Markdown body for a SKILL.md file. Ensure 'name' is a lowercase-hyphenated slug and 'description' clearly states the skill's purpose and exclusions.

```markdown
---
name: lowercase-hyphenated-slug
description: What this skill does and when to trigger it. Include "NOT for: ..." exclusion conditions. 2-4 sentences.
category: general
---

<Markdown body with practical guidance>
```

--------------------------------

### Add a Single Skill Programmatically

Source: https://context7.com/amap-ml/skillclaw/llms.txt

Adds a new skill to the SkillManager with its name, description, and content.

```python
# Add a skill programmatically
manager.add_skill({
    "name": "parse-json-files",
    "description": "Use when reading or writing JSON files. NOT for: API responses.",
    "category": "coding",
    "content": "# Parse JSON Files\n\nAlways use `with open(path) as f: json.load(f)`...",
})
# Returns True if added, False if already exists
```

--------------------------------

### Configure SkillClaw Dashboard with Shared Group Details

Source: https://github.com/amap-ml/skillclaw/blob/main/README.md

Configure the SkillClaw dashboard to point to a specific local shared root and group. This allows inspection of a particular shared environment.

```bash
skillclaw dashboard sync \
  --sharing-local-root /path/to/shared/root \
  --sharing-group-id my-group \
  --sharing-user-alias alice

skillclaw dashboard serve \
  --host 127.0.0.1 \
  --port 3791 \
  --sharing-local-root /path/to/shared/root \
  --sharing-group-id my-group \
  --sharing-user-alias alice
```

--------------------------------

### Add Multiple Skills Programmatically

Source: https://context7.com/amap-ml/skillclaw/llms.txt

Adds multiple skills at once, optionally assigning them to a common category.

```python
# Add multiple skills at once
count = manager.add_skills([
    {"name": "k8s-deploy", "description": "Deploy to Kubernetes", "content": "..."},
    {"name": "write-docs",  "description": "Write API documentation", "content": "..."},
], category="automation")
print(f"Added {count} skills")
```

--------------------------------

### Configure SkillClaw for Background Validation

Source: https://github.com/amap-ml/skillclaw/blob/main/README.md

Enable and configure the background validation worker for a second review step before publishing skills. Set idle time, poll interval, and job limits.

```bash
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
```

--------------------------------

### Configure SkillClaw for OSS Shared Group

Source: https://github.com/amap-ml/skillclaw/blob/main/README.md

Configure SkillClaw to use Object Storage Service (OSS) for shared group storage. Ensure your OSS credentials and group details are provided.

```bash
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
```

--------------------------------

### Diagnose and Restore Codex/Claude Integrations

Source: https://context7.com/amap-ml/skillclaw/llms.txt

Commands to check the status and restore configurations for Codex and Claude integrations.

```bash
skillclaw doctor codex
```

```bash
skillclaw restore codex
```

```bash
skillclaw doctor claude
```

```bash
skillclaw restore claude
```

--------------------------------

### Token Count Helper for Messages API

Source: https://context7.com/amap-ml/skillclaw/llms.txt

This endpoint helps count tokens for messages, useful for estimating costs or request limits. Requires `x-api-key`.

```bash
PROXY_PORT=30000

curl -s http://127.0.0.1:${PROXY_PORT}/v1/messages/count_tokens \
  -H "Content-Type: application/json" \
  -H "x-api-key: my-key" \
  -d '{"model": "skillclaw-model", "messages": [{"role": "user", "content": "Hello"}]}'
# {"input_tokens": 5}
```

--------------------------------

### Configure SkillClaw Validation Worker

Source: https://context7.com/amap-ml/skillclaw/llms.txt

Commands to enable and configure the background validation worker, including setting polling intervals and job limits. Shows how to check the current status and force a run.

```bash
# Enable validation in config
skillclaw config validation.enabled true
skillclaw config validation.idle_after_seconds 300     # wait 5 min of inactivity
skillclaw config validation.poll_interval_seconds 60   # check every minute
skillclaw config validation.max_jobs_per_day 5         # safety cap

# Check validation configuration and current state
skillclaw validation status
# enabled: true
# mode: replay
# idle_after_seconds: 300
# poll_interval_seconds: 60
# max_jobs_per_day: 5
# jobs_completed_today: 1
# currently_idle: false

# Run one validation iteration immediately (bypasses idle requirement)
skillclaw validation run-once --force
# checked_jobs: 1
# validated_jobs: 1
# skipped_jobs: 0
# reason: forced

# Normal operation: start the daemon — validation worker runs automatically
skillclaw start --daemon
```

--------------------------------

### Record Skill Injection and Feedback

Source: https://context7.com/amap-ml/skillclaw/llms.txt

Records which skills were injected and provides feedback scores to update their effectiveness.

```python
# Record PRM feedback to update effectiveness scores
manager.record_injection(["debug-systematically", "write-unit-tests"])
manager.record_feedback(["debug-systematically"], score=1.0)   # positive
manager.record_feedback(["write-unit-tests"],      score=0.0)  # neutral
```

--------------------------------

### SkillClaw Config

Source: https://context7.com/amap-ml/skillclaw/llms.txt

Manage SkillClaw configuration values directly via the CLI, allowing reading and writing of individual settings without manual YAML editing.

```APIDOC
## CLI: `skillclaw config`

Read or write individual configuration values without editing the YAML file directly.

```bash
# Show full config
skillclaw config show

# Read a single key
skillclaw config proxy.port
# proxy.port: 30000

# Set a value
skillclaw config proxy.port 30001
# Set proxy.port = 30001

# Key reference (dot-path notation)
skillclaw config llm.api_base https://openrouter.ai/api/v1
skillclaw config llm.model_id anthropic/claude-opus-4
skillclaw config llm.api_key sk-or-...

# Sharing config 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_KEY_ID"
skillclaw config sharing.secret_access_key "$OSS_SECRET"
skillclaw config sharing.group_id my-team
skillclaw config sharing.user_alias alice
skillclaw config sharing.auto_pull_on_start true
```
```

--------------------------------

### Retrieve Top-K Relevant Skills

Source: https://context7.com/amap-ml/skillclaw/llms.txt

Retrieves the most relevant skills based on a task description using the initialized SkillManager.

```python
# Retrieve top-k relevant skills for a task description
skills = manager.retrieve("I need to debug a Python AttributeError", top_k=3)
for s in skills:
    print(s["name"], s["description"])
```

--------------------------------

### Streaming Chat Completions Response

Source: https://context7.com/amap-ml/skillclaw/llms.txt

Use `stream: true` for streaming responses. The `-sN` flags are important for non-blocking streaming.

```bash
PROXY_PORT=30000

# Streaming response
curl -sN http://127.0.0.1:${PROXY_PORT}/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "skillclaw-model", "stream": true, 
       "messages": [{"role": "user", "content": "Hello"}]}'
```

--------------------------------

### Retrieve a Stored Response

Source: https://context7.com/amap-ml/skillclaw/llms.txt

Use this endpoint to retrieve a previously stored response using its ID.

```bash
curl -s http://127.0.0.1:${PROXY_PORT}/v1/responses/resp_abc123
```

--------------------------------

### Stateful Conversation with Responses API

Source: https://context7.com/amap-ml/skillclaw/llms.txt

Maintain a stateful conversation using the `previous_response_id` parameter. This allows for follow-up requests within the same context.

```bash
PROXY_PORT=30000

# Stateful conversation with previous_response_id
FIRST_RESPONSE_ID="resp_abc123"
curl -s http://127.0.0.1:${PROXY_PORT}/v1/responses \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"skillclaw-model\",
    \"previous_response_id\": \"${FIRST_RESPONSE_ID}\",
    \"input\": \"Now write the tests for that function\"
  }"
```

--------------------------------

### Codex-style Responses API Call

Source: https://context7.com/amap-ml/skillclaw/llms.txt

This endpoint is for Codex-style responses. It forwards requests natively when `llm_api_mode` is set to `responses`. Requires `Authorization` header.

```bash
PROXY_PORT=30000

# Codex-style Responses API call
curl -s http://127.0.0.1:${PROXY_PORT}/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer dummy" \
  -d '{
    "model": "skillclaw-model",
    "input": "Fix the bug in this code: def add(a, b): return a - b",
    "tools": [{"type": "code_interpreter"}]
  }' | python3 -m json.tool
```

--------------------------------

### Anthropic-Compatible Messages API Request

Source: https://context7.com/amap-ml/skillclaw/llms.txt

This endpoint accepts the native Anthropic request format. Ensure the PROXY_PORT is set.

```bash
PROXY_PORT=30000

curl -s http://127.0.0.1:${PROXY_PORT}/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: dummy-key" \
  -d '{
    "model": "skillclaw-model",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Explain async/await in Python"}
    ]
  }' | python3 -m json.tool
```