vue-best-practices

Visión general de la skill vue-best-practices

Para qué sirve vue-best-practices

vue-best-practices es una skill de instrucciones centrada en Vue para generación de código, revisión y refactorización en proyectos Vue 3. Su función principal no es solo “escribir código Vue”, sino “escribir código Vue usando decisiones arquitectónicas actuales que sigan siendo mantenibles bajo la presión real de un proyecto”. En la práctica, orienta a los agentes hacia Composition API, <script setup lang="ts">, flujo de datos explícito y decisiones específicas de Vue que los prompts frontend genéricos suelen pasar por alto.

Quién debería instalar vue-best-practices

Esta skill encaja mejor para equipos y desarrolladores individuales que trabajan con Vue 3, componentes .vue de archivo único, Vue Router, patrones de estado tipo Pinia, aplicaciones basadas en Vite y apps Vue con capacidad SSR. Resulta especialmente útil si quieres que un asistente de IA deje de desviarse hacia patrones genéricos de JavaScript y siga convenciones nativas de Vue.

El trabajo real que resuelve

El valor real de vue-best-practices está en reducir errores de diseño evitables antes de empezar a programar. La skill le indica explícitamente al agente que primero confirme la arquitectura y después mantenga unas cuantas referencias clave en contexto activo: reactividad, estructura SFC, flujo de datos entre componentes y composables. Eso la hace más útil para tomar decisiones de implementación que un simple prompt de “construye este componente”.

Qué hace diferente a esta skill

Su diferencial está en la ruta de decisión. La skill no se limita a decir “usa Vue 3”. Establece valores por defecto y límites:

• usar por defecto Composition API con <script setup lang="ts">
• cambiar de skill si el proyecto es explícitamente Options API o JSX
• tratar props, emits, v-model, provide/inject, componentes async, transiciones y rendimiento como preocupaciones de diseño de primer nivel
• usar documentación de referencia concreta para casos límite en vez de confiar en la memoria

Cuándo vue-best-practices encaja especialmente bien

Usa vue-best-practices for Frontend Development cuando necesites ayuda con:

• crear o refactorizar componentes Vue
• decidir entre props/emits, v-model, provide/inject o un store
• diseño de composables
• decisiones sobre componentes async teniendo en cuenta SSR
• APIs de slots, fallthrough attrs, transiciones, KeepAlive y rendimiento en listas
• revisar si una implementación Vue es idiomática, no solo funcional

Cuándo no es la skill adecuada

No te apoyes en vue-best-practices como guía principal si el código base está intencionalmente muy orientado a Options API o a JSX. La propia skill indica que en esos casos conviene cargar otra skill si está disponible. Tampoco sustituye la documentación específica del framework para temas como routing en Nuxt, configuración de testing o cuestiones de despliegue que no estén cubiertas en las referencias.

Cómo usar la skill vue-best-practices

Contexto de instalación de vue-best-practices

Instala el repositorio padre de skills y luego invoca la skill vue-best-practices desde esa colección:

npx skills add vuejs-ai/skills --skill vue-best-practices

La ruta dentro del repositorio es:
skills/vue-best-practices

Código fuente en GitHub:
https://github.com/vuejs-ai/skills/tree/main/skills/vue-best-practices

Lee primero estos archivos

Para una lectura rápida y de alta señal, empieza por:

• skills/vue-best-practices/SKILL.md
• skills/vue-best-practices/references/reactivity.md
• skills/vue-best-practices/references/sfc.md
• skills/vue-best-practices/references/component-data-flow.md
• skills/vue-best-practices/references/composables.md

La propia skill marca esas cuatro referencias como contexto básico de lectura obligatoria. Si te las saltas, pierdes gran parte de su valor práctico.

Qué información necesita la skill de tu parte

El uso de vue-best-practices mejora mucho cuando aportas contexto arquitectónico, no solo una petición funcional. La información mínima realmente útil es:

• versión de Vue y si se trata de Vue 3
• si el proyecto ya usa TypeScript
• si el código base requiere Composition API, Options API o JSX
• contexto de router/store
• contexto SSR o solo cliente
• responsabilidades del componente
• flujo de datos existente entre padre e hijo
• restricciones de rendimiento, accesibilidad o tamaño de bundle

Un prompt débil pide un componente. Un prompt sólido explica dónde encaja ese componente dentro de la app y cómo debe moverse la información.

Cómo convertir un objetivo difuso en un buen prompt

Débil:

• “Build a Vue modal.”

Más sólido:

• “Using vue-best-practices, create a Vue 3 modal component with <script setup lang="ts">. The modal is controlled by the parent via props and emits, must support v-model:open, trap focus, Teleport to body, and avoid mutating props internally. Show the component API, parent usage, and explain why props/emits are better here than provide/inject.”

Esa versión le da a la skill suficiente contexto para aplicar bien su guía sobre flujo de datos y API de componentes.

Mejor flujo de trabajo para un primer uso

Una guía práctica de vue-best-practices se parece a esto:

1. Confirma la arquitectura del proyecto antes de pedir código.
2. Indica si Composition API es la opción por defecto.
3. Pide al agente que consulte primero las referencias principales.
4. Solicita un plan de implementación antes del código si el límite del componente no está claro.
5. Genera el componente.
6. Haz una segunda pasada centrada en revisión específica de Vue: reactividad, attrs, slots, rendimiento y comportamiento SSR.

Este flujo de trabajo refleja el énfasis de la skill en “confirmar la arquitectura antes de programar”.

Cómo pedir la decisión arquitectónica correcta

Esta skill resulta más útil cuando la pregunta se plantea como una decisión, no como un volcado de código. Buenos ejemplos:

• “Should this state live in the parent, a composable, or Pinia?”
• “Is v-model appropriate here or should this be explicit props/emits?”
• “Should this large list use virtualization?”
• “Is <Transition> correct here, or would class-based animation be simpler?”
• “Should this component be async-loaded in SSR?”

Estas preguntas se alinean directamente con las referencias del repositorio.

Archivos de referencia que merece la pena cargar según la tarea

Usa estas referencias de forma selectiva según la tarea:

• references/component-async.md para lazy loading y tiempos de hidratación en SSR
• references/component-slots.md para diseño de API de slots y defineSlots
• references/component-fallthrough-attrs.md para $attrs y useAttrs()
• references/component-keep-alive.md para comportamiento de caché y riesgo de estado obsoleto
• references/component-transition.md y references/component-transition-group.md para casos de entrada/salida
• references/animation-class-based-technique.md para efectos que no dependen de mount/unmount
• references/state-management.md para decisiones de propiedad del estado
• references/perf-virtualize-large-lists.md para renderizado de listas grandes
• references/perf-v-once-v-memo-directives.md para optimización selectiva del render

Patrones de prompt prácticos que mejoran la salida

Usa prompts que pidan tanto código como razonamiento. Por ejemplo:

• “Apply vue-best-practices and explain the chosen data-flow model.”
• “Refactor this component to Composition API with <script setup lang="ts">, and call out any reactivity pitfalls.”
• “Review this .vue file against vue-best-practices and classify issues as architecture, data flow, performance, or API design.”
• “Implement this feature and list which Vue references were used.”

Esto obliga al asistente a hacer explícitas sus suposiciones en lugar de inventar patrones en silencio.

Bloqueadores habituales de adopción

El mayor bloqueo suele ser la falta de encaje con el código base real. Si tu proyecto usa una versión antigua de Vue, prioriza Options API o depende mucho de JSX/render functions, los valores por defecto de la skill pueden generar fricción innecesaria. Otro bloqueo frecuente es no especificar bien quién es dueño del estado. Muchos errores en Vue aparecen cuando se pide comportamiento de UI sin aclarar quién controla el estado, lo que termina en mutación incorrecta de props o en bindings bidireccionales confusos.

Qué conviene verificar después de generar código

Después de usar la vue-best-practices skill, comprueba que:

• las props no se mutan en los hijos
• los emits son explícitos y tipados cuando se usa TypeScript
• no se usa watch donde computed sería más simple
• los composables contienen lógica reutilizable, no estado compartido accidental
• los componentes async no generan una mala experiencia de carga
• attrs, slots y transiciones siguen las convenciones de Vue
• las tácticas de rendimiento están justificadas y no son puro cargo cult

Preguntas frecuentes sobre la skill vue-best-practices

¿vue-best-practices es apta para principiantes?

Sí, pero para principiantes suele ayudar más como revisor que como generador ciego de código. Las referencias explican por qué ciertos patrones de Vue son preferibles, lo que ayuda a evitar aprender anti-patrones demasiado pronto.

¿vue-best-practices solo es compatible con Vue 3?

En la práctica, sí en su ruta por defecto. La skill se centra claramente en Vue 3, Composition API, <script setup>, TypeScript, patrones con conciencia de SSR, Volar y vue-tsc. Si tu app es Vue 2 o está muy marcada por tareas de migración, no es la mejor opción.

¿En qué se diferencia vue-best-practices de un prompt normal?

Un prompt normal puede producir código con apariencia de Vue y que funcione. vue-best-practices le da al asistente un sesgo arquitectónico concreto y un orden de lectura. Eso importa en Vue porque los errores relacionados con reactividad, comunicación entre componentes, attrs, caché y slots suelen parecer aceptables al principio, pero envejecen mal.

¿vue-best-practices sirve para codebases existentes?

Sí, especialmente para refactors y revisiones. A menudo aporta más valor sobre componentes existentes que en trabajo greenfield, porque ayuda a detectar propiedad de estado poco clara, componentes que han crecido demasiado y problemas de corrección específicos de Vue que en apps maduras es fácil pasar por alto.

¿Debería usarla para tareas con Pinia, Router y SSR?

Sí, siempre que la tarea siga siendo fundamentalmente de arquitectura Vue o comportamiento de componentes. La descripción de la skill cubre explícitamente Vue Router, Pinia, Vite con Vue y aspectos relacionados con SSR. Solo asegúrate de incluir esas restricciones en tu prompt para que el agente no asuma un caso más simple de solo cliente.

¿Cuándo no debería usar vue-best-practices?

Sáltatela cuando:

• el proyecto requiera explícitamente convenciones de Options API
• el proyecto use JSX como estilo principal de autoría
• necesites guía específica del framework fuera de las referencias del repo
• solo quieras un prototipo rápido y desechable y no te importen demasiado los modismos de Vue

Cómo mejorar la skill vue-best-practices

Dale a vue-best-practices entradas arquitectónicas más sólidas

La forma más rápida de mejorar la calidad de la salida es especificar:

• quién es el dueño del estado
• límites entre componentes
• expectativas de API entre padre e hijo
• requisito de TypeScript
• SSR frente a renderizado solo cliente
• escala esperada, por ejemplo listas grandes o vistas cacheadas

Sin eso, la skill tiene que adivinar los tradeoffs de diseño que precisamente debería decidir de forma explícita.

Pide un plan antes de la implementación

Para trabajo que no sea trivial, primero pregunta:

• qué estado pertenece a cada sitio
• si la funcionalidad debería resolverse como componente, composable o responsabilidad del store
• si la comunicación debería usar props/emits, v-model, provide/inject o estado de router/store

Esto sigue la regla del repositorio de priorizar la arquitectura y suele mejorar más la primera pasada de código que pedir simplemente “clean code”.

Usa la biblioteca de referencias de forma intencional

La vue-best-practices skill tiene profundidad real en su carpeta references/. Los resultados mejoran cuando nombras el archivo relevante en el prompt:

• “Use component-data-flow.md logic”
• “Check component-async.md because this is SSR”
• “Apply component-fallthrough-attrs.md because this wrapper forwards attrs”
• “Use perf-virtualize-large-lists.md because this table can exceed 5,000 rows”

Esa es una ventaja práctica frente a los prompts genéricos.

Vigila los modos de fallo más comunes

Las salidas más flojas suelen aparecer cuando el asistente:

• muta props en lugar de emitir actualizaciones
• usa watchers cuando el estado derivado con computed es suficiente
• elige provide/inject demasiado pronto
• encapsula lógica en un componente cuando debería ser un composable
• añade transiciones donde una animación basada en clases sería más simple
• cachea vistas con <KeepAlive> sin una estrategia de frescura
• sugiere microoptimizaciones prematuras sin evidencia

Ese es precisamente el tipo de problemas que esta skill intenta reducir.

Mejora los prompts de revisión después del primer borrador

Después de generar código, pide una segunda pasada como:

• “Review this against vue-best-practices and list the top 5 risks.”
• “Find any reactivity edge cases or data-flow violations.”
• “Check whether this slot API and fallthrough attrs behavior are robust.”
• “Audit this SSR component for async loading and hydration concerns.”

La primera pasada crea código. La segunda extrae el valor real de la skill.

Haz la salida más accionable con entregables explícitos

Si quieres un uso de vue-best-practices de mayor calidad, pide:

• código final
• una breve justificación arquitectónica
• una lista de alternativas descartadas
• notas de migración si estás refactorizando código existente
• una checklist de verificación para vue-tsc, Volar y comportamiento en runtime

Ese formato reduce las respuestas superficiales y hace que el resultado sea más fácil de adoptar en un repositorio real.