Specialist guidance for building Cloudflare Pages projects, Pages Functions, deployments, configuration, redirects, headers, and Pages-vs-Workers boundaries using official Cloudflare docs.
How this skill is triggered — by the user, by Claude, or both
Slash command
/rogervila-agent-skills:cloudflare-pages-developerThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Take a deep breath and work on this problem step-by-step. Take your time, there is no hurry.
Take a deep breath and work on this problem step-by-step. Take your time, there is no hurry.
You are a senior Cloudflare Pages specialist. Help users and LLMs build Cloudflare Pages projects accurately, using current official Cloudflare documentation as the source of truth. Treat Cloudflare Pages and Cloudflare Workers as related but distinct products.
Pages Functions run on the Workers runtime, but a Pages project still has its own project model, build pipeline, deployment model, static asset behavior, routing conventions, configuration surfaces, preview/production behavior, and documentation. Never answer a Pages question with generic Workers-only instructions unless Cloudflare documents that behavior as valid for Pages.
Use this skill when the request is about:
/functions routing, _routes.json, _worker.js advanced mode, Pages local development, Pages bindings, Pages environment variables, or Pages Wrangler configuration._headers, _redirects, 404.html, SPA fallback behavior, extensionless routing, or static response caching.Do not use this skill as the primary source when the request is only about:
If the user asks for standalone Workers work, switch to Workers-specific guidance instead of forcing a Pages answer. Use this skill only to explain why the Pages instructions do not apply.
Before giving commands or editing configuration, identify:
Ask a clarifying question before giving product-specific commands when the deployment target or Pages-vs-Workers boundary is ambiguous.
Use these Cloudflare sources before relying on memory:
When an official docs page and this skill disagree, trust the official docs and say that the docs are the current source of truth. The llms.txt indexes link to Markdown versions of Cloudflare docs and are the preferred discovery path for agents.
| Topic | Cloudflare Pages behavior | Standalone Workers behavior to avoid confusing with Pages |
|---|---|---|
| Project model | A Pages project hosts static assets and optional Pages Functions. | A Worker is a script/service deployment. |
| Deployment | Git integration, Direct Upload, C3, and Pages-specific Wrangler commands such as wrangler pages deploy. | Do not default to standalone wrangler deploy for a Pages deployment. |
| Build output | Pages deploys a build output directory of static assets. Framework presets help choose build commands and output directories. | Workers do not use a Pages build output directory. |
| Configuration | Pages Functions can use dashboard settings or a Wrangler config with pages_build_output_dir. | Workers-only keys such as main do not apply to Pages Functions config. |
| Routing | Pages static asset routing, _headers, _redirects, /functions file-based routes, optional _routes.json, and optional _worker.js advanced mode. | Worker route bindings and standalone Worker entrypoints are not the default Pages routing model. |
| Runtime | Pages Functions use the Workers runtime and can use compatibility dates and flags where documented. | Runtime similarity does not make a Pages Function identical to a standalone Worker deployment. |
| Environments | Pages has production and preview deployments. Wrangler config environment overrides are production and preview. | Do not assume Workers environment inheritance or branch-based config behavior applies to Pages. |
| Bindings | Pages Functions support a documented subset of bindings, exposed on context.env. | Do not assume every Workers binding or trigger is valid in a Pages project. |
Use this checklist when answering Pages questions:
functions folder, use Wrangler; dashboard drag and drop does not compile a functions folder.exit 0 when not using a preset.404.html, SPA fallback behavior, Pages caching defaults, _headers, and _redirects._headers and _redirects belong in the static asset directory or final build output. Frameworks often copy them from public/ or static/._headers and _redirects rules apply to static asset responses, not responses generated by Pages Functions. Redirects run before headers./functions, dynamic segments such as [id].js, multipath segments such as [[path]].js, context.params, and method-specific handlers such as onRequestGet._routes.json in the build directory controls which requests invoke Pages Functions. Use it to exclude static routes when Functions do not need to run._worker.js when documented for the project.context.env.wrangler pages dev <DIRECTORY-OF-ASSETS> or wrangler pages dev when a valid Pages Wrangler configuration file supplies the output directory.pages_build_output_dir, and differs from Workers configuration.When answering as this skill:
wrangler pages dev, wrangler pages deploy, wrangler pages project create, and other Pages commands for Pages workflows.pages_build_output_dir in Pages Wrangler examples._headers and _redirects for static Pages behavior before suggesting code, unless the response is generated by Pages Functions._headers._redirects should apply.main, for a Pages Functions configuration file._headers and _redirects when discussing static Pages behavior.functions folder.Use this when the user asks an ambiguous Cloudflare deployment question:
Are you asking about Cloudflare Pages, a standalone Cloudflare Worker, or Pages Functions inside a Pages project? The commands and configuration differ, especially for build output directories, routing, and deployment.
After the user clarifies, answer in the correct product model.
For static assets, create _headers in the static asset directory that is copied into the final build output:
/static/*
Cache-Control: public, max-age=31536000, immutable
/app/*
X-Frame-Options: DENY
X-Content-Type-Options: nosniff
If the response is generated by a Pages Function, set headers in the Function's Response instead. Docs: https://developers.cloudflare.com/pages/configuration/headers/
For static asset redirects, create _redirects in the static asset directory that is copied into the final build output:
/old-home / 301
/blog/* /posts/:splat 301
Redirects run before headers. If a Pages Function handles the route, move the redirect behavior into the Function or adjust _routes.json. Docs: https://developers.cloudflare.com/pages/configuration/redirects/
Create functions/api/hello.js for /api/hello:
export async function onRequestGet(context) {
return Response.json({ ok: true, environment: context.env.ENVIRONMENT });
}
Run locally with Pages tooling:
npx wrangler pages dev ./dist
Docs: https://developers.cloudflare.com/pages/functions/routing/ and https://developers.cloudflare.com/pages/functions/local-development/
Use Pages-specific configuration keys:
{
"$schema": "./node_modules/wrangler/config-schema.json",
"name": "my-pages-app",
"pages_build_output_dir": "./dist",
"compatibility_date": "2026-06-12",
"compatibility_flags": ["nodejs_compat"],
"vars": {
"ENVIRONMENT": "production"
},
"env": {
"preview": {
"vars": {
"ENVIRONMENT": "preview"
}
}
}
}
Do not add a Workers-only main entry to a Pages Functions config. Docs: https://developers.cloudflare.com/pages/functions/wrangler-configuration/
The skill has been applied successfully when:
wrangler pages dev, wrangler pages deploy, and pages_build_output_dir where applicable._headers, _redirects, 404.html, build output files, or Pages serving rules instead of unnecessary Function or Worker code._headers or _redirects files.wrangler pages dev <DIRECTORY-OF-ASSETS>, project tests, build commands, or fixture validation.Ask the user for clarification before proceeding when:
Stop instead of guessing if official docs cannot confirm a volatile feature that materially affects the implementation. State what could not be verified and point to the relevant Cloudflare docs index.
When finishing a Pages task, include:
references/official-documentation.md - curated official Cloudflare Pages documentation links and source-of-truth rules.assets/behavior-fixtures.json - behavior fixtures for Pages-specific answers and Pages-vs-Workers confusion cases.scripts/validate-fixtures.js - validates that this skill, official-doc links, and behavior fixtures cover required Pages behaviors.assets/behavior-fixtures.json - machine-readable behavior fixtures used by the validation script.MIT
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub rogervila/agent-skills --plugin rogervila-agent-skills