Cloudflare Skills 贡献指南：如何编写一个高质量的 Agent Skill（官方原则详解）

Cloudflare Skills 贡献指南：如何编写一个高质量的 Agent Skill（官方原则详解）

【免费下载链接】skillsSkills for teaching agents how to build on Cloudflare.项目地址: https://gitcode.com/gh_mirrors/skills14/skills

Cloudflare Skills 是 Cloudflare 开源的 Agent 技能库，通过一个个 "Agent Skill" 教会 AI 智能体（Agent）如何在 Workers、Durable Objects、Agents SDK、Wrangler 等平台上构建应用。本文基于仓库的 CONTRIBUTING.md 官方贡献原则与 14 个内置 Skill 的设计模式，逐步拆解如何编写一个高质量、易维护的 Agent Skill，适合首次参与开源贡献的新手阅读。

一、什么是 Agent Skill：先看懂项目结构

Agent Skill 是一个可被"按上下文自动加载"的知识包：当用户请求命中某个 Skill 的触发条件时，Agent 会加载对应的SKILL.md，再按指引实时获取最新文档并完成任务。

本仓库的结构非常清晰，每个 Skill 就是一个独立文件夹：

💡 想先看全景，读 README.md 即可了解 14 个内置 Skill 各自解决什么问题、如何在不同 Agent 中安装。

二、官方贡献第一原则：Keep skills small

CONTRIBUTING.md 开头一句话就点破了第一原则：

Keep skills small: help agents find the right documentation instead of maintaining another copy of it.

翻译过来：Skill 的职责是当"路标"，而不是"仓库"。官方要求每个改动都遵守 4 条规则（见 CONTRIBUTING.md#L5-L10）：

1. 先验证再动手— 先读官方开发者文档的相关页面，确认你提出的建议有文档支撑；"链接能打开"不等于内容正确；
2. 链接优于复制— 直接链接到对应的产品/工作流页面，不要复制那些会过时的 API 签名、限额、价格、配置和示例；
3. 指针替代过期内容— 修正过时参考时，尽量用一行短指针指向当前文档，而不是保留一大段旧内容；
4. 文档缺口要诚实— 如果官方文档缺少所需指引，在 PR 中说明这个文档缺口，而不是往 Skill 里塞未经支持的"野路子"。

⚠️ 为什么这么严格？因为模型的预训练知识会过时，官方文档才是唯一最新的事实来源。复制大量细节的 Skill 半年后就会变成误导性内容。

三、"检索优先"：几乎所有 Skill 的共同设计

在大量SKILL.md中你都会看到同一句话：Prefer retrieval over pre-training（实时检索优先于模型记忆）。

以 skills/agents-sdk/SKILL.md 为例，frontmatter 之后立刻声明"你对 Agents SDK 的知识可能已过时"，随后给出一张Retrieval Sources 表，三列即可覆盖路由需求：

🔍 这套"主题 → 来源 → 用途"三列表格是整个仓库最核心的写作范式，贡献时请优先模仿。

四、解剖一份高质量 SKILL.md 的七段式结构

综合 skills/wrangler/SKILL.md 等成熟样例，一份高质量SKILL.md通常由以下 7 部分构成：

4.1 Frontmatter：技能的"触发开关"

文件顶部的 YAML 元数据，决定 Agent 何时识别并加载它：

--- name: wrangler description: Run or troubleshoot Wrangler CLI commands and configure Worker projects for local development, Previews, deployment, and Cloudflare resource management. ---

description的写法要点：

• 覆盖触发场景— skills/durable-objects/SKILL.md 甚至有独立的 "When to Use" 与 "Do NOT Use For" 两节，明确列出适合与不适合的场景，防止误触发；
• 贴近用户口吻— skills/turnstile-spin/SKILL.md 直接列举用户可能的问法："set up Turnstile"、"protect this form"、"stop bot signups"，命中率更高。

4.2 决策表：从"用户想要什么"直达"读哪篇文档"

全仓库最高频的格式，把任务场景做成可逐行匹配的表格：

• skills/wrangler/SKILL.md 的 "任务 → 文档来源" 表，15+ 行覆盖部署、Secrets、Previews、权限等全部场景；
• skills/cloudflare-email-service/SKILL.md 的 "I want to… → Path → Reference" 三列表。

🎯 原则：让 Agent 按行匹配，只读取命中的那一篇参考文档，而不是加载全部。

4.3 Quick Reference：最小可用代码集

只保留最高频的 API，用"任务 | API"两列表压缩。如 skills/durable-objects/SKILL.md 把读写状态、SQL 查询、定时任务、RPC、重试等 15 个常用操作压进一张表。

4.4 反模式清单：告诉 Agent "不能做什么"

告诉 Agent 避免什么，往往比教它做什么更重要：

• skills/durable-objects/SKILL.md 的 "Anti-Patterns (NEVER)"：单例全局 DO 会成为瓶颈、每个请求都用blockConcurrencyWhile会杀死吞吐量；
• skills/workers-best-practices/SKILL.md 的 "Anti-Patterns to Flag" 表，每条反模式都配了"后果 + 推荐模式"。

4.5 常见错误表：错误 | 原因 | 修法

skills/cloudflare-email-service/SKILL.md 的 "Common Mistakes" 是典范：11 条高频错误（漏配send_email绑定、两次读取message.raw流、硬编码令牌……）各配一句成因和一步修法，Agent 排错时可直接命中。

4.6 References：带说明的目录

把references/下的文档逐一列出并标注"它装什么"。如 skills/agents-sdk/SKILL.md 将 18 篇参考文档分成 Core、Chat & Streaming、Background Processing、Integrations、Experimental 五组，一目了然。

4.7 验证环节：闭环才算完成

wrangler 技能把整个流程组织为 Inspect → Retrieve → Apply →Validate四段：改完配置要重新生成类型、部署前 dry-run、如实汇报未完成的验证项。"闭环"是高质量 Skill 的共性特征。

五、写法对比：两种风格怎么选

turnstile-spin 是仓库中少有的带scripts/与tests/的 Skill：脚本承载 API 调用、重试等确定性逻辑，SKILL.md只负责编排、读代码和向用户确认。代价是篇幅更长，换来的是行为可复现——适合"必须走完才能成功"的任务。

六、贡献前自查清单：6 步走

结合 CONTRIBUTING.md 的原则与内置 Skill 的结构，提交 PR 前请依次过一遍：

1. ✅文档来源确认：指引是否被官方文档支撑？不支撑就在 PR 中说明文档缺口；
2. ✅保持精简：能删掉的重复 API 签名、价格、配置示例都换成链接；
3. ✅Frontmatter 检查：新 Agent 只看 name + description，能否判断何时触发这个 Skill？
4. ✅表格化表达：任务场景、检索来源、常见错误是否都做成了可逐行匹配的表格？
5. ✅护栏到位：高风险操作（写密钥、删数据、覆盖文件）是否明确禁止并有安全替代方案？
6. ✅参考按需拆分：references/是否拆得足够细、每条都有说明、可按需单篇读取？

七、写在最后

编写一个高质量的 Cloudflare Agent Skill，可以浓缩为一句话：做路标，不做仓库——触发要精准、检索要优先、表格胜过长文、护栏胜过示例、链接胜过复制。仓库里的 14 个内置 Skill 就是 14 份活的范文，从 CONTRIBUTING.md 和 README.md 读起，再精读一个你最常用的SKILL.md，你自然就会写出符合官方风格的贡献。

【免费下载链接】skillsSkills for teaching agents how to build on Cloudflare.项目地址: https://gitcode.com/gh_mirrors/skills14/skills