Turnstile Spin skill: set up Cloudflare Turnstile with your agent

Source: cloudflare/skills · Maintainer: Cloudflare · License: Apache-2.0 · Checked: 24 October 2026

What is the Turnstile Spin skill?

The turnstile-spin skill is Cloudflare's official Agent Skill for adding Cloudflare Turnstile bot verification to an existing site. It runs a guided setup that creates the widget, embeds it in your forms, adds server-side Siteverify to the backend you already have, and validates the result before it reports success.

Its SKILL.md description reads: "Set up, repair, or migrate to Cloudflare Turnstile bot verification in an existing frontend and backend, including server-side Siteverify."

The skill states its goal as turning "the prompt "set up Turnstile" into a working end-to-end integration." It is the agent version of Turnstile Spin, which Cloudflare's docs call "a setup flow for Cloudflare Turnstile." Its skills.sh page listed 91.7K installs (snapshot, 24 October 2026).

What does it do?

Unlike most Cloudflare skills, this one includes scripts. The folder has:

• SKILL.md: the wizard the agent follows.
• scripts/: auth-probe.sh (checks your API token for Turnstile scope), widget-create.sh (creates the widget through the Cloudflare API), validate.sh (a dummy Siteverify plus hostname check) and persist-skill.sh (saves the skill bundle into your repo).
• references/: snippets for vanilla HTML, Next.js App Router, Next.js Pages Router, Astro, SvelteKit and Hugo.
• tests/: validation cases and a Python test for the persist script.

The SKILL.md describes the split: "The scripts hold the deterministic logic (API calls, retry/error handling); your job is orchestration, codebase reading, confirmation, and the frontend + backend edits."

The 12-step wizard. Each step is one agent message, and several wait for you:

1. Acknowledge and ask to proceed.
2. Check the CLI setup.
3. Probe your API token for Account.Turnstile:Edit.
4. Select the account.
5. Confirm domains: always localhost and 127.0.0.1, plus your production domain.
6. Scan the codebase for the frontend framework, the backend handler and any existing CAPTCHA.
7. Show an insertion plan, with a stable action name per protected surface.
8. Create the widget in managed mode.
9. Embed the widget and add Siteverify inside each existing handler.
10. Validate with a fresh real token, then confirm a replayed token is rejected.
11. Offer to save the skill into your repo.
12. Print a final report.

The backend check. The canonical Siteverify code requires success, the expected action and a hostname from a TURNSTILE_HOSTNAMES allowlist, and fails closed on network errors. Cloudflare's server-side validation docs are the reference. The contract is "gate, don't replace": your handler keeps its logic, with a check in front.

Secret handling. The secret goes into your existing secret store as TURNSTILE_SECRET. Before writing to a .env file, the agent runs git check-ignore and stops if the file is not ignored. It never puts the secret in command arguments, logs or chat.

Migration. If it finds reCAPTCHA or hCaptcha, it swaps the script tag, widget class, token field (g-recaptcha-response becomes cf-turnstile-response) and Siteverify URL. It tells you that reCAPTCHA v3 score thresholds have no Turnstile equivalent and points reCAPTCHA Enterprise users to Cloudflare's reCAPTCHA migration guide.

Existing widgets. If you already have a sitekey, the skill skips creation and runs a guarded flow that retrieves and stores the secret without printing it. That flow requires Wrangler 4.109 or later, installed outside the project.

How do you install it?

Just this skill, with the skills CLI. This is the command on skills.sh:

npx skills add https://github.com/cloudflare/skills --skill turnstile-spin

Add -g to install it for all projects. In Claude Code the folder lands in .claude/skills/turnstile-spin/ in your project, or under ~/.claude/skills/ globally, the standard Claude Code skill locations.

Claude Code or Codex plugin. The repo README installs every Cloudflare skill plus Cloudflare's remote MCP server:

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

For Codex, run codex plugin marketplace add cloudflare/skills and then codex plugin add cloudflare@cloudflare, and start a new session.

Clone and symlink. The skill's own README suggests cloning once and linking the folder:

git clone https://github.com/cloudflare/skills ~/.config/cloudflare-skills
ln -s ~/.config/cloudflare-skills/skills/turnstile-spin ~/.claude/skills/turnstile-spin

Hosted single file. If cloning is not an option, Cloudflare hosts the prompt as one file:

mkdir -p .claude/skills/turnstile-spin && \
  curl -sSL https://developers.cloudflare.com/turnstile/spin/prompt.md \
  -o .claude/skills/turnstile-spin/SKILL.md

That version has no scripts/ or references/ and fetches them on demand. The Spin docs list Claude Code, Cursor, Codex, OpenCode and GitHub Copilot Chat as supported agents. See Codex skills and Cursor skills for where each agent reads skills.

How do you use it?

Ask for bot protection on a specific surface. The skill loads on words like "Turnstile", "CAPTCHA", "protect this form" or "stop bot signups." Example prompts (suggestions, not quotes from the repo):

• Set up Turnstile on our signup and login forms.
• We're getting spam signups. Protect the contact form with Cloudflare.
• Migrate this site from reCAPTCHA v2 to Turnstile.
• I already created a Turnstile widget with sitekey 0x4AAA... Wire it into the comment form.
• Our Turnstile widget has no server-side check. Add Siteverify to the existing handler.

Expect it to pause often: after the opening summary, at the domain list, at the insertion plan and before writing code. Before you start, create an API token with Account.Turnstile:Edit and export it in the terminal you launch the agent from, as the skill describes. You also need curl, python3 and jq, which the helper scripts check for.

Tips and limits

• It needs a backend. For a static site or a mailto form, the skill says so and exits. Siteverify must run on a server you control.
• Narrow scope by design. It will not suggest email delivery, new backends, databases or styling changes. It gates your handler and leaves the rest alone.
• Production hostnames only. The skill and the docs both say a production TURNSTILE_HOSTNAMES value must not include localhost or 127.0.0.1.
• Tokens are single use. If the page stays open after a submit, the widget must be reset before a retry. The framework references show where.
• It runs scripts. The helpers call api.cloudflare.com with your token. Read them before you run the skill if your policy requires it.
• Audits. On 24 October 2026, skills.sh showed Pass from Gen Agent Trust Hub and Socket, and Warn from Snyk. Snyk's report, dated 12 October 2026, lists two medium findings: W011 (third-party content exposure, because the scan reads files such as README.md and package.json) and W012 (an external dependency, because persist-skill.sh clones github.com/cloudflare/skills).
• License. Apache-2.0 lets you copy and change it; keep the license and notices when you redistribute.

Save it in your Kipt library

In Kipt, open Skills and paste the skill's GitHub folder link into the import box. Kipt reads the SKILL.md and the folder's files, including scripts/ and references/; for a repo with many skills it shows a list to pick from. You can also drop the folder or a .zip. Your skills live in your own private GitHub repo and install into Claude Code or Codex with one command:

npx skills add https://github.com/<you>/<repo>.git --all -g

Kipt is not affiliated with Cloudflare.

Similar skills

• Cloudflare skill: the product chooser that routes form-abuse tasks to this skill.
• Wrangler skill: for storing TURNSTILE_SECRET on a Worker and deploying.
• Security hardening skill: broader input validation and auth checks around the forms you protect.
• Cloudflare Workers skill: for reviewing a Worker backend that calls Siteverify.