1. 基本信息
| 项目 | 内容 | 数据来源 |
|---|---|---|
| 名称 | workers-best-practices-cloudflare-skills | — |
| 作者/维护者 | Cloudflare, Inc. 官方仓库 cloudflare/skills；该子技能由 Cloudflare VP of Product & Securing Agents Matt Silverlock（GitHub：elithrar）在 PR #19 引入，合并于 2026-02-12 |
GitHub API（repo + PR + 用户资料） |
| 来源链接 | https://github.com/cloudflare/skills/tree/main/skills/workers-best-practices | — |
| 许可证 | Apache-2.0（仓库根 LICENSE 声明） | GitHub API |
| GitHub Stars / Forks | 所属仓库 2,521★ / 239 forks（该数字属整个合集仓库，不代表本子技能个体热度；子技能自身证据见第 6 章） | GitHub API |
| 最新版本 | 无独立版本号系统；该子目录自 2026-02-12 引入后未见后续改动提交 | GitHub API（commits） |
| 安装方式 | Claude Code 插件市场一条命令 / npx skills / 手动复制 |
仓库 README |
2. 功能介绍与亮点
workers-best-practices 是 Cloudflare 官方为 Workers 平台编写的代码审查与代码编写规则库，教会编码 Agent 在动笔之前先核对生产环境常见反模式。核心设计：
- 检索优先：动笔写代码或做审查前，先抓取官方最新的 Workers Best Practices 文档页、
@cloudflare/workers-types包与本地wrangler的config-schema.json，不依赖可能过期的预训练知识。 - 五大类规则：配置（
compatibility_date、nodejs_compat、密钥管理）、请求/响应处理（流式响应、ctx.waitUntil()）、架构（bindings 优于 REST API、Hyperdrive、Service Bindings）、可观测性（结构化日志）、代码模式（禁止模块级全局状态、Promise 必须被处理）。 - 独立参考文档：
references/review.md给出审查流程与类型校验步骤，references/rules.md收录全部规则与代码示例，按需加载而非一次性塞进上下文。 - 反模式速查表：列出 13 条具体反模式及后果，例如“
Math.random()用于生成 token 是可预测的，非密码学安全““直接字符串比较密钥值存在时序侧信道，应使用crypto.subtle.timingSafeEqual”。
3. 适用场景
固定分类：工程效率与代码质量。
面向正在 Cloudflare Workers 平台上编写新代码或审查既有代码的开发者：新建 Worker 项目、提交前自查、排查生产环境超时或内存问题、配置 wrangler.jsonc 时希望规避常见反模式。
4. 跨 Agent 兼容性
- Claude Code：✅ 原生支持——官方页面
developers.cloudflare.com/agent-setup/claude-code/直接点名描述本技能（而非仅提及所属合集），安装走插件市场或npx skills一条命令。 - Codex：✅ 支持，但有已知路由重叠问题——仓库 README 声明“适用于任何支持 Agent Skills 标准的 Agent，包括 Claude Code、OpenCode、OpenAI Codex 和 Pi”；独立开发者 lygris 在 GitHub issue #85 中实测本仓库技能集在 Codex 下的表现，明确点名 workers-best-practices 与 wrangler、durable-objects、agents-sdk 等技能的描述字段存在触发范围重叠，可能导致多个专家技能同时加载。
- OpenClaw：❓ 未验证——README 未点名。
- Hermes Agent：❓ 未验证——同上。
5. 推荐理由
这是 Cloudflare 官方给 Workers 开发者的一份“代码质量守门人”技能：动笔写代码或做审查前，先强制拉取最新官方文档与类型定义，再对照配置、请求处理、架构、可观测性、代码模式五大类规则逐一核对，把“流式响应处理不当导致内存溢出”“密钥比较存在时序侧信道”这类容易在生产环境才暴露的问题，提前挡在评审阶段。对用 Claude Code、Codex 等 Agent 在 Cloudflare Workers 上写代码的开发者是直接可用的质量保险。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 8 | 官方 developers.cloudflare.com/agent-setup/claude-code/ 集成文档页直接点名描述本技能；作者 Matt Silverlock 系 Cloudflare VP of Product & Securing Agents；所属仓库 issue 区有独立第三方深度技术讨论（lygris 的 Codex 路由测试明确点名本技能），同时被 mcpservers.org、officialskills.sh、claudemarketplaces.com 等至少 5 个第三方 Agent Skill 目录站收录 |
| 可用性 | 9 | npx skills add cloudflare/skills --skill workers-best-practices 或插件市场一条命令即可安装；SKILL.md 主文档 + 两份独立参考文档结构清晰；检索优先设计确保规则始终对照最新官方文档，内容本身更新频率不影响时效性；无付费依赖；所属仓库近一周内仍有提交，维护活跃 |
| 安全性 | 9 | 检查清单详见下表 |
安全检查清单：
- ① 是否执行 shell 命令及权限范围：仅在审查流程中引导执行
npm pack拉取官方发布的@cloudflare/workers-types包、wrangler types生成本地类型，均为只读/生成操作，无破坏性命令 - ② 运行时是否联网外发数据：唯一网络行为是从
developers.cloudflare.com官方文档站与 npm 公共 registry 拉取参考资料，不涉及向未声明第三方外发用户数据 - ③ 是否要求 API key/凭据及其存储方式：技能本身不要求任何凭据；反模式速查表反而提醒开发者不要把 secrets 硬编码进源码，引导使用
wrangler secret put - ④ SKILL.md 与附带脚本中有无可疑指令：全文纯 Markdown + 代码示例，两份参考文档逐节审阅未见混淆代码或 prompt injection 迹象
- ⑤ 作者/组织信誉：Cloudflare, Inc. 官方组织仓库，作者 Matt Silverlock 为 Cloudflare VP of Product & Securing Agents，GitHub 账号 1073 followers
- ⑥ License 是否明确：明确，Apache-2.0
- ⑦ 最近维护时间：仓库整体活跃（近一周内仍有提交），该子技能内容自 2026-02-12 引入后未见后续改动，但因检索优先设计对内容陈旧不敏感
7. 跟同类 Skills 相比的优势
| 对比对象 | 定位 | 与本技能的差异 |
|---|---|---|
| code-review-security-owasp（OWASP 官方 secure-agent-playbook） | 通用安全代码审查技能，对照 OWASP Top 10 与 ASVS 系统性排查注入、鉴权、加密等漏洞类别，跨语言、跨平台适用 | 覆盖面更广但不含任何 Workers 平台专属知识（bindings、wrangler 配置、Durable Objects 等）；本技能反过来只覆盖 Workers 平台，但把流式处理、全局状态泄漏、Promise 未处理等 Workers 特有反模式讲得更具体 |
| wrangler-cloudflare-skills（同仓库姊妹技能） | 专注 Workers/KV/R2/D1/Vectorize/Queues 的部署与配置管理操作 | 解决“如何把代码发布上线”，本技能解决“代码本身是否符合生产最佳实践”，两者分别覆盖开发流程的部署与审查两端，互补而非重叠 |
8. 用户评价
该技能目前在第三方平台尚无独立的具名评测文章，但官方仓库 issue 区留有一条可查证的实测技术反馈：开发者 lygris 在 GitHub issue #85 中记录了在 OpenAI Codex 环境下运行本仓库技能集的具体发现——workers-best-practices 与同仓库的 wrangler、durable-objects、agents-sdk 等技能的触发描述范围存在重叠，建议把总览技能改造成更明确的路由器以减少描述重叠、降低上下文加载量。
9. 其他补充
同仓库内另有 cloudflare、agents-sdk、durable-objects、wrangler、sandbox-sdk、web-perf、turnstile-spin、cloudflare-email-service 等十余个子技能覆盖 Cloudflare 开发的不同侧面，与本技能形成互补的工具箱；仓库不设版本号升级机制，改动直接体现在提交历史中。
10. 安装使用方式
方式一：Claude Code 插件市场（推荐）
/plugin marketplace add cloudflare/skills
/plugin install cloudflare@cloudflare该命令会连带安装同仓库全部 Cloudflare 技能，包括 workers-best-practices。
方式二：npx skills 通用安装器
npx skills add cloudflare/skills --skill workers-best-practices方式三：手动复制
克隆仓库后，将 skills/workers-best-practices 文件夹复制到对应 Agent 的技能目录（如 Claude Code 的 ~/.claude/skills/、OpenAI Codex 的 ~/.codex/skills/）。
安装后无需重启；技能基于 SKILL.md 的 description 字段自动匹配触发，当对话涉及编写新 Worker、审查 Worker 代码、配置 wrangler.jsonc 或排查 Workers 反模式时会被自动加载，无需手动调用。
11. 注意事项
该技能仅覆盖 Workers 平台专属的代码质量规则，不含通用 Web 安全漏洞的系统性排查（该需求可另配合 OWASP 类通用代码审查技能）；仓库 README 的 Skills 汇总表尚未同步收录本条目，但不影响插件市场安装与实际触发；Codex 环境下已有开发者实测发现本技能与同仓库其他技能存在触发范围重叠，多个专家技能可能同时加载；OpenClaw、Hermes Agent 暂无官方兼容性声明。