给 flutter-ai-rules 贡献你的第一个技能:开发者指南与官方文档链接硬性要求
给 flutter-ai-rules 贡献你的第一个技能:开发者指南与官方文档链接硬性要求
flutter-ai-rules 是一个收录 36 个 Flutter 与 Dart AI 技能(Agent Skills)的开源仓库,供 Claude Code、Codex、Cursor 等 AI IDE 自动加载。本文带你从零开始为它贡献你的第一个技能,重点讲清楚仓库唯一的硬性要求:每一处新增内容都必须附官方文档链接,这是保证仓库客观、可审查的核心规则。
🧩 什么是 flutter-ai-rules 里的一个"技能"
一个技能就是一个文件夹,核心是一个 SKILL.md 文件。AI 代理会先读取其中的 description,判断任务是否匹配,再自动加载相应指导——你无需手动粘贴规则或 @ 提及任何文档。
标准结构如下(见 skills/README.md):
skills/
└── my-skill/
├── SKILL.md # 必需
├── scripts/ # 可选 —— 可执行脚本
├── references/ # 可选 —— 按需加载的补充文档
└── assets/ # 可选 —— 模板、配置文件
比如布局技能 skills/flutter-use-column-row-first/SKILL.md,它指导代理优先用 Row/Column 构建响应式布局:
🛠️ 第一步:克隆仓库并建立分支
先克隆仓库,然后在本地修改——这也是仓库保持只读、通过 PR 协作的方式:
git clone --depth 1 https://gitcode.com/gh_mirrors/fl/flutter-ai-rules.git
克隆后新建一个功能分支(如 add/my-skill),把新技能放在 skills/ 目录下。技能文件夹命名用小写加连字符,如 bloc、mocktail、flutter-pre-caching。
📝 第二步:编写 SKILL.md 的必备格式
参考现有技能 skills/mocktail/SKILL.md,文件顶部是 YAML frontmatter:
---
name: my-skill
description: "Use when ..."
license: MIT
---
三条关键写作约定:
- description 只写一行,且必须以
Use when开头,只包含触发条件——这是仓库全局规则文件 AGENTS.md 中的明确要求,也是技能被正确"自动选中"的关键; - 正文重写而非搬运:用本项目自己的话概括官方文档(condensation),不要整段复制原文;
- 保持文件小而聚焦:各工具官方文档建议
SKILL.md控制在 500 行以内(Claude Code 的软性建议),详细内容拆到references/按需加载。
🔗 第三步:硬性要求——官方文档链接
这是整个贡献流程中唯一的硬性要求,来自 README.md 的 Contributing 章节:
Include an official documentation link for anything you add or change. That's the one hard requirement — it's what keeps the repo objective and reviewable.
具体要做的三件事:
- 每个技能都要能追溯到来源:技能中每条指导都应指向它依据的官方文档页面,比如 skills/effective-dart/SKILL.md 对应 Dart 官方 Effective Dart,skills/flutter-errors/SKILL.md 对应 Flutter 官方 Common Errors 页面;
- 补充 ATTRIBUTION.md:如果你的来源还没有列入归属清单,把来源及其许可证加进去,清单会映射"来源 → 许可证 → 依赖它的技能";
- 注意受限来源的引用方式:
- CC BY 4.0(Flutter、Dart、Firebase 文档):可以改写后使用,但必须保留出处链接;
- MDN 是 CC BY-SA(同源共享):与 MIT 不兼容,只能以引号标注的短引用出现,不能改写润色;
- W3C(WCAG)不允许衍生作品:只能陈述事实和短引用;
- 无公开许可的来源(如 RevenueCat 文档):只可以独立重述事实,不得复制文本。
简单记:许可证不宽松,就改写重述而不是引用原文(原文规则见 LICENSE 与 ATTRIBUTION 的 "Restricted reuse" 小节)。
✅ 提交前自查清单
在提 PR 之前,对照这几项快速过一遍:
| 检查项 | 说明 |
|---|---|
| 官方文档链接 | 每处新增/修改都有出处 |
description 格式 |
一行、以 Use when 开头、只含触发条件 |
| ATTRIBUTION.md | 新来源已登记并标注许可证 |
| 文件体积 | SKILL.md 聚焦精炼,细节放进 references/ |
| 命名规范 | 文件夹与 name 字段一致,小写连字符 |
| 兼容性 | 与 rules/ 和 combined/ 的旧版规则集不冲突 |
🚀 第四步:发起 Pull Request
README.md 给出的贡献流程只有三步:
审核时维护者会重点核对两件事:内容是否确实源自官方文档、链接是否有效。只要满足"官方文档链接"这条硬性要求,且内容改写客观中立,你的技能就会和现有 36 个技能一样,被各款 AI 代理自动发现并加载。
📌 总结:贡献一个技能 = 建文件夹 + 写聚焦的 SKILL.md + 附上官方文档链接。第三件事没有捷径,也是这个仓库"无观点、只讲文档"原则的基石。

