create-adaptable-composable

create-adaptable-composable 技能概览

create-adaptable-composable 技能专门帮助你设计 Vue composable，使其能够同时优雅地兼容普通值、ref、shallow ref、writable computed value、computed ref 以及 getter。实际意义在于：调用方既可以传静态输入，也可以传响应式输入，而你不需要为不同输入形式维护多套 API。

create-adaptable-composable 真正解决的是什么问题

它要解决的核心并不是“写一个 composable”这么泛，而是“写一个在应用代码、共享库和混合响应式上下文里都依然好用、易复用的 composable API”。如果你是在为其他开发者构建 Vue 工具，这一点往往比具体实现细节更关键。

适合哪些用户和项目

这个技能尤其适合：

• Vue 3 或 Nuxt 3 开发者
• 库作者与 design system 作者
• 需要统一 composable 模式的团队
• 想把僵硬 composable 重构为更灵活 API 的前端开发者

当你的 composable 今天只接收一个普通值、但明天可能需要兼容 ref 或 getter 时，它会特别有价值。

这个技能背后的核心思路

create-adaptable-composable 的关键模式是：对输入使用 MaybeRef 或 MaybeRefOrGetter，然后在 watch()、watchEffect() 等响应式副作用内部，通过 toValue() 或 toRef() 做归一化处理。这样既能保留响应式行为，又不会强迫所有调用方必须采用同一种输入风格。

为什么它不同于普通的 Vue 提示词

一个泛用提示词也许能生成“在某个 demo 场景下可用”的 composable。但 create-adaptable-composable skill 更聚焦，也更实用：它重点处理 API 的适配性、类型选择以及归一化规则，而这些恰恰决定了你的 composable 是达到 library-grade，还是容易变脆、难复用。

采用这个技能时的主要限制

这个技能本身是有意收窄范围的。它不会直接提供完整架构、测试方案或打包工作流。如果你需要端到端的库脚手架，请把 create-adaptable-composable 看作专注于 composable API 层的设计辅助，而不是完整项目生成器。

如何使用 create-adaptable-composable 技能

create-adaptable-composable 的安装背景

通过 vuejs-ai/skills 集合使用这个技能：

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

从仓库信息来看，目前只暴露了一个 SKILL.md 文件，所以安装非常轻量；但这也意味着你应当预期它提供的是精炼指导，而不是一整套大型示例或辅助脚本体系。

先读这个文件

先从这里开始：

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

目前没有额外暴露 resources/、rules/ 或示例目录，因此核心 skill 文件就是最权威的参考来源。

什么时候该调用这个技能

当你的需求大致像下面这些时，就该用 create-adaptable-composable：

• “让这个 composable 同时支持 refs 和普通值”
• “把这个 Vue composable 重构成能在更多场景复用的形式”
• “为库使用者设计一个 composable API”
• “支持 getters 和 computed 输入，同时不破坏响应性”

如果你的问题主要集中在 routing、SSR data fetching、state 架构或 component rendering，那它就不是最合适的工具。

这个技能最少需要哪些输入信息

想得到有用的结果，至少应提供：

• composable 的名称
• composable 的用途
• 每个输入参数
• 哪些输入可能是响应式的
• 期望的返回结构
• 是否允许使用者传入 getter
• 对 writable 与 read-only 输入是否有约束

如果这些信息不明确，模型往往会退回到宽泛的 Vue 习惯写法，而不是这个技能专门针对的 adaptable-input 模式。

如何把模糊需求改写成强提示词

弱提示词：

• “Create a Vue composable for filtering items.”

更好的提示词：

• “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.”

之所以这个版本效果更好，是因为它一开始就明确了 API 意图、输入变化范围以及响应式策略。

会显著影响输出质量的输入设计规则

最关键的决策是输入类别：

• 对只读、且需要兼容 computed 的输入，使用 MaybeRefOrGetter<T>
• 当 writable ref 语义很重要时，使用 MaybeRef<T>
• 在 watch() 或 watchEffect() 内部用 toValue() 或 toRef() 做值归一化

如果你没有明确某个输入是否必须可写，最终结果很可能会暴露错误的契约。

推荐的 create-adaptable-composable 使用流程

1. 先定义 composable 的公共 API。
2. 标记每个参数是仅普通值、可选响应式，还是可写响应式。
3. 让技能帮你判断该用 MaybeRef 还是 MaybeRefOrGetter。
4. 不要只要最终代码，也要要求说明归一化发生在哪些位置。
5. 复查 watch、watchEffect、toValue 和 toRef 是否用在了正确位置。
6. 用普通值、一个 ref、以及一个 getter 分别测试生成出的 composable。

和一句话要求“写一个灵活的 composable”相比，这个流程更可靠。

检查生成代码时要看什么

好的 create-adaptable-composable 使用结果，通常应具备这些特征：

• 能兼容混合输入形式，而不是写出重复分支
• 响应式追踪保持完整
• 不会在响应式上下文之外过早解包
• TypeScript 工具类型使用清晰
• 对调用方暴露的是稳定且易理解的 API

如果输出在函数入口处就把值全部提前解包，通常意味着响应式能力可能已经丢失。

面向 Frontend Development 的实用提示词模式

在使用 create-adaptable-composable for Frontend Development 时，建议同时要求输出 API 和设计理由：

• composable 的用途
• 不同调用方写法的示例
• 每个参数选择了哪种 type utility
• 归一化发生的位置
• 为什么这种处理能保住响应性
• 一到两个使用示例

这样你审查的是整个设计，而不只是复制一段代码。

可直接复用的示例提示词

“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 技能 FAQ

create-adaptable-composable 只适合库作者吗？

不是。它在共享库场景下价值最明显，但应用团队同样受益，尤其是当 composable 会跨页面、跨功能模块或跨团队复用时。如果你预期调用方输入类型会混用，这个技能就值得用。

它真的比普通提示词更好吗？

通常是的，前提是“适配性”才是你的真实需求。普通提示词经常会生成只支持 ref 输入，或者只支持普通值输入的 composable。create-adaptable-composable skill 会把设计重点放回灵活输入契约本身。

它要求 Vue 3 或 Nuxt 3 吗？

是的。仓库给出的兼容性说明是 Vue 3+ 或 Nuxt 3+。其指导依赖的是现代 Vue 响应式模型中的 API 与类型模式。

什么情况下不该使用 create-adaptable-composable？

以下情况可以跳过：

• composable 本来就是私有的、一次性的
• 所有输入都确定是静态值
• 你的主要问题是 networking、caching 或 framework integration
• 灵活性会让 API 比实际场景更难理解，不值得

并不是每个 composable 都需要 maybe-reactive 输入。

对新手友好吗？

算是中等友好。新手也能用，但如果你已经理解 ref、computed 和 watch，效果会更好。真正难的不是语法，而是判断一个输入到底该是 writable、read-only，还是 getter-friendly。

这个技能会提供很多示例吗？

不会。根据当前可见的仓库结构，指导内容比较紧凑，主要集中在 SKILL.md 里。你应当预期拿到的是原则和模式，而不是一本大型 cookbook。

如何改进 create-adaptable-composable 技能的使用效果

在要代码之前，先把 API 意图说清楚

想提升 create-adaptable-composable 的输出质量，最快的方法不是多要功能，而是先把调用方契约描述清楚。明确每个参数代表什么、调用方是否可以修改它，以及必须支持哪些调用形式。

按参数逐个说明响应式要求

不要只说：

• “Inputs can be reactive”

更推荐写成：

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

这样可以避免类型被过度泛化，也能减少不必要的响应式包裹。

让模型解释为什么选 MaybeRef 或 MaybeRefOrGetter

一个很有效的迭代提示词是：

• “For each parameter, explain why you chose MaybeRef or MaybeRefOrGetter.”

这能更早暴露薄弱假设，也更有助于你建立对最终 API 的信任。

重点盯住这些常见失败模式

常见问题包括：

• 在 composable 顶层一次性把值全部解包
• 需要支持 getter 时却用了 MaybeRef
• 不小心暴露了 writable 语义
• 返回的值已经无法继续响应式更新
• 所有参数都强行做灵活化，反而损害可读性

这些正是你拿到首版输出后最该重点复查的地方。

提供调用方示例，能明显提升生成设计质量

如果你能给出三种调用方式，输出质量通常会更高：

• 普通值用法
• ref 用法
• getter 或 computed 用法

这样 API 必须真正证明自己具备适配性，而不只是类型写得很松。

用边界情况迭代首版结果

拿到第一版后，可以继续追问：

• “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 保持聚焦

这个技能在“适配型 composable 设计”这个范围内表现最好。如果你把 testing、docs、publishing、SSR behavior 等无关需求一次性塞进同一个提示词，输出很容易变得泛化。想获得更好的 create-adaptable-composable guide 效果，最好先把 adaptable API 设计清楚，再逐层补上其他部分。