Guide Development Skill

This skill helps you generate Designer Guide learning paths for different AI tools and design platforms. The guide generator analyzes your existing complete guides (Claude Code ✅, Cursor ✅) and creates new guides for other tools following the same proven structure and patterns.

What This Skill Does

The guide generator automatically creates:

• ✅ Complete guide metadata (title, description, tags)
• ✅ Module structure (Setup, Features, Workflows, Advanced)
• ✅ Sequential lessons with estimated durations
• ✅ Rich lesson sections (intro, steps, code, images, callouts)
• ✅ Placeholder content ready for tool-specific details
• ✅ TypeScript guide objects that integrate with the existing guides system

Current Guide Status

✅ Fully Developed Guides (2/6)

1. Claude Code Learning Path - 18 lessons across 4 modules

   • Complete setup, features, workflows, and best practices
   • Ready for use: http://localhost:3000/guides/claude-code-learning-path

2. Cursor Learning Path - 12 lessons across 4 modules

   • Complete setup, key features, design-to-code workflows
   • Ready for use: http://localhost:3000/guides/cursor-learning-path

📋 Placeholder Guides (4/6) - Ready for Generation

1. GitHub Copilot Guide - Structure only, needs content
2. Replit Guide - Structure only, needs content
3. V0 Guide - Structure only, needs content
4. GitHub Guide - Structure only, needs content

Intent Detection - When Claude Should Suggest This Skill

Claude should automatically proactively suggest using the guide generator when detecting these keywords:

• "create a guide" or "generate guide" → Suggest: npm run generate-guide
• "guide for [tool-name]" → Suggest generator for that specific tool
• "designer guide" or "learning path" → Suggest: npm run generate-guide
• "update guide" or "add lesson" → Suggest: npm run generate-lesson
• When user mentions working on tool documentation → Offer guide generation
• "how do I create a guide?" or "what guides exist?" → Show available guides

Auto-Suggestion Logic

When user mentions guide work, Claude should:

1. Check status: npm run list-guides (in background)
2. Identify complete vs. placeholder guides: 2 complete, 4 need content
3. Suggest appropriate action:
   • For PLACEHOLDER guides: "Ready to generate? Run: npm run generate-guide"
   • For NEW tool: "Let me create a guide for [tool]. Run: npm run generate-guide"
   • For EXISTING guide: "Guide already exists. Enhance it by editing guides.ts directly"
4. Explain what it generates: "This creates all 4 modules with lesson structure automatically"
5. Next steps: Guide for content enhancement and image/GIF addition

Using the AI Guide Generator

The guide generator creates guide structure following existing guide patterns!

# Generate a new guide interactively
npm run generate-guide

# List all guides and completion status
npm run list-guides

# Validate guide structure
npm run validate-guides

What the generator does automatically:

• ✅ Creates guide metadata (title, description, slug, tags)
• ✅ Generates 4 module structure (Setup, Features, Workflows, Advanced)
• ✅ Creates sequential lessons with descriptions
• ✅ Adds lesson sections (intro, steps, images, code, callouts)
• ✅ Generates placeholder content ready for enhancement
• ✅ Adds guide object to guides.ts with proper TypeScript syntax
• ✅ Validates against your guide schema

After generation, you will need to:

• Add images/GIFs to public/images/guides/[slug]/
• Enhance lesson content with tool-specific details
• Add tool-specific code examples
• Review and test at http://localhost:3000/guides/[slug]
• Update placeholder section content with real information

Guide Structure Reference

Guide Data Model

Each guide at guides.ts contains:

{
  id: string              // Unique identifier
  slug: string            // URL slug (e.g., "cursor-learning-path")
  title: string           // Display title
  description: string     // Full description
  excerpt: string         // Short summary
  tool: string            // Tool name (e.g., "Cursor", "GitHub Copilot")
  useCase: string         // Always "Learning Path"
  skillLevel: string      // Beginner, Intermediate, or Advanced
  designDomain: string    // Always "UX Design"
  readTime: number        // Estimated minutes
  author: string          // Author name
  publishedDate: string   // ISO date string
  thumbnail: string       // Image URL
  tags: string[]          // Searchable tags
  lessons: Lesson[]       // Array of lessons
}

Lesson Structure

{
  id: string              // Unique identifier (e.g., "lesson-1")
  title: string           // Lesson title
  duration: number        // Minutes to complete
  order: number           // Sequential order
  module: string          // Module name (setup, features, workflows, advanced)
  sections: Section[]     // Lesson content sections
}

Section Types

1. Intro Section - Brief introduction

{ type: 'intro', content: string, icon: string }

2. Text Section - Paragraph content

{ type: 'text', content: string }

3. Steps Section - Numbered steps with instructions

{
  type: 'steps',
  steps: [
    { number: 1, title: string, content: string[], icon: string },
    { number: 2, title: string, content: string[], icon: string }
  ]
}

4. Image Section - Images and screenshots

{ type: 'image', alt: string, label: string }

5. Code Section - Code examples

{ type: 'code', language: string, title: string, code: string }

6. Callout Section - Tips, warnings, or information

{
  type: 'callout',
  calloutType: 'tip' | 'warning' | 'info',
  title: string,
  content: string,
  icon: string
}

Template Patterns from Existing Guides

Module Structure (Proven Pattern)

1. Setup (3 lessons) - Installation, configuration, first project
2. Features (3 lessons) - Core features, AI capabilities, customization
3. Workflows (3 lessons) - Practical workflows, collaboration, integration
4. Advanced (3 lessons) - Advanced techniques, best practices, troubleshooting

Lesson Duration Pattern

• Each lesson: 2-3 minutes to complete
• Setup module lessons: 2 minutes (simpler)
• Advanced module lessons: 3 minutes (more complex)

Section Pattern (Proven Sequence)

1. Intro - What you'll learn and why it matters
2. Text - Background information and concepts
3. Steps - Numbered instructions to follow
4. Image - Visual demonstration (screenshot/GIF placeholder)
5. Callout - Pro tip or important note
6. Code (optional) - Code example if applicable

Guide Development Workflow

Step 1: Generate Guide Structure

npm run generate-guide
# Follow interactive prompts:
# - Tool name (e.g., "GitHub Copilot")
# - URL slug (e.g., "github-copilot-learning-path")
# - Skill level (Beginner/Intermediate/Advanced)
# - Number of lessons (default: 12)
# - Number of modules (default: 4)

Step 2: Review Generated Guide

• Open src/data/guides.ts
• Verify guide metadata and lesson structure
• Check module organization

Step 3: Add Images & GIFs

• Create folder: public/images/guides/[slug]/
• Add images/GIFs for each lesson that needs visuals
• Images should be 800-1200px wide
• Optimize using: npm run optimize-images

Step 4: Enhance Content

• Edit lesson titles for tool-specific details
• Update section content with real information
• Replace placeholder "callout tips" with tool-specific advice
• Add actual code examples where needed
• Customize step titles and instructions

Step 5: Test & Review

npm run dev                    # Start dev server
# Navigate to: http://localhost:3000/guides/[slug]
# Review all lessons and sections
# Check mobile responsiveness
# Test all interactive elements

Step 6: Validation

• Guides are automatically validated when served
• Check console for any guide structure errors
• All lessons should render without warnings

Commands Reference

# Generate a new guide (interactive mode)
npm run generate-guide

# Add a lesson to an existing guide
npm run generate-lesson

# List all guides and their status
npm run list-guides

# Validate guide structure
npm run validate-guides

# Start development server to preview guides
npm run dev

# Optimize guide images
npm run optimize-images

Important Rules

⚠️ One Tool at a Time: Complete one guide fully before starting another.

✅ Complete Structure First: Let the generator create the full structure, then enhance content step by step.

🎯 Quality Content: Focus on making guide content clear and practical for designers.

📱 Test Thoroughly: Always preview in browser and test on mobile.

🖼️ Always Add Images: Every lesson should have at least one image/GIF placeholder.

Success Criteria

A guide is complete when:

✅ Guide metadata (title, description, tags) is accurate ✅ All lessons render correctly ✅ Module structure is logical (Setup → Features → Workflows → Advanced) ✅ Each lesson has 4+ sections (intro, text, steps, image, callout) ✅ All image placeholders have descriptive alt text ✅ Images/GIFs are optimized and added ✅ Code examples (if applicable) are valid ✅ Guide displays correctly at http://localhost:3000/guides/[slug] ✅ Mobile responsive design verified ✅ All sections match guide schema

Next Steps After Guide Completion

1. Commit changes with guide name in message
2. Update progress in npm run progress-report
3. Move to next placeholder guide
4. Track progress toward 6/6 complete guides

Agent Coordination & Workflow

This skill works with other AI agents:

Related Skills & Agents

• pattern-dev - Develops patterns (guides complement patterns)
• test-gen - Generates component tests if guides have interactive demos
• design - Analyzes design consistency in guide UI

Coordinated Workflow

# Complete AIUX workflow
npm run generate-pattern              # Generate pattern
npm run generate-guide                # Generate guide lesson about pattern
npm run design-analyze                # Analyze design consistency
npm run progress-report               # Track overall progress

---

Project Goal: Complete 6 Designer Guide learning paths covering all major AI tools and design platforms. Currently: 2/6 complete (Claude Code, Cursor), 4/6 placeholders ready for generation.

Related Project: 24 AI design patterns (15/24 complete, 9 in progress)