docs: IS_SANDBOX=1 generator note + normative Hookdeck CLI invocation

AGENTS.md

@@ -208,23 +208,20 @@ metadata:
 
 ## Local Development
 
-For local webhook testing, install Hookdeck CLI:
+For local webhook testing, run the Hookdeck CLI via `npx` — no install required, one paste-and-run line:
 
 ```bash
-# Install via npm
-npm install -g hookdeck-cli
-
-# Or via Homebrew
-brew install hookdeck/hookdeck/hookdeck
+npx hookdeck-cli listen 3000 {provider} --path /webhooks/{provider}
 ```
 
-Then start the tunnel:
+**Conventions for this command in skill examples (apply to every example README and any `references/setup.md` that mentions a tunnel):**
 
-```bash
-hookdeck listen 3000 --path /webhooks/{provider}
-```
+- Always use `npx hookdeck-cli` (not bare `hookdeck`) — skills shouldn't push a global install of a provider-specific CLI. `npx` resolves to the package's `hookdeck` bin automatically.
+- Always pass the **source name** as the second positional arg (e.g. `stripe`, `mailgun`). The CLI's `[source]` argument is required syntactically and otherwise prompts interactively; passing it explicitly gives a copy-paste-runnable command.
+- Match the example's port: `3000` for Express and Next.js, `8000` for FastAPI.
+- The path is `/webhooks/{provider}` matching the example handler's route.
 
-No account required. Provides local tunnel + web UI for inspecting requests.
+No account required — the CLI creates a guest account on first run and provides a local tunnel + web UI for inspecting requests.
 
 ## Related Skills
 
@@ -755,6 +752,23 @@ providers:
 
 The test script reads scenarios from `providers.yaml` dynamically - no script modifications needed.
 
+## Running the Generator in Sandboxed Environments
+
+When invoking `./scripts/generate-skills.sh generate` or `review` from a sandboxed agent environment (Claude Code on the web, Docker containers, etc.), the spawned `claude` CLI passes `--dangerously-skip-permissions` to skip its interactive permission prompts. The CLI refuses that flag when the process is running as root for safety, so the run fails immediately on every provider with:
+
+```
+--dangerously-skip-permissions cannot be used with root/sudo privileges for security reasons
+```
+
+Acknowledge the sandbox by exporting `IS_SANDBOX=1` for the generator invocation. The env var is inherited by the `claude` child processes and unblocks the flag:
+
+```bash
+IS_SANDBOX=1 ./scripts/generate-skills.sh generate {provider} --config providers.yaml
+IS_SANDBOX=1 ./scripts/generate-skills.sh review --config providers.yaml --create-pr=draft
+```
+
+Always pair `IS_SANDBOX=1` with an explicit `--model` (e.g. `--model claude-opus-4-7`) — the adapter's default is pinned to an older Opus build.
+
 ## Reviewing a Provider Skill or PR
 
 When reviewing a provider skill (e.g. from a pull request or before merging):

README.md

@@ -38,6 +38,7 @@ Skills for receiving and verifying webhooks from specific providers. Each includ
 | GitHub | [`github-webhooks`](skills/github-webhooks/) | Verify GitHub webhook signatures, handle push, pull_request, and issue events |
 | GitLab | [`gitlab-webhooks`](skills/gitlab-webhooks/) | Verify GitLab webhook tokens, handle push, merge_request, issue, and pipeline events |
 | OpenAI | [`openai-webhooks`](skills/openai-webhooks/) | Verify OpenAI webhooks for fine-tuning, batch, and realtime async events |
+| OpenClaw | [`openclaw-webhooks`](skills/openclaw-webhooks/) | Verify OpenClaw Gateway webhook tokens, handle agent hook and wake event payloads |
 | Paddle | [`paddle-webhooks`](skills/paddle-webhooks/) | Verify Paddle webhook signatures, handle subscription and billing events |
 | Postmark | [`postmark-webhooks`](skills/postmark-webhooks/) | Authenticate Postmark webhooks (Basic Auth/Token), handle email delivery, bounce, open, click, and spam events |
 | Replicate | [`replicate-webhooks`](skills/replicate-webhooks/) | Verify Replicate webhook signatures, handle ML prediction lifecycle events |

providers.yaml

@@ -160,6 +160,23 @@ providers:
         - fine_tuning.job.succeeded
         - batch.completed
 
+  - name: openclaw
+    displayName: OpenClaw
+    docs:
+      webhooks: https://docs.openclaw.ai/automation/webhook
+      hooks: https://docs.openclaw.ai/automation/hooks
+      configuration: https://docs.openclaw.ai/gateway/configuration
+    notes: >
+      Open-source autonomous AI agent platform. Uses token-based authentication
+      (not HMAC signatures). Token sent via Authorization: Bearer <token> or
+      x-openclaw-token header. Two hook types: agent hooks (/hooks/agent) trigger
+      isolated agent turns, wake hooks (/hooks/wake) enqueue system events.
+      No official webhook verification SDK — use timing-safe string comparison.
+    testScenario:
+      events:
+        - agent hook
+        - wake hook
+
   - name: paddle
     displayName: Paddle
     docs:

scripts/skill-generator/prompts/generate-skill.md

@@ -66,6 +66,12 @@ Read the AGENTS.md file in this repository to understand the full skill creation
 3. **Include comprehensive tests** that generate real signatures using the provider's algorithm
 4. **Be idiomatic** to each framework (Express middleware patterns, Next.js App Router, FastAPI dependencies)
 5. **Return appropriate HTTP status codes** (200 for success, 400 for invalid signature, etc.)
+6. **Hookdeck CLI in example READMEs** — when an example shows how to receive webhooks locally, use exactly this form (no install step, source arg is required):
+   - Express: `npx hookdeck-cli listen 3000 {{PROVIDER_KEBAB}} --path /webhooks/{{PROVIDER_KEBAB}}`
+   - Next.js: `npx hookdeck-cli listen 3000 {{PROVIDER_KEBAB}} --path /webhooks/{{PROVIDER_KEBAB}}`
+   - FastAPI: `npx hookdeck-cli listen 8000 {{PROVIDER_KEBAB}} --path /webhooks/{{PROVIDER_KEBAB}}`
+
+   Do **not** write `hookdeck listen ...` (assumes a global install), and do **not** omit the source positional arg (the CLI would otherwise prompt interactively). See `AGENTS.md` → "Local Development" for the rationale.
 
 ## CRITICAL: Consistency Checks