create-adaptable-composable

create-adaptable-composable skill 概覽

create-adaptable-composable skill 會幫你設計 Vue composable，讓它能乾淨地同時支援 plain value、ref、shallow ref、writable computed value、computed ref 與 getter。實務上，這代表呼叫端可以傳入靜態或響應式輸入，而你不需要為不同輸入型態額外維護多套 API。

create-adaptable-composable 實際解決的是什麼

它真正要解的，不是「寫出任意一個 composable」，而是「設計出一個可重用、而且在 app 程式碼、共享函式庫與混合響應式情境下都維持好用的 composable API」。如果你是在為其他開發者打造 Vue 工具，這一點往往比實作細節更重要。

最適合的使用者與專案類型

這個 skill 特別適合：

• Vue 3 或 Nuxt 3 開發者
• library 與 design system 作者
• 想統一 composable 模式的團隊
• 正在把僵硬 composable 重構成更彈性 API 的 frontend 開發者

尤其當你的 composable 今天只需要接 value，但明天可能得支援 ref 或 getter 時，這個 skill 會特別有價值。

create-adaptable-composable 背後的核心觀念

create-adaptable-composable 的關鍵模式，是讓輸入接受 MaybeRef 或 MaybeRefOrGetter，再於 watch()、watchEffect() 這類 reactive effect 內，使用 toValue() 或 toRef() 做正規化。這樣能維持響應式行為，又不會強迫所有呼叫端都採用同一種輸入風格。

為什麼這個 skill 跟一般 Vue prompt 不一樣

一般 prompt 可能只能產出「某個 demo 剛好可用」的 composable。create-adaptable-composable skill 更聚焦、也更實用：它把重點放在 API 彈性、型別選擇，以及正規化規則，而這些正是決定 composable 是 library-grade 還是容易碎裂的核心。

採用 create-adaptable-composable 的主要限制

這個 skill 的定位本來就很聚焦。它不會提供完整架構、測試配置或套件封裝流程。如果你需要端到端的 library scaffold，應把 create-adaptable-composable 視為專注在 composable API 層的設計輔助，而不是完整的專案產生器。

如何使用 create-adaptable-composable skill

create-adaptable-composable 的安裝方式與使用脈絡

請從 vuejs-ai/skills 集合中使用這個 skill：

npx skills add vuejs-ai/skills --skill create-adaptable-composable

由於目前 repository 可見的內容只有單一 SKILL.md 檔案，安裝很輕量；但也代表你應預期它提供的是精簡、聚焦的指引，而不是附帶大量範例或 helper script 的完整支援系統。

先讀這個檔案

請先看：

• skills/create-adaptable-composable/SKILL.md

這裡看不到額外的 resources/、rules/ 或範例資料夾，因此核心 skill 檔案就是主要依據。

什麼情況該啟用這個 skill

當你的需求接近以下情境時，就適合呼叫 create-adaptable-composable：

• 「讓這個 composable 同時支援 refs 和 plain values」
• 「把這個 Vue composable 重構成能在更多情境重用」
• 「為 library 使用者設計一個 composable API」
• 「支援 getters 與 computed 輸入，同時不要破壞 reactivity」

如果你的主要問題其實是 routing、SSR data fetching、state architecture 或 component rendering，就不該優先用它。

create-adaptable-composable 至少需要哪些輸入資訊

想得到有用的結果，至少要提供：

• composable 名稱
• composable 的用途
• 每個輸入參數
• 哪些輸入可能是 reactive
• 預期的回傳形狀
• 是否允許使用者傳入 getter
• 對 writable 與 read-only 輸入是否有約束

如果缺少這些資訊，模型很可能會退回泛用 Vue 寫法，而不是這個 skill 要處理的 adaptable input 模式。

把模糊需求改寫成更強的 prompt

較弱的 prompt：

• 「Create a Vue composable for filtering items.」

更好的 prompt：

• 「Use create-adaptable-composable to design a Vue 3 composable named useFilteredItems. Inputs: items may be an array, ref, or getter returning an array; query may be a string, ref, computed, or getter; output should expose a computed filtered list and be read-only from the caller perspective. Prefer MaybeRefOrGetter for read-only inputs and normalize with toValue() inside reactive logic.」

這種更完整的 prompt 效果更好，因為它一開始就把 API 意圖、輸入變化性與 reactivity policy 講清楚了。

會明顯影響輸出品質的輸入設計規則

最重要的決策，是先分清輸入類型：

• read-only、且要友善支援 computed 的輸入，用 MaybeRefOrGetter<T>
• 若 writable ref 語意很重要，使用 MaybeRef<T>
• 在 watch() 或 watchEffect() 內用 toValue() 或 toRef() 正規化值

如果你沒有明確說明某個輸入是否必須可寫，最後產出的 contract 很可能會出錯。

create-adaptable-composable 的建議使用流程

1. 先定義 composable 的 public API。
2. 標記每個參數是 plain-only、maybe-reactive，還是 writable-reactive。
3. 要求 skill 在 MaybeRef 與 MaybeRefOrGetter 之間做選擇。
4. 不只要最終程式碼，也要它指出 normalization 應該發生在哪裡。
5. 檢查 watch、watchEffect、toValue 與 toRef 是否出現在正確的位置。
6. 用 plain value、ref 與 getter 各測一次產出的 composable。

這套流程比起只用一句「幫我做個彈性的 composable」要可靠得多。

檢查產生程式碼時該看什麼

好的 create-adaptable-composable usage 應該會產出這樣的程式碼：

• 能接受混合輸入形式，不需要重複分支
• 保持正確的 reactive tracking
• 避免在 reactive context 外過早 unwrap
• 使用清楚的 TypeScript utility types
• 維持穩定、可理解的呼叫端 API

如果輸出一進函式就把值全部 unwrap 掉，通常就會失去 reactivity。

給 Frontend Development 使用 create-adaptable-composable 的實用提問方式

在使用 create-adaptable-composable for Frontend Development 時，建議同時要求 API 與設計理由：

• composable 的用途
• 不同呼叫方式範例
• 每個參數選了哪種 type utility
• normalization 發生在哪裡
• 為什麼這樣能保留 reactivity
• 一到兩個使用範例

這樣你審查的是設計本身，而不只是複製貼上程式碼。

可直接重用的 prompt 範例

「Use the create-adaptable-composable skill to design a Vue 3 composable named usePagination. page may be a number, ref, computed, or getter. pageSize may be a number or ref. total is read-only and may be a getter. Return derived pagination state and navigation helpers. Explain which params should use MaybeRef vs MaybeRefOrGetter, and normalize inputs with toValue() or toRef() only where reactivity is preserved.」

create-adaptable-composable skill 常見問題

create-adaptable-composable 只適合 library 作者嗎？

不是。它對共享函式庫最有價值，但 app 團隊在 composable 會跨頁面、跨功能或跨團隊重用時，同樣能受益。只要你預期呼叫端輸入型態會混用，這個 skill 就值得用。

這會比一般 prompt 更好嗎？

通常是，前提是你的真正需求就是「可適應的輸入」。一般 prompt 很常產出只假設輸入是 ref，或只假設輸入是 plain value 的 composable。create-adaptable-composable skill 則會讓設計始終圍繞彈性的輸入 contract。

它是否要求 Vue 3 或 Nuxt 3？

是。repository 的相容性標示為 Vue 3+ 或 Nuxt 3+。整套指引都建立在現代 Vue reactivity model 的 API 與型別模式上。

什麼情況不該使用 create-adaptable-composable？

以下情況可以跳過：

• 這個 composable 本來就是私有、且只用一次
• 所有輸入都保證是靜態值
• 你的主要問題是 networking、caching 或 framework integration
• 為了彈性而增加的複雜度，反而超過實際需求

不是每個 composable 都需要 maybe-reactive 輸入。

初學者適合用嗎？

算是中等友善。初學者可以用，但如果你已經理解 ref、computed 與 watch，效果會更好。真正困難的地方不在語法，而在於判斷某個輸入該是 writable、read-only，還是 getter-friendly。

這個 skill 提供很多範例嗎？

沒有。從目前可見的 repository 結構來看，內容相對精簡，主要集中在 SKILL.md。你應該預期拿到的是原則與模式，而不是大型 cookbook。

如何提升 create-adaptable-composable skill 的使用效果

在要程式碼之前，先把 API 意圖說清楚

想提升 create-adaptable-composable 產出品質，最快的方法就是描述呼叫端 contract，而不只是功能本身。請說明每個參數代表什麼、呼叫端能不能改它，以及必須支援哪些傳入形式。

逐一指定每個參數的 reactivity

不要只說：

• 「Inputs can be reactive」

改成：

• 「source can be a getter or computed」
• 「selectedId can be writable」
• 「options should stay plain and non-reactive」

這能避免型別被過度泛化，也能減少不必要的 reactivity wrapper。

要求模型說明為什麼選 MaybeRef 或 MaybeRefOrGetter

一個很實用的迭代 prompt 是：

• 「For each parameter, explain why you chose MaybeRef or MaybeRefOrGetter.」

這樣可以提早暴露薄弱假設，也更容易建立你對最終 API 的信心。

留意 create-adaptable-composable 最常見的失敗模式

常見問題包括：

• 在 composable 最上方只 unwrap 一次值
• 明明需要支援 getter，卻用了 MaybeRef
• 不小心暴露出 writable 語意
• 回傳的值不再會隨 reactive 變更而更新
• 每個參數都一律做彈性化，結果反而降低清晰度

這些正是你看第一版輸出時最該優先檢查的地方。

提供呼叫端範例，能改善產生的設計

如果你能展示三種呼叫方式，輸出品質通常會提升：

• plain value 用法
• ref 用法
• getter 或 computed 用法

這會迫使 API 證明自己是真的 adaptable，而不是只是型別寫得很寬鬆。

用 edge cases 迭代第一版草稿

拿到第一版後，可以接著問：

• 「Will this still track updates if query is a getter?」
• 「Should this parameter be read-only?」
• 「What happens if the caller passes a plain value first and later changes to a ref-based usage pattern?」
• 「Can you simplify the API without losing adaptability?」

這類問題通常比直接要求整份重寫，更能得到高品質修正。

讓 create-adaptable-composable 保持聚焦

這個 skill 在「可適應 composable 設計」的範圍內效果最好。如果你把 testing、docs、publishing 與 SSR behavior 等不相關需求一次塞進同一個 prompt，輸出很容易變得泛泛而談。想得到更好的 create-adaptable-composable guide 結果，先把 adaptable API 設計做好，再逐步疊加其他需求。