@moon791017/neo-skills 1.0.28 → 1.0.29

package/GEMINI.md

@@ -109,3 +109,5 @@ When interacting with this codebase or using the extension, the agent follows th
 *   **SwiftUI 專家:** 支援 iOS 16.0+ 與 Swift 5.0+ 的現代開發模式，專注於 NavigationStack、Observation 框架、資料流架構及高效能視圖設計。
 
 *   **JavaScript 現代語法專家:** 跨版本 JavaScript 專家 (ES6-ES2025+)，專注於現代化語法、模組系統與高效能開發模式。
+
+*   **Vue 現代開發專家:** 專注於 Vue 3 Composition API (`<script setup>`)、Pinia 狀態管理與 Vue Router 4，嚴格遵循官方 Style Guide 與最佳實踐。

package/README.md

@@ -56,10 +56,13 @@
 ### 8. JavaScript 開發專家
 *   **JavaScript 現代語法專家 (`skills/neo-javascript`)**：跨版本 JavaScript 專家 (ES6 - ES2025+)，專注於現代化語法、模組系統與高效能開發模式。
 
-### 9. 需求釐清助手
+### 9. Vue 開發專家
+*   **Vue 3 現代開發專家 (`skills/neo-vue`)**：專注於 Vue 3 Composition API (`<script setup>`)、Pinia 狀態管理與 Vue Router 4。嚴格遵循官方 Style Guide 與最佳實踐，並提供反模式 (Anti-Patterns) 的避坑指引。
+
+### 10. 需求釐清助手
 *   **需求釐清**：系統化引導用戶釐清模糊需求，並將其轉化為結構化的規格文件（背景、功能、約束、驗收標準）。
 
-### 10. 安全守衛 (Security Guard)
+### 11. 安全守衛 (Security Guard)
 *   **主動防護 (`secret-guard.ts`)**：作為 CLI 的中介軟體 (Hook)，自動攔截並掃描所有工具執行的參數。若偵測到敏感資訊（如環境設定檔、私鑰、雲端憑證等）將強制阻擋執行，防止機密外洩。
 
 ## 📂 系統架構

package/gemini-extension.json

@@ -1,7 +1,7 @@
 {
   "name": "neo-skills",
   "description": "A universal capability extension for Gemini CLI",
-  "version": "0.54.0",
+  "version": "0.55.0",
   "mcpServers": {
     "neo-skills": {
       "command": "node",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moon791017/neo-skills",
-  "version": "1.0.28",
+  "version": "1.0.29",
   "type": "module",
   "description": "Neo Skills: A Universal Expert Agent Extension",
   "homepage": "https://neo-blog-iota.vercel.app/",

package/skills/neo-vue/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: neo-vue
+version: "1.0.0"
+category: "Core"
+description: "Modern Vue 3 expert skill. Supports comprehensive applications from Composition API to Pinia and Vue Router, and strictly follows the official Vue Style Guide to ensure code quality and style consistency."
+compatibility: "Supports Vue 3.x (Composition API), Pinia, and Vue Router 4. Adaptive to modern frontend build tools like Vite."
+---
+
+# Modern Vue 3 Expert Skill
+
+## Trigger On
+- The user asks to write, debug, refactor, or review Vue.js code.
+- The project directory contains `*.vue`, `*.ts`/`*.js` files specifically importing Vue APIs, or Vue-related configuration files (e.g., `vite.config.ts`, `vue.config.js`).
+- The user wants to implement state management using Pinia.
+- The user wants to configure routing using Vue Router.
+- The user asks for a code review on existing Vue code or architecture.
+
+## Workflow
+1. **Perceive (Environment Awareness):**
+   - Inspect project configuration (`package.json`, `vite.config.ts`) to identify Vue version (Vue 3 vs Vue 2) and tooling (Vite, TypeScript, ESLint, Prettier).
+   - Identify if the file is a Single-File Component (`.vue`), a composable (`useX.ts`), a store (`store.ts`), or router configuration.
+   - Detect the presence of Pinia or Vue Router in the project dependencies.
+2. **Reason (Planning Phase):**
+   - Evaluate the modernization level of the current code. If Vue 2 Options API is used, plan for refactoring to Vue 3 Composition API with `<script setup>`.
+   - Mentally load the rules from `references/coding-style.md` and `references/anti-patterns.md` to ensure component naming (PascalCase), structure, and reactivity are correct.
+   - Mentally load the best practices from `references/patterns.md` to plan architecture, utilizing `ref` over `reactive`, and extracting logic into composables.
+3. **Act (Execution Phase):**
+   - Write high-quality, idiomatic Vue 3 code using `<script setup>` syntax.
+   - Strictly follow component naming conventions (multi-word, `Base`/`The` prefixes) and structure (props validation, self-closing tags).
+   - Implement state using Pinia Setup Stores and handle routing with Named Routes.
+4. **Validate (Standard Validation):**
+   - Validate that directive shorthands (`:`, `@`, `#`) are used consistently.
+   - Check that `computed` properties are pure and free of side effects.
+   - Ensure that props are not mutated directly.
+   - Verify that arrays iterated with `v-for` have stable and unique `key`s, and `v-if` is not used on the same element as `v-for`.
+
+## Feature Roadmap (Vue 3 Core Features)
+- **Composition API:** `<script setup>` for clean, boilerplate-free component authoring.
+- **Reactivity:** `ref`, `reactive`, `computed`, `watch`, and `watchEffect` for explicit state management.
+- **Macros:** `defineProps`, `defineEmits`, `defineExpose`, `defineOptions`, `defineModel` (Vue 3.4+) for compiler-aware declarations.
+- **Composables:** Extracting and reusing stateful logic across components (e.g., `useFetch`, `useAuth`).
+- **Teleport:** Render components outside the main DOM hierarchy (e.g., for modals or tooltips).
+- **Suspense:** Handle asynchronous dependencies in the component tree gracefully.
+- **Pinia:** State management using Setup Stores instead of Vuex.
+- **Vue Router 4:** Modern routing utilizing Composition API hooks (`useRouter`, `useRoute`).
+
+## Coding Standards
+- **Component Naming:** Always use multi-word PascalCase for `.vue` files and component references in templates (e.g., `TodoItem.vue`, `<TodoItem />`).
+- **Setup Script:** ALWAYS use `<script setup>` for new Vue components. Use TypeScript (`lang="ts"`) where possible.
+- **Reactivity:** Prioritize `ref` over `reactive` for local state to maintain consistency in accessing values via `.value`.
+- **Props and Emits:** Define Props and Emits strictly with type annotations using `defineProps<{ ... }>()` and `defineEmits<{ ... }>()`.
+- **CSS Scoping:** Use `<style scoped>` or CSS Modules to prevent global style leakage.
+
+## Deliver
+- **Modern Architecture:** Provide Vue 3 Composition API-based solutions utilizing modern features and TypeScript.
+- **Refactoring Insights:** Provide actionable suggestions to upgrade legacy Options API code to Composition API or Vuex to Pinia.
+- **Style Compliance:** Ensure all delivered code adheres to the official Vue Style Guide (Priority A & B).
+
+## Validate
+- Ensure the provided code complies with Vue 3 syntax and best practices.
+- Validate the avoidance of common anti-patterns (e.g., mutating props, side-effects in `computed`, missing `key` in `v-for`).
+- Confirm the code is robust, readable, and properly utilizes Vue's reactivity system.
+
+## Documentation
+### Official References
+- [Vue 3 Documentation](https://vuejs.org/guide/introduction.html)
+- [Vue Style Guide](https://vuejs.org/style-guide/)
+- [Pinia Documentation](https://pinia.vuejs.org/)
+- [Vue Router Documentation](https://router.vuejs.org/)
+
+### Internal References
+- [Vue Coding Style and Naming Conventions Guide](reference/coding-style.md)
+- [Vue Anti-Patterns and Best Practices](reference/anti-patterns.md)
+- [Modern Vue Architecture Patterns Guide](reference/patterns.md)

package/skills/neo-vue/reference/anti-patterns.md

@@ -0,0 +1,180 @@
+# Vue 3 Anti-Patterns and Common Mistakes
+
+This document lists common incorrect practices (Anti-Patterns) in Vue 3 (Composition API) development and provides the corresponding correct best practices to ensure code maintainability and performance.
+
+## 1. Templates & Directives
+
+### 1.1 Mixing `v-if` and `v-for` on the same element
+**❌ Bad**:
+When both exist on the same node, `v-if` has a higher priority than `v-for`. That means the `v-if` condition will not have access to variables from the scope of the `v-for`.
+```vue-html
+<!--
+This will throw an error because property "todo"
+is not defined on instance.
+-->
+<li v-for="todo in todos" v-if="!todo.isComplete">
+  {{ todo.name }}
+</li>
+```
+
+**✅ Good**:
+Move `v-for` to a wrapping `<template>` tag or replace the list with a computed property that returns the filtered list.
+```vue-html
+<template v-for="todo in todos">
+  <li v-if="!todo.isComplete">
+    {{ todo.name }}
+  </li>
+</template>
+```
+
+### 1.2 Using Array Index as `key` in `v-for`
+**❌ Bad**:
+Using the index can lead to severe rendering errors or mixed-up component states when the order of the array elements changes (e.g., additions, deletions, sorting).
+```vue-html
+<li v-for="(item, index) in items" :key="index">
+```
+
+**✅ Good**:
+Always use a unique and stable ID from your data.
+```vue-html
+<li v-for="item in items" :key="item.id">
+```
+
+## 2. Component Design & Data Flow
+
+### 2.1 Mutating Props Directly
+**❌ Bad**:
+Props enforce a one-way data flow. Mutating them directly will cause Vue to emit warnings and break data synchronization between parent and child components.
+```typescript
+const props = defineProps<{ count: number }>();
+
+function increment() {
+  // Error: Cannot mutate a prop directly
+  props.count++; 
+}
+```
+
+**✅ Good**:
+Notify the parent component to update via `emit`, or use `v-model` (paired with `defineModel` in Vue 3.4+).
+```typescript
+const count = defineModel<number>('count');
+
+function increment() {
+  // Correct: Two-way binding update via defineModel
+  count.value++; 
+}
+```
+
+### 2.2 Implicit Parent-Child Communication
+**❌ Bad**:
+Using `this.$parent` or modifying props directly to communicate state changes to the parent.
+```javascript
+function removeTodo() {
+  const parent = instance.parent
+  if (!parent) return
+
+  parent.props.todos = parent.props.todos.filter((todo) => {
+    return todo.id !== props.todo.id
+  })
+}
+```
+
+**✅ Good**:
+Props down, events up. Emit an event to let the parent mutate the state.
+```typescript
+const emit = defineEmits(['delete']);
+
+function removeTodo() {
+  emit('delete');
+}
+```
+
+## 3. State Management & Reactivity
+
+### 3.1 Side Effects in `computed`
+**❌ Bad**:
+Computed properties should be pure functions. You must never mutate other states, call APIs, or manipulate the DOM inside them.
+```typescript
+const sortedList = computed(() => {
+  // Error: Mutating external state
+  isSorting.value = true;
+  return list.value.slice().sort();
+});
+```
+
+**✅ Good**:
+If you need to produce side effects, use `watch` or handle them inside event handler functions. `computed` is strictly for returning a new value based on dependencies.
+```typescript
+const sortedList = computed(() => {
+  return list.value.slice().sort();
+});
+
+watch(sortedList, () => {
+  console.log('List was sorted!');
+});
+```
+
+### 3.2 Abusing Provide / Inject for Global State
+**❌ Bad**:
+Stuffing large and frequently changing global states (like user info or configurations) into the root component's `provide`. This makes dependency tracking difficult and degrades performance.
+
+**✅ Good**:
+For global states that need to be shared across many different levels of components, use **Pinia**. Reserve `provide`/`inject` for developing specific UI component libraries or tightly scoped dependency injection.
+
+## 4. DOM Manipulation & Styling
+
+### 4.1 Direct DOM Manipulation (Bypassing Vue)
+**❌ Bad**:
+Using `document.querySelector` or manually manipulating DOM attributes breaks Vue's virtual DOM rendering mechanism.
+```typescript
+function focusInput() {
+  document.getElementById('my-input')?.focus();
+}
+```
+
+**✅ Good**:
+Use Template Refs (`ref`) or `useTemplateRef` (Vue 3.5+) to obtain references to DOM elements.
+```vue
+<template>
+  <input ref="my-input" />
+</template>
+
+<script setup lang="ts">
+import { useTemplateRef } from 'vue';
+
+const inputRef = useTemplateRef('my-input');
+
+function focusInput() {
+  inputRef.value?.focus();
+}
+</script>
+```
+
+### 4.2 Element Selectors with `scoped`
+**❌ Bad**:
+Using element selectors (e.g., `button`, `p`) in `<style scoped>` can cause performance issues because Vue injects attributes (like `data-v-xxx`) to elements to scope them. Element-attribute selectors are much slower than class-attribute selectors.
+```vue-html
+<template>
+  <button>×</button>
+</template>
+
+<style scoped>
+button {
+  background-color: red;
+}
+</style>
+```
+
+**✅ Good**:
+Prefer class selectors in scoped styles.
+```vue-html
+<template>
+  <button class="btn-close">×</button>
+</template>
+
+<style scoped>
+.btn-close {
+  background-color: red;
+}
+</style>
+```

package/skills/neo-vue/reference/coding-style.md

@@ -0,0 +1,96 @@
+# Core Code Style Conventions for Vue 3
+
+This document is extracted from the official Vue Style Guide, incorporating essential rules from Priority A (Essential) and Priority B (Strongly Recommended). When authoring Vue components and applications, it is imperative to adhere strictly to these conventions.
+
+## 1. Naming Conventions
+
+### 1.1 Component Naming
+- **Multi-word component names**: Component names must consist of multiple words to prevent conflicts with future HTML tags (exceptions include the root `App` component and built-in components like `<transition>`).
+  - ✅ `TodoItem`, `UserProfile`
+  - ❌ `Todo`, `User`
+- **Single-File Component (SFC) filename casing**: Filenames should consistently use **PascalCase** (preferred) or kebab-case.
+  - ✅ `MyComponent.vue`
+- **Base component names**: Base, stateless, or purely presentational components should begin with a specific prefix such as `Base`, `App`, or `V`.
+  - ✅ `BaseButton.vue`, `BaseIcon.vue`, `AppTable.vue`
+- **Single-instance component names**: Components that appear only once per page (e.g., navigation bars, sidebars) should use `The` as a prefix.
+  - ✅ `TheHeader.vue`, `TheSidebar.vue`
+- **Tightly coupled component names**: If a child component is tightly coupled with its parent, the child's name should use the parent's name as a prefix.
+  - ✅ `TodoList.vue` -> `TodoListItem.vue` -> `TodoListItemButton.vue`
+
+### 1.2 Component and Tag Syntax in Templates
+- **Components in SFCs and string templates**: Always use **PascalCase** and ensure they are self-closing.
+  - ✅ `<MyComponent />`
+- **Components in DOM templates**: Must use kebab-case.
+  - ✅ `<my-component></my-component>`
+
+## 2. Properties and Data Flow (Props & Data Flow)
+
+### 2.1 Prop Definitions
+- **Detailed prop definitions**: The `type` must be explicitly specified. It is strongly recommended to provide `required` or `default` values, and include a `validator` when necessary.
+  ```typescript
+  // ✅ Good
+  props: {
+    status: {
+      type: String,
+      required: true,
+      validator: (value: string) => ['syncing', 'synced', 'error'].includes(value)
+    }
+  }
+  ```
+
+## 3. Template Syntax and Structure
+
+### 3.1 Directive Shorthands
+- Consistently use directive shorthands; do not mix full syntax with shorthands.
+  - `v-bind:` should be `:`
+  - `v-on:` should be `@`
+  - `v-slot:` should be `#`
+
+### 3.2 Component Style Scoping
+- Unless global styles are explicitly required, the `<style>` tag within an SFC should generally include the `scoped` attribute, or utilize CSS Modules (`<style module>`) to prevent global style pollution.
+- Avoid using element selectors with `scoped` styling as it can impact performance. Prefer class selectors.
+  ```vue
+  <!-- ✅ Good -->
+  <style scoped>
+  .btn-close {
+    background-color: red;
+  }
+  </style>
+  
+  <!-- ❌ Bad -->
+  <style scoped>
+  button {
+    background-color: red;
+  }
+  </style>
+  ```
+
+## 4. Quoted Attribute Values
+- **Non-empty HTML attribute values** should always be enclosed in quotes (single or double, choosing the one not used in the surrounding JavaScript).
+  ```vue-html
+  <!-- ✅ Good -->
+  <input type="text">
+  <AppSidebar :style="{ width: sidebarWidth + 'px' }">
+  
+  <!-- ❌ Bad -->
+  <input type=text>
+  <AppSidebar :style={width:sidebarWidth+'px'}>
+  ```
+
+## 5. Simple Expressions in Templates
+- **Component templates should only contain simple expressions.** More complex logic should be refactored into computed properties or methods.
+  ```vue-html
+  <!-- ✅ Good -->
+  {{ normalizedFullName }}
+  
+  <!-- ❌ Bad -->
+  {{
+    fullName.split(' ').map((word) => {
+      return word[0].toUpperCase() + word.slice(1)
+    }).join(' ')
+  }}
+  ```
+
+## 6. Order of Options and Attributes
+- **Component/instance options should be ordered consistently.** (e.g., `name` -> `components` -> `props` -> `emits` -> `setup` -> `computed` -> `watch` -> lifecycle hooks -> `methods` -> `template`).
+- **Attributes of elements should be ordered consistently.** (e.g., `is` -> `v-for` -> `v-if`/`v-show` -> `id` -> `ref`/`key` -> `v-model` -> other attributes -> `v-on` -> `v-html`/`v-text`).

package/skills/neo-vue/reference/patterns.md

@@ -0,0 +1,82 @@
+# Vue 3 Architecture and Modern Patterns
+
+This document defines the architectural guidelines for modern Vue 3 development, covering Composition API practices, Pinia state management principles, Vue Router configuration recommendations, and general best practices for building robust Vue applications.
+
+## 1. Composition API and Script Setup
+
+- **Prefer `<script setup>`**: All new Single-File Components (SFCs) must use the `<script setup>` syntax to achieve concise code, better runtime performance, and superior TypeScript support.
+- **Reactivity**:
+  - Prefer using `ref()` for defining both primitive types and objects to maintain consistency in how values are accessed (always via `.value`).
+  - Only use `reactive()` when there is an explicit need to flatten an object's properties for reactivity without `.value`, or when integrating with external state systems that require it.
+  - When returning state from composables, prefer returning an object of refs over a single reactive object to allow consumers to destructure without losing reactivity (or use `toRefs()`).
+- **Props and Emits**:
+  - Use `defineProps()` and `defineEmits()` to define component interfaces.
+  - In TypeScript, it is strongly recommended to define them using pure type declarations:
+    ```typescript
+    const props = defineProps<{
+      id: number;
+      title?: string;
+    }>();
+    const emit = defineEmits<{
+      (e: 'update', id: number): void;
+    }>();
+    ```
+  - For default prop values with type-based declarations, utilize Reactive Props Destructure (Vue 3.5+) or `withDefaults()`.
+- **Computed Properties (`computed`)**:
+  - `computed` must be a pure function. Never generate side effects or mutate the original state inside a `computed` getter.
+  - Avoid mutating the value returned by a computed property; treat it as read-only derived state.
+  - Break down complex computed properties into multiple simpler computed properties for better readability and testability.
+- **Logic Reuse (Composables)**:
+  - Encapsulate complex business logic, state, and side effects into Composables (e.g., `useAuth()`, `useUser()`).
+  - Composables should follow the naming convention of starting with `use`.
+  - The return values of Composables should be destructured into `ref`s for external use.
+  - Properly clean up side effects (like event listeners or timers) inside `onUnmounted()` within the composable.
+  - Use `toValue()` (Vue 3.3+) to normalize arguments that can be either a value, a ref, or a getter.
+
+## 2. State Management (Pinia)
+
+- **Use Setup Stores**: When defining Pinia stores, use the Setup syntax (similar to Composition API) rather than the Options syntax. This provides better alignment with the Composition API mental model and allows the use of composables within stores.
+  ```typescript
+  export const useUserStore = defineStore('user', () => {
+    const name = ref('Alice');
+    const isAuthenticated = computed(() => !!name.value);
+    function login(newName: string) {
+      name.value = newName;
+    }
+    return { name, isAuthenticated, login };
+  });
+  ```
+- **Separation of Concerns**: Stores should focus solely on maintaining global/shared state. Trivial logic related to UI interactions or component-local state should remain within the Components.
+
+## 3. Routing Configuration (Vue Router)
+
+- **Use Named Routes**:
+  - During development, always prefer navigating using the route `name` rather than the `path`. This prevents broken links if URL paths are refactored in the future.
+    ```typescript
+    // ✅ Good
+    router.push({ name: 'UserProfile', params: { id: 123 } });
+    
+    // ❌ Bad
+    router.push(`/user/${id}`);
+    ```
+- **Route Guards**:
+  - Place permission validation, authentication checks, and global interception logic in global `beforeEach` guards or route-specific guards, rather than handling them inside a component's `onMounted` lifecycle hook.
+
+## 4. Component Communication
+
+- **Props Down, Events Up**: Adhere to the one-way data flow principle. Parents pass data down via props, and children communicate changes back up by emitting events.
+- **Avoid Implicit Communication**: Do not use `this.$parent` or attempt to directly mutate props. If a child needs to update a prop value, it must emit an event to request the parent to perform the mutation.
+- **Two-Way Binding (`v-model`)**: Use `defineModel()` (Vue 3.4+) to easily create two-way bindings for components.
+
+## 5. Performance Optimizations
+
+- **Virtualize Large Lists**: For rendering massive lists, use list virtualization libraries (like `vue-virtual-scroller`) instead of rendering all DOM nodes upfront.
+- **Stable Props**: Try to keep props passed to child components as stable as possible to prevent unnecessary re-renders.
+- **`v-once` and `v-memo`**: Utilize `v-once` for static content that never updates, and `v-memo` (Vue 3.2+) for conditionally skipping updates in large sub-trees or `v-for` lists based on dependency arrays.
+- **Shallow Reactivity**: Use `shallowRef()` and `shallowReactive()` when dealing with large immutable data structures where deep reactivity tracking overhead is undesirable.
+
+## 6. Provide / Inject
+
+- Use `provide` and `inject` to avoid "prop drilling" when passing data through deeply nested component trees.
+- Keep mutations to reactive state inside the provider whenever possible. If an injector needs to update the data, the provider should also provide a function responsible for the mutation.
+- Use `Symbol` keys for injection to avoid naming collisions in large applications.