Skip to main content
skill CX Codex

pinia · martinholovsky — Claude Code skill: what it does, how to install

pinia is a Claude Code skill for designing Vue and Nuxt application stores using Composition API and TDD. It sets up typed Pinia stores, Vitest unit tests, and input validation rules.

Unlicense 198 installs ★ 48 updated 2025-12-06

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add martinholovsky/claude-skills-generator --skill pinia -a claude-code
Open on GitHub

What pinia does

The skill builds Pinia stores following a test-driven development workflow. It starts by writing a failing test in Vitest using setActivePinia, implements a setup store with the Composition API, and verifies code with npm run typecheck.

It includes implementation patterns for system metrics, command queues, and persisted preferences. For Nuxt setups, it configures @pinia/nuxt with store scanning in ./stores/** and optional persistence via pinia-plugin-persistedstate.

The skill blocks storing authentication tokens or passwords in localStorage through persisted state. Store actions validate every parameter before mutating state.

What it helps with

  • write Vitest unit tests for Pinia stores
  • generate typed setup stores with the Composition API
  • configure state persistence with pinia-plugin-persistedstate
  • add parameter validation inside store actions

Example prompts for the agent

  • Create a Pinia metrics store with Vitest tests
  • Configure persistent preferences with pinia-plugin-persistedstate
  • Implement a typed command queue store with input validation

How to install pinia

1Skills CLI (Vercel)

npx skills add martinholovsky/claude-skills-generator --skill pinia -a claude-code

2Manually: put the files in place

~/.claude/skills/pinia/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/pinia/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about pinia

How to install pinia in Claude Code?

Run npx skills add martinholovsky/claude-skills-generator --skill pinia -a claude-code. The skill file will be placed in ~/.claude/skills/pinia/SKILL.md.

What does the pinia skill do?

It guides the creation of TypeScript Pinia stores using test-driven development. It writes Vitest unit tests, configures setup stores, and verifies state mutations.

What dependencies does the pinia skill require?

The skill relies on pinia version ^2.1.0 and vitest. Optional Nuxt integration uses @pinia/nuxt, while client persistence requires pinia-plugin-persistedstate.

Source text

SKILL.md · Unlicense
---
name: pinia
description: Pinia state management for JARVIS system state
model: sonnet
risk_level: MEDIUM
version: 1.0.0
---

# Pinia State Management Skill

> **File Organization**: This skill uses split structure. See `references/` for advanced patterns and security examples.

## 1. Overview

This skill provides Pinia expertise for managing application state in the JARVIS AI Assistant, including system metrics, user preferences, and HUD configuration.

**Risk Level**: MEDIUM - Manages sensitive state, SSR considerations, potential data exposure

**Primary Use Cases**:
- System metrics and status tracking
- User preferences and settings
- HUD configuration state
- Command history and queue
- Real-time data synchronization

## 2. Core Responsibilities

### 2.1 Core Principles

1. **TDD First**: Write store tests before implementation
2. **Performance Aware**: Optimize subscriptions and computed values
3. **Type Safety**: Define stores with full TypeScript typing
4. **SSR Security**: Prevent state leakage between requests
5. **Composition API**: Use setup stores for better TypeScript support
6. **Minimal State**: Store only necessary data, derive the rest
7. **Action Validation**: Validate inputs in actions before mutations
8. **Persistence Security**: Never persist sensitive data to localStorage

## 3. Technology Stack & Versions

### 3.1 Recommended Versions

| Package | Version | Notes |
|---------|---------|-------|
| pinia | ^2.1.0 | Latest stable |
| @pinia/nuxt | ^0.5.0 | Nuxt integration |
| pinia-plugin-persistedstate | ^3.0.0 | Optional persistence |

### 3.2 Nuxt Configuration

```typescript
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@pinia/nuxt'],
  pinia: {
    storesDirs: ['./stores/**']
  }
})
```

### 3.3 Implementation Workflow (TDD)

Follow this workflow for every store:

**Step 1: Write Failing Test First**

```typescript
// tests/stores/metrics.test.ts
import { describe, it, expect, beforeEach } from 'vitest'
import { setActivePinia, createPinia } from 'pinia'
import { useMetricsStore } from '~/stores/metrics'

describe('MetricsStore', () => {
  beforeEach(() => {
    setActivePinia(createPinia())
  })

  it('should initialize with default values', () => {
    const store = useMetricsStore()
    expect(store.cpu).toBe(0)
    expect(store.memory).toBe(0)
  })

  it('should clamp values within valid range', () => {
    const store = useMetricsStore()
    store.updateCpu(150)
    expect(store.cpu).toBe(100)
    store.updateCpu(-50)
    expect(store.cpu).toBe(0)
  })

  it('should compute health status correctly', () => {
    const store = useMetricsStore()
    store.updateCpu(95)
    store.updateMemory(90)
    expect(store.healthStatus).toBe('critical')
  })
})
```

**Step 2: Implement Minimum to Pass**

```typescript
// stores/metrics.ts
export const useMetricsStore = defineStore('metrics', () => {
  const cpu = ref(0)
  const memory = ref(0)

  const healthStatus = computed(() => {
    const avg = (cpu.value + memory.value) / 2
    if (avg > 90) return 'critical'
    if (avg > 70) return 'warning'
    return 'healthy'
  })

  function updateCpu(value: number) {
    cpu.value = Math.max(0, Math.min(100, value))
  }

  function updateMemory(value: number) {
    memory.value = Math.max(0, Math.min(100, value))
  }

  return { cpu, memory, healthStatus, updateCpu, updateMemory }
})
```

**Step 3: Refactor Following Patterns**

- Extract validation logic
- Add TypeScript interfaces
- Optimize computed dependencies

**Step 4: Run Full Verification**

```bash
npm run test -- --filter=stores
npm run typecheck
npm run build
```

## 4. Implementation Patterns

### 4.1 Setup Store with TypeScript

```typescript
// stores/jarvis.ts
import { defineStore } from 'pinia'
import { ref, computed } from 'vue'

interface SystemMetrics {
  cpu: number
  memory: number
  network: number
  timestamp: number
}

interface JARVISState {
  status: 'idle' | 'listening' | 'processing' | 'responding'
  securityLevel: 'normal' | 'elevated' | 'lockdown'
}

export const useJarvisStore = defineStore('jarvis', () => {
  // State
  const state = ref<JARVISState>({
    status: 'idle',
    securityLevel: 'normal'
  })

  const metrics = ref<SystemMetrics>({
    cpu: 0,
    memory: 0,
    network: 0,
    timestamp: Date.now()
  })

  // Getters
  const isActive = computed(() =>
    state.value.status !== 'idle'
  )

  const systemHealth = computed(() => {
    const avg = (metrics.value.cpu + metrics.value.memory) / 2
    if (avg > 90) return 'critical'
    if (avg > 70) return 'warning'
    return 'healthy'
  })

  // Actions
  function updateMetrics(newMetrics: Partial<SystemMetrics>) {
    // ✅ Validate input
    if (newMetrics.cpu !== undefined) {
      metrics.value.cpu = Math.max(0, Math.min(100, newMetrics.cpu))
    }
    if (newMetrics.memory !== undefined) {
      metrics.value.memory = Math.max(0, Math.min(100, newMetrics.memory))
    }
    if (newMetrics.network !== undefined) {
      metrics.value.network = Math.max(0, newMetrics.network)
    }
    metrics.value.timestamp = Date.now()
  }

  function setStatus(newStatus: JARVISState['status']) {
    state.value.status = newStatus
  }

  function setSecurityLevel(level: JARVISState['securityLevel']) {
    state.value.securityLevel = level

    // ✅ Audit security changes
    console.info(`Security level changed to: ${level}`)
  }

  return {
    state,
    metrics,
    isActive,
    systemHealth,
    updateMetrics,
    setStatus,
    setSecurityLevel
  }
})
```

### 4.2 User Preferences Store (with Persistence)

```typescript
// stores/preferences.ts
export const usePreferencesStore = defineStore('preferences', () => {
  const preferences = ref({
    theme: 'dark' as 'dark' | 'light',
    hudOpacity: 0.8,
    soundEnabled: true
  })

  function updatePreference<K extends keyof typeof preferences.value>(
    key: K, value: typeof preferences.value[K]
  ) {
    if (key === 'hudOpacity' && (value < 0 || value > 1)) return
    preferences.value[key] = value
  }

  return { preferences, updatePreference }
}, {
  persist: {
    key: 'jarvis-preferences',
    paths: ['preferences.theme', 'preferences.hudOpacity']
    // ❌ Never persist: tokens, passwords, API keys
  }
})
```

### 4.3 Command Queue Store

```typescript
// stores/commands.ts
interface Command {
  id: string
  action: string
  status: 'pending' | 'executing' | 'completed' | 'failed'
}

export const useCommandStore = defineStore('commands', () => {
  const queue = ref<Command[]>([])
  const history = ref<Command[]>([])
  const MAX_HISTORY = 100

  const pendingCommands = computed(() =>
    queue.value.filter(cmd => cmd.status === 'pending')
  )

  function addCommand(action: string) {
    const cmd: Command = { id: crypto.randomUUID(), action, status: 'pending' }
    queue.value.push(cmd)
    return cmd.id
  }

  function completeCommand(id: string, status: 'completed' | 'failed') {
    const idx = queue.value.findIndex(cmd => cmd.id === id)
    if (idx !== -1) {
      const [cmd] = queue.value.splice(idx, 1)
      cmd.status = status
      history.value = [cmd, ...history.value].slice(0, MAX_HISTORY)
    }
  }

  return { queue, history, pendingCommands, addCommand, completeCommand }
})
```

### 4.4 SSR-Safe Store Usage

```vue
<script setup lang="ts">
// ✅ Safe for SSR - store initialized per-request
const jarvisStore = useJarvisStore()

// ✅ Fetch data on server
const { data } = await useFetch('/api/metrics')

// Update store with fetched data
if (data.value) {
  jarvisStore.updateMetrics(data.value)
}
</script>
```

### 4.5 Store Composition

```typescript
// stores/dashboard.ts
export const useDashboardStore = defineStore('dashboard', () => {
  // ✅ Compose from other stores
  const jarvisStore = useJarvisStore()
  const commandStore = useCommandStore()

  const dashboardStatus = computed(() => ({
    systemHealth: jarvisStore.systemHealth,
    pendingCommands: commandStore.pendingCommands.length,
    isActive: jarvisStore.isActive
  }))

  return {
    dashboardStatus
  }
})
```

## 5. Security Standards

### 5.1 OWASP Coverage

| OWASP Category | Risk | Mitigation |
|----------------|------|------------|
| A01 Broken Access Control | MEDIUM | Validate actions, check permissions |
| A04 Insecure Design | MEDIUM | SSR state isolation |
| A07 Auth Failures | MEDIUM | Never persist tokens |

### 5.3 Sensitive Data Handling

```typescript
// ❌ NEVER persist: tokens, API keys, passwords
// ✅ Store sensitive data in memory only (no persist option)
const authStore = defineStore('auth', () => {
  const token = ref<string | null>(null)
  return { token }
})
```

## 5.5 Performance Patterns

### Pattern 1: Selective Subscriptions

```typescript
// BAD - Subscribes to entire store
const store = useJarvisStore()
watch(() => store.state, () => { /* ... */ }, { deep: true })

// GOOD - Subscribe to specific properties
const store = useJarvisStore()
watch(() => store.state.status, (newStatus) => {
  console.log('Status changed:', newStatus)
})
```

### Pattern 2: Computed Getters (Memoization)

```typescript
// BAD - Recalculates on every access
function getFilteredItems() {
  return items.value.filter(i => i.active)
}

// GOOD - Cached until dependencies change
const filteredItems = computed(() =>
  items.value.filter(i => i.active)
)
```

### Pattern 3: Batch Updates

```typescript
// BAD - Multiple reactive triggers
function updateAll(data: MetricsData) {
  metrics.value.cpu = data.cpu
  metrics.value.memory = data.memory
  metrics.value.network = data.network
}

// GOOD - Single reactive trigger
function updateAll(data: MetricsData) {
  metrics.value = { ...metrics.value, ...data, timestamp: Date.now() }
}
```

### Pattern 4: Lazy Store Initialization

```typescript
// BAD - Store initializes immediately
const heavyStore = useHeavyDataStore()

// GOOD - Initialize only when needed
const heavyStore = ref<ReturnType<typeof useHeavyDataStore> | null>(null)

function loadHeavyData() {
  if (!heavyStore.value) {
    heavyStore.value = useHeavyDataStore()
  }
  return heavyStore.value
}
```

### Pattern 5: Optimistic Updates

```typescript
// BAD - Wait for server response
async function deleteItem(id: string) {
  await api.delete(`/items/${id}`)
  items.value = items.value.filter(i => i.id !== id)
}

// GOOD - Update immediately, rollback on error
async function deleteItem(id: string) {
  const backup = [...items.value]
  items.value = items.value.filter(i => i.id !== id)

  try {
    await api.delete(`/items/${id}`)
  } catch (error) {
    items.value = backup  // Rollback
    throw error
  }
}
```

## 6. Testing & Quality

See **Section 3.3** for complete TDD workflow with vitest examples.

## 8. Common Anti-Patterns

### Security Anti-Patterns

```typescript
// ❌ Global state leaks between SSR users
const state = reactive({ user: null })

// ✅ Pinia isolates per-request
export const useUserStore = defineStore('user', () => {
  const user = ref(null)
  return { user }
})

// ❌ Never persist auth tokens (XSS risk)
persist: { paths: ['authToken'] }

// ✅ Use httpOnly cookies for auth
```

### Performance Anti-Patterns

See **Section 5.5** for detailed performance patterns with Good/Bad examples.

## 13. Pre-Implementation Checklist

### Phase 1: Before Writing Code

- [ ] Store interface designed with TypeScript types
- [ ] Test file created with failing tests
- [ ] Security requirements identified (persistence, SSR)
- [ ] Performance patterns selected for use case

### Phase 2: During Implementation

- [ ] Tests passing after each feature added
- [ ] Actions validate all inputs
- [ ] Computed values use minimal dependencies
- [ ] No sensitive data in persisted state
- [ ] SSR state properly isolated

### Phase 3: Before Committing

- [ ] All store tests passing: `npm run test -- --filter=stores`
- [ ] Type check passing: `npm run typecheck`
- [ ] Build succeeds: `npm run build`
- [ ] No global state outside Pinia
- [ ] State shape documented in types

## 14. Summary

Pinia provides type-safe state management for JARVIS:

1. **TDD First**: Write store tests before implementation
2. **Performance**: Optimize subscriptions and computed values
3. **Security**: Never persist sensitive data, isolate SSR state
4. **Type Safety**: Use setup stores with full TypeScript

**References**: See `references/` for advanced patterns and security examples.

© martinholovsky · Unlicense · martinholovsky/claude-skills-generator

Similar skills

All skills for Frontend and UI →

pinia by other authors comes first.

pinia Anthony Fu A skill for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode that loads Pinia v4.0.3 reference docs into the agent's context. The agent correctly defines stores, applies storeToRefs(), and sets up SSR state hydration. CX Codex +1 20,600installs unit-test-vue-pinia official github unit-test-vue-pinia writes and reviews unit tests for Vue 3, TypeScript, Vitest and Pinia code. Useful when your tests reach into component internals instead of behavior. CX Codex +1 1,800installs vue-pinia-cursorrules-prompt-file PatrickJS vue-pinia-cursorrules-prompt-file guides Cursor to write clean Vue 3 and TypeScript state management using Pinia setup stores, proper reactivity, SSR safeguards, and tests. CX Codex +1 ★ 41,178repo stars Expert Nuxt Developer official github Expert Nuxt Developer guides Nuxt 3 and Nitro development with TypeScript typing. Helps configure data fetching via useFetch, resolve hydration issues, and structure server routes. CX Codex +1 ★ 41,430repo stars pinia-colada secondsky Brings Pinia Colada data fetching into Claude Code and other AI editors. Handles async state, query caching, SSR, and migration from TanStack Vue Query with useQuery and useMutation. CX Codex +1 253installs pinia-skilld skilld-dev pinia-skilld — a skill that feeds your coding agent the correct Pinia 4.x APIs: stores, getters, actions, SSR hydration, testing and v2/v3 migration notes. CX Codex +1 349installs pinia-colada-skilld skilld-dev pinia-colada-skilld gives coding assistants patterns and rules for @pinia/colada in Vue. Helps write queries, handle mutations, invalidate cache, and set up SSR. CX Codex +1 240installs

From the same set50

The whole set →
Cross-Platform Build Expert Cross-Platform Build Expert guides desktop application packaging for Windows, macOS, and Linux, focusing on Tauri setups, code signing, and CI/CD pipelines. CX Codex +1 210installs cloud-api-integration cloud-api-integration is a Claude Code skill for building cloud AI API integrations. It covers clients for Claude, GPT-4, and Gemini, including request security and provider fallback. CX Codex +1 203installs harbor-expert harbor-expert — a skill that turns the agent into a Harbor registry admin: Trivy scans on push, Notary v2 and Cosign signing, project RBAC and multi-region replication. CX Codex +1 200installs model-quantization model-quantization — a skill for Claude Code, Codex, Cursor, and other agents that adds LLM quantization expertise: 4-bit/8-bit levels, GGUF conversion, memory budgeting for constrained hardware. CX Codex +1 199installs Auto-Update Systems Expert Auto-Update Systems Expert walks through Tauri auto-updates: signed manifests, an HTTPS endpoint, rollback and phased rollouts. CX Codex +1 196installs dbus Guides secure D-Bus IPC development on Linux, covering method calls, signal handling, bus filtering, and test-driven workflows. CX Codex +1 195installs linux-at-spi2 linux-at-spi2 — a skill that lets an agent drive GTK and Qt apps on Linux through AT-SPI2 and D-Bus, with password fields blocked and actions written to a log. CX Codex +1 190installs kanidm-expert kanidm-expert guides setup and maintenance of Kanidm identity management, covering OAuth2, OIDC, WebAuthn, LDAP, RADIUS, and SSH access. CX Codex +1 189installs

Project sponsors

Companies that keep this analytics open