webflow-mcp:cms-best-practices

What this skill does

# CMS Best Practices

Provide expert guidance on Webflow CMS architecture, relationships, optimization, and troubleshooting.

## Important Note

**ALWAYS use Webflow MCP tools for all operations:**
- Use Webflow MCP's `webflow_guide_tool` to get best practices before starting
- Use Webflow MCP's `data_sites_tool` with action `list_sites` to identify available sites
- Use Webflow MCP's `data_sites_tool` with action `get_site` to retrieve site details and plan limits
- Use Webflow MCP's `data_cms_tool` with action `get_collection_list` to analyze existing collections
- Use Webflow MCP's `data_cms_tool` with action `get_collection_details` to examine collection schemas
- Use Webflow MCP's `data_cms_tool` with action `list_collection_items` to assess content volume
- Use Webflow MCP's `data_pages_tool` with action `list_pages` to understand page structure
- Use Webflow MCP's `ask_webflow_ai` for specific API questions
- DO NOT use any other tools or methods for Webflow operations
- All tool calls must include the required `context` parameter (15-25 words, third-person perspective)

## Instructions

### Phase 1: Discovery & Analysis
1. **Identify the request**: Determine if user is:
   - Planning new CMS structure
   - Optimizing existing collections
   - Troubleshooting performance issues
   - Setting up relationships
   - Seeking architecture guidance
2. **Get site information**: Use Webflow MCP's `data_sites_tool` with actions `list_sites` and `get_site` to understand plan limits
3. **Analyze existing structure**: Use Webflow MCP's `data_cms_tool` with actions `get_collection_list` and `get_collection_details` to examine current setup
4. **Assess content volume**: Use Webflow MCP's `data_cms_tool` with action `list_collection_items` to understand scale
5. **Review pages**: Use Webflow MCP's `data_pages_tool` with action `list_pages` to see how content is displayed

### Phase 2: Requirements Gathering
6. **Understand use case**: Ask clarifying questions:
   - What content needs to be managed?
   - Who will update the content?
   - How will content be displayed?
   - What relationships are needed?
   - Expected content volume?
7. **Identify constraints**: Consider plan limits, technical constraints, team skills
8. **Define success criteria**: Performance goals, editorial workflow, scalability needs

### Phase 3: Architecture Planning
9. **Design collection structure**: Plan collections, fields, and relationships
10. **Select field types**: Choose appropriate field types for each content element
11. **Plan relationships**: Design one-to-many and many-to-many connections
12. **Consider taxonomy**: Determine categories, tags, and organizational structure
13. **Plan for scale**: Design for growth (pagination, performance, limits)
14. **Document decisions**: Explain tradeoffs and reasoning

### Phase 4: Recommendations & Validation
15. **Generate recommendations**: Provide specific, actionable guidance
16. **Prioritize changes**: Organize by impact (quick wins vs. long-term)
17. **Explain tradeoffs**: Help users understand limitations and workarounds
18. **Validate against best practices**: Check against Webflow limitations and patterns
19. **Provide alternatives**: Offer multiple approaches when applicable
20. **Create implementation roadmap**: Break down into phases

### Phase 5: Implementation Guidance
21. **Provide step-by-step instructions**: Clear guidance for implementation
22. **Offer to assist**: Suggest using other skills (cms-collection-setup, bulk-cms-update)
23. **Document structure**: Recommend documentation for team reference
24. **Suggest testing approach**: Guide on how to validate changes
25. **Plan for migration**: If refactoring, provide migration strategy

## Collection Architecture

### When to Use CMS vs Static

**Use CMS when:**
- Content updates frequently (weekly or more)
- Multiple similar items (blog posts, products, team members, projects)
- Non-technical users need to edit content
- Content needs filtering/sorting on the frontend
- Same content appears on multiple pages (author bios, product features)
- Content follows a consistent structure across items
- You need to dynamically generate pages

**Use Static when:**
- Content rarely changes (annual updates or less)
- Unique one-off sections (about page hero, homepage special features)
- Complex custom layouts per item that don't follow patterns
- No need for dynamic filtering or search
- Content is highly customized and doesn't share structure
- Performance is critical and content doesn't change
- You need complete design flexibility per section

**Hybrid Approach:**
- Static pages with CMS-driven sections (e.g., static homepage with CMS testimonials)
- CMS for recent content, static archives for old content
- Static landing pages, CMS for subpages

### Field Type Selection

| Content Type | Recommended Field | Notes | Character Limits |
|--------------|-------------------|-------|------------------|
| Short text | Plain Text | Titles, names, slugs | Max 256 chars |
| Long text (no formatting) | Plain Text (long) | Descriptions, excerpts | Unlimited |
| Formatted content | Rich Text | Blog content, bios, articles | Unlimited |
| Single image | Image | Photos, thumbnails, headers | 4MB max per image |
| Multiple images | Multi-image | Galleries, product photos | Up to 25 images |
| File downloads | File | PDFs, documents, downloads | 4MB max per file |
| Yes/No values | Switch | Featured flags, visibility toggles | Boolean |
| Single choice | Option | Status, type, category | Unlimited options |
| Date/time | Date/Time | Publish dates, events, deadlines | ISO 8601 format |
| Link to one item | Reference | Author → Post, Category → Post | One item |
| Link to multiple items | Multi-reference | Post → Tags, Post → Related Posts | Multiple items |
| External URL | Link | Social links, external resources | Max 2048 chars |
| Numeric values | Number | Prices, ratings, order, counts | Integer or decimal |
| Phone numbers | Phone | Contact numbers | E.164 format |
| Email addresses | Email | Contact emails | Valid email format |
| Color values | Color | Theme colors, accents, brand colors | Hex format |
| Video embeds | Video | YouTube, Vimeo embeds | Embed URL |

### Field Type Decision Tree

```
Need to store:
├── Text?
│   ├── Short (≤256 chars)? → Plain Text
│   ├── Long + Formatting? → Rich Text
│   └── Long + No Formatting? → Plain Text (long)
├── Media?
│   ├── Single image? → Image
│   ├── Multiple images? → Multi-image
│   ├── Video? → Video
│   └── File download? → File
├── Choice/Selection?
│   ├── Yes/No? → Switch
│   ├── One option? → Option
│   └── Link to item? → Reference/Multi-reference
├── Structured data?
│   ├── Number? → Number
│   ├── Date/Time? → Date/Time
│   ├── Phone? → Phone
│   ├── Email? → Email
│   └── URL? → Link
└── Visual?
    └── Color? → Color
```

## Relationship Patterns

### One-to-Many (Reference Field)

**Example:** Posts → Author
```
Authors Collection:
├── name (Text, required)
├── slug (Text, required)
├── bio (Rich Text)
├── photo (Image)
├── title (Text) - job title
├── email (Email)
└── social-links (Link)

Posts Collection:
├── title (Text, required)
├── slug (Text, required)
├── content (Rich Text)
└── author (Reference → Authors)  ← Each post has ONE author
```

**Display:** On post page, access `author.name`, `author.photo`, `author.bio`

**Filtering:** Can filter posts by specific author

**Advantages:**
- ✅ Centralized author data (update once, reflects everywhere)
- ✅ Easy to maintain consistency
- ✅ Can create author profile pages showing all their posts
- ✅ Efficient (one reference per post)

**Use cases:**
- Blog posts → Author
- Products → Brand
- Events → Venue
- Projects → Client
- Testimonials → Customer

### Many-to-Many (Multi-Reference)

**Example:** Posts ↔ Tags
```
Tags Collection:
├── name (Text, required)
├── slug (Text, required)
├── description (Plain Text)
└── color (Color) - optional visual grouping

Posts Collecti