OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
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.
npx skills add webflow/webflow-skills --skill cms-best-practices
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