* Add Sandbox 1.0 migration skills
Refresh sandbox-sdk for @next and add sandbox-v1-migration plus
sandbox-2026-deprecation so agents install migrate paths from
cloudflare/skills instead of docs-only markdown.
* Split Sandbox skills by package line
Agents need separate build paths for stable and @next so they do
not mix incompatible exec models. Keep migration as its own
performable upgrade skill.
* Rename sandbox-sdk skill to sandbox-next
Pair build skills as sandbox-next and sandbox-stable so the
package line is obvious from the skill name.
* Restructure Sandbox skills as retrieval maps
Build skills gate the package line, state the contract, and
route to docs by task. Keep migrate as a stepwise port runbook.
* Clarify @next API file is a cheatsheet only
Point exhaustive reading at types and docs so agents do not
treat the process/terminal stub as the full Sandbox surface.
* turnstile-spin: guide token reset after submit to fix V2 double-redemption
Turnstile tokens are single-use. When siteverify returns success:false and
the user retries, the browser resubmits the same cf-turnstile-response and
Cloudflare's edge rejects it with timeout-or-duplicate. V2 telemetry since
the 2026-07-14 launch shows 4.86% sv_fail rate, of which 99% (123/124) are
double redemptions — 5x the V1 baseline of 0.9%.
Add reset-on-submit guidance to the canonical frontend snippet in SKILL.md
and to each framework reference so the widget re-solves before the retry.
Also add a 'Token lifecycle' paragraph explaining the single-use contract.
- SKILL.md: id=cf-form + reset script; Token lifecycle paragraph
- vanilla-html: main HTML + AJAX variant get reset calls
- nextjs-app: handleSubmit resets on !data.ok; Server Action variant
covers useActionState error branch
- nextjs-pages: reset script wrapped in <Script> for hydration ordering
- sveltekit: use:enhance callback resets on non-redirect + client-fetch
variant
- astro: main form script + Astro Actions variant reset
- hugo: partial gets reset script
* [Turnstile] Spin skill: address code review warnings from docs PR
Mirrors the fixes applied in cloudflare/cloudflare-docs#32147:
* Siteverify snippet in Step 9 now wraps fetch+json in try/catch,
checks r.ok, and replaces the non-existent reject(403, ...) helper
with res.status(403).send('forbidden') plus a comment about
adapting to the target framework.
* Recovery flow step 3 no longer offers 'ask user or exit' for
non-no_clearance widgets, which contradicted the scope boundary.
Always exits per the boundary now.
Keeps this file byte-for-byte in sync with the docs prompt.md and
stratus spinSkillContent.ts (the three-surface parity that the
Spin machinery depends on).
* [Turnstile] Spin skill: broaden scope beyond forms per review
Marina flagged on cloudflare/cloudflare-docs#32147 that the skill's
scope reads too form-centric, when Turnstile actually applies to any
user-triggered request the customer wants to gate: form submissions,
SPA button-triggered API calls, download links, comment or vote
submissions, and any other explicit user action that hits a backend
the customer controls.
Broadened six spots to match how Turnstile is actually used in the
wild (per the product docs at developers.cloudflare.com/turnstile),
while keeping the canonical form example in the frontend-edit
contract section as the primary illustration:
* Description: 'embed it on the right forms' -> 'embed it where user
requests need bot verification (form submissions, SPA actions, API
endpoints, download links, comment or vote submissions, etc.)'.
* When-to-load triggers: added 'protect this endpoint', 'protect this
button', 'block bots on <target>'; the 'specific request' example
bullet now lists downloads / comments / API endpoints alongside
signup / login / contact form.
* Brief-acknowledge line the agent says on Step 1.
* Wire-the-integration statement the agent says on Step 9.
* Hard-scope-boundary sentence: dropped 'form' qualifier on handler.
* Frontend-edit-contract opener: covers form or user-triggered
endpoint; dropped 'submit' from handler.
Kept in sync across all three surfaces (this canonical SKILL.md,
prompt.md docs, stratus spinSkillContent.ts).
* Harden Turnstile Spin helper scripts (safety + portability)
Replaces hand-escaped JSON with python3 json.dumps for both request
bodies and response outputs, adds argument-value validation before
each shift, structures HTTP error handling, and switches auth-probe
from a GET-based read probe to a POST-invalid-payload probe so it
tests Turnstile:Edit specifically.
widget-create.sh:
- python3 json.dumps for request body + success/error output
(replaces `echo "{\"name\":\"$NAME\",...}"` which broke
on names containing quotes, backslashes, or control characters)
- Argument value validation before shift
- Remove `2>/dev/null` on the API curl so network errors reach stderr
- URL-encode account_id
validate.sh:
- Argument value validation
- mktemp + -o + %{http_code} pattern for the widget-domains lookup
- python3 with structured error handling for JSON parse failures
- URL-encode account_id and sitekey
auth-probe.sh:
- `command -v wrangler` guard before invocation (avoids npx
install-prompt hang in non-interactive envs); fall back to
$CLOUDFLARE_ACCOUNT_ID when wrangler is not on PATH
- Replace GET-based scope probe with POST-invalid-payload probe:
a GET would authorize a Read-only token and let the agent proceed
to widget-create where it would fail. POST-invalid tests Edit
specifically: 401/403/err-10000 -> missing_scope, 400/422 -> scope OK.
- mktemp with explicit template for macOS/BSD portability
- Argument value validation
fetch-secret.sh:
- Argument value validation
- mktemp with explicit template + trap-based cleanup on early exit
- Python fallbacks use .get() with structured error output on
missing keys or non-JSON responses
- URL-encode account_id and sitekey
persist-skill.sh:
- Argument value validation
- Build scripts JSON list via python3 os.listdir + json.dumps
(replaces ls | sed | paste which mishandled filenames with quotes,
backslashes, or newlines)
Flagged by cloudflare-docs-bot on
https://github.com/cloudflare/cloudflare-docs/pull/32147: 1 critical
(CR-22ef8f6771b1) + 15 warnings + 1 suggestion. All 19 addressed.
Companion: cloudflare-docs #32147, stratus MR !40817.
* Harden Turnstile Spin helper scripts (second pass on docs-bot findings)
Second round of docs-bot findings: 6 real issues + 3 secrets-in-argv
warnings addressed. The bot's critical (EXIT trap fires in $() subshell)
is a false positive verified with a bash test: subshells reset their
parent's traps per the bash manual, so $tmp survives curl $() calls
and the trap only fires on outer-script exit.
- All scripts: 'command -v python3' guard at top; emit structured JSON
error on missing prerequisite instead of raw shell error.
- All scripts: header comments now document exit 2 (invalid usage) in
addition to exit 0 (success) and exit 1 (failure).
- widget-create.sh, validate.sh, fetch-secret.sh, auth-probe.sh:
Authorization header written to mode-600 tempfile, curl reads it via
'-H @file'. Bearer token never appears in argv.
- validate.sh: Turnstile secret written to mode-600 tempfile, curl reads
it via --data-urlencode 'secret@file'. Secret never appears in argv.
- validate.sh: strip whitespace from each expected-domains token so
'--expected-domains "a.com, b.com"' matches correctly.
- fetch-secret.sh, auth-probe.sh: guard 'errors[0]' with '(errors[0] or {})'
before .get() to survive non-dict error entries.
- All parse blocks: 'isinstance(data, dict)' check after json.loads;
emit structured error output when response is not a JSON object.
- persist-skill.sh: catch OSError (not just FileNotFoundError) so
NotADirectoryError/PermissionError on the scripts dir emit
'scripts: []' instead of a traceback.
Skipped:
- CR-04913c72363f (critical, false positive; bash test in the docs PR
triage comment)
- CR-14b4e5e6a596 (suggestion; --path is user-supplied by design so
agents can persist to .claude/skills, .opencode/skills, etc.)
Companion: cloudflare-docs #32147, stratus MR !40817.
* Guard mktemp, malformed errors list, and npx prerequisite
Docs-bot third-round review flagged four items:
- Unchecked mktemp in widget-create.sh (two calls). Applied
inline mktemp guards across all mktemp calls in
widget-create.sh, validate.sh, fetch-secret.sh, and
auth-probe.sh. On failure the scripts emit structured error
JSON matching the existing contract and clean up any earlier
tempfiles before exit.
- fetch-secret.sh accessed errors[0] without first checking
that errors is a list. Added isinstance(errors, list) guard
and applied the same fix to widget-create.sh, validate.sh,
and auth-probe.sh which have the same pattern.
- persist-skill.sh had a python3 command -v guard but not one
for npx (needed for the degit call). Added the npx guard
next to it, returning a structured error JSON on absence.
* Add cleanup safety net to auth-probe Edit-scope probe
Docs-bot and gsa_claude flagged that the Edit-scope probe POSTs a
widget-create request with intentionally-invalid empty name/domains
to distinguish Read scope (401/403) from Edit scope (400/422). The
API rejects the payload today, so no widget is created, but there
was no safety net if validation ever loosened.
Parse result.sitekey from the probe response and, if a widget was
unexpectedly created (success:true with a sitekey), fire a DELETE
against it so the probe stays side-effect-free regardless of future
API validation changes. Verdict logic and existing 400/422/200/401/
403 branches are unchanged.
* Correct Step 2 + Troubleshooting prose to match auth-probe behavior
gsa_claude flagged that Step 2's CLI-check paragraph still said Spin's
helper scripts use `npx wrangler whoami` for account enumeration and
that no persistent CLI install is required. Neither is accurate after
the auth-probe.sh rewrite: the probe uses PATH-resident `wrangler`
(not npx, so a non-interactive shell won't hang on auto-install) and
falls back to requiring `$CLOUDFLARE_ACCOUNT_ID` when wrangler is
missing.
Rewrite line 38 (Step 2) and line 195 (`wrangler whoami` troubleshooting
row) to reflect the actual behavior: PATH check first, otherwise
require the account ID be exported. Also drop the misleading suggestion
to curl `/accounts` as a fallback \x2D the Account.Turnstile:Edit token
can't list accounts (`/accounts` is Account.Read-scoped), so that
fallback would 403.
* Harden Turnstile Spin skill after independent semantic review
Independent review of the Turnstile Spin skill surfaced a critical
Python module-shadowing risk, several correctness gaps in the recovery
flow and reference examples, and drift in the README install path.
Fixes applied to SKILL.md, all six framework references, the four
helper scripts, the test doc, and the README:
- Run every embedded python3 invocation with -I to prevent cwd-relative
module shadowing of stdlib (urllib, json, hashlib, os, re, sys).
Covers -c inline, - stdin heredoc, and the bootstrap loop.
- auth-probe.sh: distinguish network_failure and upstream_failure from
missing_scope; SKILL.md Step 3 documents branches for both.
- SKILL.md Step 3: post-auth recovery resumes at Step 4 (the numbered
wizard) instead of jumping over Steps 4-7.
- SKILL.md Step 9: require git check-ignore before writing to any
.env-style file, with fallback to the platform's secret manager.
- Framework references (vanilla-html, nextjs-app, nextjs-pages, astro,
sveltekit, hugo): inline a TURNSTILE_HOSTNAMES allowlist and compare
result.hostname against it in every server-side snippet. Includes
Node, Ruby, and Python variants in vanilla-html.
- README: recommend the git-clone/symlink install path; keep the
single-file curl bootstrap only as a read-only fallback with a note
that persist-skill.sh needs the cloned bundle.
- Remove fetch-secret.sh (superseded by the in-flow existing-widget
recovery in SKILL.md, no callers remain).
Scripts still pass shellcheck and safe smoke tests (missing_token,
file_target_not_supported, empty-array rejection, unsupported-mode
rejection). Isolation is confirmed by poisoning urllib.py/json.py/
hashlib.py in the working directory and re-running each script.
---------
Co-authored-by: Jules Lemee <jules@cloudflare.com>
Wrangler 4.109 ships an alpha 'turnstile widget create/list/get/update/
delete' subcommand tree that talks to the same Cloudflare API as the
bundled widget-create.sh helper. When wrangler is installed with the
turnstile subcommand available, use it directly; otherwise fall back to
the curl-based script. Also updates Step 2 (CLI check) to name the
preference explicitly.
Server-side, dashboard-created widgets tag deployed_via=dashboard,
wrangler-created widgets tag deployed_via=wrangler, and curl-script
widgets tag deployed_via=api. The agent only needs to write the
turnstile-spin-v2 marker; the deployment channel is inferred from the
User-Agent/host on the create call.
Remove hardcoded "what's supported / not supported" boxes and any
"docs lag the engine" framing from the data-platform references.
The skills now treat the Cloudflare docs as authoritative and point
the agent to the SQL reference, limitations, and troubleshooting pages
for feature support. Keeps code templates, connection values, and
operational gotchas.
Address review feedback: reduce hardcoded prose and drift-prone content
(exhaustive function catalogs, limits, settings tables) in favor of
documentation pointers the agent should pull via the cloudflare-docs
MCP or webfetch. Each reference keeps code examples, templates, the
verified API details/endpoints, and the corrections where docs are
wrong (catalog URI/warehouse format, R2 SQL JOIN/window support).
Adds a "Documentation (pull latest)" link map to each README.
Rewrite the three data-platform references in the cloudflare skill to
match the current state of the products (verified live, June 2026).
Key corrections:
- Catalog URI is https://catalog.cloudflarestorage.com/{ACCOUNT_ID}/{BUCKET}
and warehouse is {ACCOUNT_ID}_{BUCKET} (old iceberg/ path form was wrong)
- R2 SQL endpoint is api.sql.cloudflarestorage.com/api/v1/.../r2-sql/query
- R2 SQL now supports JOINs, subqueries, CTEs, UNION/INTERSECT/EXCEPT,
SELECT DISTINCT, and the full window-function set + QUALIFY (verified);
OFFSET and the named WINDOW clause remain unsupported
- R2 Data Catalog compaction has no hard throughput cap (former 2GB/hour
limit lifted); snapshot expiration now removes unreferenced data files
- Document the new get-table control-plane API
- Pipelines: REST vs CLI field-name differences, pipeline->stream binding
rename, Logpush source, Terraform, lifecycle states, GraphQL observability
Also remove a stray SKILL.md.backup file and add R2 Data Catalog / R2 SQL
to the SKILL.md storage and analytics decision trees.
This skill stays as the v1 agent-led path; the dashboard's 'Set up with
Spin' button is the v2 parallel path. Two small SKILL.md prose edits so
the agent does the right thing when it encounters a v2-created widget:
- Recovery flow: dashboard's Deployment column flips on either v1 or
v2 marker. If the user is recovering a dashboard-created widget, a
Worker is likely already deployed in the account; confirm before
redeploying, or skip to Step 10 to wire the frontend against the
existing Worker URL.
- Telemetry marker: this skill always writes v1, but preserve v2 if
you encounter it on an existing widget. Both feed the same
account-level activation telemetry.
No changes to scripts, references, templates, or tests. Fresh widgets
created via this skill keep the turnstile-spin-v1 marker.
Co-authored-by: jules lemee <jules@cloudflare.com>
This skill stays as the v1 agent-led path; the dashboard's 'Set up with
Spin' button is the v2 parallel path. Two small SKILL.md prose edits so
the agent does the right thing when it encounters a v2-created widget:
- Recovery flow: dashboard's Deployment column flips on either v1 or
v2 marker. If the user is recovering a dashboard-created widget, a
Worker is likely already deployed in the account; confirm before
redeploying, or skip to Step 10 to wire the frontend against the
existing Worker URL.
- Telemetry marker: this skill always writes v1, but preserve v2 if
you encounter it on an existing widget. Both feed the same
account-level activation telemetry.
No changes to scripts, references, templates, or tests. Fresh widgets
created via this skill keep the turnstile-spin-v1 marker.
* Add Turnstile Spin skill
Adds an agent skill at skills/turnstile-spin/ that scaffolds Cloudflare Turnstile end-to-end: scan the codebase, create the widget via the Cloudflare API, deploy the managed siteverify Worker (template bundled at skills/turnstile-spin/templates/worker/), write the frontend snippets, and validate the integration.
Every emitted widget carries action='turnstile-spin-v1' for analytics segmentation.
Mirrors developers.cloudflare.com/turnstile/spin/.
* Refactor turnstile-spin skill: extract deterministic logic to scripts/
Per maintainer feedback (cf https://github.com/cloudflare/skills/pull/58),
SKILL.md is now a thin orchestration layer (~160 LoC, down from ~500)
and the deterministic API calls + retry logic live in 6 helper scripts:
- scripts/auth-probe.sh: token + scope + account-mismatch detection
- scripts/widget-create.sh: Cloudflare API widget creation
- scripts/worker-deploy.sh: degit + wrangler deploy + secret put + retry on name conflict
- scripts/validate.sh: health + dummy-siteverify + hostname-domains end-to-end checks
- scripts/persist-skill.sh: fetch canonical SKILL.md with HTTP 200 + frontmatter validation
- scripts/fetch-secret.sh: recovery-flow secret retrieval via API
Each script outputs structured JSON; the agent branches on the status field
instead of parsing prose. The conversational flow, hard scope boundaries,
recovery decision tree, and CAPTCHA-migration logic remain in SKILL.md
since those are agent-behavior policy, not API mechanics.
* fix(turnstile-spin): multi-account auth probe, Workers scope check, set_secret failure handling
- auth-probe.sh now handles multi-account tokens: emits multiple_accounts
when >1 accounts and CLOUDFLARE_ACCOUNT_ID is unset, checks membership
(not [0] equality) when the env var is set
- auth-probe.sh probes GET /workers/scripts after GET /challenges/widgets
so a token missing Account.Workers Scripts:Edit fails before the agent
creates a widget (irreversible) and then tries to deploy
- worker-deploy.sh makes set_secret failure fatal: previously the script
could emit status:ok with the Worker deployed but TURNSTILE_SECRET_KEY
unset
- SKILL.md Step 3 documents the new statuses (multiple_accounts,
missing_workers_scope) and the re-run loop after the user picks an
account
- SKILL.md Step 9 documents the set_secret_failed recovery path
* fix(turnstile-spin): capture both stdout and stderr in worker-deploy
Wrangler emits the deployed Worker URL on stdout (progress indicators on
stderr). The script captured only stderr and then grepped that file for
the URL, so successful deploys could still emit url_parse_failed.
Capture both streams.
* fix(turnstile-spin): comprehensive sweep before reviewer round 3
Addresses 14 issues found in an internal adversarial review:
Scripts:
- auth-probe.sh: reword Workers scope comment (best-effort proxy,
not a guarantee that Read implies Edit).
- worker-deploy.sh: URL parser falls back from workers.dev regex
to a broader match for custom domains and Workers for Platforms.
set_secret failure now captures wrangler stderr into a temp file
and includes a detail field in the error JSON instead of
swallowing the diagnostic.
- fetch-secret.sh: emit clearance_level and domains so the recovery
flow's pre-clearance check is implementable. Without these the
contract was documentation theatre.
- validate.sh: hit /health (not /); the diagnostic was lying about
the path. Also assert _worker metadata is present in the dummy
siteverify response (Step 7b promised this; the script never
checked).
- persist-skill.sh: install canonical bundle (SKILL.md + scripts/ +
references/ + templates/) via degit from cloudflare/skills
instead of writing the inlined bootstrap index.md. Persisted
skills now re-run without the /tmp/ bootstrap path.
SKILL.md:
- Recovery flow uses fetch-secret.sh's new clearance_level and
domains fields. Drops the ?widget=<id> URL trigger (nothing
parsed it; it was documentation theatre). Recovery is now
invoked verbally.
- Edge case table replaces $WORKER_NAME env var references with
the worker_name field returned by worker-deploy.sh.
- Adds explicit set_secret_failed recovery row.
Worker template:
- parseBody accepts the reCAPTCHA-style `response` field name
alongside `token` and `cf-turnstile-response`, so backends
migrated from reCAPTCHA/hCaptcha work without backend code
changes (drop the secret field, keep the rest).
* fix(turnstile-spin): match docs on suffix entropy + scope parallel-work hint
- worker-deploy.sh now uses openssl rand -hex 3 for the
name-conflict retry suffix, falling back to the previous date
tail if openssl is absent. The docs prose already called this a
hash; the script body now matches.
- SKILL.md Step 3's parallel-work hint is conditional on option 3
(paste in chat). Options 1 and 2 restart the session and lose any
pre-fetched scan state, so the agent no longer pre-fetches in
those cases.
---------
Co-authored-by: jules lemee <jules@cloudflare.com>
* Add Flagship feature flags skill to cloudflare mega-skill
Add reference files for Cloudflare Flagship (feature flag service) under
skills/cloudflare/references/flagship/ following the standard 5-file
structure (README, api, configuration, patterns, gotchas).
Covers:
- Binding API for Workers (env.FLAGS)
- OpenFeature SDK (server + client providers)
- REST API for flag management (CRUD, toggle, targeting rules, rollouts)
- FlagDefinition schema, operators, conditions, rate limits
- Progressive rollout workflows and safe deletion patterns
Also updates the cloudflare mega-skill SKILL.md with a feature flags
decision tree and product index entry.
* fix(cloudflare): remove overly specific Flagship details from skill description
Even when using the Wrangler Skill — I'm seeing that agents (Ex: Codex, via the Cloudflare Plugin) will first go off and call the MCP server to understand the shape of the REST API for Workers — and even attempt to deploy code by manually constructing API requests.
It eventually figures out it needs Wrangler — but it should _start_ here and just always use Wrangler.
This change more explicitly guides the agent to use Wrangler.
* Update cloudflare-email-service skill to match latest docs
Sync skill with updated Cloudflare Email Service documentation:
- Fix REST API endpoint from /email-service/send to /email/sending/send
- Update REST API field names (address vs email, reply_to vs replyTo)
- Update REST API response format (delivered/permanent_bounces/queued)
- Add public beta notice and known limitations
- Add Legacy EmailMessage API section
- Add ForwardableEmailMessage interface with canBeForwarded
- Add suppression lists documentation (global + account)
- Add platform limits table
- Update error codes (add E_RECIPIENT_NOT_ALLOWED, E_HEADER_VALUE_INVALID)
- Add env.EMAIL.send() as recommended reply method for routing
* Trim skill from 2,739 to ~1,000 lines
- Remove Python, Go, Node.js SDK examples (SDKs not ready), keep curl only
- Cut overlapping examples (invoice processing, D1 tracking, magic link, AI agent)
- Reduce wrangler CLI examples, point to docs and --help
- Condense routing, deliverability, and cli-and-mcp references
- Keep all essential API details, error codes, and gotchas
* Add deliverability monitoring, MCP usage, and inline attachments; consolidate reference files
- Add monitoring section to deliverability.md: dashboard, sending limits,
suppression list API, zone-level GraphQL analytics (emailSendingAdaptiveGroups,
emailSendingAdaptive) verified against production schema
- Update cli-and-mcp.md with Cloudflare MCP server search/execute examples
for email endpoints
- Add inline attachment docs (content_id, disposition: "inline") to rest-api.md
- Fix attachment content handling in sending.md (raw string/ArrayBuffer for
Workers binding vs base64 for REST API)
- Move error codes table from SKILL.md to sending.md where it belongs
- Add "Store and Reply Later" pattern to routing.md
- Remove examples.md (consolidated into other references)
- Trim SKILL.md: remove duplicated limits, prerequisites, error codes
Replace legacy building-* guides with a consolidated agents-sdk skill: update SKILL.md to expand capabilities and retrieval links, add multiple new reference pages (client-sdk, configuration, durable-execution, browse-the-web, human-in-the-loop, observability, queue-retries, routing, server-driven-messages, and others), and update command docs (build-agent.md, build-mcp.md) to point to the agents-sdk pages and include scaffold examples. Remove deprecated building-ai-agent-on-cloudflare and building-mcp-server-on-cloudflare content. These changes centralize documentation around the Agents SDK, add scaffold/snippet guidance, and refresh links to the live Cloudflare developer docs.
Address Snyk W007 (HIGH) finding for insecure credential handling.
- Remove `echo "secret-value" | wrangler secret put` pattern; use interactive
prompt as primary method and file redirect for CI
- Replace hardcoded connection string `postgres://user:pass@...` with env var
reference `$HYPERDRIVE_CONNECTION_STRING` and individual params
- Replace `--origin-password "new-password"` with `$DB_PASSWORD` env var
- Fix incorrect `--public-credential` flag to actual wrangler flags
(`--aws-access-key-id`, `--dockerhub-username`) with env var references
- Add security callout blocks in Secrets and Container Registries sections
- Add best practice #9: never embed secrets in commands
Brendan Irvine-Broque