Miro Spec Extraction Guide

What is miro-spec?

The miro-spec plugin extracts specification content from Miro boards and saves it to local files. This enables AI to reference specs during planning and implementation without requiring repeated API calls.

When to Use miro-spec

Use miro-spec when you need to:

Extract product requirements from Miro boards
Save design specifications for implementation
Download prototypes and diagrams for reference
Create local copies of documentation from Miro
Work with specs offline or in version control

Command: /miro-spec:get

Extract specs from a Miro board or item:

/miro-spec:get [url]

URL Types

Board URLs - Extract all spec items:

https://miro.com/app/board/uXjVK123abc=/

Item URLs - Extract single item:

https://miro.com/app/board/uXjVK123abc=/?moveToWidget=3458764612345

Understanding .miro/specs/ Directory

Directory Structure

.miro/specs/
├── documents/      # Miro documents (Markdown format)
├── diagrams/       # Diagram descriptions (Markdown)
├── prototypes/     # Prototype containers (Markdown) and screens (HTML)
├── tables/         # Table data (JSON)
├── frames/         # Frame summaries (Markdown)
├── other/          # Unknown types like slides (Markdown)
├── images/         # Downloaded images (PNG)
└── index.json      # Metadata index

Content Types

Documents (.md)

Markdown content with formatting
Preserved headings and structure
Clean text format

Diagrams (.md)

AI-generated description of diagram
Flow analysis and component relationships
Key elements and connections

Prototypes (.md / .html)

Containers: Markdown with navigation map (.md, suffix -container)
Screens: HTML markup with UI layout (.html, suffix -screen)
UI component structure

Tables (.json)

Structured data with column definitions
All rows and cell values
Column types and metadata

Frames (.md)

AI-generated summary of frame contents
Overview of contained items
Organizational structure

Images (.png)

Automatically extracted from prototypes
Referenced by relative paths in prototype screens
Named by Miro item ID

Extraction Workflow

1. Run Extraction Command

/miro-spec:get https://miro.com/app/board/uXjVK-spec=/

2. Handle Existing Content

If .miro/specs/ already has files, choose:

Clean and extract fresh - Start over
Add to existing - Keep current files
Cancel - Abort

3. Review Extraction Summary

Output shows:

Extracted 5 documents, 3 diagrams, 2 prototypes, 1 table
Downloaded 12 images
Saved to .miro/specs/

4. Check Metadata Index

Open .miro/specs/index.json to see:

All extracted items with types
File paths for each item
Original Miro URLs
Extraction timestamp

Board URLs vs Item URLs

Board URLs

When to use:

Extract complete specifications
Get all related documents and diagrams
Comprehensive spec extraction

What it does:

Lists all items on the board
Filters for spec-related types
Extracts each item individually

Example:

/miro-spec:get https://miro.com/app/board/uXjVK123abc=/

Item URLs

When to use:

Extract single document or diagram
Get specific prototype screen
Targeted extraction

What it does:

Extracts only the specified item
Faster for single items
Uses moveToWidget parameter

Example:

/miro-spec:get https://miro.com/app/board/uXjVK123abc=/?moveToWidget=3458764612345

How Images Are Extracted

Automatic Image Discovery

Plugin scans prototype screen HTML content
Finds Miro image URLs in src attributes
Extracts board_id and item_id from URLs
Downloads each image using Miro MCP

URL Replacement

Original HTML:

<img src="https://miro.com/api/v2/boards/uXjVK123abc=/images/3458764612345"/>

After extraction:

<img src="../images/3458764612345.png"/>

Benefits

Images work offline
No API calls to view documents
Faster loading from local files
Can be committed to version control

Using Specs for Implementation Planning

Workflow Example

Extract specs:

/miro-spec:get https://miro.com/app/board/uXjVK-product-spec=/

Review what was extracted: Check .miro/specs/index.json to see available specs
Ask AI to plan implementation: "Based on the specs in .miro/specs/, create an implementation plan for the user authentication feature"
AI reads relevant files: AI automatically reads documents, diagrams, and tables during planning
Implement with context: AI uses spec content to guide code generation

Example AI Prompts

Planning with specs:

"Review the product requirements in .miro/specs/documents/ and create a technical implementation plan"

Using specific diagrams:

"Reference the architecture diagram in .miro/specs/diagrams/3458764612345.md and implement the database schema"

Validating implementation:

"Compare the authentication flow I implemented against the spec in .miro/specs/prototypes/3458764612346.html"

Best Practices

Extraction Strategy

Use board URLs for initial comprehensive extraction
Use item URLs for updating specific documents
Extract before starting implementation
Re-extract when specs change

Directory Management

Keep .miro/specs/ in .gitignore if specs are temporary
Commit to version control if specs should be shared
Clean extraction when board structure changes significantly
Add to existing when updating individual items

Working with Specs

Always check index.json first to understand what's available
Read HTML files directly for full document content
Use markdown files for quick diagram overviews
Parse JSON files for structured table data

Performance Tips

Extract from specific frames using item URLs if board is large
Clean old extractions to avoid confusion
Use board URLs sparingly (can be slow for large boards)
Cache extractions between implementation sessions

Common Workflows

Extract Product Requirements

# Extract all PRD documents
/miro-spec:get https://miro.com/app/board/uXjVK-prd=/

# Review extracted docs
cat .miro/specs/index.json | grep documents

# Plan implementation
"Plan implementation based on requirements in .miro/specs/"

Update Single Specification

# Extract updated design doc
/miro-spec:get https://miro.com/app/board/uXjVK=/.../?moveToWidget=3458764612345

# Choose "Add to existing" when prompted
# Review changes in .miro/specs/documents/3458764612345.html

Extract Architecture Diagrams

# Extract board with diagrams
/miro-spec:get https://miro.com/app/board/uXjVK-architecture=/

# Check diagram summaries
ls .miro/specs/diagrams/
cat .miro/specs/diagrams/*.md

Troubleshooting

No items extracted from board:

Board may not contain document/frame/table items
Try using item URL for specific content
Check if board URL is correct

Images not downloading:

Some images may not be accessible via MCP
Original URLs preserved if download fails
Documents still readable with external image URLs

Files not found after extraction:

Check .miro/specs/index.json for actual paths
Verify extraction completed successfully
Look for error messages in extraction output

Large boards taking too long:

Use item URLs to extract specific content
Extract individual frames instead of entire board
Consider filtering by content type

miro-spec-guide