npx skills add ...
npx skills add webflow/webflow-skills --skill cms-best-practices
npx skills add webflow/webflow-skills --skill cms-best-practices
Expert guidance on Webflow CMS architecture and best practices. Use when planning collections, setting up relationships, optimizing content structure, or troubleshooting CMS issues.
Provide expert guidance on Webflow CMS architecture, relationships, optimization, and troubleshooting.
ALWAYS use Webflow MCP tools for all operations:
webflow_guide_tool to get best practices before startingdata_sites_tool with action list_sites to identify available sitesdata_sites_tool with action get_site to retrieve site details and plan limitsdata_cms_tool with action get_collection_list to analyze existing collectionsdata_cms_tool with action get_collection_details to examine collection schemasdata_cms_tool with action list_collection_items to assess content volumedata_pages_tool with action list_pages to understand page structureask_webflow_ai for specific API questionscontext parameter (15-25 words, third-person perspective)data_sites_tool with actions list_sites and get_site to understand plan limitsdata_cms_tool with actions get_collection_list and get_collection_details to examine current setupdata_cms_tool with action list_collection_items to understand scaledata_pages_tool with action list_pages to see how content is displayedUse CMS when:
Use Static when:
Hybrid Approach:
| 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 | Contact emails | Valid email format | |
| Color values | Color | Theme colors, accents, brand colors | Hex format |
| Video embeds | Video | YouTube, Vimeo embeds | Embed URL |
Example: Posts → Author
Display: On post page, access author.name, author.photo, author.bio
Filtering: Can filter posts by specific author
Advantages:
Use cases:
Example: Posts ↔ Tags
Display: On post page, loop through tags to show all tags
Filtering: Can filter posts by specific tag
Advantages:
Limitations:
Workarounds for multiple tag filtering:
Use cases:
Example: Categories with subcategories
Use cases:
Advantages:
Limitations:
Alternative: Use Option field for simple 1-2 level categorization
Example: Related Posts
Display: Show related posts at bottom of post page
Advantages:
Challenges:
Solutions:
User prompt:
Step 1: Requirements Gathering
Step 2: After User Responds
Recipe → Author (one-to-many) ↓ Recipe → Category (one-to-many) ↓ Recipe → Cuisine (one-to-many) ↓ Recipe → Dietary Tags (many-to-many) ↓ Recipe → Cooking Methods (many-to-many)
Recipe Detail Page (/recipes/[slug]):
Benefits:
1. Pagination Strategy
2. Image Optimization
3. Reference Field Strategy
4. Collection List Limits
Automatic (no manual curation):
Ready to implement? I can help you:
Which would you like to start with?
My collection list is slow with 500+ items. How do I optimize?
⚡ CMS Performance Optimization
Analyzing your performance issue with 500+ items...
Problem: Loading 500+ items on a single page Impact:
Root Causes:
Current: Loading all 500+ items Fix: Limit to 12-20 items per page
In Webflow Designer:
Impact: 95% faster page load ✅ Time to implement: 5 minutes Effort: Low
Current: Full-resolution images loading immediately Fix: Use proper image sizes + lazy loading
Implementation:
Impact: 60-70% faster load ✅ Time to implement: 15 minutes Effort: Low
Current: Binding all reference fields Fix: Only display what you actually need
Check your Collection List:
Why: Each reference field = separate database query Impact: 30-40% faster ✅ Time to implement: 10 minutes Effort: Low
Current: Loading all items, then hiding with conditional visibility Fix: Use collection list filters
Example:
Implementation:
Impact: 50% faster + cleaner ✅ Time to implement: 30 minutes Effort: Medium
Alternative to pagination: Smoother UX
Options: a) Webflow native: Pagination with "Load More" styling b) Finsweet: CMS Load plugin (free) c) Custom code: AJAX load more
Benefits:
Impact: Better UX, same performance as pagination ✅ Time to implement: 1-2 hours Effort: Medium
Instead of: One giant "All Posts" page Create: Multiple filtered pages
Example:
Benefits:
Impact: Significant UX improvement ✅ Time to implement: 2-3 hours Effort: Medium
Strategy: Dynamic recent + static archives
Implementation:
When to use:
Impact: Maintains fast performance at scale ✅ Time to implement: 1-2 weeks Effort: High
Problem: Too many reference lookups Solution: Copy frequently-accessed data
Example:
When to use:
Tradeoff: ⚠️ Must update in multiple places if data changes
Impact: 40-50% faster for reference-heavy pages ✅ Time to implement: Varies (requires data migration) Effort: High
Use: Finsweet CMS Filter (free)
Benefits:
Best for:
Limitation: All items loaded initially (use with pagination)
Impact: Instant filtering ✅ Time to implement: 2-4 hours Effort: Medium-High
Before deploying:
Test on staging:
Performance testing:
User testing:
Monitor after launch:
Priority 1 (Do First):
Priority 2 (This Week): 4. Add lazy loading 5. Create filtered views 6. Implement "Load More" option
Priority 3 (If Needed): 7. Finsweet CMS Filter 8. Archive old content 9. Denormalize critical data
Would you like me to walk you through implementing any of these optimizations? I can provide:
Let me know which optimization you'd like to tackle first!
My reference fields aren't showing up on the page. What's wrong?
🔍 Troubleshooting: Reference Fields Not Displaying
Let me help you diagnose and fix this issue.
Symptom: Empty space where data should be Diagnosis: Element exists but has no data binding
Fix:
Example:
Symptom: Some items show data, others don't Diagnosis: Not all collection items have the reference assigned
Fix:
Prevention:
Symptom: Reference field not appearing in dropdown Diagnosis: Element is outside collection list context
Fix:
Symptom: Only showing first item or nothing Diagnosis: Multi-reference needs nested collection list
Fix:
Symptom: Reference field shows nothing despite being assigned Diagnosis: Referenced item was deleted from other collection
Fix:
Prevention:
Symptom: Works in designer, not on live site Diagnosis: Referenced collection items are drafts
Fix:
Check:
Single Reference (Author):
Multi-Reference (Tags):
Self-Reference (Related Posts):
Make critical references required
Provide default content
Test with incomplete data
Document reference structure
Use descriptive field names
| Symptom | Most Likely Cause | Quick Fix |
|---|---|---|
| Nothing shows | Not bound | Bind element to reference field |
| Some items empty | Reference not assigned | Assign reference in CMS |
| Works in designer, not live | Items not published | Publish referenced collection items |
| Only first tag shows | Using text binding on multi-ref | Use nested collection list |
| Shows random data | Wrong collection context | Check collection list nesting |
| Broken after deletion | Referenced item deleted | Re-assign or recreate item |
Would you like me to walk through your specific setup to diagnose the exact issue? I can:
Let me know what you'd like me to check!
Starter Plan:
Basic Plan:
CMS Plan:
Business Plan:
Enterprise Plan:
✅ Good Names:
❌ Bad Names:
Make REQUIRED:
Make OPTIONAL:
Use when:
Examples: ✅ Post → Author (each post has one author) ✅ Product → Brand (each product has one brand) ✅ Event → Venue (each event has one venue)
Don't use when: ❌ Item can have multiple parents (use multi-reference) ❌ Relationship is temporary (consider option field) ❌ Data is simple and rarely changes (use option field instead)
Use when:
Examples: ✅ Post ↔ Tags (posts have many tags, tags apply to many posts) ✅ Product ↔ Features (products have many features, features apply to many products) ✅ Course ↔ Topics (courses cover many topics, topics span many courses)
Remember: ⚠️ Max 5 multi-reference fields per collection ⚠️ Can only filter by ONE multi-reference at a time ⚠️ Cannot sort by referenced field values ⚠️ Performance impact (more queries)
Use when:
Implementation:
Example Structure: Categories: ├── Web Development (level 1, parent: null) │ ├── Frontend (level 2, parent: Web Development) │ └── Backend (level 2, parent: Web Development) └── Design (level 1, parent: null)
Minimal (1 collection):
Standard (3 collections):
Advanced (5+ collections):
Minimal (1 collection):
Standard (4 collections):
Advanced (7+ collections):
Minimal (1 collection):
Standard (3 collections):
Advanced (5+ collections):
Minimal (1 collection):
Standard (4 collections):
Advanced (6+ collections):
Content Volume → Items Per Page:
Usage → Recommended Size:
Format Priority:
Optimization Levels:
Level 1 - Display Only What's Needed: ❌ Binding entire author object: {{author}} ✅ Binding specific fields: {{author.name}}, {{author.photo}}
Level 2 - Denormalize Critical Data: Instead of: Post → Author.name (2 queries) Store: Post.author-name (1 query) When: Performance critical + data rarely changes
Level 3 - Lazy Load Related Content: Show main content immediately Load related items on interaction (click, scroll) Reduces initial page load
Best Practices:
Filter at Collection Level: ✅ Use native collection list filters ❌ Load all items then hide with conditionals
Limit Items: ✅ Set reasonable limit (12-20 items) ❌ Load unlimited items
Optimize Nested Lists: ✅ Limit nested collection lists to 3-5 items ❌ Nest multiple unlimited lists
Use Conditional Loading: ✅ Load content based on viewport ❌ Load everything upfront
Implement Pagination: ✅ Enable Webflow pagination or "Load More" ❌ Infinite scroll with all items
Required Fields:
Recommended: 5. Schema.org structured data (JSON-LD) 6. Open Graph tags (Facebook/LinkedIn) 7. Twitter Card tags 8. Alt text for all images
✅ Good Slugs:
❌ Bad Slugs:
Rules:
Common Types:
Blog Post (Article schema):
Product (Product schema):
Event (Event schema):
Recipe (Recipe schema):
Local Business (LocalBusiness schema):
Create guide for each collection:
Example - Blog Posts Collection:
Name* (required)
Slug* (required)
Post Summary
Featured Image*
Author*
... (document all fields)
Before Publishing: □ Name filled □ Slug set (no generic slugs like "untitled") □ Summary written (compelling, 160 chars) □ Featured image uploaded with alt text □ Author assigned □ Category selected □ Published date set □ Content proofread □ Links tested □ Images optimized □ SEO reviewed
Create as Draft:
Complete Content:
Internal Review:
Publish:
Ongoing:
Audit Current Structure:
Design New Structure:
Validate Approach:
Pros: ✅ No downtime ✅ Easy rollback ✅ Test before fully committing
Cons: ❌ Temporarily doubled content ❌ Longer timeline ❌ Must manage both systems temporarily
Pros: ✅ Faster completion ✅ Clean cutover ✅ No duplicate content
Cons: ❌ Higher risk ❌ Potential downtime ❌ Harder to rollback
Pros: ✅ Balanced risk/speed ✅ Can catch issues early ✅ Incremental testing
Cons: ❌ Requires careful planning ❌ More complex execution
Possible causes:
Diagnosis:
Fix:
Possible causes:
Fix:
Possible causes:
Diagnosis:
Fix:
Possible causes:
Fix:
Cause: Wrong display method
Fix: Must use nested collection list: ❌ Direct text binding ✅ Collection List > Get items from [field] > Collection Item > Display
Example: <Collection List - Posts> <Collection Item - Post> Tags: <Collection List - Get items from Post > tags> <Collection Item - Tag> {{tag.name}} </Collection Item> </Collection List> </Collection Item> </Collection List>
Use Case: Show different layouts based on category
Implementation:
Limitation: Can only check one value at a time Alternative: Use option field with class name, apply class dynamically
Implementation:
Benefits:
Limitation: Items exist but filtered, not truly unpublished
Option 1: Manual Sort Order
Option 2: Auto Sort by Engagement
Option 3: Date-Based Sorting
Approach 1: Separate Collections per Language
Pros: Simple, native Webflow Cons: Must duplicate structure, harder to maintain
Approach 2: Language Field + Filter
Pros: Single structure, easier to maintain Cons: All content in one collection
Approach 3: Webflow Localization (CMS Plan+)
Pros: Official solution, best SEO Cons: Requires CMS plan+, setup complexity
Option 1: Native (Limited)
Option 2: Finsweet CMS Filter (Free)
Option 3: Algolia/Custom (Advanced)
Recommendation:
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 authorTags Collection:
├── name (Text, required)
├── slug (Text, required)
├── description (Plain Text)
└── color (Color) - optional visual grouping
Posts Collection:
├── title (Text, required)
├── slug (Text, required)
├── content (Rich Text)
└── tags (Multi-Reference → Tags) ← Each post has MANY tagsCategories Collection:
├── name (Text, required)
├── slug (Text, required)
├── description (Plain Text)
├── parent (Reference → Categories) ← Self-reference for hierarchy
└── level (Number) - 1, 2, 3 for display logicPosts Collection:
├── title (Text, required)
├── slug (Text, required)
├── content (Rich Text)
└── related-posts (Multi-Reference → Posts) ← Self-reference to other postsI'm building a recipe site. How should I structure the CMS?📐 CMS Planning: Recipe Site
Let me ask a few questions to design the best structure:
1. **Content Volume**: How many recipes do you plan to have?
- Small (≤50): Simple structure
- Medium (50-200): Moderate organization
- Large (200+): Advanced taxonomy needed
2. **Recipe Attributes**: What information will each recipe have?
- Basic: Name, ingredients, instructions, image
- Advanced: Prep time, cook time, difficulty, nutrition, dietary tags
3. **Organization Needs**: How will users find recipes?
- By meal type (breakfast, lunch, dinner)
- By cuisine (Italian, Mexican, Asian)
- By dietary restrictions (vegan, gluten-free, keto)
- By cooking method (baking, grilling, slow cooker)
- By ingredients (chicken, pasta, vegetables)
4. **Author Setup**: Single or multiple authors?
- Single: You manage all content
- Multiple: Team of recipe creators
5. **User Engagement**: What interactive features?
- Comments/reviews
- Ratings
- Save favorites
- Print recipe cards
Based on your answers, I'll design the optimal CMS architecture.📐 Recommended CMS Architecture: Recipe Site
Based on your requirements (Medium volume, Multiple authors, Advanced filtering):
---
## Collections Needed: 4
### 1. Recipes (Main Content)
├── name (Text, required) - "Homemade Pasta Carbonara"
├── slug (Text, required) - "homemade-pasta-carbonara"
├── description (Plain Text, 160 chars) - Brief summary for SEO
├── featured-image (Image) - Hero image for detail page
├── thumbnail-image (Image) - Smaller image for grid cards
├── prep-time (Number, required) - Minutes of prep
├── cook-time (Number, required) - Minutes of cooking
├── total-time (Number) - Auto-calculated or manual
├── servings (Number, required) - Number of servings
├── difficulty (Option: Easy, Medium, Hard)
├── ingredients (Rich Text, required) - Ingredient list with quantities
├── instructions (Rich Text, required) - Step-by-step directions
├── notes (Rich Text) - Cook's notes, tips, substitutions
├── nutrition-info (Plain Text) - Calories, protein, etc.
├── author (Reference → Authors, required)
├── category (Reference → Categories, required) - Primary meal type
├── cuisine (Reference → Cuisines) - Italian, Mexican, etc.
├── dietary-tags (Multi-Reference → Dietary Tags) - Vegan, GF, etc.
├── cooking-methods (Multi-Reference → Methods) - Baking, Grilling, etc.
├── featured (Switch) - Highlight on homepage
├── published-date (Date, required)
└── view-count (Number) - Track popularity
**Total fields:** 22 fields
**Plan required:** CMS plan minimum (20 collections, 2000 items)
### 2. Authors
├── name (Text, required)
├── slug (Text, required)
├── title (Text) - "Head Chef", "Recipe Developer"
├── bio (Rich Text)
├── photo (Image)
├── specialty (Plain Text) - "Italian Cuisine", "Baking"
├── social-instagram (Link)
├── social-website (Link)
└── email (Email)
**Purpose:** Reusable author information across all recipes
### 3. Categories
├── name (Text, required) - "Breakfast", "Lunch", "Dinner", "Desserts"
├── slug (Text, required)
├── description (Plain Text)
├── image (Image) - Category hero image
├── color (Color) - Brand color for UI
└── sort-order (Number) - Control display order
**Purpose:** Primary meal type classification
**Suggested Categories (8):**
- Breakfast & Brunch
- Appetizers & Snacks
- Lunch
- Dinner & Main Courses
- Side Dishes
- Salads
- Desserts & Sweets
- Drinks & Beverages
### 4. Cuisines
├── name (Text, required) - "Italian", "Mexican", "Asian"
├── slug (Text, required)
├── description (Plain Text)
└── flag-icon (Image) - Optional visual
**Purpose:** Filter by cuisine type
**Suggested Cuisines (12):**
- American, Italian, Mexican, Asian, Mediterranean, French, Indian, Thai,
Chinese, Japanese, Greek, Middle Eastern
### 5. Dietary Tags
├── name (Text, required) - "Vegan", "Gluten-Free", "Keto"
├── slug (Text, required)
├── description (Plain Text)
├── icon (Image) - Badge icon
└── color (Color) - Badge color
**Purpose:** Multi-select dietary filters
**Suggested Tags (10):**
- Vegetarian, Vegan, Gluten-Free, Dairy-Free, Keto, Paleo, Low-Carb,
High-Protein, Nut-Free, Pescatarian
### 6. Cooking Methods
├── name (Text, required) - "Baking", "Grilling", "Slow Cooker"
├── slug (Text, required)
└── description (Plain Text)
**Purpose:** Filter by cooking technique
**Suggested Methods (8):**
- Baking, Grilling, Slow Cooker, Instant Pot, Stovetop, No-Cook,
Air Fryer, Sous Vide
---
## Relationship Map
**Multi-reference count:** 2 fields (within 5-field limit ✅)
---
## Recommended Page Structure
### 1. Homepage (/)
- Hero section with featured recipe
- Category cards (8 categories)
- Latest recipes (collection list, 6 items)
- Popular recipes (sorted by view-count)
- Call-to-action
### 2. Recipes Index (/recipes)
- Collection list showing all recipes
- Filter sidebar:
- Category (tabs or dropdown)
- Cuisine (multi-select)
- Dietary tags (checkboxes)
- Cooking time (< 30 min, 30-60 min, 60+ min)
- Difficulty (easy, medium, hard)
- Pagination (12 recipes per page)
- Search bar (Finsweet CMS Filter)
### 3. Recipe Detail (/recipes/[slug])
- Hero image + title
- Prep/cook/total time + servings
- Difficulty badge + dietary badges
- Ingredients list
- Step-by-step instructions
- Author card with bio
- Related recipes (same category or tags)
- Print button
### 4. Category Pages (/category/[slug])
- Category hero image + description
- Filtered recipes by category
- Breadcrumbs: Home > Recipes > [Category]
- Related categories
### 5. Cuisine Pages (/cuisine/[slug])
- Cuisine description + flag
- Filtered recipes by cuisine
- Popular cuisines sidebar
### 6. Author Profiles (/authors/[slug])
- Author photo + bio
- Author's recipes (collection list)
- Social links
- Author stats (total recipes, join date)
### 7. Dietary Filter Pages (/diet/[slug])
- Dietary tag description
- Filtered recipes by tag
- Related dietary tags
---
## SEO Optimization
### Collection Template SEO