Flutter 仓库 Agent Skills 协作规范：Skill 采纳要求、维护职责与 dart_skills_lint 校验实战

本篇围绕 Flutter 仓库的 .agents/skills 目录展开，系统讲解在此共享代码库中落地一个新 Agent Skill 必须满足的五项硬性要求、所有权与维护职责、推荐创作实践，以及如何用 dart_skills_lint 工具和自动化测试对 Skill 做校验。读完后，你将能够独立创建一个符合仓库规范、并通过 CI 校验的 Agent Skill。

一、.agents/skills 目录是什么

Flutter 仓库在 .agents/skills 目录下集中维护了一批面向 Flutter 贡献者（而非普通用户）的 Agent Skills。根据 目录说明文档，这些 skill 是“designed for consumption by Flutter contributors”（专为 Flutter 贡献者消费而设计）。

从仓库的实际结构看，每个 skill 通常是一个独立目录，目录内包含一份带 YAML frontmatter 的 SKILL.md（声明 name 与 description），以及可选的 scripts/ 脚本子目录。例如：

• rebuilding-flutter-tool/SKILL.md：重建 Flutter 工具与 CLI 的工作流；
• flutter-cherry-pick/SKILL.md：针对已合并 PR 的正式 cherry-pick 流程。

以 rebuilding-flutter-tool/SKILL.md 为例，可以看到一份典型 SKILL.md 的最小结构：开头是 name 与 description 的 frontmatter，正文则是一个严格分步（Step 1 / Step 2）的工作流，并在每步结尾明确要求 STOP——这正是文档强调的“结构化、规则化”写法。部分 skill 还会附带 Dart 脚本，如 flutter-cherry-pick/scripts/flutter_cp.dart 和 rebuilding-flutter-tool/scripts/rebuild.dart。

此外，仓库还维护了同级的 .agents/agents 目录，用于放置更完整的自主 Agent 配置。按 agents 说明文档，其中的贡献与维护规则要求：每个 agent 目录必须在根 CODEOWNERS 中指定 owner 或团队；贡献者自行编写的本地 skill（位于 .agents/agents/<agent_name>/skills/，不是通过 npx 安装的第三方依赖）必须注册进仓库的 skill 校验测试套件 dev/tools/test/validate_skills_test.dart。这与本文的 skill 校验章节直接呼应。

二、新 Skill 采纳的五项硬性要求

在把一个初始 skill 落地到该共享代码库之前，采纳要求文档 列出了必须全部满足的 5 项要求。逐条说明如下：

1. Prior Usage（先期使用）：该 skill 必须已被作者实际使用过。即不允许提交一个从未在真实场景中验证过的工作流。
2. Target Audience（目标受众）：该 skill 必须明确是为 Flutter 贡献者设计的用途，而非面向泛化用户。
3. Provide Examples（提供示例）：新增该 skill 的 PR 中必须附上使用该 skill 时的 prompt 示例，以及该 agent/skill/bot 产生的输出。这是为了让评审者能直接看到 skill 的真实行为。
4. Naming Conventions（命名规范）：skill 名称必须遵循既定的 Claude 命名约定（文档中链接到 Claude 平台的 Agent Skills 最佳实践中的命名规范一节）。
5. Standard Compliance（标准合规）：skill 必须遵循 agentskills.io 中定义的开放标准规范。

适用前提：以上要求仅针对落地到 .agents/skills 这一“共享”代码库的 skill。个人本地使用的 skill 不受此约束，但若要纳入中央仓库则必须逐条达标。

三、所有权与维护职责

文档在 “Ownership and Responsibilities” 一节明确了 skill 的归属责任：

• Ownership（所有权）：skill 的作者持有所有权。这意味着作者有责任 审批对该 skill 的任何修改，并 缓解任何负面副作用。
• Succession（继任）：当作者无法继续维护该 skill 时，作者本人或其经理有责任为它寻找新的 owner。

从仓库的治理结构看，这一“作者即 owner”的原则与 .agents/agents 目录中“每个 agent 目录必须在根 CODEOWNERS 中指派明确 owner 或团队”的要求（见 agents 说明）是一脉相承的：Flutter 仓库普遍通过 CODEOWNERS + 责任归属来保证每一个共享资产都有明确、可追溯的维护主体。

四、推荐创作实践（非强制）

文档鼓励（但非强制要求）贡献者在创作 skill 时遵循以下实践。每一条都对应了真实 skill 中可观察到的写法：

• Provide Novel Information（提供增量信息）：告诉 agent 它需要知道的东西，而不是它已经知道的东西。避免复述 agent 已经掌握的通用知识，聚焦仓库特定的约束与步骤。
• One Skill Per CLI Tool（一个 CLI 工具一个 skill）：为每个 CLI 工具创建专属 skill，从而更有效地引导 agent 按你期望的方式使用该工具。
• Structure and Rules（结构化与规则化）：对风格保持极其严格。你的指令越结构化、越规则化（例外越少），效果越好——文档特别指出 “Agents have an exponential reward function for structure.”（Agent 对结构化有指数级的奖励函数）。
• Read-Only Mode（只读模式）：在合适场景下，明确告诉 agent 如何以严格的只读方式访问真实数据，以防止意外的更改。
• Dart Scripts（Dart 脚本）：脚本应使用 Dart 编写。这一点从真实 skill 中得到印证——flutter-cherry-pick/scripts/flutter_cp.dart 与 rebuilding-flutter-tool/scripts/rebuild.dart 均为 .dart 文件。

对照 rebuilding-flutter-tool/SKILL.md 可以看到这些原则的落地：整个工作流被压缩为两步，每步都以“STOP”作为明确的规则化出口，几乎没有任何自由发挥空间——这正是“越规则化越好”的典范。

五、用 dart_skills_lint 校验 Skill

这是文档中最具实操价值的部分。你可以手动运行 dart_skills_lint 工具来校验 skill 并修复常见问题。

5.1 手动运行校验命令

进入 dev/tools 目录后执行：

dart run dart_skills_lint:cli --skills-directory ../../.agents/skills --check-trailing-whitespace --check-absolute-paths --check-relative-paths

其中 --skills-directory 指向相对 dev/tools 的两个层级之上的 .agents/skills 目录，即仓库根下的 skill 集合。

从依赖来源看，dart_skills_lint 并非本地工具，而是通过 Git 依赖引入。在 dev/tools/pubspec.yaml 中可以看到：

dart_skills_lint:
  git:
    url: https://github.com/flutter/skills
    path: tool/dart_skills_lint
    ref: 05e5a45fa412ddbdd1d694eee0c71f4bbaea2617

即该工具锁定在 flutter/skills 仓库的 tool/dart_skills_lint 路径下的一个具体 commit。

5.2 配置规则

校验规则在 dev/tools/dart_skills_lint.yaml 中集中声明，内容如下：

dart_skills_lint:
  rules:
    check-relative-paths: error
    check-absolute-paths: error
    check-trailing-whitespace: error
  directories:
    - path: ".agents/skills"

可以看到，默认启用并设为 error 级别的规则恰好对应 CLI 命令中传的三个 --check-* 开关，校验目录为 .agents/skills。

对于个别确需豁免的 skill，仓库通过 dart_skills_lint_ignore.json 做白名单。例如当前豁免了 find-release 的 check-relative-paths 规则（针对其 SKILL.md）：

{
  "skills": {
    "find-release": [
      { "rule_id": "check-relative-paths", "file_name": "SKILL.md" }
    ]
  }
}

5.3 面向作者的有用标志位

文档列出了四个对作者有帮助的 flags：

• --fix：预览失败 lint 的修复方案，但不实际修改文件（dry run）。
• --fix-apply：自动应用可修复规则（如行尾空白）的修复。
• --check-trailing-whitespace：强制无行尾空白（换行所需的 2 个空格除外）。
• --check-absolute-paths：确保链接不使用绝对路径。
• --check-relative-paths：确保相对链接指向真实存在的文件。

要“检查一切并预览修复”，文档给出了组合命令：

dart run dart_skills_lint:cli --fix --check-trailing-whitespace --check-absolute-paths --check-relative-paths --skills-directory ../../.agents/skills

5.4 运行自动化校验测试

除了手动运行工具，还可以在 dev/tools 目录下运行自动化校验测试：

dart test test/validate_skills_test.dart

对应实现见 dev/tools/test/validate_skills_test.dart。从源码结构看，该测试做了三件事：

1. Validate Flutter Skills：调用 ConfigParser.loadConfig 读取 dev/tools/dart_skills_lint.yaml 配置，再对 .agents/skills 与 .agents/agents/reidbaker-agent/skills 两个目录调用 validateSkills，断言校验结果为真。
2. Relative to root paths are not in backticks：遍历仓库顶层两级目录构造合法路径集合，用自定义规则 CheckBackticksRelativePathsRule 校验 skill 中反引号内引用的相对路径（并禁用其余内置规则，聚焦这一条）。
3. CheckBackticksRelativePathsRule handles Windows paths：验证该规则对 Windows 风格路径（反斜杠）的处理，确保跨平台一致。

这也印证了 agents 说明文档 中“贡献者本地 skill 必须注册进 dev/tools/test/validate_skills_test.dart 校验套件”的治理要求。

六、适合贡献 Skill 的方向

文档最后给出了寻找 skill 创作切入点的建议方向。若你是常规贡献者，以下都是好的起点：

• 何时使用仓库中的某个命令行工具、其参数，以及如何解读它的输出。
• 如何运行某一组特定测试。
• 如何运行带有仓库特定配置的 analyzer 或 linter。
• 修改某块代码之后，所必需的产品化（productization）步骤。
• 如何调试或区分某一类常见问题。

这些方向恰好对应仓库中已存在的真实 skill——如 run-devicelab-with-led（如何跑 devicelab）、flutter-pr-checks-finder（如何找 PR 检查项）、analyze-github-flake（如何分析 flake）——可作为你撰写新 skill 的参考模板。

七、小结

.agents/skills 目录是 Flutter 仓库为贡献者沉淀“Agent 可执行工作流”的共享资产。落地一个新 skill 需要同时满足五项采纳要求（先期使用、面向贡献者、提供示例、遵循命名约定、符合开放标准），并由作者承担所有权与继任责任；创作上应追求“增量信息 + 一工具一 skill + 强结构化 + 只读优先 + Dart 脚本”。落地前务必用 dart_rules_lint 工具（配合 dev/tools/dart_skills_lint.yaml 配置与 dart_skills_lint_ignore.json 豁免）手动校验，并通过 dart test test/validate_skills_test.dart 确保自动化测试通过。掌握这一套规范与校验流程，你就能在 Flutter 仓库中提交既合规、又高质量、还可在 CI 中稳定通过的 Agent Skill。