| name | mvp-creator |
| description | Create comprehensive MVP documentation for Rails applications. Use this skill whenever a user describes a new app idea, wants to explore a SaaS concept, needs competitor research, or is starting a new project from scratch — even if they don't explicitly say "MVP". Triggers on "I have an idea for...", "I want to build...", "help me plan...", "research competitors for...", "create a business plan for...", "design a brand for my app", "set up Claude for my Rails project", "bootstrap an app", or any request to plan, research, or document a new application concept. |
MVP Creator
Create comprehensive MVP documentation for Rails applications through guided research and discovery.
Overview
This skill produces 5 deliverables for a new Rails application:
- Research Report — Competitor analysis, market overview, feature comparison
- MVP Business Plan — Vision, features, user flows, success metrics
- Brand Guide — Logo, colors, typography, components, voice
- Technical Guide — Architecture, patterns, data models, code style
- Claude Setup — CLAUDE.md, .mcp.json, commands for Claude Desktop/Code
Workflow
Topic/Idea → Research → Discovery Questions → Generate Deliverables → Handoff to SDD
Phase 1: Research
When user provides a topic or app idea:
- Conduct web search for 2-5 similar apps/competitors
- Research business models, features, pricing
- Identify market gaps and opportunities
- Present findings and ask for feedback before proceeding
Output: Research Report (saved to docs/RESEARCH_REPORT.md)
Phase 2: Discovery Questions
After research is approved, gather project-specific information using the templates in the Discovery Question Templates section below. Do not re-list the questions here — go directly to the templates.
Ask the Core Questions first. Ask Feature Questions after research review. Ask Brand Questions just before generating the Brand Guide.
Phase 3: Generate Deliverables
Generate each deliverable sequentially. Before presenting any deliverable, run its checklist from the Quality Checklist section below. Get approval before moving to the next.
- MVP Business Plan →
docs/MVP_BUSINESS_PLAN.md
- Brand Guide →
docs/BRAND_GUIDE.md (with logo SVGs generated inline — see Logo Generation below)
- Technical Guide →
docs/TECHNICAL_GUIDE.md
- Claude Setup →
CLAUDE.md, .mcp.json, .claudeignore, .claude/commands/
Phase 4: Handoff to SDD
After all deliverables are approved, always suggest:
"Your MVP foundation is ready. The natural next step is to initialize Spec-Driven Development and convert these documents into feature specs, task breakdowns, and implementation prompts for Claude Code. Start with:
'Initialize SDD using the MVP documents we created.'"
Technical Stack (Non-Negotiable)
All projects use this Rails stack. See rails-philosophy.md for the "why".
| Component | Choice | Reference |
|---|
| Framework | Rails 8.x | Vanilla Rails |
| Frontend | Hotwire (Turbo + Stimulus) | No JS frameworks |
| CSS | Tailwind CSS 4 | CSS-first config |
| Components | maquina_components | maquina.app |
| Database | SQLite (dev) / PostgreSQL (prod) | Solid Queue/Cache/Cable |
| Auth | Rails 8 built-in | Not Devise |
| Testing | Minitest + Fixtures | Not RSpec |
| Deployment | Kamal 2 | Docker-based |
Architecture Patterns
- Rich domain models with concerns (no service objects)
- CRUD resources for everything (no custom actions)
- State as records, not booleans
- Money as integer cents
- Turbo Morph by default, Frames sparingly
See rails-implementation-patterns.md for the "how".
Discovery Question Templates
Core Questions (Always Ask First)
I'd like to learn more about your app idea to create comprehensive documentation.
1. **App Name:** Do you have a name in mind? If it has meaning in another language, what does it mean?
2. **Core Problem:** In one sentence, what problem does this app solve?
3. **Target Users:** Who is the primary user? (demographics, behaviors, pain points)
4. **Region:** Any geographic focus? (affects language, payment methods, API availability)
5. **Differentiator:** What makes this different from existing solutions?
Feature Questions (After Research Review)
Based on my research, I have some feature questions:
1. **Main Sections:** What are the primary app sections/tabs?
(e.g., Today, Transactions, Settings)
2. **Critical Flow:** What's the ONE action that must be fast and frictionless?
(This becomes the UX we obsess over)
3. **Data Model:** What are the main things users create/track?
(e.g., transactions, projects, bookings)
Brand Questions (Before Brand Guide)
Before I create the brand guide:
1. **Personality:** How should the app feel?
- Professional / Playful
- Minimal / Bold
- Serious / Friendly
2. **Colors:** Any preferences or brand colors to incorporate?
Or should I propose a palette based on the app's personality?
3. **Logo:** Want me to create SVG logo proposals?
I can generate 2-3 concepts representing the app's core idea.
Logo Generation
Always generate logos yourself, as SVG code written inline in the Brand Guide (rather than delegating to another skill).
- Concept first: Describe the visual metaphor before generating SVG
- Simple shapes: Use basic geometric forms only
- Two versions: Full logo (wordmark + icon) + standalone icon/mark
- Monochrome requirement: Must be legible in a single color
Example approach:
The logo represents [concept]. Using [shape] to symbolize [meaning].
Primary version: [description]
Icon version: [description]
Then generate actual SVG code inline in the brand guide.
Interaction Patterns
Starting a New Project
User: "Help me create an MVP for a personal finance app"
Response:
- Acknowledge the idea
- Conduct web research (2-5 competitors)
- Present research findings
- Ask Core discovery questions
- Generate deliverables sequentially with approval gates
Continuing Previous Work
User: "Let's continue with the brand guide"
Response:
- Summarize what is known so far
- Ask Brand Questions if not yet answered
- Generate the brand guide
- Ask for feedback before moving on
Specific Deliverable Request
User: "Just create a technical guide for my app called Resto"
Response:
- Ask minimum required questions (stack preferences, locale, key features)
- Load technical guide template and Rails references
- Generate the technical guide
- Save to
docs/TECHNICAL_GUIDE.md
Revising a Deliverable
User: "The brand guide doesn't feel right — too corporate"
Response:
- Acknowledge specifically what missed the mark
- Ask 1–2 targeted questions to redirect (e.g., "What aesthetic would feel more right — can you point to an app or brand as reference?")
- Re-generate the deliverable from scratch rather than patching it
- Note explicitly what changed in the new version
Quality Checklist
Run the relevant checklist before presenting each deliverable.
Research Report
MVP Business Plan
Brand Guide
Technical Guide
Claude Setup
Output File Structure
[project_name]/
├── docs/
│ ├── RESEARCH_REPORT.md
│ ├── MVP_BUSINESS_PLAN.md
│ ├── BRAND_GUIDE.md
│ ├── TECHNICAL_GUIDE.md
│ └── assets/
│ ├── logo.svg
│ └── logo-icon.svg
├── CLAUDE.md
├── .mcp.json
├── .claudeignore
└── .claude/
└── commands/
├── test.md
├── db.md
├── analyze.md
├── generate.md
└── guide.md
Tips
- Show, don't tell — ground every deliverable in concrete examples from the user's own domain.
- Bilingual by default — for a LATAM or multilingual audience, show Spanish/English examples throughout.
(The core discipline — research first, ask before assuming, one deliverable at a time with approval — is the Workflow above.)
Related Skills
| Skill | When to Use |
|---|
frontend-design | UI screen mockups and design rationale — after brand guide is approved |
spec-driven-development | Implementation planning — convert MVP docs into specs and tasks |
maquina-ui-standards | When building UI for Rails apps with maquina_components |
