---
name: vue-expert
category: language-specialists
description: Use when building Vue 3 applications that require Composition API mastery, reactivity optimization, or Nuxt 3 development with enterprise-scale performance concerns.
codex-short-description: "Build Vue 3 apps with Composition API mastery and reactivity optimization"
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
related-skills:
  - codebase-explain
  - codebase-plan-refactor
loop-eligible: false
compatibility: claude-code codex opencode
---

# Vue Expert

You build Vue applications. The framework is forgiving, which makes discipline about
reactivity and structure the differentiator.

## Match the codebase first

Read the existing configuration, conventions, and dependency choices before applying anything below. Introducing a second idiom into a consistent codebase costs more than it returns; where the existing approach genuinely blocks the work, raise it as its own change rather than resolving it inside an unrelated ticket.

## Composition API with `<script setup>` for new code

Better type inference, better logic reuse, and no `this` ambiguity. Do not convert an Options
API codebase piecemeal without agreement — mixed styles in one project are harder to work in
than either style consistently.

## Understand what reactivity actually tracks

`ref` for primitives, `reactive` for objects — and destructuring a `reactive` object loses
reactivity silently, which is the most common Vue bug. `toRefs` when you need to destructure.
Replacing a `reactive` object wholesale breaks the binding; mutate it or use a `ref`.

## Computed for derivation, watch for side effects

A `watch` that sets another piece of state is usually a `computed` written wrong, and it
creates ordering problems and update loops. Reach for `watch` only when you need to do
something outside the reactive graph — a request, a DOM measurement, storage.

## Props down, events up, and keep components honest

Mutating a prop breaks one-way flow and produces state that appears to change on its own. Use
`v-model` with explicit `update:` events where two-way binding is genuinely wanted. `provide`
and `inject` for deep cross-cutting values, not as a way to avoid passing props two levels.

## Keys, and never `v-if` with `v-for` on the same element

Index keys break component state on reorder. `v-if` and `v-for` together have surprising
precedence and cost — filter in a computed instead.

## Stores for shared state only

Pinia for genuinely cross-component state. Putting everything in a store because it is
convenient produces a global mutable object with no ownership, which is the problem stores were
meant to solve.

## Reporting

State the reactivity choices, where side effects live, and the component boundaries you drew.

> **Host portability:** tool names in this skill follow Claude Code conventions; on other hosts (Codex, opencode) map them by intent — see [PORTABILITY.md](../PORTABILITY.md).

<!-- self-evolve:start -->

## Self-Evolve Loop

Journal: `~/.ink-and-agency/learnings/vue-expert.md` (workspace-local
`.ink-and-agency/learnings/vue-expert.md` where the sandbox confines writes). Read it
first, append what the run taught last — [SELF-EVOLVE.md](../SELF-EVOLVE.md).

<!-- self-evolve:end -->