在 Flutter 项目里装 Skills：从搭建 AI 辅助开发程序

使用假设

再看文章类型，教程干货；目标读者：Flutter 开发者、独立开发者、技术团队负责人；主要目标：知识沉淀 + 涨粉；作者调性：独立开发者，不过，

备选标题

1. 在 Flutter 项目里装 Skills：让 AI 写代码时自动遵守你的规范
2. Flutter + Skills：从零搭建 AI 辅助开发的完整工作流
3. 给 Flutter 项目装上 AI 大脑：Skills 落地实战教程
4. 让 AI 成为你的 Flutter 专家：Skills 程序搭建全流程
5. Flutter 开发效率翻倍：用 Skills 驯服 AI 编码助手

摘要

在 Flutter 项目中使用 AI 编码助手时最常见的问题是"AI 写的代码不符合项目规范"。这篇文章从基础开始，教你如何在 Flutter 项目中搭建 Skills 程序。让 AI 编码助手自动理解并遵守你的项目架构、代码风格和常用方法。包含完整的操作步骤、可复用的配置模板和真实坑点处理。

你可能正在经历的事

• 状态管理混用了 Provider 和 Riverpod
• 路由配置没有用 GoRouter
• 代码风格和项目现有规范不一致
• Widget 嵌套层级不合理
• A.I. 只知道通用 Flutter 知识。却不知道你的项目架构与规范

本质上，AI 编码助手不知道你的项目“游戏规则”。它只知道通用的 Flutter 知识，但不知道你的项目用什么架构、遵循什么规范、哪些文件该放哪里。怎么说呢，

Skills 就是解决这个问题的钥匙。

什么是 Skills？为什么 Flutter 项目需要它？

定义与价值定位

Skills 是一组由指令文件、脚本和资源组成的文件夹，专门给 AI 编码助手“充电”用。再看可以类比为，

• A.I. 的专业教材： 让 A.I. 助手在特定领域更精准高效。
• 开放标准： 遵循统一技能规范，可在不同 A.I. Agent 之间自由迁移。
• 即插即用： 一条命令安装到项目中，A.I. 自动识别并应用。

简单装上 Skills 后你的 A.I. 编码助手就从“通用选手”升级为“你的项目专属专家”。

为什么 Flutter 项目特别需要 Skills？

1. 强类型程序：Dart 的类型程序很严格，但 A.I. 容易生成类型不匹配代码。
2. 布局约束复杂：Flutter 的布局程序与 Web 差异大，A.I. 对约束传递理解不足。
3. 状态管理方案多样：Mixed usage of Provider,Riverpod,Bloc,GetX 等。需要明确告知 A.I.
4. 代码组织规范：A.Widgets 拆分、文件目录结构、命名约定等，A.I. 默认不会遵守。

再看从零搭建，Flutter 项目的 Skills 程序

前置条件

• a 已有或新建一个 Flutter 项目
• a 安装了支持 Skills 的 A.I. 编码助手
• a 了解基本 Flutter 项目结构与架构

步骤一这方面。初始化 .skills/ 目录

.skills/ 是 A.I. 自动识别的位置，请确保它位于项目根目录。

mkdir -p .skills
cd .skills
tree -L 2
# .skills/
# ├── AGENTS.md # 全局规则
# ├── skills/
# │ ├── flutter-architecture/
# │ ├── flutter-code-style/
# │ ├── flutter-state-management/
# │ ├── flutter-routing/
# │ └── flutter-widget-patterns/
# └── workflows/ # 工作流

至于步骤二，编写 AGENTS.md

技术栈 & 主要红线:

## 技术栈
- 框架: Flutter>= 3.x + Dart
- 状态管理: Riverpod>= X.X
- 路由: GoRouter
- 网络请求: Dio
- 代码生成: build_runner + freezed
## 全局红线
1️⃣ 状态管理统一使用 Riverpod，禁止混合 Provider 等方案
2️⃣ 路由必须通过 GoRouter 配置，禁止手写 Navigator.push
3️⃣ 所有 Widget 必须使用 const 构造函数
4️⃣ 文件命名采用 snake_case，类名采用 PascalCase
5️⃣ 单个文件行数 ≤ 200 行。否则拆分
## 目录结构约定
lib/
├─ main.dart # entry point
├─ app/ # 主要原因
│  ├─ app.dart # 根 Widget
│  └─ routes.dart # 路由配置
├─ features/ # 功能模块
│  └─ auth/ # 示例模块
│    ├─ presentation/ # UI 层
│    ├─ domain/ # 域层模型 / BLoC / UseCase 等
│    └─ data/ # 数据层
├─ shared/ # 共用组件 & 工具集
└─ providers/ # Riverpod Providers
## Skills 索引表
| Skill | 用途 | 触发场景 |
|-------|------|----------|
| flutter‑architecture | 架构规范和分层原则 | 新增模块 |
| flutter‑code‑style | 命名及格式化 | 自动生成 |
| flutter‑state‑management | Riverpod 使用规范 | 状态相关 |
| flutter‑routing | GoRouter 路由配置 | 路由相关 |
| flutter‑widget‑patterns | 常用 Widget 模式 | UI 开发 |

步骤三的观点是，编写第一个 Skill — 状态管理规范

## 主要规则
1️⃣ 优先使用 NotifierProvider 管理可变状态
2️⃣ 使用 StateProvider 管理只读状态
3️⃣ 使用 Family 为需要参数化 provider
4️⃣ 所有状态变更必须在 Notifier 内部完成，不得在 UI 层直接修改 state
## 示例模板 – CounterProvider
dart
// lib/providers/counter_provider.dart
import 'package:flutter_riverpod/flutter_riverpod.dart';final counterProvider = NotifierProvider;class CounterNotifier extends Notifier {
@override int build => 0;void increment => state++;void decrement => state--;怎么说呢，void reset => state = 0;}
### 在 Widget 中使用
dart
// lib/features/home/presentation/home_screen.dart
import 'package:flutter/material.dart';老实说，import 'package:flutter_riverpod/flutter_riverpod.dart';import '../../../providers/counter_provider.dart';class HomeScreen extends ConsumerWidget {
const HomeScreen;@override Widget build {
final count = ref.watch;return Scaffold(
说到body，Center)。floatingActionButton: FloatingActionButton(
onPressed: => ref.read.increment,child: const Icon,),);}
}

常见错误与修复 – 状态管理部分

Error: // ❌ 错误 ref.watch.notifier.state++; Corrent: // ✅ 正确 ref.read.increment;

---

Error: // ❌ 错误 final userProvider = StateProvider => User);// 用于复杂状态但实际应该是 NotifierProvider // ✅ 正确 final userProvider = NotifierProvider;// 使用 Notifier 来管理复杂业务逻辑 php ### 步骤四：编写路由配置 Skill `.skills/skills/flutter-routing/SKILL.md`: markdown # Flutter Routing Skill ## 主要规则. **所有路由必须在 app/routes.dart 中统一配置**. **使用命名路由**，禁止使用方法字符串字面量. **路由参数必须通过 GoRouter 的 extra 或 pathParameters **传递** **页面 Widget 必须是 ConsumerWidget** ' --- #### 步骤四继续 —— 路由配置 Skill 示例 dart // lib/app/routes.dart import 'package:flutter/material.dart';import 'package:go_router/go_router.dart';import '../features/home/presentation/home_screen.dart';import '../features/auth/presentation/login_screen.dart';final router = GoRouter( initialLocation: '/',routes:!，话说回来，return ProfileScreen;},),],)，导航示例： dart // 正确： context.pushNamed;context.pushNamed;// 错误： context.push;--- #### 路由命名规范

全部小写且单词间以 `-` 分隔，如 `home-page` 或 `user-profile`。怎么说呢，语义化名称优先。例如 `home`,`login`,`profile`。避免缩写或简写，以便后期维护。

---

步骤五 —— 测试效果

打开你已安装支持 Skills 的 A.I. 编码助手，让它帮你创建一个新的页面。

text 请帮我创建一个使用者资料页面包含使用者名、头像和简介。

如果 Skills 配置正确

• 会在 lib/features/profile/presentation/ 下创建页面；
• 若需要状态，则会通过 Riverpod 管理；
• 会自动更新 app/routes.dart 并添加命名路由；
• 所有代码将符合之前定义好的风格与结构。

---

实战案例 — Todo 功能模块演示

: 创建 Todo 列表，包括展示、添加、删除还有状态切换。

: 以下为完整实现示例。

dart // lib/features/todo/presentation/todoscreen.dart import 'package:flutter/material.dart';import 'package:flutterriverpod/flutterriverpod.dart';import '../domain/todoentity.dart';

class TodoScreen extends ConsumerWidget { final _controller = TextEditingController;

TodoScreen;
@override
void dispose{ _controller.dispose;话说回来，super.dispose;}
@override
Widget build{
final todos=ref.watch;return Scaffold(
appBar : AppBar)。body : ListView.builder(
itemCount : todos.length,itemBuilder : {
final todo=todos;return ListTile(
title : Text,leading : Checkbox(
value : todo.completed。onChanged :=>ref.read.toggle,),trailing : IconButton(
icon : Icon,onPressed :=>ref.read.remove
),);},),floatingActionButton : FloatingActionButton(
onPressed :=>_showAddTodoDialog。child : Icon,),);}
void _showAddTodoDialog{
showDialog(context:ctx。builder:=>AlertDialog(
再看title，text,content:UITextField,actions:,)
);}

}

// lib/features/todo/domain/todo_entity.dart class Todo{ const Todo({ required this.id。required this.title,required this.completed,});final String id;final String title;final bool completed;Todo copyWith=>Todo;}

// lib/providers/todolistprovider.dart import 'package:flutterriverpod/flutterriverpod.d.ts';import '../features/todo/domain/todo_entity.d.ts';

final todoListProviders=NotifierProvider;

class TodoListNotifier extends Notifier{ @override Listwbuild=>;void add{state=;} void remove{state=state.where=>t.id!=id).toList，} void toggle{state=state.map=>t.id==id?t.copyWith)else t).toList;} }

验证结果的观点是。

• ✅ 使用了 Riverpod 的 Notifier\ • ✅ 所有 Widgets 为 ConsumerWidget • ✅ 文件方法符合约定 • ✅ 状态变更全部集中于 Notifier 内部 • ✅ widget 均采用 const 构造函数 • ⚠️ 若仍出现非 const 构造，请检查业务逻辑是否存在副作用。​

---

常见坑点与方法

坑点一——AI 忽略了 Skill 定义

• 触发场景AI 输出未按规定使用 Riverpod 而改用了 Provider。
• 根本原因 ：.skills 文件位置错误或格式问题导致 AI 未识别。
• 解决思路 1．确认 .skills/ 位于根目录；2．确认每个 /SKILL.md 存在且无语法错误；3．检查 A.I 工具是否支持最新 Spec；4．若仍然忽略，可把关键规则 写入 AGENTS.md 中。并以更明确语言描述，
• 预防措施 ：每次添加新 Skill 后用小任务验证一次效果；记录失败日志做快速迭代，按理说，

坑点二——Skill 冲突

• 触发场景 ：多个 skill 对同一行为给出相反规定。例如 “Riverpod” vs “StatefulWidget”。按理说，
• 根本原因 ：缺乏优先级声明。
• 解决思路
  • 在 AGENTS.md 顶部声明全局优先级最高，其余 skill 为局部覆盖；
  • 对冲突规则做注释说明，例如 “StatefulWidget 禁止用于此功能”。
  • 如需强制执行，可把冲突规则放进同一个 SKILL.md 并加备注。
• 预防措施 ：每新增 skill 前先扫描已有 skill 确认无重叠。

坑点三——Skill 内容过长导致上下文溢出

• 触发场景 ：单个 SKILL.md 超过几千行或包含大量冗余说明。
• 根本原因 ：A.I 有限；描述过于啰嗦导致主干信息被抹去。怎么说呢，
• 解决思路
  • 拆分成多个子技能。例如 “layout‑rules”,“nav‑rules”，分别放进不同子目录；
  • 用简洁明了语言描述主要要点；老实说，
  • 提供最少必要实例。并移除重复条款，
• 预防措施 ：每次新增 rule 时保持长度 ≤ 200 行且条款 ≤ 10 条。

---

可收藏清单 — 完整检查表

1⃣️ .skills/ 是否位于项目根目录？- 如果不存在请立即创建并放入正确位置。

2⃣️ AGENTS.md 是否完整列出技术栈及全局红线？- 检查是否遗漏关键依赖，如 Dart SDK 或特定版本号。

3⃣️ 是否提供了完整索引表？- 每个 Skill 应对应一行记录并列出触发场景。

4⃣️ 至少包含以下四大 core skills？- architecture → codestyle → statemanagement → routing。

5⃣️ 每个 skill 是否配套示例 & 错误对比？- 能否帮助新人快速上手而无需额外解释？

6⃣️ 是否定义冲突优先级策略？- 如 Global> Feature> Module，以避免模糊情况。

7⃣️ 是否跑过至少一次真实需求测试？说起来，- 如新建页面或业务功能。并验证所有 rule 生效率 ≥ 95%。

8⃣️ .skills 已加入 VCS 并共享给团队成员吗？- 确保大家都能同步更新并自行修改 / rules。

---

写在最终

Skills 并不是魔法，它只是把你们对项目知识进行程序化后交给机器的一种方式。当 AI 开始自动遵守这些规则，你就会发现自己不再是“校对员”。而成为真正意义上的“A.I 指挥官”——制定方向与策略，由机器完成具体编码工作。

如果想让 AI 更深入参与流程。可进一步学习如何编写 Workflow，把多个技能串联成完整工作流，实现端到端自动化。其实，

#Flutter #Skills #AI编程 #Riverpod #GoRouter