PlugWiki

turnstile-spin Skill for Claude: Add Cloudflare Turnstile Bot Protection End to End

turnstile-spin makes your assistant add Cloudflare Turnstile bot protection to your frontend and backend, step by step, and test it.

Installs
98.7K
on skills.sh
Stars
3.2K
on GitHub
Files
14
besides SKILL.md
Updated
Oct 2026
last repo commit

turnstile-spin runs a wizard. It checks your Cloudflare API token, scans your code, creates a Turnstile widget, adds it to the forms or buttons you choose, and puts a server-side Siteverify check in your existing backend. It then tests that a real token works once and that replaying it fails. It has framework notes for plain HTML, Next.js (App and Pages), Astro, SvelteKit and Hugo, and a migration path from reCAPTCHA or hCaptcha.

It loads when you mention Turnstile, CAPTCHA, bot protection or protecting a form. It runs four shell scripts that call the Cloudflare API with your token, so read the safety notes below. It needs a backend to place the check in.

Good for

  • Developers protecting signup, login or contact forms from bots
  • Teams replacing reCAPTCHA or hCaptcha with Turnstile
  • Cloudflare users who want the Siteverify check done correctly

Install turnstile-spin

Claude Code

  1. 1

    Copy this prompt.

    Install the turnstile-spin skill in Claude Code. Run this command:

/plugin marketplace add cloudflare/skills
/plugin install cloudflare@cloudflare

Then check that it loaded and tell me how to use it.
  2. 2

    Paste it into Claude Code. It shows the change and asks before running it.

Pick one route, not both. The README says the plugin installs the Cloudflare guidance and the main Cloudflare MCP server, and it brings every skill in the repo. The skills CLI route installs only this skill.

From the project README. Source.

What's in the skill

When it loads

Set up, repair, or migrate to Cloudflare Turnstile bot verification in an existing frontend and backend, including server-side Siteverify.

Sections in SKILL.md

  1. Framework references
  2. When to load this skill
  3. Choose the flow before responding
  4. Conversation flow
  5. Things you must NOT do
  6. Hard scope boundary: DO NOT ask the user about
  7. Existing-widget flow: retrieve and store the secret without chat
  8. The frontend-edit contract
  9. Migrating from another CAPTCHA
  10. Edge cases
  11. Skill feedback

Key facts

Author
cloudflare (GitHub)
Repository
cloudflare/skills, folder skills/turnstile-spin
Installs on skills.sh
98,673 (as of 2026-11-02)
Repo stars
3,244 (whole repository, as of 2026-11-02)
License
Apache-2.0
Last repo commit
2026-10-31
Files in the skill folder
15 files: SKILL.md, README, 7 reference guides, 4 shell scripts and 2 test files
skills.sh audits
Gen Agent Trust Hub: pass, Socket: warn, Snyk: warn

What it includes

  • Checks your Cloudflare API token for Turnstile access

    Needs CLOUDFLARE_API_TOKEN. Sends one deliberately invalid create request to the Turnstile widgets endpoint of your account to learn whether the token has Account.Turnstile:Edit, and prints a status such as ok or missing_scope. The script says no widget is created, and deletes one if it ever is.

    Runs code · scripts/auth-probe.sh

  • Creates the Turnstile widget through the Cloudflare API

    Used when an approved Wrangler is not available. Sends a create request to the Cloudflare API and prints JSON with the sitekey and the secret on stdout. SKILL.md says to capture that in a shell variable and report only the sitekey.

    Runs code · scripts/widget-create.sh

  • Looks up the widget, then runs a dummy Siteverify test

    Reads the widget secret from standard input, fetches the widget from the Cloudflare API with your token, checks the sitekey, domains and secret, and sends a dummy token to the Siteverify endpoint.

    Runs code · scripts/validate.sh

  • Copies the skill bundle into your repo

    Run only if you agree to save the skill. It clones cloudflare/skills from GitHub into a temporary folder, copies skills/turnstile-spin into the target folder inside your project, and refuses a target folder that is not empty.

    Runs code · scripts/persist-skill.sh

  • Acknowledge, auth, domain, scan, plan, create, wire, validate, report

    Asks you to confirm before each irreversible step, then edits frontend and backend and validates with a real token.

    Write · Wizard steps 1 to 12

  • Use a widget you already made

    Retrieves the secret with Wrangler 4.109 or later and stores it without printing it, after you confirm a manifest.

    Runs code · Existing-widget flow

  • Swap scripts, fields and the verify URL

    Switches the token field to cf-turnstile-response and warns that Turnstile has no score thresholds.

    Write · Migrating from reCAPTCHA or hCaptcha

From the official docs

Permissions

Medium risk

It uses a Cloudflare API token to create a widget and store its secret, runs shell scripts that call the Cloudflare API, edits your forms and backend, and if you report bad guidance may offer to post a public GitHub issue after you approve the text. Give the token only the Turnstile permission, never paste it into chat, and review each diff.

What it can do

  • Read your data
  • Create and change things
  • Delete things
  • Read-only mode

Watch out for

  • It uses a Cloudflare API token

    The SKILL.md says never to paste the token into chat; export it in your terminal or save it to a user-only file. Create the token with only the Turnstile permission for the one account.

  • Its scripts call the Cloudflare API and GitHub

    auth-probe.sh sends one intentionally invalid create request to your account's Turnstile widgets endpoint, validate.sh reads the widget with your token and calls the Siteverify endpoint, and persist-skill.sh clones cloudflare/skills from GitHub into a temporary folder and copies it into your project. Read the scripts before you let the assistant run them.

  • It creates a widget and stores a secret

    It creates a real Turnstile widget and writes the widget secret to your env file or Worker secrets. It checks that the env file is git-ignored first.

  • It edits frontend and backend code

    It shows diffs before overwriting files and asks before each irreversible step. Work on a branch.

  • Wrangler must come from outside the project

    For secret handling it asks you to approve a Wrangler outside the project folder and never to use npx, a package script or a project-local binary.

  • The single-file install fetches scripts at run time

    The skill README offers a hosted single-file prompt from developers.cloudflare.com as a fallback. It says that install has no scripts and that the prompt fetches them on demand. Prefer the full folder install, where you can read the scripts first.

  • The plugin route also adds Cloudflare's MCP server

    The README says the Claude Code plugin installs the Cloudflare guidance and the main remote Cloudflare MCP server, which gives access to the Cloudflare API and docs. The skills CLI route installs only this skill.

  • Skill feedback can post a public GitHub issue

    A bundled skill-feedback.md tells the assistant what to do if you report wrong or outdated guidance: ask your permission, draft an issue for cloudflare/skills, show you the exact title and body and post only after you answer yes. It uses `gh issue create`, and the issue is public, so check the text for secrets before you approve.

Technical details
Talks toapi.cloudflare.com. challenges.cloudflare.com. github.com (persist-skill.sh clone)
Scopes

  • Cloudflare API token with Account.Turnstile:Edit

Questions

What does the turnstile-spin skill do?

It sets up Cloudflare Turnstile in an existing site. It creates the widget, adds it to the forms you pick, adds the server check for the token, and tests it with a real token.

How do I install turnstile-spin?

Use the install box at the top of the page. Install the full folder so the scripts come with it. The skill's README says a single-file install of the hosted prompt does not include the scripts and fetches them on demand.

Does turnstile-spin need an API key?

Yes. It needs a Cloudflare API token with the Account.Turnstile:Edit permission, or an existing widget secret retrieved with Wrangler. The SKILL.md says not to paste the token into chat.

Does it work without a backend?

No. The SKILL.md says that if the form has no backend handler, such as a static site with only mailto, it says so and exits, because Siteverify must run on a server.

Is turnstile-spin safe?

It handles a Cloudflare token and a widget secret and runs four shell scripts, so read the permissions section first. Its SKILL.md rules include never printing the secret, never writing it to disk except your own secret store, asking before each irreversible step and showing diffs before overwriting files.

Can it replace reCAPTCHA?

Yes. It detects reCAPTCHA and hCaptcha and plans a swap of scripts, token field and verify URL. It does not auto-migrate reCAPTCHA Enterprise, and Turnstile has no score, so code that relied on v3 scores will reject on failure instead.

Information

updated Nov 2, 2026

Repository
cloudflare/skills
Folder
skills/turnstile-spin

cloudflare/skillsskills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 9
  1. cloudflare/skills README · github.com
  2. skills.sh listing · skills.sh
  3. turnstile-spin SKILL.md · github.com
  4. turnstile-spin scripts/auth-probe.sh · github.com
  5. turnstile-spin scripts/widget-create.sh · github.com
  6. turnstile-spin scripts/validate.sh · github.com
  7. turnstile-spin scripts/persist-skill.sh · github.com
  8. turnstile-spin README · github.com
  9. turnstile-spin skill-feedback.md · github.com

Updated Nov 2, 2026.