vue

vue skill 總覽

vue skill 是用來做什麼的

vue skill 是一份聚焦型指南，專門幫助產生與審查符合現代最佳實務的 Vue 3 程式碼，重點涵蓋 Composition API、<script setup lang="ts">``、compiler macros、reactivity APIs，以及 Transition、Teleport、Suspense、KeepAlive` 等內建元件。當你希望 AI 代理直接產出符合現代 Vue 風格的 Vue Single File Components，而不是退回較舊的 Options API 寫法時，這個 vue skill 特別有用。

誰適合安裝這個 vue skill

這個 vue skill 很適合前端工程師、全端工程師，以及經常請 AI 產生 Vue 元件、composables 或重構程式碼的使用者。若你希望輸出結果以 TypeScript 為優先、理解 macros，並且貼近 Vue 3.5 時代的文件與寫法，而不是混入 Vue 2／早期 Vue 3 的習慣，這個 skill 的價值會特別明顯。

實際要解決的工作需求

多數使用者並不需要一份泛泛的框架介紹，而是需要代理能穩定寫出這種 Vue 程式碼：

• 預設使用 Composition API
• 優先採用 <script setup lang="ts">
• 正確處理 defineProps、defineEmits 與 defineModel
• 更精準地選擇 ref、shallowRef、computed 與 watch
• 只在真正適合的情況下才使用進階內建功能

這正是 vue for Frontend Development 的實際價值：降低 AI 產碼之後還要大量清理與修正的成本。

這個 skill 真正有差異的地方

它最明顯的差異，在於帶有明確立場的指引。原始內容明白偏好 TypeScript、<script setup lang="ts"> 與 Composition API，並且不鼓勵使用 Reactive Props Destructure。它也提供幾組非常聚焦的參考內容，涵蓋：

• script setup macros
• reactivity 與較新的 core APIs
• 進階內建元件與 directives

因此，和那種廣泛的「教我 Vue」提示相比，這個 skill 更適合實作型工作。

這個 skill 不打算涵蓋什麼

這不是一張完整的 Vue 生態地圖。它不能取代 routing、狀態管理函式庫、SSR framework、測試或建置工具等面向的深入文件。如果你的主要任務是 Nuxt 架構設計、Vue Router 設定、Pinia 規劃，或部署流程，那麼 vue skill 能幫你把元件層級的程式碼風格拉齊，但不應該成為你唯一的資訊來源。

如何使用 vue skill

vue 的安裝方式與使用情境

請在支援 skills 的環境中，使用以下指令安裝：

npx skills add antfu/skills --skill vue

從 repository 內容可確認，這個 skill 位於 antfu/skills 底下的 skills/vue。這裡並不是安裝 Vue runtime 本身，而是加入一套指引，讓 AI 在協助產生 Vue 程式碼時做得更好。

建議先讀這些檔案

如果你想在使用 vue skill 前先走一條資訊密度最高的路徑，建議依序閱讀：

1. skills/vue/SKILL.md
2. skills/vue/references/script-setup-macros.md
3. skills/vue/references/core-new-apis.md
4. skills/vue/references/advanced-patterns.md
5. skills/vue/GENERATION.md

為什麼是這個順序：

• SKILL.md 先交代整體偏好、運作方式與適用範圍。
• 三份 reference 檔案提供代理最可能實際套用的細節。
• GENERATION.md 說明這些內容是根據 Vue 文件生成，並且對應的是相對近期的版本快照。

vue skill 需要你提供哪些輸入

vue usage 的品質，很大程度取決於你丟給代理的需求資訊。請盡量提供：

• 元件用途
• props 與 emitted events
• 是否需要 v-model
• 預期的 state 結構
• 是否有 async data 需求
• 輸出應該是 component、composable，還是 pattern example
• 如果不是近期 Vue 3，請明確說明版本限制
• 是否必須使用 TypeScript
• 任何 UI 或效能限制

較弱的輸入：

• 「幫我做一個搜尋用的 Vue component。」

較強的輸入：

• 「Create a Vue 3.5 SFC using <script setup lang="ts"> for a searchable product list. Props: items, loading, modelValue. Emit update:modelValue and select. Use defineModel if appropriate, debounce local search input, and prefer shallowRef for large item arrays.」

如何把模糊需求變成有效的 vue prompts

要把 vue skill 用得好，請明確要求實作上的選擇。好的 prompt 結構通常是：

1. 先說要產出什麼
2. 再說明 Vue 慣例
3. 定義輸入與輸出
4. 補上行為需求與限制
5. 若有取捨，要求說明理由

範例：

「Using the vue skill style, write a Vue 3 component with <script setup lang="ts">. Use Composition API only. Define typed props and emits, avoid Options API, and explain whether ref or shallowRef is the better fit for the main state. Include template and minimal styles.」

這會比泛泛一句「寫個 Vue」更有效，因為它直接對齊了 skill 內建的偏好。

這個 vue skill 預設會推向的程式風格

原始內容會強烈引導代理傾向以下風格：

• Vue 3.5
• Composition API
• <script setup lang="ts">
• 以 macro 為核心的元件定義
• 型別明確的 props 與 emits
• 在效能敏感資料上選擇性使用 shallowRef

如果你想要 Options API、純 JavaScript，或較舊的 Vue 寫法，請明確說出來，因為這個 skill 本身是刻意偏離那些模式的。

最適合的 vue usage 場景

這份 vue guide 最擅長的情境包括：

• 撰寫新的 Vue SFC
• 將舊元件重構成 <script setup>
• 定義具型別的 props、emits 與 models
• 在 ref、reactive、computed 與 watchers 之間做選擇
• 使用 Transition、Teleport、Suspense 或 KeepAlive
• 產出符合現代 Vue 慣例的 composable 範例

相較之下，它比較不適合純視覺設計工作，或與特定框架無關的前端任務。

產出第一版結果的實用 workflow

一個可靠的流程是：

1. 先要求產出第一版 Vue SFC，並明確寫出 props、emits 與 state shape。
2. 檢查產生的 API 是否真的符合你的元件 contract。
3. 再要求第二輪，收緊 reactivity 選擇、typing 與 edge cases。
4. 最後才加入 transitions 或 suspense boundaries 等進階功能。

這個順序很重要，因為如果基礎 state flow 還沒釐清，Vue 的進階功能很容易被過度使用。

會直接影響輸出品質的 repository 細節

從 skill 原始內容中，可以提煉出幾個很實用的細節：

• defineModel 被視為可用於 Vue 3.4+
• withDefaults 在 Vue 3.4 及以下仍然重要
• reactive() 在解構後會失去 reactivity
• 如果不需要深層 reactivity，會偏好使用 shallowRef
• Transition 與 Suspense 等內建功能有對應的實務 pattern

這些正是能讓產生程式碼超越「大概看過 repo」水準的關鍵資訊。

很適合這個 skill 的 request 範例

好的 vue usage 請求例如：

• 「Refactor this Options API component into <script setup lang="ts">.」
• 「Generate typed defineProps and defineEmits for this form component.」
• 「Show a Vue 3 example using Teleport for a modal.」
• 「Explain whether to use watch, watchEffect, or computed here.」
• 「Rewrite this component to use defineModel on Vue 3.4+.」

安裝前常見的期待落差

不要期待只靠 vue skill 就能解決以下問題：

• 專案腳手架建立
• router 架構設計
• 大型應用中的 state store 規劃
• SSR 或 Nuxt 專屬決策
• test runner 設定
• CSS framework 整合細節

如果這些才是你的主要卡點，請把它視為提升元件生成品質的工具，而不是完整的 Vue stack 指南。

vue skill 常見問題

這個 vue skill 適合初學者嗎？

適合，但前提是你已經在用 Vue 3 開發，且希望 AI 產出的結果更乾淨一致。它不是一套初學者課程，不過它透過明確偏好單一風格——也就是搭配 <script setup lang="ts"> 的 Composition API——來降低混用寫法帶來的困惑。對較新的使用者來說，這種一致性很有幫助。

vue skill 支援舊版 Vue 寫法嗎？

不是第一優先。原始內容明確表示，應該一律優先使用 Composition API，而非 Options API。如果你的 codebase 帶有大量 legacy 寫法，仍然可以使用這個 skill，但你需要明確要求相容性限制，並仔細檢查 migration 相關調整。

這和一般的 Vue prompt 有什麼不同？

一般 prompt 很容易產生風格不一致的 Vue 程式碼：API 混用、型別較弱，或使用過時的 macros。vue skill 給代理的是一套更收斂的 playbook，裡面包含偏好設定、現代 macro 用法，以及針對性的參考資料。通常代表你需要手動修正的地方會更少。

如果我在用 Nuxt 或更大的技術堆疊，只安裝 vue 就夠嗎？

不夠。vue install 能幫你處理元件與 reactivity 層級的指引，但更大範圍的技術堆疊仍然需要 Nuxt、routing、state、data fetching 與 deployment 的知識。請把它當成 Vue 程式碼生成層，而不是完整的應用架構 skill。

什麼情況下不適合使用 vue skill？

當你的任務是以下情況時，可以跳過它：

• 框架中立的 UI 程式碼
• React／Angular／Svelte 工作
• 純後端實作
• 大量 Nuxt 專屬慣例、但幾乎沒有原生 Vue 元件實作
• 嚴格維護 legacy Options API，且不允許現代寫法

它有涵蓋進階 Vue 功能嗎？

有，但不是毫無邊界地全包。附帶的參考資料涵蓋 Transition、Teleport、Suspense、KeepAlive、directives、reactivity APIs、lifecycle hooks 與 macros。對許多真實前端任務來說，這樣的範圍已經很夠用，同時又不會膨脹成一本完整的 Vue 百科全書。

如何改進 vue skill 的使用效果

先給代理明確的版本與相容性邊界

這個 skill 建立在 Vue 3.5 時代的指引之上。如果你的應用使用的是 Vue 3.3、3.4，或有較舊的 macro 支援限制，請一開始就先說清楚。這對 defineModel 這類功能，以及 props default 的處理方式尤其重要。

不要只描述 UI 點子，要直接定義元件 contract

想提升 vue 輸出品質，最快的方法就是提供：

• prop 名稱與型別
• emitted events
• model bindings
• async states
• empty 與 error states
• parent-child responsibilities

當 contract 清楚時，這個 skill 在實作上很強；但若你只給模糊的 UI 描述，要它自行推斷完整 API，效果就會明顯變弱。

針對 reactivity 選擇直接下指令

很多 Vue 問題出在 state modeling，而不是 template 語法。因此可以直接在 prompt 裡要求這些取捨，例如：

• 「Use shallowRef if deep tracking is unnecessary.」
• 「Explain whether computed or watch is more appropriate.」
• 「Avoid destructuring reactive objects unless using toRefs.」

這樣做更能對齊 references 裡最有價值的內容，也比抽象地要求「best practices」更能提升程式碼品質。

及早抓出常見失誤模式

請在第一版輸出時優先檢查以下問題：

• 你明明要 Composition API，卻出現 Options API
• 使用了普通的 <script>，而不是 <script setup lang="ts">
• defineProps 或 defineEmits 沒有型別
• 不必要的深層 reactivity
• 其實用 computed 更簡單，卻誤用了 watchers
• 沒有實際需求卻硬塞進階 built-ins

這些都是最常見、也最容易讓泛用型生成結果偏離 skill 預期品質門檻的地方。

一次只迭代一個面向

拿到第一版之後，不要一次要求全部都改。建議分輪優化：

1. API shape
2. typing 與 macros
3. reactivity 正確性
4. rendering states
5. 進階 UX patterns

這樣比較容易驗證每一項調整，也能讓代理持續對齊 vue guide，避免整個元件被不可預測地重生一次。

把 reference 檔案當成升級路徑來用

如果第一版結果已經接近可用，但還不夠扎實，可以直接引導代理回到 skill 自帶的 references：

• references/script-setup-macros.md：處理 props、emits、models、slots 與 macro 語法
• references/core-new-apis.md：處理 reactivity、watchers 與 composables
• references/advanced-patterns.md：處理內建元件與 directives

這是提升 vue for Frontend Development 輸出品質最實用的方法之一，而且不需要把整個 prompt 重寫。

先要最小可用版，再要 production 版

一個很有效率的模式是：

• 第一輪：先要最小可用的 SFC
• 第二輪：再要 production pass，補上 typing、states、accessibility 與 performance 選擇

這樣可以避免第一稿就過度膨脹，也更容易看出哪些地方真的需要 Vue 特有的決策。

讓 skill 對齊你的 codebase 規範

如果你的團隊慣例和這個 skill 的預設不同，請直接說清楚。例如：

• 只用 JavaScript
• 不使用 defineModel
• 避免 Suspense
• 用明確的 prop 物件，而不是只有型別宣告
• 除非特別要求，否則不要使用進階 built-ins

vue skill 本身帶有明確立場，這是它的優點；但只有把這些預設調整成符合你真實 repository 限制的方式，輸出結果才會最好。