devskill 2.0.2

package/skills/vue-best-practices/references/sfc.md

@@ -0,0 +1,310 @@
+---
+title: Single-File Component Structure, Styling, and Template Patterns
+impact: MEDIUM
+impactDescription: Consistent SFC structure and styling choices improve maintainability, tooling support, and render performance
+type: best-practice
+tags: [vue3, sfc, scoped-css, styles, build-tools, performance, template, v-html, v-for, computed, v-if, v-show]
+---
+
+# Single-File Component Structure, Styling, and Template Patterns
+
+**Impact: MEDIUM** - Using SFCs with consistent structure and performant styling keeps components easier to maintain and avoids unnecessary render overhead.
+
+## Task List
+
+- Use `.vue` SFCs instead of separate `.js`/`.ts` and `.css` files for components
+- Colocate template, script, and styles in the same SFC by default
+- Use PascalCase for component names in templates and filenames
+- Prefer component-scoped styles
+- Prefer class selectors (not element selectors) in scoped CSS for performance
+- Access DOM / component refs with `useTemplateRef()` in Vue 3.5+
+- Use camelCase keys in `:style` bindings for consistency and IDE support
+- Use `v-for` and `v-if` correctly
+- Never use `v-html` with untrusted/user-provided content
+- Choose `v-if` vs `v-show` based on toggle frequency and initial render cost
+
+## Colocate template, script, and styles
+
+**BAD:**
+```
+components/
+├── UserCard.vue
+├── UserCard.js
+└── UserCard.css
+```
+
+**GOOD:**
+```vue
+<!-- components/UserCard.vue -->
+<script setup>
+import { computed } from 'vue'
+
+const props = defineProps({
+  user: { type: Object, required: true }
+})
+
+const displayName = computed(() =>
+  `${props.user.firstName} ${props.user.lastName}`
+)
+</script>
+
+<template>
+  <div class="user-card">
+    <h3 class="name">{{ displayName }}</h3>
+  </div>
+</template>
+
+<style scoped>
+.user-card {
+  padding: 1rem;
+}
+
+.name {
+  margin: 0;
+}
+</style>
+```
+
+## Use PascalCase for component names
+
+**BAD:**
+```vue
+<script setup>
+import userProfile from './user-profile.vue'
+</script>
+
+<template>
+  <user-profile :user="currentUser" />
+</template>
+```
+
+**GOOD:**
+```vue
+<script setup>
+import UserProfile from './UserProfile.vue'
+</script>
+
+<template>
+  <UserProfile :user="currentUser" />
+</template>
+```
+
+## Best practices for `<style>` block in SFCs
+
+### Prefer component-scoped styles
+
+- Use `<style scoped>` for styles that belong to a component.
+- Keep **global CSS** in a dedicated file (e.g. `src/assets/main.css`) for resets, typography, tokens, etc.
+- Use `:deep()` sparingly (edge cases only).
+
+**BAD:**
+
+```vue
+<style>
+/* ❌ leaks everywhere */
+button { border-radius: 999px; }
+</style>
+```
+
+**GOOD:**
+
+```vue
+<style scoped>
+.button { border-radius: 999px; }
+</style>
+```
+
+**GOOD:**
+
+```css
+/* src/assets/main.css */
+/* ✅ resets, tokens, typography, app-wide rules */
+:root { --radius: 999px; }
+```
+
+### Use class selectors in scoped CSS
+
+**BAD:**
+```vue
+<template>
+  <article>
+    <h1>{{ title }}</h1>
+    <p>{{ subtitle }}</p>
+  </article>
+</template>
+
+<style scoped>
+article { max-width: 800px; }
+h1 { font-size: 2rem; }
+p { line-height: 1.6; }
+</style>
+```
+
+**GOOD:**
+```vue
+<template>
+  <article class="article">
+    <h1 class="article-title">{{ title }}</h1>
+    <p class="article-subtitle">{{ subtitle }}</p>
+  </article>
+</template>
+
+<style scoped>
+.article { max-width: 800px; }
+.article-title { font-size: 2rem; }
+.article-subtitle { line-height: 1.6; }
+</style>
+```
+
+## Access DOM / component refs with `useTemplateRef()`
+
+For Vue 3.5+: use `useTemplateRef()` to access template refs.
+
+```vue
+<script setup lang="ts">
+import { onMounted, useTemplateRef } from 'vue'
+
+const inputRef = useTemplateRef<HTMLInputElement>('input')
+
+onMounted(() => {
+  inputRef.value?.focus()
+})
+</script>
+
+<template>
+  <input ref="input" />
+</template>
+```
+
+## Use camelCase in `:style` bindings
+
+**BAD:**
+```vue
+<template>
+  <div :style="{ 'font-size': fontSize + 'px', 'background-color': bg }">
+    Content
+  </div>
+</template>
+```
+
+**GOOD:**
+```vue
+<template>
+  <div :style="{ fontSize: fontSize + 'px', backgroundColor: bg }">
+    Content
+  </div>
+</template>
+```
+
+## Use `v-for` and `v-if` correctly
+
+### Always provide a stable `:key`
+
+- Prefer primitive keys (`string | number`).
+- Avoid using objects as keys.
+
+**GOOD:**
+
+```vue
+<li v-for="item in items" :key="item.id">
+  <input v-model="item.text" />
+</li>
+```
+
+### Avoid `v-if` and `v-for` on the same element
+
+It leads to unclear intent and unnecessary work.
+([Reference](https://vuejs.org/guide/essentials/list.html#v-for-with-v-if))
+
+**To filter items**
+**BAD:**
+
+```vue
+<li v-for="user in users" v-if="user.active" :key="user.id">
+  {{ user.name }}
+</li>
+```
+
+**GOOD:**
+
+```vue
+<script setup lang="ts">
+import { computed } from 'vue'
+
+const activeUsers = computed(() => users.value.filter(u => u.active))
+</script>
+
+<template>
+  <li v-for="user in activeUsers" :key="user.id">
+    {{ user.name }}
+  </li>
+</template>
+```
+
+**To conditionally show/hide the entire list**
+**GOOD:**
+
+```vue
+<ul v-if="shouldShowUsers">
+  <li v-for="user in users" :key="user.id">
+    {{ user.name }}
+  </li>
+</ul>
+```
+
+## Never render untrusted HTML with `v-html`
+
+**BAD:**
+```vue
+<template>
+  <!-- DANGEROUS: untrusted input can inject scripts -->
+  <article v-html="userProvidedContent"></article>
+</template>
+```
+
+**GOOD:**
+```vue
+<script setup>
+import { computed } from 'vue'
+import DOMPurify from 'dompurify'
+
+const props = defineProps<{
+  trustedHtml?: string
+  plainText: string
+}>()
+
+const safeHtml = computed(() => DOMPurify.sanitize(props.trustedHtml ?? ''))
+</script>
+
+<template>
+  <!-- Preferred: escaped interpolation -->
+  <p>{{ props.plainText }}</p>
+
+  <!-- Only for trusted/sanitized HTML -->
+  <article v-html="safeHtml"></article>
+</template>
+```
+
+## Choose `v-if` vs `v-show` by toggle behavior
+
+**BAD:**
+```vue
+<template>
+  <!-- Frequent toggles with v-if cause repeated mount/unmount -->
+  <ComplexPanel v-if="isPanelOpen" />
+
+  <!-- Rarely shown content with v-show pays initial render cost -->
+  <AdminPanel v-show="isAdmin" />
+</template>
+```
+
+**GOOD:**
+```vue
+<template>
+  <!-- Frequent toggles: keep in DOM, toggle display -->
+  <ComplexPanel v-show="isPanelOpen" />
+
+  <!-- Rare condition: lazy render only when true -->
+  <AdminPanel v-if="isAdmin" />
+</template>
+```

package/skills/vue-best-practices/references/state-management.md

@@ -0,0 +1,135 @@
+---
+title: State Management Strategy
+impact: HIGH
+impactDescription: Choosing the wrong store pattern can cause SSR request leaks, brittle mutation flows, and poor scaling
+type: best-practice
+tags: [vue3, state-management, pinia, composables, ssr, vueuse]
+---
+
+# State Management Strategy
+
+**Impact: HIGH** - Use the lightest state solution that fits your app architecture. SPA-only apps can use lightweight global composables, while SSR/Nuxt apps should default to Pinia for request-safe isolation and predictable tooling.
+
+## Task List
+
+- Keep state local first, then promote to shared/global only when needed
+- Use singleton composables only in non-SSR applications
+- Expose global state as readonly and mutate through explicit actions
+- Prefer Pinia for SSR/Nuxt, large apps, and advanced debugging/plugin needs
+- Avoid exporting mutable module-level reactive state directly
+
+## Choose the Lightest Store Approach
+
+- **Feature composable:** Default for reusable logic with local/feature-level state.
+- **Singleton composable or VueUse `createGlobalState`:** Small non-SSR apps needing shared app state.
+- **Pinia:** SSR/Nuxt apps, medium-to-large apps, and cases requiring DevTools, plugins, or action tracing.
+
+## Avoid Exporting Mutable Module State
+
+**BAD:**
+```ts
+// store/cart.ts
+import { reactive } from 'vue'
+
+export const cart = reactive({
+  items: [] as Array<{ id: string; qty: number }>
+})
+```
+
+**GOOD:**
+```ts
+// composables/useCartStore.ts
+import { reactive, readonly } from 'vue'
+
+let _store: ReturnType<typeof createCartStore> | null = null
+
+function createCartStore() {
+  const state = reactive({
+    items: [] as Array<{ id: string; qty: number }>
+  })
+
+  function addItem(id: string, qty = 1) {
+    const existing = state.items.find((item) => item.id === id)
+    if (existing) {
+      existing.qty += qty
+      return
+    }
+    state.items.push({ id, qty })
+  }
+
+  return {
+    state: readonly(state),
+    addItem
+  }
+}
+
+export function useCartStore() {
+  if (!_store) _store = createCartStore()
+  return _store
+}
+```
+
+## Do Not Use Runtime Singletons in SSR
+
+Module singletons live for the runtime lifetime. In SSR this can leak state between requests.
+
+**BAD:**
+```ts
+// shared singleton reused across requests
+const cartStore = useCartStore()
+
+export function useServerCart() {
+  return cartStore
+}
+```
+
+**GOOD:**
+
+> `pinia` dependency required.
+
+```ts
+// stores/cart.ts
+import { defineStore } from 'pinia'
+
+export const useCartStore = defineStore('cart', {
+  state: () => ({
+    items: [] as Array<{ id: string; qty: number }>
+  }),
+  actions: {
+    addItem(id: string, qty = 1) {
+      const existing = this.items.find((item) => item.id === id)
+      if (existing) {
+        existing.qty += qty
+        return
+      }
+      this.items.push({ id, qty })
+    }
+  }
+})
+```
+
+## Use `createGlobalState` for Small SPA Global State
+
+> `@vueuse/core` dependency required.
+
+If the app is non-SSR and already uses VueUse, `createGlobalState` removes singleton boilerplate.
+
+```ts
+import { createGlobalState } from '@vueuse/core'
+import { computed, ref } from 'vue'
+
+export const useAuthState = createGlobalState(() => {
+  const token = ref<string | null>(null)
+  const isAuthenticated = computed(() => token.value !== null)
+
+  function setToken(next: string | null) {
+    token.value = next
+  }
+
+  return {
+    token,
+    isAuthenticated,
+    setToken
+  }
+})
+```

package/skills/vue-best-practices/references/updated-hook-performance.md

@@ -0,0 +1,187 @@
+---
+title: Avoid Expensive Operations in Updated Hook
+impact: MEDIUM
+impactDescription: Heavy computations in updated hook cause performance bottlenecks and potential infinite loops
+type: capability
+tags: [vue3, vue2, lifecycle, updated, performance, optimization, reactivity]
+---
+
+# Avoid Expensive Operations in Updated Hook
+
+**Impact: MEDIUM** - The `updated` hook runs after every reactive state change that causes a re-render. Placing expensive operations, API calls, or state mutations here can cause severe performance degradation, infinite loops, and dropped frames below the optimal 60fps threshold.
+
+Use `updated`/`onUpdated` sparingly for post-DOM-update operations that cannot be handled by watchers or computed properties. For most reactive data handling, prefer watchers (`watch`/`watchEffect`) which provide more control over what triggers the callback.
+
+## Task List
+
+- Never perform API calls in updated hook
+- Never mutate reactive state inside updated (causes infinite loops)
+- Use conditional checks to verify updates are relevant before acting
+- Prefer `watch` or `watchEffect` for reacting to specific data changes
+- Use throttling/debouncing if updated operations are expensive
+- Reserve updated for low-level DOM synchronization tasks
+
+**BAD:**
+```javascript
+// BAD: API call in updated - fires on every re-render
+export default {
+  data() {
+    return { items: [], lastUpdate: null }
+  },
+  updated() {
+    // This runs after every single state change!
+    fetch('/api/sync', {
+      method: 'POST',
+      body: JSON.stringify(this.items)
+    })
+  }
+}
+```
+
+```javascript
+// BAD: State mutation in updated - infinite loop
+export default {
+  data() {
+    return { renderCount: 0 }
+  },
+  updated() {
+    // This causes another update, which triggers updated again!
+    this.renderCount++ // Infinite loop
+  }
+}
+```
+
+```javascript
+// BAD: Heavy computation on every update
+export default {
+  updated() {
+    // Expensive operation runs on every keystroke, every state change
+    this.processedData = this.heavyComputation(this.rawData)
+    this.analytics = this.calculateMetrics(this.allData)
+  }
+}
+```
+
+**GOOD:**
+```javascript
+import debounce from 'lodash-es/debounce'
+
+// GOOD: Use watcher for specific data changes
+export default {
+  data() {
+    return { items: [] }
+  },
+  watch: {
+    // Only fires when items actually changes
+    items: {
+      handler(newItems) {
+        this.syncToServer(newItems)
+      },
+      deep: true
+    }
+  },
+  methods: {
+    syncToServer: debounce(function(items) {
+      fetch('/api/sync', {
+        method: 'POST',
+        body: JSON.stringify(items)
+      })
+    }, 500)
+  }
+}
+```
+
+```vue
+<!-- GOOD: Composition API with targeted watchers -->
+<script setup>
+import { ref, watch, onUpdated } from 'vue'
+import { useDebounceFn } from '@vueuse/core'
+
+const items = ref([])
+const scrollContainer = ref(null)
+
+// Watch specific data - not all updates
+watch(items, (newItems) => {
+  syncToServer(newItems)
+}, { deep: true })
+
+const syncToServer = useDebounceFn((items) => {
+  fetch('/api/sync', { method: 'POST', body: JSON.stringify(items) })
+}, 500)
+
+// Only use onUpdated for DOM synchronization
+onUpdated(() => {
+  // Scroll to bottom only if content changed height
+  if (scrollContainer.value) {
+    scrollContainer.value.scrollTop = scrollContainer.value.scrollHeight
+  }
+})
+</script>
+```
+
+```javascript
+// GOOD: Conditional check in updated hook
+export default {
+  data() {
+    return {
+      content: '',
+      lastSyncedContent: ''
+    }
+  },
+  updated() {
+    // Only act if specific condition is met
+    if (this.content !== this.lastSyncedContent) {
+      this.syncContent()
+      this.lastSyncedContent = this.content
+    }
+  },
+  methods: {
+    syncContent: debounce(function() {
+      // Sync logic
+    }, 300)
+  }
+}
+```
+
+## Valid Use Cases for Updated Hook
+
+```javascript
+// GOOD: Low-level DOM synchronization
+export default {
+  updated() {
+    // Sync third-party library with Vue's DOM
+    this.thirdPartyWidget.refresh()
+
+    // Update scroll position after content change
+    this.$nextTick(() => {
+      this.maintainScrollPosition()
+    })
+  }
+}
+```
+
+## Prefer Computed Properties for Derived Data
+
+```javascript
+// BAD: Calculating derived data in updated
+export default {
+  data() {
+    return { numbers: [1, 2, 3, 4, 5] }
+  },
+  updated() {
+    this.sum = this.numbers.reduce((a, b) => a + b, 0) // Causes another update!
+  }
+}
+
+// GOOD: Use computed property instead
+export default {
+  data() {
+    return { numbers: [1, 2, 3, 4, 5] }
+  },
+  computed: {
+    sum() {
+      return this.numbers.reduce((a, b) => a + b, 0)
+    }
+  }
+}
+```

package/skills/vue-jsx-best-practices/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 hyf0, SerKo <https://github.com/serkodev>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/vue-jsx-best-practices/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: vue-jsx-best-practices
+description: JSX syntax in Vue (e.g., class vs className, JSX plugin config).
+version: 2.0.0
+license: MIT
+author: github.com/vuejs-ai
+---
+
+Vue JSX best practices and differences from React JSX.
+
+### JSX
+- Migrating React JSX code to Vue or getting attribute type errors → See [render-function-jsx-vue-vs-react](reference/render-function-jsx-vue-vs-react.md)

package/skills/vue-jsx-best-practices/SYNC.md

@@ -0,0 +1,5 @@
+# Sync Info
+
+- **Source:** `vendor/vuejs-ai/skills/vue-jsx-best-practices`
+- **Git SHA:** `f3dd1bf4d3ac78331bdc903e4519d561c538ca6a`
+- **Synced:** 2026-03-24