给 flutter-ai-rules 贡献你的第一个技能:开发者指南与官方文档链接硬性要求

原创2026-11-04 12:05:321,931 阅读
文章标签:AI 技能AI 插件移动开发开发工具

给 flutter-ai-rules 贡献你的第一个技能:开发者指南与官方文档链接硬性要求

flutter-ai-rules 是一个收录 36 个 Flutter 与 Dart AI 技能(Agent Skills)的开源仓库,供 Claude Code、Codex、Cursor 等 AI IDE 自动加载。本文带你从零开始为它贡献你的第一个技能,重点讲清楚仓库唯一的硬性要求:每一处新增内容都必须附官方文档链接,这是保证仓库客观、可审查的核心规则。

flutter-ai-rules 技能自动选择示意图

🧩 什么是 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 构建响应式布局:

flutter Row Column 布局示例(flutter-ai-rules 技能配图)

🛠️ 第一步:克隆仓库并建立分支

先克隆仓库,然后在本地修改——这也是仓库保持只读、通过 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.

具体要做的三件事:

  1. 每个技能都要能追溯到来源:技能中每条指导都应指向它依据的官方文档页面,比如 skills/effective-dart/SKILL.md 对应 Dart 官方 Effective Dart,skills/flutter-errors/SKILL.md 对应 Flutter 官方 Common Errors 页面;
  2. 补充 ATTRIBUTION.md:如果你的来源还没有列入归属清单,把来源及其许可证加进去,清单会映射"来源 → 许可证 → 依赖它的技能";
  3. 注意受限来源的引用方式:
    • 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 给出的贡献流程只有三步:

  1. Fork 本仓库(或基于克隆建立分支);
  2. 在 skills/ 下新增/修改技能,或在 rules/ 下修改规则文件;
  3. 开一个 PR,在描述中说明变更依据,并附上官方文档链接。

审核时维护者会重点核对两件事:内容是否确实源自官方文档、链接是否有效。只要满足"官方文档链接"这条硬性要求,且内容改写客观中立,你的技能就会和现有 36 个技能一样,被各款 AI 代理自动发现并加载。

📌 总结:贡献一个技能 = 建文件夹 + 写聚焦的 SKILL.md + 附上官方文档链接。第三件事没有捷径,也是这个仓库"无观点、只讲文档"原则的基石。

登录后查看全文
flutter-ai-rules