最近用 AI 写 Cloudflare Workers，我常有一种熟悉的感觉。
像是找来一个很聪明的工程师。他代码写得快，TypeScript 也熟，甚至能顺手补上测试。只是偶尔会把几年前的接口、已经过时的配置和现在的最佳实践，十分自信地装在同一个项目里。
代码看上去没有问题。
直到 wrangler deploy。
然后终端开始说话。
这其实不能全怪 AI。Cloudflare 的产品很多，Workers、Pages、D1、R2、KV、Durable Objects、Queues、Workflows、Agents SDK、Vectorize，各自都有适用边界；运行时、Wrangler 和平台能力又一直在更新。让模型只凭训练数据记住所有细节，就像让人不看 datasheet，凭印象给一颗刚发布的 MCU 配时钟树。
偶尔也能点亮。
只是心里不太踏实。
Cloudflare 官方开源的 cloudflare/skills，就是为这件事准备的。
仓库名字叫 cloudflare/skills，严格来说，它不是单独一份提示词，而是一组面向 AI Coding Agent 的技能包。
它遵循 Agent Skills 的目录结构，把 Cloudflare 平台知识拆成多个可按需加载的模块。目前官方仓库包含的核心方向有：[1]
仓库还提供 Claude Code、OpenCode、OpenAI Codex、Pi 和 Cursor 等工具的安装说明，并带有面向 Cloudflare 文档、Bindings、Builds 和 Observability 的远程 MCP Server 配置。[1]
所以，与其把它理解为“Cloudflare 的一段超级 Prompt”，不如把它看成：
Cloudflare 给 AI 编程助手准备的一套现场手册。
需要写 Worker 时翻 Workers 那一页；需要设计 Durable Object 时，再把对应章节拿出来。
手册不必每天从第一页背到最后一页。用到哪里，看哪里就好。
大模型知道 Cloudflare Workers，这通常没有问题。
问题在于，它知道的是哪个时期的 Workers。
AI 很容易写出“语法上合理、历史上也许正确、现在却不再推荐”的代码。例如：
compatibility_date；这些代码未必当场报错。有些甚至能顺利部署。
麻烦在于，它们会把问题留给以后。
Cloudflare 的 Workers Best Practices Skill 明确要求 AI 在开始编码前先获取最新文档，确认 API、限制和配置仍然有效，而不是只依赖模型预训练时记住的知识。[2]
这是我最喜欢它的一点。
它没有假装 AI 无所不知，反而先承认：
平台会变，文档比记忆可靠。
写错一行代码，编译器大多会告诉你。
产品选错了，项目可能要过几个月才开始难受。
例如：
waitUntil() 就够了？Cloudflare 主 Skill 不只是列出产品名称，还提供了按“计算、存储、AI、网络、安全、可观测性”等分类组织的产品地图，以及面向常见需求的决策树。[3]
这意味着 AI 不只是帮你回答“代码怎么写”，还会在动手之前多问一句：
这件事真的应该用这个产品做吗？
这一句，经常比后面的几十行代码更值钱。
我们都知道应该读官方文档。
但现实是，项目一忙起来，常见流程往往是：先让 AI 写，能跑就继续，不能跑再搜索报错。文档当然也看，只是通常在终端已经红了以后。
Skills 的价值，是把这些检查提前到 AI 的工作过程里。
以 Workers Best Practices 为例，它会提醒 Agent 关注：[2]
ctx.waitUntil() 处理响应后的工作；compatibility_date 和兼容标志；wrangler types 生成环境类型；这些内容单独看都不神秘。
真正有用的是，它们不再只是文档里“以后有空再看”的一章，而是在 AI 准备交付代码时，变成一张实际的检查清单。
假设我让 AI 完成这样一个任务：
使用 Cloudflare Workers 和 R2，做一个图片上传 API。
没有 Skills 时，AI 很可能迅速给出：
fetch() Handler；wrangler.toml；它完成的是“代码生成”。
加载 Cloudflare Skills 后，一个更成熟的回答应该先处理：
wrangler.jsonc 中的 Binding 配置；wrangler types 生成 Env 类型；waitUntil() 或 Queues；这时它完成的就不只是“写一段代码”，而是开始参与工程设计。
Skills 没有更换底层模型，却改变了模型拿什么资料、按什么顺序思考，以及交付前检查什么。
有点像给一个会焊接的人，补上原理图、BOM、器件 datasheet 和测试规范。
烙铁还是那把烙铁，成品会稳很多。
仓库里的内容不少，不必一口气全部消化。对普通 Cloudflare 开发，我会优先关注下面几个。
这是整个仓库的总入口。
它覆盖 Cloudflare 的主要产品，并提供产品分类、快速决策树和文档入口。遇到需求比较模糊时，可以先让 Agent 使用它做架构判断。
适合的问题包括：
我要做一个全球访问的图片服务，Cloudflare 上应该怎么选型？
KV、D1 和 Durable Objects 分别适合什么数据？
这个后台任务应该使用 Queues、Workflows，还是 waitUntil？它更像 Cloudflare 平台的导航图。
先知道往哪走，再研究路怎么修。
如果只选一个，我最推荐这个。
它不负责介绍 Cloudflare 的全部产品，而是专门约束 Workers 项目的生产质量：配置、Bindings、流式响应、异步任务、全局状态、Secret、类型生成、错误处理、日志和测试都在检查范围内。[2]
尤其适合：
Cloudflare 项目最终绕不开 Wrangler。
初始化、开发、部署、Bindings、Secret、D1、R2、Queues、类型生成，都可能通过 Wrangler 完成。命令参数又会随版本更新，仅靠模型记忆很容易写出旧命令。
这个 Skill 适合让 Agent：
Durable Objects 很强，也很容易被误用。
它适合强一致状态、连接协调、WebSocket 会话、房间和实体级状态等场景，但不是看到“状态”两个字就应该上。
专门的 Skill 能帮助 Agent 理解它的存储、生命周期、RPC、Alarm、WebSocket Hibernation 和迁移方式，也能提醒你什么时候根本不需要 Durable Objects。
如果准备在 Cloudflare 上构建 AI Agent，这两个 Skill 会更直接。
它们覆盖 Agents SDK、状态管理、实时通信、计划任务、工具调用和相关平台集成。与普通“调用一次模型 API”相比，Agent 应用通常更需要持久状态和长连接，这也是 Cloudflare 生态比较有特色的部分。
这个 Skill 面向 Web 性能分析。
它可以结合 Chrome DevTools MCP 检查 Core Web Vitals、渲染阻塞、关键请求链、缓存、图片、字体和可访问性问题。[1]
如果项目已经能跑，下一步是“为什么还不够快”，它会比泛泛地让 AI 优化页面更有方向。
官方 README 为 OpenAI Codex 提供了两种方式。[1]
npx skills add https://github.com/cloudflare/skills这适合希望快速安装的人。
安装完成后，可以重新启动或刷新 Codex，让它重新发现 Skills。
git clone https://github.com/cloudflare/skills.git然后把需要的技能目录复制到：
~/.codex/skills/在 Windows 上，通常对应：
%USERPROFILE%\.codex\skills\我更喜欢第二种方式，或者至少在安装前先打开仓库看一遍。
Skills 会参与 Agent 的工作方式。哪怕来源是官方仓库，也应该知道自己给 AI 增加了哪些规则、脚本和工具说明。
这与安装 npm 包差不多：官方身份能降低风险，不能代替阅读。
装好 Skill，不代表每次只说“帮我写个 Worker”就能得到最佳结果。
需求越具体，Skill 越能发挥作用。
使用 Cloudflare Workers、D1 和 Hono 构建一个书签 API。
先用 Cloudflare Skill 检查产品选型，再用 Workers Best Practices
审查 Bindings、类型、Secret、错误处理、日志和测试。审查当前 Worker 是否符合 Cloudflare 官方最佳实践。
重点检查全局状态、流式响应、waitUntil、Bindings、
compatibility_date、Secret、类型生成和可观测性。我要保存用户偏好、上传图片，并处理异步缩略图任务。
请比较 KV、D1、R2、Queues 和 Workflows，
给出 Cloudflare 原生架构及不选择其他方案的理由。基于当前项目的 wrangler 配置和部署日志排查问题。
不要凭记忆猜命令，先核对最新 Wrangler 文档。这里有个关键点：
不要只让 AI “使用 Cloudflare”，要让它明确执行选型、查文档和最佳实践审查。
Skill 提供了工具箱，任务描述决定它先拿扳手还是万用表。
推荐一个工具，不能只说好话。
如果业务需求本身含糊，AI 仍然可能在错误方向上写出一套很规范的代码。
最危险的项目不一定代码差，而是把错误的东西实现得非常完整。
产品目标、数据边界、成本预期和安全要求，仍然需要人来说明。
Skill 会提醒 AI 查文档、运行检查、生成类型和执行测试，但前提是 Agent 拥有相应工具与权限，而且这些步骤真的被执行了。
最后仍然要看：
bun test
bunx wrangler types
bunx wrangler deploy --dry-run如果项目有集成环境，还应验证真实的 D1、R2、KV、Queues 或 Durable Objects 行为。
文档正确，不代表实现一定正确；实现正确，也不代表部署环境配置正确。
Skill 越多，不一定越好。
一次普通的 Worker 修改，没有必要同时加载 Web Performance、Cloudflare One、AI Agent 和 Sandbox SDK 的全部知识。无关上下文太多，反而可能让 Agent 变慢，或者把简单任务想得太复杂。
按需使用，仍然是最好的办法。
Workers Best Practices 会检查 Secret、错误处理和常见工程问题，但它不等于完整的安全审计。
身份验证、授权、输入验证、数据隔离、速率限制、供应链风险和业务逻辑漏洞，仍然需要单独评估。
不要因为代码旁边写着“Best Practices”，就默认它已经不会出事。
我会把推荐对象分成几类。
它是专业工具，不是 AI 编程的必装主题包。
Cloudflare 用得越深，它的价值越明显。
cloudflare/skills 最吸引我的，不是它收录了多少产品，也不是它能让 AI 多写几个 API。
真正值得推荐的是它背后的思路：
这套方法不只适用于 Cloudflare。
以后如果 React、Next.js、Bun、嵌入式 SDK 或芯片厂商都能提供同样高质量的官方 Skills，AI Coding 会少很多“看起来很对”的代码。
做硬件时，没有人会因为自己用过几次 STM32，就决定从此不看 Reference Manual。寄存器的位置可能记得，复位值、时序条件和芯片差异还是要查。
写 Cloudflare 也一样。
AI 可以记住大概，Skill 负责把手册放到桌上。至于最后那块板子能不能点亮，仍然要看我们有没有认真测量。