AI coding 工具的問題，已經不只是「模型會不會寫 Flutter」。

更核心的問題是：當一個團隊的開發規範、專案慣例、SDK 限制、測試流程與部署步驟都放進 AI 工作流時，這些知識到底該放在哪裡？

放在 system prompt，會變成每次對話都要攜帶的長篇背景。放在 rules files，能被版本控制，卻容易變成一份越來越大的總則。全部交給 MCP，則會把「工具能力」與「任務知識」混在一起。Flutter 與 Dart 官方推出的 Agent Skills，提供了一個更清楚的分層答案：MCP 提供工具，Skills 提供完成特定任務的操作知識。

本文的核心判斷是：

Skills 的價值不在於替代 rules files 或 MCP，而在於把 AI 指引從「全域規範」拆成「可按需載入、可版本化、可審查的任務流程」。

這不是單純的 prompt 技巧，而是上下文工程的架構選擇。

先做事實邊界：哪些說法有來源，哪些不能寫成事實？

根據 Flutter 官方文件，Agent Skills 是給 AI agents 的「task-oriented blueprints」，用來提供特定任務的逐步指引。Flutter 文件也明確區分 rules files、MCP 與 Agent Skills：rules files 管全域行為，MCP 提供專用工具，Skills 則提供如何正確操作這些工具的專業知識。

官方文件也確認了 progressive disclosure：agent 一開始只讀取 skill 的 metadata，只有在任務需要時才載入完整指令。Agent Skills 規格頁進一步說明，一個 skill 至少是一個包含 SKILL.md 的資料夾，SKILL.md 需要 YAML frontmatter 與 Markdown 內容，並可附帶 scripts/、references/、assets/ 等資源。

Flutter 官方 GitHub repo 目前是 flutter/agent-plugins，不是早期文章中常見的 flutter/skills。Flutter docs 也特別註明：flutter/skills 已改名為 flutter/agent-plugins，既有安裝命令應更新。

這些是可查證事實。

相對地，以下說法在本次查證範圍內沒有足夠來源支撐，不能寫成確定事實：

• 「使用 Skills 後效率從 17% 提升到 85%+」；
• 「300 個 skills 只需要數千 tokens」；
• 「Skills 是 on-device Gemma 複雜 agent 任務的核心支柱」；
• 「Flutter 團隊正式提供名為 dart_skills_lint 的工具」。

這些說法可以作為待查證假設或策略推論討論，但不能直接寫成官方結論。若要放進正式文章，需要補上原始 benchmark、工具 repo、commit、release note 或官方文件。

這個刪減很重要。AI 指引文章最容易失控的地方，就是把合理的工程直覺包裝成「官方已證實」。這會讓文章看起來更完整，但也會降低技術可信度。

從 system prompt 到 Skills：問題不是資訊不夠，而是資訊放錯層

早期控制 AI agent 的方式很直覺：在 system prompt 裡告訴它「你是 Flutter 專家」、「請遵守 Clean Architecture」、「請先寫測試」。這種做法適合定調，但不適合承載複雜任務。

原因很簡單：system prompt 是全域背景。它不會知道眼前任務到底是「修 RenderFlex overflow」、「新增 localization」、「做 FFI binding」，還是「把測試遷移到 package:checks」。當所有規則都放在同一層，模型只能在龐大的背景裡自行判斷哪些內容相關。

Rules files 往前走了一步。它們通常放在 repo 內，可以版本控制，也能描述專案慣例。例如：註解用英文、分支從 develop 切、review AI 生成的 code 要更嚴格。這些是橫切關注點，適合放在 rules files。

但 rules files 不適合把每一種任務的細節都塞進去。若你把「如何新增 Flutter widget test」、「如何跑 coverage」、「如何處理 package conflict」、「如何設定 GoRouter」全部寫進同一份規則，最後會得到一份看似完整、實際上難以使用的操作手冊。

Skills 解決的是這個分層問題。它把知識拆成一個個任務單元：當使用者要求新增 widget test，agent 才讀取 flutter-add-widget-test；當使用者要求解 dependency conflict，agent 才讀取 dart-resolve-package-conflicts。

這是本文分析：Skills 不是「更多文件」，而是把文件切到 agent 能在正確時間取用的粒度。

MCP 與 Skills 的差別：工具箱不會自動教你施工

Flutter 官方文件對 MCP 與 Skills 的分工很直接：MCP 給 agent 專用工具；Agent Skill 則提供操作這些工具的 know-how。Flutter blog 也用了類似比喻：MCP 提供工具，Skill 提供藍圖與專業知識。

這個區分對架構決策很關鍵。

MCP 適合做可執行能力，例如：

• 讀取 runtime error；
• 呼叫 static analysis；
• 查詢 package 或 documentation；
• 操作模擬器、瀏覽器或外部服務。

Skills 適合描述任務流程，例如：

• 什麼情境下需要 widget test，而不是 integration test；
• 修 layout overflow 時要先確認 constraints，而不是盲目包 SingleChildScrollView；
• 做 FFI binding 時應優先考慮 ffigen，而不是手寫大量 dart:ffi binding；
• 跑 static analysis 後，哪些 fix 可以機械套用，哪些需要人工審查。

如果只給 MCP，agent 會有工具，但未必知道如何組合工具。如果只給 Skills，agent 有流程，但在需要真實驗證時缺少可執行能力。兩者的關係不是替代，而是分工。

可以用這個表格理解：

層級	適合放什麼	不適合放什麼
System instructions	角色、語氣、安全邊界、不可違反的全域限制	具體任務的長流程
Rules files	專案規範、分支策略、註解語言、PR 粒度、review 標準	每個 SDK 或任務的完整操作手冊
MCP servers	可執行工具、外部系統操作、runtime 查詢	對特定任務的工程判斷
Skills	任務型流程、常見錯誤、驗證步驟、專案特定操作知識	永遠適用的全域政策

這個分層能降低兩種常見錯誤：把工具當成流程，或把規範當成工具。

Progressive disclosure：真正的收益是避免無關上下文污染

Agent Skills 規格描述了三階段載入：啟動時載入 name 與 description；任務匹配時載入完整 SKILL.md；必要時再讀取 scripts、references 或 assets。

這種 progressive disclosure 通常會被解釋成 token 成本優化。這是合理方向，但只談成本不夠。

更重要的是：它降低了無關指令互相干擾的機率。

假設一個 repo 同時有 Flutter layout、Firebase deploy、Dart package conflict、native assets、legal review、content publishing 等 skills。如果每次任務都把所有內容塞進上下文，模型不只會變慢，也更容易被不相關規則帶偏。修一個 overflow 時，它不需要讀 Firebase hosting 的部署流程；寫 Dart CLI 時，它也不需要知道 Flutter localization 的 l10n.yaml。

Skills 的設計讓 agent 先看「目錄」，再讀「章節」。這比把整本手冊攤開在模型面前更接近人類工程師的工作方式。

但這裡也有一個容易被忽略的限制：progressive disclosure 的效果取決於 description 寫得夠精準。Agent Skills 規格明確要求 description 說明 skill 做什麼、何時使用，並建議包含能幫助 agent 判斷相關性的關鍵字。

換句話說，skill 的 description 不是摘要文案，而是 routing contract。寫得太籠統，例如「Help with Flutter」，agent 就很難在正確時機啟用它。

Flutter 與 Dart 官方 skills 目前提供什麼？

Flutter docs 指向兩個官方來源：

• dart-lang/skills：Dart 團隊維護的 skills；
• flutter/agent-plugins：Flutter 團隊維護的 agent plugins，其中包含 skills、MCP server configuration 與 rules。

依照目前 GitHub README，Flutter skills 覆蓋的任務包含：

• 新增 integration test；
• 新增 widget preview；
• 新增 widget test；
• 套用 Flutter architecture best practices；
• 建立 responsive layout；
• 修 layout issues；
• 實作 JSON serialization；
• 設定 declarative routing；
• 設定 localization；
• 使用 http package。

Dart skills 則包含：

• 新增 unit test；
• 建立 CLI app；
• 收集 coverage；
• 設定 FFI assets；
• 修 runtime errors；
• 產生 test mocks；
• 遷移到 package:checks；
• 解 package conflicts；
• 執行 static analysis；
• 使用 ffigen；
• 使用 pattern matching。

這份清單透露一個重要策略：官方第一批 skills 多數不是百科型文件，而是高頻、容易犯錯、需要驗證步驟的開發任務。

這也呼應 Flutter blog 的說法：早期實驗發現，只提供文件的 skills 沒有想像中有價值，因為現代模型已能找到許多公開文件；後來方向轉向 task-oriented skills，讓 agent 能可靠完成開發任務。

這是本文認為最關鍵的地方。若團隊只是把 README 拆成多個 skills，價值有限。真正值得 skill 化的是「資深工程師會照著做，但新人或 AI 常跳過」的流程。

一個有效的 SKILL.md 應該長什麼樣？

Agent Skills 規格要求 SKILL.md 使用 YAML frontmatter 加 Markdown body。必要欄位是 name 與 description。name 有命名限制，且必須與父目錄名稱一致；description 需要說明 skill 做什麼以及何時使用。

一個比較健康的 skill 結構通常包含：

---
name: flutter-fix-layout-issues
description: Fix Flutter layout errors such as RenderFlex overflowed and unbounded constraints. Use when UI layout fails, overflows, or behaves differently across screen sizes.
---

# Flutter layout issue workflow

## Goal

Fix the layout bug while preserving the intended visual hierarchy.

## Steps

1. Reproduce the layout failure.
2. Identify whether the issue is constraints, intrinsic size, scrolling, or flex allocation.
3. Prefer local constraint fixes over broad wrappers.
4. Run static analysis and the relevant widget test.

## Common mistakes

- Do not wrap the whole screen in a scroll view before identifying the failing constraint.
- Do not replace `Expanded` and `Flexible` blindly.

這段只是示意，不是官方 skill 內容。重點是：好的 skill 不只告訴 agent「做什麼」，還要告訴它「何時做」、「先查什麼」、「不要做什麼」、「用什麼證據確認完成」。

如果你的 skill 只有概念介紹，agent 仍然需要自行推導步驟；如果你的 skill 只有命令清單，agent 可能會在錯誤情境執行正確命令。任務型 skill 的價值，在於把判斷流程與驗證流程寫在一起。

團隊什麼時候該建立自己的 Skills？

不要因為官方有 skills，就急著替每個流程都建一個 skill。這會製造另一種文件債。

比較務實的判斷標準是：當某類任務同時符合以下三個條件，就值得 skill 化。

第一，模型或新人反覆犯同一類錯。
例如每次修 Flutter layout 都用過大的 wrapper 掩蓋問題；每次新增 localization 都忘記 l10n.yaml 或生成流程；每次處理 FFI 都手寫 binding 而不是先評估 ffigen。

第二，任務有可重複的專案慣例。
例如你的 app 對 routing、state management、repository pattern、feature folder、error handling、analytics event 命名有固定規則。這些不是官方文件能完整提供的知識。

第三，任務有確定性驗證方式。
例如 dart analyze、flutter test、特定 golden test、integration test、schema check、build command。沒有驗證的 skill 很容易變成「看起來很專業的建議文」。

這裡需要直接指出一個不合理的做法：把所有團隊規範塞進單一 mega skill，通常是錯的。那只是換了一個檔名的 rules file。Skill 的粒度應該跟任務匹配，而不是跟組織架構匹配。

品質保證：Skill 也需要 lint，不然只是另一種不受測文件

Agent Skills 規格頁提到可用 skills-ref validate ./my-skill 驗證 SKILL.md frontmatter 與命名規範。這是一個重要方向：AI 指引本身也需要確定性檢查。

團隊至少應該檢查：

• SKILL.md 是否存在；
• frontmatter 是否有效；
• name 是否符合命名規範並與資料夾一致；
• description 是否非空、具體且包含觸發情境；
• 相對連結是否存在；
• scripts 是否可執行且有清楚錯誤訊息；
• skill 中的命令是否仍符合目前專案。

這是本文分析：AI 工作流越依賴 skills，越不能把 skills 當成普通文件。它們更像 build scripts、runbooks 或 migration playbooks，應該進入 code review 與 CI。

但目前不應把「dart_skills_lint 是 Flutter 官方工具」寫成事實。本次查證到的官方 Agent Skills 規格提到的是 skills-ref validate；Flutter repo 也有 tool/ 目錄，但僅憑目前來源不足以支持 dart_skills_lint 這個具體名稱與發布狀態。

導入策略：先從最常失敗的三件事開始

如果要在 Flutter/Dart 團隊導入 Skills，我不建議第一步就是「盤點所有文件並轉成 skills」。這聽起來完整，但很容易變成大規模文件整理專案。

更務實的路線是：

1. 從最近一個 AI 或新人反覆出錯的任務開始；
2. 寫一個最小可用 skill；
3. 在下一次真實任務中使用；
4. 把錯誤回填進 Common mistakes 或 Validation；
5. 只有被多次使用的 skill 才進一步拆 references 或 scripts。

例如：

• layout 問題多，就先寫 flutter-fix-project-layout-issues；
• 測試資料常亂，就先寫 project-widget-test-fixtures；
• Firebase deploy 常漏步驟，就寫 project-firebase-deploy-preflight；
• 多 agent review 常看錯範圍，就寫 project-code-review-diff-contract。

命名上要避免過度抽象。project-best-practices 太大；project-checkout-flow-test 更容易被正確觸發。

結論：AI 指引的成熟，不是 prompt 更長，而是知識分層更清楚

Flutter 與 Dart 官方 Agent Skills 的重點，不是「官方終於也有 AI 文件」。真正的訊號是：AI coding 的控制面正在從單一 prompt，走向分層的上下文架構。

System instructions 定義全域邊界。Rules files 保存專案政策。MCP 提供可執行工具。Skills 則把可重複的任務流程封裝成可按需載入的知識單元。

這個架構不會讓 AI 自動變成資深工程師。它只能把資深工程師已經知道、但常常沒有寫下來的操作判斷，轉成 agent 能讀、能遵守、能被 review 的形式。

所以導入 Skills 的真正問題不是「我們要不要追 Flutter 官方的新工具」，而是：

團隊裡哪些工程判斷已經重要到值得被版本化、被驗證、被 AI 重複使用？

如果這個問題答不出來，先不要寫 skill。先找到失敗案例。

如果答得出來，Skills 就不只是 AI 指令文件，而是把團隊知識變成可執行資產的一種方式。

---

參考資料與查證邊界

• Flutter Docs：Agent skills for Flutter and Dart
• Flutter Blog：Introducing Skills for Dart and Flutter
• GitHub：flutter/agent-plugins
• GitHub：dart-lang/skills
• Agent Skills：Overview
• Agent Skills：Specification
• CodeLove：Flutter 發表 Skills 官方，Flutter 在 AI 領域再添一助力
• Medium / Easy Flutter：New official Skills for Dart and Flutter

本文以 2026 年 7 月 26 日可讀取到的官方文件、GitHub README 與使用者提供連結為準。文中標示「本文分析」的段落，是基於來源內容做出的工程判斷，不代表 Flutter 或 Dart 團隊的官方承諾。未能由來源支撐的具體數字與工具名稱，已從正文事實敘述中移除或改列為查證邊界。