前言¶

在 Cloudflare 上做一个项目，第一步往往不是写代码，而是选产品。要跑逻辑，可能是 Workers、Pages、Durable Objects，也可能是 Workflows 或 Containers；要存数据，KV、D1、R2、Hyperdrive 看着都像能用；要接模型，又会碰到 Workers AI、Vectorize、Agents SDK。文档按产品拆开，API、绑定字段和限额还经常变。AI 编程助手如果只靠训练数据往外推，很容易给出过时的 wrangler 配置、已经下线的模型 ID，或者把该用 Durable Objects 的协调场景写成普通 KV。

Cloudflare 官方在 cloudflare/skills 仓库里维护了一套 Agent Skills。其中名为 cloudflare 的这一条，是整份清单里的全平台入口：先用决策树帮 Agent 选对产品，再按需加载对应参考文件，并且把「先查官方文档、不要死记参考文件里的数字」写进了技能本身。

这是什么¶

cloudflare 是 Cloudflare 官方出品的综合性平台 Skill，目录在：

https://github.com/cloudflare/skills/tree/main/skills/cloudflare

YAML 头里的定位很直接：覆盖 Workers、Pages、存储（KV、D1、R2）、AI（Workers AI、Vectorize、Agents SDK）、功能开关（Flagship）、网络（Tunnel、Spectrum）、安全（WAF、DDoS）以及基础设施即代码（Terraform、Pulumi）。适用场景写的是 any Cloudflare development task，同时明确：偏向从 Cloudflare 文档检索，而不是依赖模型的预训练知识。

它解决的不是「再塞一份 Wrangler 命令速查」，而是两件更常见的事：

产品太多，Agent 先选错原语，后面绑定、限额、一致性模型全会跟着错。
平台面变化快，参考文件只能当起点。Skill 正文要求：引用具体数字、API 签名或配置项之前，先去官方文档、Workers 类型包、Wrangler 配置 schema 或 changelog 核对；参考文件和文档冲突时，以文档为准。

同一仓库里还有更专项的 Skill，例如 wrangler（部署与资源管理）、agents-sdk（有状态 Agent）、durable-objects。cloudflare 这条是总索引：任务还没收敛到某一个产品时，先走它。

核心设计：决策树加按需加载¶

Skill 目录很简单，只有一份入口和一大片参考资料：

skills/cloudflare/
├── SKILL.md
└── references/          # 目前 63 个产品子目录
    ├── workers/
    ├── pages/
    ├── kv/
    ├── d1/
    ├── r2/
    ├── workers-ai/
    ├── vectorize/
    ├── wrangler/
    └── ...

SKILL.md 本身不把每个产品的 API 都写进去。正文先给一组「我需要做什么」的决策树，再指向 references/<产品>/。仓库当前能列到 63 个产品目录，从 Workers、D1、Workers AI，到 Tunnel、WAF、Terraform、Email Workers 都有对应条目。

以「我要存数据」为例，Skill 里的树大致是：

Need storage?
├─ Key-value（配置、会话、缓存） → kv/
├─ 关系型 SQL → d1/（SQLite）或 hyperdrive/（已有 Postgres/MySQL）
├─ 对象/文件（S3 兼容） → r2/
├─ 向量检索 → vectorize/
├─ 强一致的实体状态 → durable-objects/
└─ 异步消息 → queues/

「我要跑代码」同样按场景分流：边缘函数走 workers/，Git 驱动的全栈站点走 pages/，有状态协同走 durable-objects/，长步骤任务走 workflows/，跑容器走 containers/，定时任务走 cron-triggers/。

每个产品目录通常再拆成几份按需读的文件，例如 Workers 参考里写的阅读顺序是：

任务	先读	再读
第一个 Worker	README → configuration → api	patterns
加存储 / 绑定	configuration → api	对应产品的 See Also
排错	gotchas	具体 binding 文档
类型安全	configuration（TypeScript）	frameworks

这就是 Agent Skills 里常见的渐进加载：对话开始时只看到 Skill 的名称和描述；任务匹配后再读 SKILL.md；真正写某个产品时，才打开对应的 configuration.md、api.md、patterns.md 或 gotchas.md。整朵云的文档被压进一个 Skill，但不会一次性灌进上下文。

安装与启用¶

官方 README 写明：这套 Skill 面向支持 Agent Skills 标准的助手，包括 Claude Code、Cursor、OpenCode、OpenAI Codex 和 Pi。安装方式按工具分开，不要混用。

1、用 npx skills（跨工具通用）

安装整个 Cloudflare Skills 集合：

npx skills add https://github.com/cloudflare/skills

只装这一条平台 Skill 时，officialskills.sh 上的页面给出的命令是：

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

2、Claude Code（插件市场）

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

同一插件里还带了远程 MCP 服务（cloudflare-docs、cloudflare-bindings、cloudflare-api 等）以及 /cloudflare:build-agent、/cloudflare:build-mcp 两条斜杠命令。它们和 cloudflare 这条 Skill 同仓，但不是 SKILL.md 本身的内容。

3、Cursor

官方 README 的写法是：从 Cursor Marketplace 安装，或在 Settings > Rules > Add Rule > Remote Rule (Github) 里填 cloudflare/skills。

4、克隆后按目录拷贝

工具	Skill 目录
Claude Code	`~/.claude/skills/`
Cursor	`~/.cursor/skills/`
OpenCode	`~/.config/opencode/skills/`
OpenAI Codex	`~/.codex/skills/`
Pi	`~/.pi/agent/skills/`

拷进去的应是 skills/cloudflare/ 这一整个文件夹，保证 SKILL.md 和 references/ 的相对路径还在。Agent 一般会按描述自动启用；任务是「帮我选 Cloudflare 存储 / 写 Worker 绑定 / 接 Workers AI」时，就会对上这条 Skill。

典型用法¶

下面几段都来自官方 Skill 参考文件里的可复现示例，用来说明 Agent 加载这条 Skill 之后应当怎么写，而不是另编一套教程。

1、先让 Agent 选产品，再写代码¶

可以直接把决策树当成提示词约束，例如：

我要做一个带用户配置、文件上传和定时清理的边缘 API。
请按 cloudflare Skill 的决策树先选计算和存储原语，再给出 wrangler 配置和 Worker 骨架。
不要凭记忆填写限额和模型 ID，有数字先对照 Cloudflare 文档。

Skill 自己列的典型触发场景包括：为新项目挑选 Workers / Pages / D1 / R2 / Durable Objects；把 Workers AI 或 Vectorize 接到现有应用；给内网服务开 Tunnel 或 Spectrum；给生产域名配 WAF 和 DDoS；用 Terraform 或 Pulumi 管 Cloudflare 资源。

2、Workers 入口与绑定¶

参考文件推荐的模块 Worker 写法是：

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    return new Response('Hello World!');
  },
};

三个参数的含义在 references/workers/README.md 里写得很清楚：request 是标准 Request，env 挂 KV / D1 / R2 / secrets 等绑定，ctx 提供 waitUntil 一类执行上下文。新建项目可以用官方脚手架：

npm create cloudflare@latest my-worker -- --type hello-world
cd my-worker
npx wrangler dev

绑定写在 wrangler.jsonc（参考文件推荐这个格式）。一份同时挂上 KV、R2、D1 的例子如下，字段名来自 references/workers/configuration.md：

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2025-01-01",
  "kv_namespaces": [{ "binding": "MY_KV", "id": "abc123" }],
  "r2_buckets": [{ "binding": "MY_BUCKET", "bucket_name": "my-bucket" }],
  "d1_databases": [{ "binding": "DB", "database_name": "my-db", "database_id": "xyz789" }]
}

改完绑定后要重新生成类型：

npx wrangler types

代码里通过 env.MY_KV、env.MY_BUCKET、env.DB 访问，绑定名是代码里的标识符，和 Cloudflare 控制台上的资源 ID 不是一回事。Secrets 不要写进配置文件，用：

npx wrangler secret put API_KEY

3、KV、D1、R2 怎么选、怎么写¶

Skill 把三类存储的分工写得很硬：

KV：读多写少、最终一致，适合配置、会话、缓存。单 key 写入有频率限制，全局可见性不是立刻的。
D1：SQLite 语义的无服务器库，适合按用户 / 租户拆库；需要写后立刻读时，参考文件指向 Sessions API，而不是假设每次查询都强一致。
R2：S3 兼容对象存储，适合文件、备份、媒体；Worker 里直接 put / get。

KV 的最小读写：

await env.MY_KV.put("key", "value", { expirationTtl: 300 });
const value = await env.MY_KV.get("key");

D1 用预处理语句，避免拼 SQL：

const user = await env.DB.prepare(
  "SELECT * FROM users WHERE id = ?"
).bind(userId).first();

R2 上传和下载：

await env.MY_BUCKET.put(key, data, {
  httpMetadata: { contentType: "image/jpeg" },
});
const object = await env.MY_BUCKET.get(key);
if (object) return new Response(object.body);

对应的 CLI 在各产品 README 里也能找到，例如 wrangler kv namespace create、wrangler d1 create、wrangler r2 bucket create。本地开发默认走模拟资源；要打到线上的 KV / AI 等，参考文件反复强调加 --remote。

4、Workers AI：写法对，模型名要再查一遍¶

Skill 推荐的调用方式是 Workers 原生绑定，不要再装已经废弃的 @cloudflare/ai 包：

{ "ai": { "binding": "AI" } }

export default {
  async fetch(request: Request, env: Env) {
    const response = await env.AI.run("@cf/meta/llama-3.1-8b-instruct", {
      messages: [{ role: "user", content: "What is Cloudflare?" }],
    });
    return Response.json(response);
  },
};

npx wrangler dev --remote   # 本地没有模型，AI 必须走 remote
npx wrangler deploy

上面这段 env.AI.run(...) 的结构来自 references/workers-ai/，现在仍然适用。但 示例里的模型 ID 不要照抄当现行推荐：Cloudflare 在 2026-05-08 的 changelog 里宣布，@cf/meta/llama-3.1-8b-instruct、@cf/meta/llama-3.1-70b-instruct、@cf/mistral/mistral-7b-instruct-v0.1 等已于 2026-05-30 弃用。同系列仍可用的包括 @cf/meta/llama-3.1-8b-instruct-fast；changelog 另给出的替代方向有 @cf/zai-org/glm-4.7-flash、@cf/google/gemma-4-26b-a4b-it、@cf/moonshotai/kimi-k2.6。完整目录以 Workers AI Models 为准。

这件事本身就是这条 Skill 的设计目的：参考文件会过期，Agent 必须先检索再引用。你在提示词里可以写一句「模型名以 developers.cloudflare.com/workers-ai/models 为准」，避免助手把 Skill 仓库里的旧示例当成当前生产配置。

适用场景与注意事项¶

比较适合这条 Skill 的情况：

新项目还没想清楚该用 Workers 还是 Pages、KV 还是 D1。
要在同一个 Worker 里把计算、存储、AI、队列串起来，需要正确的 binding 形状。
既要写应用代码，也要碰 Tunnel、WAF、Terraform 这类平台侧配置。
你已经遇到过助手编造过时 API 或限额，希望它改成「先选产品、再读参考、再查文档」。

不太适合、或需要换专项 Skill 的情况：

任务已经明确是 wrangler deploy、绑定排错，用同仓的 wrangler Skill 更直接。
目标就是用 Agents SDK 做有状态 Agent，用 agents-sdk 更贴。
这条 Skill 是给编码助手的工作流，不是 Cloudflare 控制台的替代品，也不会替你创建账号或付款。

使用时有几条参考文件反复出现的坑，值得提前写进提示词：

Workers 在请求之间没有可靠的模块级状态，持久数据放到 KV / D1 / Durable Objects。
绑定名和资源 ID 不是一回事；多环境时，非继承字段（各类 bindings）要在每个 env 下重写。
新项目必须设 compatibility_date，否则运行时行为会随平台默认值漂移。
Workers AI、部分远程资源在纯本地 wrangler dev 下不可用，需要 --remote。
数字类事实（CPU 时限、免费额度、模型价格、节点数量）不要从 Skill 参考文件里摘抄定稿。例如 Workers 参考里仍写「300+ locations」，而 Cloudflare 官方网络页当前标注的是 337 座城市；两者不一致时，按 Skill 自己的规则信文档。

小结¶

cloudflare 这条 Skill 的价值，不在于把官方文档再复制一遍，而在于给 Agent 一条可执行的路径：先用决策树收敛产品，再按 references/ 加载配置和 API，最后用 Cloudflare 文档校准会过期的部分。Cloudflare 的产品面宽、变更也快，这种「一个 Skill 覆盖整朵云、但按需展开」的结构，比把整本开发者文档塞进系统提示更实际。

官方目录：https://github.com/cloudflare/skills/tree/main/skills/cloudflare

仓库说明与各工具安装方式：https://github.com/cloudflare/skills

cloudflare Skill：给 AI 一份可渐进加载的 Cloudflare 全平台手册

前言¶

这是什么¶

核心设计：决策树加按需加载¶

安装与启用¶

典型用法¶

1、先让 Agent 选产品，再写代码¶

2、Workers 入口与绑定¶

3、KV、D1、R2 怎么选、怎么写¶

4、Workers AI：写法对，模型名要再查一遍¶

适用场景与注意事项¶

小结¶

精选优惠券

cloudflare Skill：给 AI 一份可渐进加载的 Cloudflare 全平台手册

前言¶

这是什么¶

核心设计：决策树加按需加载¶

安装与启用¶

典型用法¶

1、先让 Agent 选产品，再写代码¶

2、Workers 入口与绑定¶

3、KV、D1、R2 怎么选、怎么写¶

4、Workers AI：写法对，模型名要再查一遍¶

适用场景与注意事项¶

小结¶

精选优惠券

相关文章