Add reference docs, Cloudflare examples, and test runner

.github/workflows/ci.yml

@@ -17,9 +17,33 @@ jobs:
       - name: Run lint
         run: script/lint
 
+  test-snippets:
+    if: github.event_name == 'push' || !github.event.pull_request.head.repo.fork
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v3
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+      - name: Install npm dependencies
+        run: npm install --silent
+        working-directory: test
+      - name: Run snippet tests
+        env:
+          REPLICATE_API_TOKEN: ${{ secrets.REPLICATE_API_TOKEN }}
+        run: python script/test_snippets.py
+
   publish-clawhub:
     if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-    needs: lint
+    needs: [lint, test-snippets]
     runs-on: ubuntu-latest
     steps:
       - name: Checkout

.gitignore

@@ -2,3 +2,6 @@
 *.swp
 *.swo
 *~
+node_modules/
+__pycache__/
+*.greger

AGENTS.md

@@ -2,27 +2,49 @@
 
 ## Purpose
 
-This repo publishes a single Agent Skills document for Replicate.
-
-Keep it short and focused: a human- and agent-readable guide to discovering models, inspecting schemas, running predictions, and handling outputs.
+This repo publishes Agent Skills for Replicate: a main skill document plus focused reference docs covering predictions, model search, collections, workflows, deployments, Cloudflare integration, and the HTTP API.
 
 ## Files that matter
 
-- `skills/replicate/SKILL.md` is the canonical skill.
-- `.mcp.json` points to the remote MCP server.
-- `.claude-plugin/` contains marketplace metadata for Claude Code.
+- `skills/replicate/SKILL.md` — the main skill (overview, common patterns, reference table).
+- `skills/replicate/references/*.md` — detailed reference docs linked from SKILL.md.
+- `script/lint` — validates the skill and lints Python with ruff.
+- `script/test_snippets.py` — extracts and runs every code snippet from the markdown files.
+- `test/fixtures/` — test assets (e.g. images for workers that accept file uploads).
+- `.mcp.json` — points to the remote MCP server.
+- `.claude-plugin/` — marketplace metadata for Claude Code.
 
 ## Editing guidelines
 
-- Keep `SKILL.md` concise and practical. Prefer bullet lists over long prose.
+- Keep `SKILL.md` concise. Detailed examples go in `references/`.
+- Every code snippet must be runnable. The test runner executes them all.
+- Snippets starting with `// worker.js` or `// workflow.js` are tested via `wrangler dev`.
+- Snippets whose worker reads `request.blob()` or `request.arrayBuffer()` get a test image POSTed automatically.
 - Treat `https://api.replicate.com/openapi.json` as the source of truth.
-- Keep mentions of deprecated or unofficial endpoints out of the skill.
 - Do not add language-specific client guidance unless explicitly requested.
 
 ## Linting
 
-Lint before committing changes:
-
 ```
 script/lint
 ```
+
+## Testing
+
+Runs all code snippets (bash, python, javascript) from every markdown file:
+
+```
+REPLICATE_API_TOKEN=... python script/test_snippets.py
+```
+
+Syntax check only (no API calls):
+
+```
+REPLICATE_API_TOKEN=... python script/test_snippets.py --syntax-only
+```
+
+Test a single reference file:
+
+```
+REPLICATE_API_TOKEN=... python script/test_snippets.py --include references/CLOUDFLARE_WORKERS.md
+```

script/lint

@@ -1,10 +1,7 @@
 #!/bin/sh
 
-# script/lint: Validate Agent Skills definitions with skills-ref.
-# skills-ref is the reference CLI for the Agent Skills spec (agentskills.io).
-# It provides the `agentskills` executable with a `validate` subcommand.
-# Uses uvx if available for a clean, isolated install of the validator.
-# Falls back to a local Python module install if uv is not present.
+# script/lint: Validate Agent Skills definitions with skills-ref,
+# then lint and format Python scripts with ruff.
 
 set -e
 
@@ -18,17 +15,21 @@ echo "==> Validating Agent Skills in $SKILL_PATH"
 
 if command -v uv >/dev/null 2>&1; then
   uvx --from skills-ref agentskills validate "$SKILL_PATH"
-  exit 0
-fi
-
-PYTHON_BIN="${PYTHON_BIN:-python3}"
-if ! command -v "$PYTHON_BIN" >/dev/null 2>&1; then
-  if command -v python >/dev/null 2>&1; then
-    PYTHON_BIN=python
-  else
-    echo "python not found. Install Python 3 or uv to run skills-ref." >&2
-    exit 1
+else
+  PYTHON_BIN="${PYTHON_BIN:-python3}"
+  if ! command -v "$PYTHON_BIN" >/dev/null 2>&1; then
+    if command -v python >/dev/null 2>&1; then
+      PYTHON_BIN=python
+    else
+      echo "python not found. Install Python 3 or uv to run skills-ref." >&2
+      exit 1
+    fi
   fi
+  "$PYTHON_BIN" -m skills_ref validate "$SKILL_PATH"
 fi
 
-"$PYTHON_BIN" -m skills_ref validate "$SKILL_PATH"
+echo "==> Linting Python (ruff check)"
+uvx ruff check script/test_snippets.py
+
+echo "==> Formatting Python (ruff format --check)"
+uvx ruff format --check script/test_snippets.py