---
slug: "claude-skill-vue-development"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/alexanderop/claude-skill-vue-development@main/README.md"
repo: "https://github.com/alexanderop/claude-skill-vue-development"
source_file: "README.md"
branch: "main"
---
# Vue Development Plugin for Claude Code

A comprehensive, test-driven Vue 3 development skill that enforces modern best practices with 100% compliance under pressure.

**Now available as a Claude Code plugin!** See [PLUGIN-README.md](https://github.com/alexanderop/claude-skill-vue-development/blob/HEAD/PLUGIN-README.md) for installation and usage instructions.

## Overview

This skill teaches Claude agents to write production-quality Vue 3 code using:
- **TypeScript-first** patterns (no runtime validation)
- **Modern Composition API** (defineModel, not manual props)
- **User-behavior testing** (Testing Library, not implementation details)
- **Clean composables** (single responsibility, no UI logic)

## Plugin Structure

```
.claude-plugin/
├── plugin.json (Plugin manifest)
├── marketplace.json (Marketplace configuration)
└── skills/
    └── vue-development/
        ├── SKILL.md (1,216 words)
        │   ├── Red flags (12 anti-patterns)
        │   ├── Quick rules (components, testing, routing, composables)
        │   ├── Essential patterns with examples
        │   ├── Rationalization table (11 excuses countered)
        │   └── Quick checklists (4 domains)
        └── references/
            ├── component-patterns.md (616 words)
            ├── composable-patterns.md (1,848 words)
            ├── routing-patterns.md (589 words)
            ├── testing-composables.md (1,627 words)
            └── testing-patterns.md (785 words)

Total: 6,681 words (1,216 main + 5,465 references)
```

**Legacy Structure:** The original skill files remain in `.claude/skills/vue/` for backward compatibility during migration.

## What It Covers

### Components (`component-patterns.md`)
- Props: `defineProps<{ }>()` with TypeScript, no `const` unless needed
- Emits: `const emit = defineEmits<{ event: [args] }>()`
- V-model: `defineModel<type>()` (NOT manual modelValue)
- Templates: `:prop` shorthand, `#slot` shorthand, explicit `<template>` tags
- Naming: PascalCase or kebab-case, general → specific

### Composables (`composable-patterns.md`)
- Naming: `useFeatureName.ts` with PascalCase
- Structure: Primary state → Metadata → Methods
- Single responsibility principle
- Error exposure (no console.error only)
- NO UI logic (toasts/alerts belong in components)
- Functional core, imperative shell pattern

### Testing Components (`testing-patterns.md`)
- PRIMARY: `@testing-library/vue` for user behavior
- API mocking: MSW (`msw`)
- NEVER: `setTimeout()` in tests, testing internal state
- Async: `findBy*` queries or `waitFor()`
- Query priority: accessibility > test IDs

### Testing Composables (`testing-composables.md`)
- **Independent composables**: Test directly (no lifecycle/inject)
- **Dependent composables**: Use `withSetup` helper (lifecycle hooks)
- **Inject composables**: Use `useInjectedSetup` helper (provide/inject)
- Patterns for async, localStorage, document title, etc.

### Routing (`routing-patterns.md`)
- File-based routing with unplugin-vue-router
- AVOID: `index.vue` → use route groups `(name).vue`
- Explicit params: `[userId]` not `[id]`
- Navigation: Named routes with typed params
- Route guards and meta fields

## Effectiveness

### Before Skill: 37.5% compliance
- Props: 0/3 correct (used const unnecessarily, runtime validation)
- Emits: 0/1 correct (array syntax, no types)
- V-model: 0/1 correct (manual modelValue)
- Testing: 3/4 correct (rejected setTimeout but missed Testing Library)

### After Skill: 100% compliance
- Props: ✅ TypeScript generics, no const when unused
- Emits: ✅ Typed event signatures
- V-model: ✅ defineModel() usage
- Testing: ✅ Proper async, no setTimeout
- Composables: ✅ Correct naming, structure, error handling

**Improvement: 167% increase**

## Key Features

### Red Flags (Auto-Detection)
Agents STOP when they catch themselves:
- "For speed" / "quick demo" → shortcuts
- Manual modelValue → use defineModel()
- setTimeout() in tests → proper async
- UI logic in composables → expose error state
- Generic `[id]` params → explicit names

### Rationalization Table
Counters 11 common excuses:
- "TypeScript is too verbose" → It's actually LESS code
- "We can clean it up later" → Write it right the first time
- "Composables can show toasts" → UI belongs in components
- "counter.ts is fine" → Must use 'use' prefix

### Reference Architecture
Heavy content loads on-demand:
- Components → 616 words
- Composables → 1,848 words
- Routing → 589 words
- Testing (components) → 785 words
- Testing (composables) → 1,627 words

Main skill stays small (1,216 words) for fast initial load.

## Installation

### As a Plugin (Recommended)

See [PLUGIN-README.md](https://github.com/alexanderop/claude-skill-vue-development/blob/HEAD/PLUGIN-README.md) for detailed installation instructions.

**Quick Start:**

```bash
# Add the marketplace
/plugin marketplace add alexanderop/claude-skill-vue-development

# Install the plugin
/plugin install vue-development@vue-development-marketplace
```

### Legacy Installation (Direct Skill)

1. Place skill files in `.claude/skills/vue/`
2. The skill auto-loads when:
   - Creating Vue 3 components
   - Implementing v-model
   - Defining props/emits
   - Setting up routes
   - Writing Vue tests
   - Creating composables

Or invoke manually:
```
Skill: vue-development
```

## Testing Methodology

Created using **Test-Driven Development for Documentation**:

1. **RED Phase**: Created 8 pressure scenarios, ran baseline tests without skill
2. **GREEN Phase**: Wrote minimal skill addressing observed failures
3. **REFACTOR Phase**: Closed loopholes, achieved 100% compliance

All rationalizations captured from real agent behavior under:
- Time pressure ("ASAP", "ship tonight")
- Authority pressure ("just make it work")
- Exhaustion pressure ("debugging for 2 hours")
- Confusion pressure ("I think I need to...")

## Documentation

- `SKILL-CREATION-SUMMARY.md` - TDD methodology and results
- `OPTIMIZATION-SUMMARY.md` - Reference architecture details
- `FINAL-STATUS.md` - Complete status and metrics
- `test-scenarios/` - All baseline and with-skill test results

## Usage Examples

### Component Creation
**Without skill:** Used runtime validation, `const props =` unnecessarily, no emits types
**With skill:** TypeScript generics, correct const usage, fully typed emits

### V-Model Implementation
**Without skill:** Manual modelValue prop + update:modelValue emit
**With skill:** `defineModel<string>()` for clean two-way binding

### Testing
**Without skill:** setTimeout(1000), testing internal state
**With skill:** findBy* queries, user-visible behavior only

### Composables
**Without skill:** UI logic in composables, missing 'use' prefix, console.error only
**With skill:** Proper naming, error exposure, no UI logic, single responsibility

## Requirements

- Vue 3.4+ (for defineModel)
- TypeScript
- Vitest (recommended for testing)
- @testing-library/vue
- msw (for API mocking)
- unplugin-vue-router (for file-based routing)

## Contributing

The skill enforces best practices from:
- Official Vue 3 documentation
- Vue Composition API RFC
- Testing Library principles
- Kent C. Dodds testing philosophy
- Community best practices from alexop.dev

## Status

✅ **PRODUCTION-READY**

- 100% compliance rate in testing
- 25% smaller main file (1,216 vs original 1,618 words)
- 312% more comprehensive (6,681 total words)
- Tested under multiple pressure scenarios
- Zero new rationalizations after optimization

## License

Created following Claude Code superpowers methodology.