前言¶

在 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：寫法對，模型名要再查一遍¶

適用場景與注意事項¶

小結¶

精选优惠券

相關文章