diff --git a/skills/zbdw/SKILL.md b/skills/zbdw/SKILL.md
new file mode 100644
index 0000000..879d64f
--- /dev/null
+++ b/skills/zbdw/SKILL.md
@@ -0,0 +1,154 @@
+---
+name: zbdw
+description: >-
+  Operate ZBD agent wallets with the zbdw CLI: setup, balance checks, send/receive,
+  withdrawals, and L402 paid fetch. Use when users ask to configure zbdw, run wallet
+  commands, pay Lightning invoices or addresses, inspect payment history, or fetch
+  paywalled endpoints. Triggers on "zbdw", "agent wallet", "send sats", "Lightning address",
+  "withdraw", "payment id", "L402", "paywall", "fetch paid endpoint", "ZBD API key".
+argument-hint: <zbdw task or command>
+homepage: https://github.com/zbdpay/agent-wallet
+metadata:
+  openclaw:
+    emoji: "⚡"
+    requires:
+      anyBins:
+        - zbdw
+        - npx
+    install:
+      - id: node-global
+        kind: node
+        package: "@zbdpay/agent-wallet"
+        bins:
+          - zbdw
+        label: Install zbdw globally (npm)
+---
+
+# zbdw Wallet Operations
+
+Use this skill to run safe, repeatable `zbdw` wallet workflows and return machine-readable JSON results.
+
+## When to Use
+
+- User needs to install or initialize ZBD wallet CLI
+- User asks to check balance, send, receive, withdraw, or inspect payment history
+- User needs to fetch an L402-protected endpoint with payment caps
+- User needs troubleshooting for common `zbdw` error codes
+
+## Core Workflow
+
+1. Confirm CLI availability (`zbdw --help` or `npx @zbdpay/agent-wallet --help`).
+2. Resolve API key source with strict precedence:
+   - `--key` flag
+   - `ZBD_API_KEY` env var
+   - `~/.zbd-wallet/config.json`
+3. Run the minimum command needed for the task.
+4. Return structured output and explain key fields.
+5. If command fails, map error code to concrete next action.
+
+## Setup and First Run
+
+```bash
+# global install
+npm install -g @zbdpay/agent-wallet
+
+# or one-shot
+npx @zbdpay/agent-wallet init --key <your_api_key>
+
+# validate setup
+zbdw info
+zbdw balance
+```
+
+## Command Quick Reference
+
+| Task | Command |
+|---|---|
+| Initialize wallet identity | `zbdw init --key <apiKey>` |
+| Show wallet metadata | `zbdw info` |
+| Get wallet balance | `zbdw balance` |
+| Create invoice | `zbdw receive <amount_sats>` |
+| Create static receive endpoint | `zbdw receive --static [amount_sats]` |
+| Send payment | `zbdw send <destination> <amount_sats>` |
+| List local payments | `zbdw payments` |
+| Inspect one payment | `zbdw payment <id>` |
+| Create withdraw request | `zbdw withdraw create <amount_sats>` |
+| Check withdraw status | `zbdw withdraw status <withdraw_id>` |
+| Fetch paid endpoint | `zbdw fetch <url> [--method] [--data] [--max-sats]` |
+
+## Destination Rules for `zbdw send`
+
+- `lnbc...` -> BOLT11 invoice
+- `lnurl...` -> LNURL pay
+- `@gamertag` -> ZBD gamertag payout
+- `name@domain.com` -> Lightning Address payout
+
+If destination does not match one of these forms, return `unsupported_destination` and ask for a valid target.
+
+## L402 Paid Fetch Pattern
+
+```bash
+# first request may pay and cache token
+zbdw fetch "https://api.example.com/premium" --max-sats 100
+
+# second request should reuse cache when token is still valid
+zbdw fetch "https://api.example.com/premium" --max-sats 100
+```
+
+Interpretation:
+- first call often includes non-null `payment_id` / `amount_paid_sats`
+- cache hits often return `payment_id: null` and `amount_paid_sats: null`
+
+## JSON Contract
+
+Always expect JSON output.
+
+Success examples:
+
+```json
+{"lightningAddress":"name@zbd.ai","status":"ok"}
+{"balance_sats":50000}
+{"payment_id":"pay_123","fee_sats":1,"status":"completed"}
+```
+
+Error shape:
+
+```json
+{"error":"error_code","message":"Human-readable message","details":{}}
+```
+
+## Red Flags - STOP
+
+- Missing API key source -> do not continue with payment actions
+- Amount is non-integer or <= 0 for send/receive/withdraw -> reject and correct input
+- `fetch --max-sats` would be exceeded -> stop instead of forcing payment
+- Destination format unclear -> stop and normalize destination first
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---|---|
+| Using wrong key header assumptions | zbdw already uses `apikey` header internally; provide valid API key only |
+| Expecting human-readable plain text output | Parse JSON output for automation workflows |
+| Treating `payment <id>` as remote-only lookup | It is local-first and falls back to API when needed |
+| Forgetting Node version constraints | Use Node.js 22+ |
+| Setting empty `ZBD_API_BASE_URL` and expecting default | Unset the variable entirely or set a valid URL |
+
+## Useful Environment Variables
+
+| Variable | Default |
+|---|---|
+| `ZBD_API_KEY` | none |
+| `ZBD_API_BASE_URL` | `https://api.zbdpay.com` |
+| `ZBD_AI_BASE_URL` | `https://zbd.ai` |
+| `ZBD_WALLET_CONFIG` | `~/.zbd-wallet/config.json` |
+| `ZBD_WALLET_PAYMENTS` | `~/.zbd-wallet/payments.json` |
+| `ZBD_WALLET_TOKEN_CACHE` | `~/.zbd-wallet/token-cache.json` |
+| `ZBDW_NO_PROGRESS` | unset |
+
+## Additional Resources
+
+- [`references/command-reference.md`](references/command-reference.md) for command outputs and task mapping
+- [`references/troubleshooting.md`](references/troubleshooting.md) for error-code playbook
+
+Use these references when a task needs exact output fields or concrete recovery steps.
diff --git a/skills/zbdw/references/command-reference.md b/skills/zbdw/references/command-reference.md
new file mode 100644
index 0000000..2e2ce6f
--- /dev/null
+++ b/skills/zbdw/references/command-reference.md
@@ -0,0 +1,158 @@
+# zbdw Command Reference
+
+This reference maps common user intents to exact `zbdw` commands and expected JSON fields.
+
+## Setup and Identity
+
+### Initialize wallet config
+
+```bash
+zbdw init --key <apiKey>
+```
+
+Expected fields:
+- `lightningAddress` (string)
+- `status` (`"ok"`)
+
+### Inspect configured wallet
+
+```bash
+zbdw info
+```
+
+Expected fields:
+- `lightningAddress` (string or `null`)
+- `apiKey` (`"***"`)
+- `balance_sats` (number)
+
+## Balance and Receiving
+
+### Check balance
+
+```bash
+zbdw balance
+```
+
+Expected fields:
+- `balance_sats` (number)
+
+### Create one-time invoice
+
+```bash
+zbdw receive <amount_sats> [description]
+```
+
+Expected fields:
+- `invoice` (BOLT11)
+- `payment_hash` (string or `null`)
+- `expires_at` (ISO timestamp)
+
+### Create static receive endpoint
+
+```bash
+zbdw receive --static [amount_sats] [description]
+```
+
+Expected fields:
+- `charge_id` (string)
+- `lightning_address` (string, optional)
+- `lnurl` (string, optional)
+
+## Sending and Payment History
+
+### Send sats to destination
+
+```bash
+zbdw send <destination> <amount_sats>
+```
+
+Destination patterns:
+- `lnbc...` -> BOLT11
+- `lnurl...` -> LNURL
+- `@name` -> ZBD gamertag
+- `name@domain.com` -> Lightning Address
+
+Expected fields:
+- `payment_id` (string)
+- `fee_sats` (number)
+- `status` (string)
+- `preimage` (string, optional)
+
+### List local payments
+
+```bash
+zbdw payments
+```
+
+Expected output: JSON array of payment records.
+
+### Inspect one payment
+
+```bash
+zbdw payment <id>
+```
+
+Behavior:
+- returns local record if present
+- falls back to API lookup when missing locally
+
+## Withdraw
+
+### Create withdraw request
+
+```bash
+zbdw withdraw create <amount_sats>
+```
+
+Expected fields:
+- `withdraw_id` (string)
+- `lnurl` (string)
+
+### Check withdraw status
+
+```bash
+zbdw withdraw status <withdraw_id>
+```
+
+Expected fields:
+- `withdraw_id` (string)
+- `status` (string)
+- `amount_sats` (number)
+
+## L402 Protected Fetch
+
+### Fetch a paid endpoint
+
+```bash
+zbdw fetch <url> [--method <http_method>] [--data <json>] [--max-sats <amount>]
+```
+
+Expected fields:
+- `status` (HTTP status)
+- `headers` (response headers)
+- `body` (JSON or text)
+- `payment_id` (string or `null`)
+- `amount_paid_sats` (number or `null`)
+
+Token-cache behavior:
+- first paid call often includes non-null `payment_id` and `amount_paid_sats`
+- follow-up calls may reuse cached token and return both as `null`
+
+## Output Contract
+
+All commands return JSON to stdout.
+
+Error envelope:
+
+```json
+{"error":"error_code","message":"Human-readable message","details":{}}
+```
+
+## API Key Resolution Order
+
+Resolution precedence is strict:
+1. `--key`
+2. `ZBD_API_KEY`
+3. `~/.zbd-wallet/config.json`
+
+If no key is available, command should fail with `missing_api_key`.
diff --git a/skills/zbdw/references/troubleshooting.md b/skills/zbdw/references/troubleshooting.md
new file mode 100644
index 0000000..afc3e6a
--- /dev/null
+++ b/skills/zbdw/references/troubleshooting.md
@@ -0,0 +1,135 @@
+# zbdw Troubleshooting
+
+Use this playbook to map `zbdw` JSON errors to concrete fixes.
+
+## Fast Triage
+
+1. Confirm runtime: Node.js `>=22`
+2. Confirm command path: `zbdw --help` or `npx @zbdpay/agent-wallet --help`
+3. Confirm API key source with precedence (`--key` > `ZBD_API_KEY` > config)
+4. Re-run failing command and inspect `error`, `message`, and `details`
+
+## Error Mapping
+
+### `missing_api_key`
+
+Cause:
+- no valid key in flag, env var, or config
+
+Fix:
+- pass `--key <apiKey>`, or
+- set `ZBD_API_KEY`, or
+- run `zbdw init --key <apiKey>` to persist config
+
+### `invalid_api_key`
+
+Cause:
+- ZBD API rejected provided key
+
+Fix:
+- verify key value and environment
+- ensure `ZBD_API_BASE_URL` points to the correct ZBD API host
+
+### `register_unreachable`
+
+Cause:
+- registration service cannot be reached
+
+Fix:
+- verify `ZBD_AI_BASE_URL`
+- verify network access to `${ZBD_AI_BASE_URL}/api/register`
+
+### `register_failed`
+
+Cause:
+- registration endpoint returned non-success or invalid payload
+
+Fix:
+- inspect `details.status` and `details.response`
+- validate upstream static charge/create identity dependencies
+
+### `wallet_request_failed`
+
+Cause:
+- wallet endpoint request failed
+
+Fix:
+- verify `ZBD_API_BASE_URL`
+- check API availability and auth scope
+
+### `wallet_response_invalid`
+
+Cause:
+- wallet response missing `balance` in msats-compatible shape
+
+Fix:
+- inspect upstream response schema
+- verify proxy/transformation layers are not stripping fields
+
+### `receive_failed`
+
+Cause:
+- invoice/static charge response missing required fields
+
+Fix:
+- check upstream API response payload
+- confirm request params and API compatibility
+
+### `unsupported_destination`
+
+Cause:
+- `send` destination does not match supported patterns
+
+Fix:
+- normalize destination to one of:
+  - `lnbc...`
+  - `lnurl...`
+  - `@gamertag`
+  - `name@domain.com`
+
+### `invalid_amount`
+
+Cause:
+- amount not a positive integer sats value
+
+Fix:
+- provide integer sats (`1`, `1000`, `50000`)
+
+### `fetch_budget_exceeded`
+
+Cause:
+- invoice cost exceeds `--max-sats`
+
+Fix:
+- increase `--max-sats` intentionally, or
+- do not pay and choose another endpoint
+
+## Practical Diagnostics
+
+### Check effective environment
+
+```bash
+env | grep '^ZBD_'
+```
+
+### Verify config files
+
+```bash
+ls -la ~/.zbd-wallet
+```
+
+Expected files:
+- `config.json`
+- `payments.json`
+- `token-cache.json`
+
+### Validate L402 cache behavior
+
+```bash
+zbdw fetch "https://api.example.com/premium" --max-sats 100
+zbdw fetch "https://api.example.com/premium" --max-sats 100
+```
+
+Expected:
+- first call may include non-null `payment_id`
+- second call may return `payment_id: null` when token is reused