# SkillClaw Evolve Pipeline — Reference

Condensed from the AMAP-ML/SkillClaw repo README, source (`evolve_server/`, `skillclaw/api_server.py`), and the 2026-07-28 bring-up session on the VPS.

## Architecture

Two components meet **only through shared storage** (local dir / OSS / S3):

- **Client proxy** (`skillclaw`, port 30000): injects skills into proxied requests, records conversation artifacts, uploads session records, pulls evolved skills back (poll, `skill_reload_interval_seconds: 30`).
- **Evolve server** (`skillclaw-evolve-server`, port 8787): drains session records, evolves/creates skills, writes them back to `<shared>/<group_id>/skills/<name>/SKILL.md`.

Single-user local loop = `sharing.backend: local` + dedicated `sharing.local_root` + one evolve server with `--use-skillclaw-config` (reads the client's config.yaml for storage + LLM settings).

## Session lifecycle (client side)

1. Turns buffered in `_pending_records` per session id.
2. Session CLOSES on: explicit close signal, inactivity timeout (300s for new-session detection), or the **idle sweeper** (`session_idle_close_seconds`, default 180s) — log: `[SessionDetect] closed session=... reason=idle_timeout`.
3. On close: `_upload_session_data()` writes `<shared>/<group_id>/sessions/<session_id>.json`, then (if `evolve.server_url` set) POSTs `{url}/trigger` to the evolve server, and pulls skills if the trigger reports uploads.
4. Optional mid-session snapshots: `sharing.session_upload_interval` > 0 uploads partial snapshots every N user turns (default 0 = off).

## Evolve cycle stages (workflow engine)

Per cycle (`--interval` seconds, or on `/trigger`):

1. **Drain** session keys from storage (`drained N session(s)`).
2. **Summarize** each session via LLM (`[Summarizer] summarized N sessions`).
3. **Judge** sessions without benchmark scores (`[SessionJudge] judged N/N candidate sessions`) — produces a quality score per session.
4. **Aggregate** into skill groups vs no-skill sessions (`N sessions -> G skill groups + M no-skill sessions`).
5. **Evolve/create** skills per group; for no-skill sessions the LLM may decide to skip (`no-skill sessions: LLM decided to skip`) — normal for trivial exchanges.
6. **Publish** per `--publish-mode`: `direct` (default) writes straight to `skills/`; `validated` stages jobs for opted-in client validation workers first.
7. **Cleanup**: processed session keys are deleted (`[OSS] deleted N/N session keys`) — applies to local storage too.

## /trigger response fields

```json
{"elapsed_seconds": 61.4, "sessions": 1, "skill_groups": 0, "no_skill_sessions": 1,
 "actions": 0, "skills_evolved": 0, "uploaded_skills": 0, "candidates_queued": 0,
 "published_after_validation": 0, "evolutions": [],
 "session_judge": {"enabled": true, "judged_sessions": 1, "mean_score": 1.0},
 "skill_verifier": {"enabled": false, ...},
 "validation_publish": {"publish_mode": "direct", ...},
 "had_processing_error": false}
```

- `uploaded_skills > 0` → client proxy auto-pulls after its trigger call.
- `had_processing_error: true` → check `journalctl -u skillclaw-evolve` for the failing stage.

## Log-line glossary

| Log line | Meaning |
|---|---|
| `proxy ready at http://127.0.0.1:30000` | client proxy up |
| `claw_type=none — skipping auto-configuration` | external agent (gateway) untouched, as intended |
| `skill pull: 0 downloaded ... 0 total remote` | shared root has no skills yet (normal at bootstrap) |
| `session uploaded: default/sessions/<id>.json (N turns, B bytes)` | closed session pushed to shared root |
| `triggered evolve server: http://127.0.0.1:8787` | proxy kicked the server post-upload |
| `queue empty - checking pending validation publish jobs` | cycle ran with nothing to do |
| `=== cycle done: N sessions, G skill groups, U uploaded, Q queued in Ts ===` | cycle summary |

## Engines

- `workflow` (default, what runs on the VPS): fixed pipeline above, needs only the `openai` package (`pip install -e ".[evolve]"`).
- `agent`: OpenClaw-agent-driven evolution (`--engine agent --openclaw-bin ... --agents-md ...`) — heavier, not configured here.

## Upgrade paths deliberately not taken (as of 2026-07-28)

- Remote sharing (OSS/S3/nacos) for multi-device/team loop — client config only, no server change needed to *join* a group.
- Validation workers (`validation.enabled`) — second review step before publish; needs `publish-mode validated` on the server.
- Dashboard (`skillclaw dashboard serve`, port 3788) — read-only inspection of local/shared skills, sessions, validation progress.
- Routing `hermes-gateway.service` traffic through the proxy so real Desktop sessions feed evolution — biggest lever for skill quality; changes the live inference path, so treat as its own decision with trade-offs (latency hop, proxy as SPOF for chat, evolve cost scaling with all traffic).