agentleFS
clawwork-aiclawwork-ai/ClawWork/.claude/skills/sync-gateway-docs/SKILL.md

sync-gateway-docs

Skill533 starsChanged 5 months agoApache-2.0View on GitHub

Sync the three ClawWork Gateway reference documents against the latest OpenClaw source code. Run all three phases. Each phase is independent and can be run in parallel via subagents. The whitepaper is the protocol contract. It must match the current openclaw source exactly. Step 1 — Detect changes. Read the following openclaw files and diff against what the whitepaper currently documents: Step 2 — Apply changes. For each detected difference: - New methods → add to §5 method list +…

The file

Show its rules and text

We split this skill into the rules it gives an agent

13 rules. About 0 are common, 6 are distinctive, and 7 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 7

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    When adding a new Gateway feature to ClawWork and the docs feel stale

    line 8
  2. Distinctive:

    Run all three phases. Each phase is independent and can be run in parallel via subagents.

    line 26
  3. Distinctive:

    Step 1 — Detect changes: Read the following openclaw files and diff against what the whitepaper currently documents:

    line 32
  4. Very specific:

    Step 4 — Verify inline sources: Every section must have a > Source: annotation.

    line 66
  5. Distinctive:

    Step 1 — Detect structural changes: Check:

    line 72
  6. Very specific:

    Step 3 — Verify flow diagrams: If the request/auth/broadcast flow changed, update the ASCII diagrams in §4.1, §4.3.

    line 84
  7. Very specific:

    Step 1 — Scan ClawWork RPC calls: Read:

    line 90
  8. Very specific:

    Step 2 — Scan ClawWork event handlers: Read:

    line 94
  9. Very specific:

    Step 4 — Update ConnectParams (§5): Read the current connect handshake in gateway-client.ts and verify client.id, client.mode, caps, …

    line 104
  10. Distinctive:

    Do not invent information.

    line 117
  11. Distinctive:

    Do not change the document structure (section numbers, headings) without reason.

    line 118
  12. Distinctive:

    Use the whitepaper as the intermediate reference: Phase 1 updates it from openclaw, Phase 3 references it for the full capability list.

    line 120
  13. Very specific:

    If a change is ambiguous (e.g., a method was renamed vs.

    line 121

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Skill: sync-gateway-docs

Sync the three ClawWork Gateway reference documents against the latest OpenClaw source code.

When to Use

  • Periodically (e.g., after OpenClaw releases or major Gateway changes)
  • When adding a new Gateway feature to ClawWork and the docs feel stale
  • User says: "更新 Gateway 文档", "sync gateway docs", or similar

Documents

DocPathPurpose
Whitepaperdocs/openclaw-gateway-whitepaper.mdProtocol contract reference — what Gateway exposes
Source Guidedocs/openclaw-gateway-source-guide.mdCode navigation — where to find things in openclaw
Capability Mapdocs/clawwork-gateway-capability-map.mdUsage inventory — what ClawWork actually uses

Prerequisites

  • OpenClaw repo checked out at ~/git/openclaw with latest main
  • ClawWork repo at ~/git/clawwork/main

Execution

Run all three phases. Each phase is independent and can be run in parallel via subagents.

Phase 1: Update Whitepaper

The whitepaper is the protocol contract. It must match the current openclaw source exactly.

Step 1 — Detect changes. Read the following openclaw files and diff against what the whitepaper currently documents:

What to checkOpenClaw source file
Protocol versionsrc/gateway/protocol/schema/protocol-schemas.ts → PROTOCOL_VERSION
Method listsrc/gateway/server-methods-list.ts → BASE_METHODS (count and diff)
Event listsrc/gateway/server-methods-list.ts → GATEWAY_EVENTS (count and diff)
Frame schemassrc/gateway/protocol/schema/frames.ts → ConnectParams, HelloOk, ErrorShape
Client IDs/modes/capssrc/gateway/protocol/client-info.ts → GATEWAY_CLIENT_IDS, MODES, CAPS
Chat schemassrc/gateway/protocol/schema/logs-chat.ts
Session schemassrc/gateway/protocol/schema/sessions.ts
Agent schemassrc/gateway/protocol/schema/agent.ts
Agent/model/skill schemassrc/gateway/protocol/schema/agents-models-skills.ts
Cron schemassrc/gateway/protocol/schema/cron.ts
Error codessrc/gateway/protocol/schema/error-codes.ts
Constantssrc/gateway/server-constants.ts, src/gateway/handshake-timeouts.ts
Scope mappingssrc/gateway/method-scopes.ts
Event scope guardssrc/gateway/server-broadcast.ts → EVENT_SCOPE_GUARDS
Rate limitingsrc/gateway/auth-rate-limit.ts
Snapshot/presencesrc/gateway/protocol/schema/snapshot.ts

Step 2 — Apply changes. For each detected difference:

  • New methods → add to §5 method list + add schema details if it's a major domain
  • New events → add to §4 event table with scope guard + dropIfSlow info
  • Changed schemas → update the TypeScript snippets inline
  • Changed constants → update §2.4 constants table
  • New/changed client IDs → update §3.3 tables

Step 3 — Update metadata. Bump the version line at the top of the whitepaper:

> Source of truth: reverse-engineered from `~/git/openclaw` (version YYYY.M.D)
> Date: YYYY-MM-DD

Step 4 — Verify inline sources. Every section must have a > Source: annotation. If a new section was added, add one.

Phase 2: Update Source Guide

The source guide maps code structure. It must reflect the current directory layout and file responsibilities.

Step 1 — Detect structural changes. Check:

  • ls src/gateway/protocol/schema/ — any new/removed schema files?
  • ls src/gateway/server-methods/ — any new/removed handler files?
  • ls src/gateway/server/ — any new/removed infrastructure files?
  • ls src/gateway/server/ws-connection/ — any changes to auth/handshake files?

Step 2 — Apply changes.

  • New schema files → add to §2.1 directory map
  • New handler files → add to §3.1 directory map with methods they handle
  • New infrastructure files → add to §4.2 key infrastructure table
  • Changed file responsibilities → update descriptions

Step 3 — Verify flow diagrams. If the request/auth/broadcast flow changed, update the ASCII diagrams in §4.1, §4.3.

Phase 3: Update Capability Map

The capability map tracks what ClawWork uses. It must reflect the current ClawWork code.

Step 1 — Scan ClawWork RPC calls. Read:

  • packages/desktop/src/main/ws/gateway-client.ts — all sendReq() calls (the method string is the first argument)
  • packages/desktop/src/main/ipc/ws-handlers.ts — all ipcMain.handle() registrations

Step 2 — Scan ClawWork event handlers. Read:

  • packages/core/src/services/gateway-dispatcher.ts — the dispatch switch/if-else block
  • packages/desktop/src/main/ws/gateway-client.ts — the handleEvent() method

Step 3 — Diff against existing doc.

  • New RPC calls in ClawWork → move from §2 (unused) to §1 (used), add location + IPC channel
  • Removed RPC calls → move from §1 to §2
  • New event handlers → move from §3.2 (unhandled) to §3.1 (handled)
  • New Gateway methods (from Phase 1) not in ClawWork → add to §2 (unused)

Step 4 — Update ConnectParams (§5). Read the current connect handshake in gateway-client.ts and verify client.id, client.mode, caps, scopes, device fields match.

Step 5 — Update coverage summary (§8). Recalculate percentages.

Output

After updating, report:

  1. What changed in each document (bullet list)
  2. New Gateway capabilities that ClawWork could benefit from (if any)
  3. Any discrepancies found (e.g., ClawWork calling a removed method)

Rules

  • Do not invent information. Every claim must trace to a source file.
  • Do not change the document structure (section numbers, headings) without reason.
  • Preserve all > Source: inline annotations.
  • Use the whitepaper as the intermediate reference: Phase 1 updates it from openclaw, Phase 3 references it for the full capability list.
  • If a change is ambiguous (e.g., a method was renamed vs. removed+added), check git log --oneline -20 -- <file> in the openclaw repo.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.