create-adaptable-composable

Overview of create-adaptable-composable skill

The create-adaptable-composable skill helps you design Vue composables that work cleanly with plain values, refs, shallow refs, writable computed values, computed refs, and getters. In practice, that means callers can pass either static or reactive inputs without you maintaining separate APIs.

What create-adaptable-composable actually solves

The real job-to-be-done is not “write any composable,” but “write a reusable composable API that stays ergonomic across app code, shared libraries, and mixed reactivity contexts.” If you build Vue utilities for other developers, this matters more than the implementation details.

Best-fit users and projects

This skill is best for:

• Vue 3 or Nuxt 3 developers
• library and design-system authors
• teams standardizing composable patterns
• frontend developers refactoring rigid composables into more flexible APIs

It is especially useful when your composable should accept a value today but may need to accept a ref or getter tomorrow.

Core idea behind the skill

The key pattern in create-adaptable-composable is to accept MaybeRef or MaybeRefOrGetter inputs, then normalize them with toValue() or toRef() inside reactive effects such as watch() or watchEffect(). That keeps behavior reactive without forcing every caller into the same input style.

Why this skill is different from a generic Vue prompt

A generic prompt may produce a composable that works for one demo case. The create-adaptable-composable skill is narrower and more useful: it centers API adaptability, type choices, and normalization rules that directly affect whether the composable is library-grade or brittle.

Main adoption constraint

This skill is intentionally narrow. It does not give you a full architecture, testing setup, or packaging workflow. If you need end-to-end library scaffolding, treat create-adaptable-composable as a focused design aid for the composable API layer, not a complete project generator.

How to Use create-adaptable-composable skill

Install context for create-adaptable-composable

Use this skill from the vuejs-ai/skills collection:

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

Because the repository evidence shows only a single SKILL.md file, installation is lightweight but also means you should expect concise guidance rather than a large support system of examples or helper scripts.

Read this file first

Start with:

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

There are no extra resources/, rules/, or example folders surfaced here, so the core skill file is the source of truth.

Know when to invoke the skill

Call create-adaptable-composable when your request sounds like any of these:

• “Make this composable accept both refs and plain values”
• “Refactor this Vue composable to be reusable in more contexts”
• “Design a composable API for library consumers”
• “Support getters and computed inputs without breaking reactivity”

Do not reach for it if your problem is mainly routing, SSR data fetching, state architecture, or component rendering.

The minimum input the skill needs

To get a useful result, provide:

• the composable name
• the purpose of the composable
• each input parameter
• which inputs may be reactive
• expected return shape
• whether consumers should be allowed to pass getters
• any constraints around writable vs read-only inputs

Without that, the model may default to broad Vue patterns instead of the adaptable-input pattern this skill is built for.

Turn a rough request into a strong prompt

Weak prompt:

• “Create a Vue composable for filtering items.”

Better 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.”

That stronger prompt works better because it defines API intent, input variability, and reactivity policy up front.

Input design rules that materially affect output quality

The most important decision is input category:

• Use MaybeRefOrGetter<T> for read-only, computed-friendly inputs
• Use MaybeRef<T> when writable ref semantics matter
• Normalize values inside watch() or watchEffect() with toValue() or toRef()

If you do not specify whether an input must be writable, the result may expose the wrong contract.

Suggested workflow for create-adaptable-composable usage

1. Define the composable’s public API.
2. Mark each parameter as plain-only, maybe-reactive, or writable-reactive.
3. Ask the skill to choose between MaybeRef and MaybeRefOrGetter.
4. Ask for normalization points, not just final code.
5. Review whether watch, watchEffect, toValue, and toRef are used in the right places.
6. Test the generated composable with a plain value, a ref, and a getter.

This workflow is more reliable than asking for “a flexible composable” in one sentence.

What to look for in the generated code

Good create-adaptable-composable usage should produce code that:

• accepts mixed input styles without duplicate branches
• keeps reactive tracking intact
• avoids premature unwrapping outside reactive contexts
• uses clear TypeScript utility types
• preserves a stable, understandable caller API

If the output unwraps values too early at function entry, it may lose reactivity.

Practical prompt pattern for Frontend Development

For create-adaptable-composable for Frontend Development, ask for both API and reasoning:

• composable purpose
• example caller variants
• chosen type utility per param
• where normalization happens
• why that choice preserves reactivity
• one or two usage examples

This helps you review the design, not just paste code.

Example prompt you can reuse

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

Is create-adaptable-composable only for library authors?

No. It is most valuable for shared libraries, but app teams also benefit when composables are reused across pages, features, or teams. If you expect mixed caller input types, this skill is worth using.

Is this better than an ordinary prompt?

Usually yes, when adaptability is the real requirement. Ordinary prompts often generate composables that assume ref inputs only, or plain values only. The create-adaptable-composable skill keeps the design centered on flexible input contracts.

Does it require Vue 3 or Nuxt 3?

Yes. The repository compatibility states Vue 3+ or Nuxt 3+. The guidance relies on APIs and typing patterns from the modern Vue reactivity model.

When should I not use create-adaptable-composable?

Skip it when:

• the composable is intentionally private and single-use
• all inputs are guaranteed static
• your main problem is networking, caching, or framework integration
• flexibility would make the API harder to understand than the use case justifies

Not every composable needs maybe-reactive inputs.

Is it beginner-friendly?

Moderately. Beginners can use it, but it helps if you already understand ref, computed, and watch. The tricky part is not syntax; it is choosing when an input should be writable, read-only, or getter-friendly.

Does the skill provide many examples?

No. Based on the surfaced repository structure, the guidance is compact and mostly contained in SKILL.md. Expect principles and patterns rather than a large cookbook.

How to Improve create-adaptable-composable skill

Give clearer API intent before asking for code

The fastest way to improve create-adaptable-composable results is to describe the caller contract, not just the feature. Say what each parameter represents, whether callers may mutate it, and which caller forms must be supported.

Specify parameter-by-parameter reactivity

Instead of:

• “Inputs can be reactive”

Use:

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

This prevents over-generalized typing and unnecessary reactivity wrappers.

Ask the model to justify MaybeRef vs MaybeRefOrGetter

A strong iteration prompt is:

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

That exposes weak assumptions early and improves trust in the final API.

Watch for the main failure modes

Common problems include:

• unwrapping values once at the top of the composable
• using MaybeRef where getter support is needed
• exposing writable semantics accidentally
• returning values that no longer update reactively
• adding flexibility to every parameter even when it hurts clarity

These are exactly the points to review after first output.

Provide caller examples to improve the generated design

If you show three invocation styles, output quality usually improves:

• plain value usage
• ref usage
• getter or computed usage

That forces the API to prove it is genuinely adaptable, not just typed loosely.

Iterate on the first draft with edge cases

After the first result, ask:

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

These questions produce better refinement than asking for a total rewrite.

Keep create-adaptable-composable focused

The skill works best when scoped tightly to adaptable composable design. If you combine it with unrelated asks like testing, docs, publishing, and SSR behavior in one prompt, the output may become generic. For better create-adaptable-composable guide results, solve the adaptable API first, then layer on the rest.