/category-pages

name: category-page-generator
description: When the user wants to create, optimize, or audit e-commerce category pages or listing pages. Also use when the user mentions "category page," "product category," "faceted navigation," "filter URLs," "e-commerce listing," "category SEO," "category structure," "product filters," or "listing page." For programmatic SEO at scale, use programmatic-seo.
metadata:
  version: 1.0.1

Pages: Category Pages

Guides e-commerce category page structure, content, and SEO optimization. Category pages organize products by attributes and drive 3x more organic revenue than product pages by ranking for broad, high-volume keywords.

**When invoking**: On **first use**, if helpful, open with 1-2 sentences on what this skill covers and why it matters, then provide the main output. On **subsequent use** or when the user asks to skip, go directly to the main output.

Initial Assessment

**Check for project context first:** If `.claude/project-context.md` or `.cursor/project-context.md` exists, read it for product catalog and site structure.

Identify: 1. **Catalog**: Product count, categories, subcategories 2. **Facets**: Filters (size, color, price, brand, etc.) 3. **URL structure**: Current hierarchy, parameter handling

Category Structure

Hierarchy

| Principle | Practice | |-----------|----------| | **Logical grouping** | General -> specific (e.g., Furniture -> Bedroom furniture -> Beds) | | **User search intent** | Match how users search (e.g., "bedroom furniture" vs "furniture") | | **Crawl depth** | <=4 clicks from homepage; shorter paths improve indexing | | **Long-tail categories** | Niche categories convert better (36% vs 11.5% for broad) |

URL Structure

• **Subfolders**: `example.com/shoes/sneakers`, `example.com/shoes/outdoor-shoes`
• **Slugs**: Descriptive, keyword-rich; lowercase; no stop words
• **Avoid**: Dates, timestamps, `/category/` prefix
• **Breadcrumbs**: Show path; help users and crawlers

Faceted Navigation (Filters)

Filters create many URL combinations (size + color + price). Manage to avoid duplicate content and crawl waste:

| Strategy | Use | |----------|-----| | **Canonical** | Point all faceted URLs to base category URL | | **robots.txt** | Block faceted URLs from indexing if needed | | **nofollow** | Add to internal links to faceted URLs | | **JavaScript** | Keep filters client-side; single URL for category |

On-Page Content

Content Requirements

• **150-300 words** unique copy; pages with this rank ~2.7x higher than product-only grids
• **Placement**: After hero/H1; FAQ block at bottom
• **Purpose**: Help users decide; answer curation, materials, recommendations
• **Avoid**: Manufacturer copy; crowding product grid

SEO Elements

| Element | Practice | |---------|----------| | **H1** | One per page; primary keyword; clear purpose | | **Title tag** | 50-60 chars; keyword; compelling for CTR | | **Meta description** | 150-160 chars; value props (free shipping, returns) | | **Schema** | ItemList, Product; AggregateRating if reviews; FAQ if applicable |

Trust & Conversion

• **Reviews**: Star ratings in SERPs; 99.9% of users read reviews; see **serp-features** for review rich results
• **FAQ**: Answer materials, quality, recommendations; +157% conversion when used
• **Guides**: Link to product guides; internal linking for SEO

Technical

• **Consistent layout**: Same template across categories; predictable UX
• **Mobile**: Responsive; touch targets >=44x44px
• **Redirects**: 301 to category when product pages move; avoid breaking hierarchy

Output Format

• **Structure** (hierarchy, URL paths)
• **Facet strategy** (canonical, nofollow, robots)
• **Content** (H1, intro copy, FAQ)
• **SEO** (metadata, schema)
• **Checklist** for audit

Related Skills

• **programmatic-seo**: Programmatic SEO strategy; category pages as template-based scale
• **card**: Card layout; product card structure, grid design
• **grid**: Product grid layout; responsive columns
• **products-page-generator**: Product cards, grid layout
• **canonical-tag**: Faceted URL canonicalization
• **schema-markup**: ItemList, Product, FAQ schema
• **internal-links**: Category linking
• **breadcrumb-generator**: Breadcrumb trail for category hierarchy
• **url-structure**: URL hierarchy