lvt-add-skill

name: lvt-add-skill description: Use when creating new Claude Code skills for lvt CLI commands - covers TDD methodology for documentation, research process, skill structure, testing, and refinement

lvt:add-skill

Create high-quality Claude Code skills for lvt CLI commands using TDD methodology.

🎯 ACTIVATION RULES

Context Detection

This skill typically runs in existing LiveTemplate projects (.lvtrc exists).

✅ Context Established By:

1. Project context - .lvtrc exists (most common scenario)
2. Agent context - User is working with lvt-assistant agent
3. Keyword context - User mentions "lvt", "livetemplate", or "lt"

Keyword matching (case-insensitive): lvt, livetemplate, lt

Trigger Patterns

With Context: ✅ Generic prompts related to this skill's purpose

Without Context (needs keywords): ✅ Must mention "lvt", "livetemplate", or "lt" ❌ Generic requests without keywords

Overview

This skill documents the process for creating new lvt command skills. It follows TDD for documentation: RED (understand baseline behavior) → GREEN (write skill) → REFACTOR (close loopholes).

When to use this skill:

• Adding skills for new lvt commands
• Documenting lvt workflows
• Creating comprehensive reference documentation

Result: Production-ready skill that prevents common mistakes and accelerates user workflows.

TDD Methodology for Skills

Apply RED-GREEN-REFACTOR to documentation:

Phase 1: RESEARCH (RED)

1. Identify the Command/Feature

# Example: Creating skill for "lvt seed" command
# Find the implementation
find . -name "*seed*"
# Find: commands/seed.go, internal/seeder/

2. Read Core Implementation

Read in this order:

1. Command file - CLI structure, flags, validation
2. Implementation files - Business logic, core functionality
3. Related files - Dependencies, helpers, generators
4. Tests - Usage patterns, edge cases

Example research for lvt seed:

Read files:
1. commands/seed.go           ← Command structure
2. internal/seeder/seeder.go  ← Core seeding logic
3. internal/seeder/generator.go ← Data generation

3. Document Baseline Mistakes

Ask yourself: "Without a skill, what would users struggle with?"

Common baseline mistakes:

• Missing prerequisites (migrations not run)
• Wrong command syntax
• Incorrect flag usage
• Not understanding error messages
• Skipping important steps
• Misunderstanding command behavior

Example for lvt seed:

• ❌ Forgetting to run migrations before seeding
• ❌ Using wrong resource name (typo)
• ❌ Not knowing about --cleanup flag
• ❌ Confusion about test record markers

Phase 2: WRITE SKILL (GREEN)

Skill File Structure

File naming:

• Location: ~/.claude/skills/lvt/[category]/[command-name].md
• Category: core/, workflows/, advanced/, meta/
• Name: Kebab-case matching command (e.g., add-resource.md, seed-data.md)

Frontmatter:

---
name: lvt-command-name       # Must match: lvt-[command]
description: One-line description of when to use this skill - covers [topics]
---

# lvt:command-name

One-sentence summary.

## Overview
- What the command does
- Key features (3-5 bullets)
- When to use it

## Prerequisites
What must be true before using this command

## Basic Usage
Simplest examples that work

## Commands/Sections
Detailed command reference

## Common Issues
❌ Error scenarios with fixes

## Examples
Real-world usage patterns

## Quick Reference
Table: "I want to..." → Command

## Remember
✓ Do's
✗ Don'ts

Writing Guidelines

1. Start with simplest example:

## Basic Usage

```bash
# Generate 50 products
lvt seed products --count 50

**2. Add prerequisites explicitly:**
```markdown
**Before seeding:**
1. ✓ Resource generated (`lvt gen resource`)
2. ✓ Migrations applied (`lvt migration up`)
3. ✓ Database exists (`app.db`)

3. Show command output:

**Progress tracking:**

Seeding products with 50 rows... Progress: 10/50 Progress: 20/50 ✅ Successfully seeded 50 rows

4. Document errors with context:

### ❌ Resource Not Found

```bash
# Error: resource 'product' not found in schema

# Cause: Typo or not generated yet

# Fix: Check spelling
lvt seed products --count 50  # not 'product'

**5. Add "why wrong" explanations:**
```markdown
**Why wrong:** SQLite requires CGO. Without it, database operations fail.

Skill Template

Save this template for new skills:

---
name: lvt-COMMAND
description: Use when [doing X] - covers [key topics]
---

# lvt:COMMAND

[One sentence description]

## Overview

[2-3 sentences explaining what this command does]

**Key features:**
- [Feature 1]
- [Feature 2]
- [Feature 3]

## Prerequisites

**Before using this command:**
1. ✓ [Prerequisite 1]
2. ✓ [Prerequisite 2]

## Basic Usage

```bash
# Simplest example
lvt COMMAND [args]

Commands Reference

Common Scenarios

[Scenario 1]

# [Description]
lvt COMMAND [example]

Common Issues

❌ [Error Name]

# Error: [error message]

# Cause: [Why this happens]

# Fix:
lvt COMMAND [correct usage]

Why wrong: [Explanation]

Examples

[Use Case 1]

# [Description]
lvt COMMAND [example]

Generated/Output:

• [What happens]

Quick Reference

Remember

✓ [Do this] ✓ [Do that]

✗ Don't [avoid this] ✗ Don't [avoid that]

## Phase 3: TEST SKILL (GREEN)

### Testing Approaches

**Option A: Run actual commands (preferred)**
```bash
# Test the documented workflow
cd /tmp
mkdir test_skill && cd test_skill
lvt new testapp
cd testapp

# Follow skill instructions exactly
lvt gen resource products name price:float
lvt migration up
lvt seed products --count 50

# Verify output matches skill documentation

# IMPORTANT: Clean up test files when done
cd /tmp
rm -rf test_skill

Option B: Code analysis (when bash unavailable)

# Read implementation to verify skill accuracy
cat commands/seed.go
cat internal/seeder/seeder.go

# Check skill against code:
# - Are flags documented correctly?
# - Are error messages accurate?
# - Are examples valid?

Test Checklist

• Basic example works as documented
• Prerequisites are accurate
• Error scenarios produce documented errors
• Command flags are correct
• Examples are realistic and valid
• Output samples match actual output
• Quick reference commands work
• Test files cleaned up after testing

Phase 4: REFACTOR

Finding Loopholes

Common loopholes:

1. Missing context - Assumes knowledge user doesn't have
2. Incomplete error coverage - Missing common errors
3. Vague prerequisites - Not specific enough
4. Missing "why" explanations - Commands without context
5. Unclear defaults - What happens when flags omitted
6. Edge cases - Unusual but valid scenarios

Loophole Checklist

Ask these questions:

• Are all flags/options documented?
• Does it explain WHY, not just WHAT?
• Are error messages copy-pasted from actual output?
• Does it cover edge cases?
• Are examples copy-paste ready?
• Does quick reference match detailed sections?
• Are prerequisites testable?
• Does it link to related skills?

Example Refactoring

Before (loophole):

Run migrations before seeding.

After (closed):

**Before seeding:**
1. ✓ Resource generated (`lvt gen resource`)
2. ✓ Migrations applied (`lvt migration up`)
3. ✓ Database exists (`app.db`)

```bash
# Complete setup before seeding
lvt gen resource products name price:float
lvt migration up
lvt seed products --count 50

## Real Example: Creating lvt:seed-data

**Phase 1: Research**
```bash
# Read implementation
Read commands/seed.go
Read internal/seeder/seeder.go
Read internal/seeder/generator.go

# Identified:
- Context-aware generation based on field names
- --count and --cleanup flags
- Test record markers (test-seed- prefix)
- Progress tracking

Phase 2: Baseline mistakes

Without skill, users would:
❌ Forget to run migrations first
❌ Not know about --cleanup flag
❌ Confusion about resource name vs table name
❌ Not understand context-aware generation
❌ Miss foreign key dependencies

Phase 3: Write skill

Created sections:
1. Basic Usage - Simple examples
2. Prerequisites - Explicit requirements
3. Commands - --count, --cleanup, both
4. Context-Aware Generation - Field name table
5. Common Issues - With fixes
6. Quick Reference - Task → Command

Phase 4: Test

# Would test (bash was unavailable):
lvt new testapp
cd testapp
lvt gen resource products name price:float
lvt migration up
lvt seed products --count 50

Phase 5: Refactor (loopholes found)

1. ❌ Boolean field generation not documented
   ✅ Added enabled/active/is_* pattern

2. ❌ Fallback behavior for unknown fields missing
   ✅ Added fallback explanation

3. ❌ Schema.yaml dependency not explained
   ✅ Clarified seeder reads from schema.yaml

4. ❌ No guidance on choosing record counts
   ✅ Added "Choosing Record Counts" section

Cross-Referencing Skills

Link to related skills:

## Related Skills

- **lvt:new-app** - Create app before adding resources
- **lvt:add-migration** - Custom migrations after resource generation
- **lvt:run-and-test** - Testing your resources

## See Also

For production deployment, see **lvt:deploy** skill.

When to cross-reference:

• Prerequisites: "Complete lvt:new-app first"
• Next steps: "See lvt:deploy for production"
• Alternatives: "For views without database, see lvt:add-view"
• Advanced topics: "For custom queries, see lvt:customize"

Common Patterns

Pattern 1: Prerequisites Section

Always show complete setup:

**Before [command]:**
1. ✓ [Prerequisite with verification command]
2. ✓ [Next prerequisite]

```bash
# Complete setup before [command]
[step 1]
[step 2]
[the command]

### Pattern 2: Error Documentation

Follow this format:
```markdown
### ❌ [Error Name]

```bash
# Error: [exact error message]

# Cause: [Why this happens]

# Fix:
[correct command]

Why wrong: [Technical explanation]

### Pattern 3: Quick Reference

Always include task-oriented table:
```markdown
**I want to...** | **Command**
---|---
[User goal] | `[exact command]`

Pattern 4: Remember Section

Structure as do's and don'ts:

## Remember

✓ [Positive action]
✓ [Positive action]

✗ Don't [avoid this]
✗ Don't [avoid that]

Skill Organization

Directory structure:

~/.claude/skills/lvt/
├── core/              ← Core commands
│   ├── new-app.md
│   ├── add-resource.md
│   ├── add-view.md
│   ├── add-migration.md
│   ├── run-and-test.md
│   ├── customize.md
│   ├── seed-data.md
│   └── deploy.md
├── workflows/         ← Multi-command workflows
│   └── full-crud.md
├── advanced/          ← Advanced topics
│   └── custom-templates.md
└── meta/              ← Skills about skills
    └── add-skill.md   ← This file

Example Session Workflow

Complete skill creation session:

# 1. Research phase
Read implementation files
Document baseline mistakes
Create TodoWrite todos for tracking

# 2. Write phase
Create skill file
Fill in sections following template
Add examples and error scenarios

# 3. Test phase
Run commands to verify accuracy
Check examples work
Verify error messages match

# 4. Refactor phase
Find loopholes
Add missing details
Close gaps
Update Remember section

# 5. Complete
Mark todos complete
Verify skill is comprehensive

TodoWrite pattern:

1. Research [command] and implementation
2. Understand how [feature] works
3. Document baseline mistakes (no skill)
4. GREEN phase: Write skill
5. Test skill with real scenarios
6. REFACTOR: Close loopholes

Quality Checklist

Before marking skill complete:

• File named correctly (~/.claude/skills/lvt/[category]/[name].md)
• Frontmatter has name and description
• Overview explains what/when/why
• Prerequisites are explicit and testable
• Basic usage has simplest working example
• All command flags documented
• Common errors have fixes with "why wrong"
• Examples are realistic and copy-paste ready
• Quick reference table is complete
• Remember section has do's and don'ts
• Cross-references to related skills added
• No assumptions about user knowledge
• Tested with actual commands (or code analysis)
• Test files cleaned up
• Loopholes identified and closed
• TodoWrite todos marked complete

Common Mistakes When Creating Skills

❌ Assuming User Knowledge

# WRONG
Run the seeder.

# CORRECT
**Before seeding:**
1. ✓ Resource generated (`lvt gen resource`)
2. ✓ Migrations applied (`lvt migration up`)

```bash
lvt seed products --count 50

### ❌ Vague Error Messages

```markdown
# WRONG
You might get an error about the database.

# CORRECT
### ❌ Database Not Found

```bash
# Error: database not found

# Cause: Haven't run migrations yet

# Fix: Run migrations first
lvt migration up
lvt seed products --count 50

### ❌ Missing "Why" Explanations

```markdown
# WRONG
Use CGO_ENABLED=1 when building.

# CORRECT
```bash
# Build with CGO enabled
CGO_ENABLED=1 go build ./cmd/myapp

Why: SQLite requires CGO. Without it, database operations fail with "undefined: sqlite3.Open" errors.

### ❌ Incomplete Quick Reference

```markdown
# WRONG
**I want to...** | **Command**
---|---
Seed data | `lvt seed`

# CORRECT
**I want to...** | **Command**
---|---
Generate 50 products | `lvt seed products --count 50`
Remove test data | `lvt seed products --cleanup`
Fresh start | `lvt seed products --cleanup --count 50`

Quick Reference

Remember

✓ Use TDD methodology (RED-GREEN-REFACTOR) ✓ Start with research (read implementation) ✓ Document baseline mistakes first ✓ Use skill template for consistency ✓ Follow naming convention: lvt-[command].md ✓ Test with actual commands when possible ✓ Clean up test files after testing ✓ Close loopholes before marking complete ✓ Add "why wrong" explanations for errors ✓ Make examples copy-paste ready ✓ Cross-reference related skills ✓ Use TodoWrite to track progress

✗ Don't skip research phase ✗ Don't assume user knowledge ✗ Don't write vague error messages ✗ Don't forget prerequisite verification ✗ Don't skip testing phase ✗ Don't leave test files behind ✗ Don't leave loopholes open ✗ Don't forget cross-references to related skills ✗ Don't mark complete without quality checklist