Cloudflare Skills 贡献指南如何编写一个高质量的 Agent Skill官方原则详解【免费下载链接】skillsSkills for teaching agents how to build on Cloudflare.项目地址: https://gitcode.com/gh_mirrors/skills14/skillsCloudflare 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 就是一个独立文件夹路径作用skills/技能名/SKILL.md单个技能的入口文件包含触发描述与行为指引skills/技能名/references/辅助参考文档由SKILL.md按需加载plugin.json插件清单声明插件名称、版本与关键词mcp.json插件附带捆绑的 MCP 服务器配置CONTRIBUTING.md官方贡献原则本文的灵魂rules/workers.mdc面向特定 Agent 场景的规则文件 想先看全景读 README.md 即可了解 14 个内置 Skill 各自解决什么问题、如何在不同 Agent 中安装。二、官方贡献第一原则Keep skills smallCONTRIBUTING.md 开头一句话就点破了第一原则Keep skills small: help agents find the right documentation instead of maintaining another copy of it.翻译过来Skill 的职责是当路标而不是仓库。官方要求每个改动都遵守 4 条规则见 CONTRIBUTING.md#L5-L10先验证再动手— 先读官方开发者文档的相关页面确认你提出的建议有文档支撑链接能打开不等于内容正确链接优于复制— 直接链接到对应的产品/工作流页面不要复制那些会过时的 API 签名、限额、价格、配置和示例指针替代过期内容— 修正过时参考时尽量用一行短指针指向当前文档而不是保留一大段旧内容文档缺口要诚实— 如果官方文档缺少所需指引在 PR 中说明这个文档缺口而不是往 Skill 里塞未经支持的野路子。⚠️ 为什么这么严格因为模型的预训练知识会过时官方文档才是唯一最新的事实来源。复制大量细节的 Skill 半年后就会变成误导性内容。三、检索优先几乎所有 Skill 的共同设计在大量SKILL.md中你都会看到同一句话Prefer retrieval over pre-training实时检索优先于模型记忆。以 skills/agents-sdk/SKILL.md 为例frontmatter 之后立刻声明你对 Agents SDK 的知识可能已过时随后给出一张Retrieval Sources 表三列即可覆盖路由需求列作用以 agents-sdk 为例TopicQuick start、Configuration、Callable methods、Scheduling…Docs URL官方文档站对应页面Use for什么任务去查哪一行 这套主题 → 来源 → 用途三列表格是整个仓库最核心的写作范式贡献时请优先模仿。四、解剖一份高质量 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 的共性特征。五、写法对比两种风格怎么选风格代表适用场景文档地图型wrangler、agents-sdk、durable-objects官方文档完备的产品Skill 只做路由 护栏向导型turnstile-spin端到端多步骤任务SKILL.md定义 12 步向导scripts/ 放确定性脚本鉴权探测、创建组件、验证tests/ 放验证用例turnstile-spin 是仓库中少有的带scripts/与tests/的 Skill脚本承载 API 调用、重试等确定性逻辑SKILL.md只负责编排、读代码和向用户确认。代价是篇幅更长换来的是行为可复现——适合必须走完才能成功的任务。六、贡献前自查清单6 步走结合 CONTRIBUTING.md 的原则与内置 Skill 的结构提交 PR 前请依次过一遍✅文档来源确认指引是否被官方文档支撑不支撑就在 PR 中说明文档缺口✅保持精简能删掉的重复 API 签名、价格、配置示例都换成链接✅Frontmatter 检查新 Agent 只看 name description能否判断何时触发这个 Skill✅表格化表达任务场景、检索来源、常见错误是否都做成了可逐行匹配的表格✅护栏到位高风险操作写密钥、删数据、覆盖文件是否明确禁止并有安全替代方案✅参考按需拆分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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考