Kostja Zhang

---
name: api-page-generator
description: 'When the user wants to create, optimize, or audit the API introduction/overview page. Also use when the user mentions "API page," "API landing page," "/api page," "API overview," "developer landing," "API marketing," or "API for developers." Note: API documentation (endpoint reference) lives in docs; use docs-page-generator.'
metadata:
  version: 1.0.1
---

# Pages: API Introduction

Guides the API introduction page →typically at `/api` →that overviews the API, use cases, and links to documentation. API documentation (endpoint reference, code examples) lives on separate pages.

**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 and developer use cases.

Identify:
1. **API type**: REST, GraphQL, etc.
2. **Audience**: Developers (integration) vs. decision makers (evaluation)
3. **Docs location**: Where API documentation lives (e.g. `/docs`, `/api/reference`, external)

## Page Role

- **API page** (`/api`): Introduction, overview, value prop, CTA to docs or signup
- **API documentation**: Lives in docs (docs.*) → API Reference section with endpoint reference, auth, examples

## Best Practices

### Overview and Structure

- **What the API does**: Clear value proposition, key capabilities
- **Use cases**: Who uses it, common scenarios
- **Getting started**: Quick path to first call or docs
- **Link to docs**: Prominent CTA to API documentation

### Content

- **Key concepts**: High-level, not endpoint-level detail
- **Auth overview**: How auth works; link to docs for details
- **Pricing/limits**: If relevant for evaluation
- **SDKs and tools**: If available; link to docs

### SEO and Discovery

- **Developer search**: Target "API" + product/category terms
- **Metadata**: Title, description for developer intent
- **Internal links**: From homepage, features, resources

## Output Format

- **Structure** outline (sections)
- **Value proposition** and key messages
- **CTA** to documentation or signup
- **SEO** metadata for developer search

## Related Skills

- **homepage-generator**: Link to API page for developers
- **schema-markup**: WebPage or SoftwareApplication schema
- **title-tag, meta-description, page-metadata**: API page metadata

---
name: homepage-generator
description: When the user wants to create, optimize, or audit the main site homepage (primary entry page). Also use when the user mentions "homepage," "main page," "home page," "hero section," "above the fold," "home page design," "homepage conversion," or "homepage structure." Not for paid campaign or ad landing pages—use landing-page-generator. For sitewide page planning, use website-structure.
metadata:
  version: 1.2.0
---

# Pages: Homepage

Guides homepage content, structure, and conversion optimization.

**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.

## Homepage Role & Purpose

| Role | Priority | Notes |
|------|----------|-------|
| **Conversion** | Primary | Homepage is a trust machine and conversion engine—not a sales pitch. Most visitors (70–80%) are first-time; they need clarity, credibility, and orientation within 3–5 seconds. Convert through trust-building and guided exploration, not aggressive selling. |
| **Brand** | Primary | First impression, credibility test, orientation center. Answers: Who are you? What do you offer? Why should I care? Brand voice and differentiation live here—see **branding**. |
| **Branded keywords SEO** | Required | Primary SEO goal: rank for brand name so people can find you in SERPs. Branded searches indicate high intent and familiarity; they convert better than non-branded. |
| **Broad/non-branded SEO** | Secondary | Homepage is not the main SEO traffic driver—blog, product pages, and category pages typically carry that. A well-optimized homepage can rank for related non-branded terms as a bonus; do not sacrifice UX or conversion for broad keyword stuffing. |

**Principle**: SEO and CRO work together. Good homepage SEO aligns with user needs; conversion optimization ensures attracted traffic converts. See **landing-page-generator** for single-goal campaign pages (homepage is multi-purpose).

## Initial Assessment

**Check for project context first:** If `.claude/project-context.md` or `.cursor/project-context.md` exists, read it for product, audience, and value proposition. See **branding** for brand strategy, positioning, differentiation.

Identify:
1. **Primary goal**: Sign up, demo, purchase, learn more
2. **Audience**: Cold visitors, returning, specific segment
3. **Traffic source**: Organic, paid, referral

## Homepage Structure

| Section | Purpose |
|---------|---------|
| **Hero** | Value proposition, primary CTA, above the fold |
| **Social proof** | Logos, testimonials, metrics; "As Seen In" (press coverage) when applicable; see **customer-stories-page-generator** for case study snippets |
| **Features/Benefits** | What it does, why it matters |
| **Use cases** | Who it's for, how they use it |
| **Objection handling** | FAQ, guarantees, comparisons |
| **Final CTA** | Repeat primary action |

### Common Modules (from website-structure)

Combine as needed: Headline, Subheadline, Primary CTA, Supporting Image/Demo, Benefits Section, Social Proof, Search Box (if applicable), Secondary CTA, Banner. **Navigation**: Horizontal Bar, Dropdown, Hamburger (mobile), Sidebar, Footer; ensure Desktop + Mobile parity. See **hero-generator** for hero design.

## Best Practices

### Value Proposition

- **Clarity**: Visitor understands in 5 seconds
- **Specificity**: Concrete benefit, not vague
- **Differentiation**: Why you, not alternatives — see **branding** for positioning framework
- **Customer language**: Their words, not jargon
- **Avoid "not speaking human"**: Don't over-emphasize brand with vague definitions; communicate in user-friendly ways—if someone searches "AI presentation maker," the answer should be obvious from your headline

### CTA

- One clear primary action (avoid decision paralysis)
- Button copy: value-focused ("Start Free Trial") not generic ("Submit")
- Visible without scrolling
- Repeated at logical points

### Conversion Checklist

- Clear value proposition above the fold
- Single primary CTA; simplified navigation (5–7 menu items)
- Immediate social proof (reviews, trust badges, media logos)
- Mobile-first, fast-loading design

### Visual & Aesthetics

- **Frontend aesthetics**: For distinctive typography, motion, spatial composition, backgrounds—see **brand-visual-generator** Frontend Aesthetics

### SEO

**Branded keywords first**: Title and meta should include brand name; ensure homepage ranks for "[Brand Name]" so users can find the official site. See **brand-protection** when impersonation risk exists—place "Official website: [domain]" above fold or in hero.

- **Title tag** (50–60 chars): Brand name + primary keyword; e.g. "Canva – Free Website Builder"
- **Meta description** (150–160 chars): CTA + secondary keywords; engaging to encourage clicks
- **H1**: Value proposition or primary headline; one per page; include primary keyword naturally
- **Body**: Primary keyword in first 100 words; secondary keywords in H2–H6 and body
- Logical H2–H6 structure for scannability and LLM/AI Overview visibility

**Schema**: Add **Organization + WebSite** JSON-LD on homepage (or in root layout for site-wide). Organization establishes brand entity; WebSite enables sitelinks searchbox. Do not put Organization only on About page—About uses AboutPage schema. See **schema-markup**, **entity-seo**.

## Output Format

- **Structure** outline (sections)
- **Hero** copy options (headline, subheadline, CTA)
- **Key sections** content suggestions
- **SEO** metadata (title, description, H1)
- **Conversion** checklist

## Related Skills

- **branding**: Brand strategy, value prop, differentiation; homepage implements brand voice
- **brand-protection**: "Official website" placement when impersonation risk exists
- **landing-page-generator**: For single-goal campaign pages (affiliate signup, lead capture); homepage is multi-purpose
- **pricing-page-generator**: Homepage often links to pricing
- **features-page-generator**: Features section or link to features page
- **press-coverage-page-generator**: "As Seen In" section (logo strip) when coverage exists; full page links from homepage
- **customer-stories-page-generator**: Testimonials, case study snippets for social proof section
- **schema-markup, entity-seo**: Organization + WebSite schema placement (homepage or root layout)
- **title-tag, meta-description, page-metadata, open-graph, twitter-cards**: Homepage metadata and social previews
- **heading-structure**: Homepage heading structure

---
name: contact-page-generator
description: When the user wants to create, optimize, or audit contact page and forms. Also use when the user mentions "contact page," "contact form," "get in touch," "support form," "contact us," "reach us," "contact information," "support contact," or "inquiry form." For sitewide page planning, use website-structure.
metadata:
  version: 1.0.1
---

# Pages: Contact

Guides contact page design and form optimization for conversions.

**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 brand voice.

Identify:
1. **Contact types**: Sales, support, general, press
2. **Form purpose**: Lead capture, support ticket, demo request
3. **Alternative channels**: Email, phone, chat, social

## Best Practices

### Form Design

| Principle | Guideline |
|-----------|-----------|
| **Short** | 3-5 fields for basic contact; long forms increase abandonment |
| **Single column** | Vertical layout; works better on mobile |
| **Logical grouping** | Name+email together; address fields together |
| **Required fields** | Mark clearly (asterisk); avoid surprises |
| **Progressive disclosure** | Show relevant fields based on selections |

### Field Labels

- **Clear language**: "Email Address" not "Email ID"
- **Conversational**: Friendly, welcoming
- **No jargon**: Universally understood terms

### CTA Button

- **Action verbs**: "Send Message," "Get in Touch," "Start a Conversation"
- **Avoid generic**: "Submit" ? "Send Message"
- **Stand out**: Contrasting color, clear hierarchy

### Page-Level

| Element | Guideline |
|---------|-----------|
| **Visibility** | "Contact" or "Support" in main nav, not just footer |
| **Mobile** | Appropriate input types (tel for phone), large tap targets |
| **Proofreading** | No typos--credibility at conversion moment |
| **Alternatives** | Email, phone, chat if form isn't right |

### Trust

- **Response time**: "We reply within 24 hours"
- **Privacy**: Link to privacy policy near form
- **Security**: HTTPS, visible trust signals

## Output Format

- **Form** structure (fields, order)
- **Copy** (labels, placeholder, CTA)
- **Page** layout and placement
- **SEO** metadata
- **Accessibility** checklist

## Related Skills

- **landing-page-generator**: Lead capture LP contains contact form; demo request CTA destination
- **about-page-generator**: Contact often linked from About
- **legal-page-generator**: Privacy policy link near form
- **title-tag, meta-description, page-metadata**: Contact page metadata

---
name: about-page-generator
description: When the user wants to create, optimize, or audit About page content. Also use when the user mentions "about page," "about us," "company story," "our team," "about section," "company overview," "brand story," "team page," or "who we are." For sitewide page planning, use website-structure.
metadata:
  version: 1.0.1
---

# Pages: About

Guides About page content, structure, and trust-building for company websites.

**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 company story, values, and differentiation. See **branding** for full brand strategy framework (purpose, values, storytelling).

Identify:
1. **Audience**: Job seekers, buyers, partners, press
2. **Key message**: Mission, values, differentiation
3. **Proof points**: Awards, metrics, testimonials

## Best Practices

### Essential Elements

| Element | Purpose |
|---------|---------|
| **Company overview** | Who, what, where, when, why, how |
| **Origin story** | Journey, founding, milestones |
| **Team** | Key people, photos, roles |
| **Mission and values** | What you stand for |
| **Visuals** | Photos, videos, office/culture |
| **Social proof** | Testimonials, awards, certifications |
| **Contact** | Easy way to reach you |

### Strategic Approach

- **Tell a story**: Convey who you are and why you're different—not just facts. See **branding** for origin story, hero's journey, narrative arc.
- **Customer-focused**: Frame around what you solve for customers, not self-promotion
- **Build trust**: Social links, testimonials, contact details, certifications
- **Visible placement**: About in main nav, not buried in footer

### Schema (AboutPage, Not Organization)

- **AboutPage** schema: Use on About page—describes page content (headline, description, author, about). Helps search engines understand this page's purpose.
- **Organization** schema: Place on **homepage or root layout**, not About. Organization is entity-level (brand that owns the site); AboutPage is page-level. See **schema-markup** for placement.

### Why It Matters

- One of the most-visited pages
- 58% of customers buy based on company values
- 60% of job candidates choose employers based on values
- Entry point for branded search; impacts conversions

## Output Format

- **Structure** outline (sections)
- **Story** narrative and key messages
- **Team** section approach
- **SEO** metadata (title, description, H1)
- **Trust** elements checklist

## Related Skills

- **branding**: Brand strategy, storytelling, purpose, values; About page implements brand story
- **homepage-generator**: About often linked from homepage
- **contact-page-generator**: Contact info on About
- **customer-stories-page-generator**: Social proof complements About
- **title-tag, meta-description, page-metadata**: About page metadata
- **schema-markup**: AboutPage schema for About; Organization goes on homepage/root layout
- **brand-protection**: Official domain and identity declaration; helps users distinguish from impersonation sites

---
name: visual-content
description: When the user wants to plan, create, or repurpose visual content (images, infographics, social post images) across channels. Also use when the user mentions "content images," "social media images," "infographic," "visual content," "post image," "image specs," "visual repurposing," "content visuals," or "image for social post." For Pinterest, use pinterest-posts.
metadata:
  version: 1.0.1
---

# Content: Visual Content

Guides visual content planning and creation across website, social media, email, and other channels. Images are needed not just for websites—social posts, infographics, and repurposed content all require visuals. Visual-first planning in content calendars improves engagement; cross-channel consistency and repurposing maximize ROI.

**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.

## Scope

- **When to use images**: By content type and format
- **Specs by context**: Website vs social vs email
- **Platform image specs**: X, LinkedIn, Pinterest, Instagram, Facebook, YouTube
- **Repurposing**: One visual → multiple formats and channels
- **Visual-first planning**: Content calendar with image planning

## Initial Assessment

**Check for project context first:** If `.claude/project-context.md` or `.cursor/project-context.md` exists, read Section 12 (Visual Identity) for brand consistency.

Identify:
1. **Context**: Article, social post, infographic, email, landing page
2. **Channels**: Which platforms will use this visual
3. **Repurposing**: Will this visual be adapted for other formats?

---

## 1. When to Use Images

| Content Type | Visual Need | Notes |
|--------------|-------------|-------|
| **Article / Blog** | Hero image, in-article images, screenshots | See **image-optimization** for web (alt, WebP, LCP) |
| **Social post** | Single image, carousel, or link preview | Platform-specific specs below |
| **Infographic** | Primary format; data visualization | Repurpose to social (cropped), blog (full) |
| **Case study** | Customer photo, results chart, logo | Repurpose to LinkedIn carousel, blog |
| **Product update** | Screenshot, feature graphic | Changelog, email, social |
| **Email** | Header image, inline graphics | Keep lightweight; many clients block images |
| **Landing page** | Hero, trust badges, screenshots | See **hero-generator**, **image-optimization** |

---

## 2. Website vs Social vs Email

| Context | Priority | Skill |
|---------|----------|-------|
| **Website** | Alt text, WebP, LCP, responsive, lazy loading | **image-optimization** |
| **Social posts** | Platform dimensions, aspect ratio, file size | **Platform skills** (X, LinkedIn, Pinterest, etc.) |
| **OG / Twitter Cards** | 1200×630, 1200×675 for link previews | **open-graph**, **twitter-cards** |
| **Email** | Inline-friendly; avoid heavy images; alt for blocked | **email-marketing** |

---

## 3. Platform Image Specs (Social)

| Platform | Post Image | Stories / Reels | Profile | Notes |
|----------|------------|-----------------|---------|-------|
| **X (Twitter)** | 1200×675 (16:9), 800×800 | — | 400×400 | See **twitter-x-posts** |
| **LinkedIn** | 1200×627, 1200×1200; carousel up to 20 | — | 400×400 | See **linkedin-posts**; vertical preferred on mobile |
| **Pinterest** | 1000×1500 (2:3) | — | 165×165 | Alt text ~25% more impressions; see **pinterest-posts** |
| **Instagram** | 1080×1350 (4:5), 1080×1080 | 1080×1920 (9:16) | 320×320 | 4:5 outperforms square on feed |
| **Facebook** | 1200×630, 1080×1080 | 1080×1920 | 320×320 | |
| **YouTube** | Thumbnail 1280×720 | — | 800×800 | |

**General**: 1080px width works across most platforms; vertical (4:5, 9:16) outperforms square on mobile-first feeds. Keep critical elements (logo, text) in safe center—platforms may crop.

---

## 4. Visual Repurposing

**Principle**: One core visual → multiple crops/formats → multiple channels.

| Core Visual | Adaptations | Channels |
|-------------|-------------|----------|
| **Infographic** | Full (blog), cropped sections (Instagram, LinkedIn carousel), square (X) | Blog, LinkedIn, Instagram, X |
| **Case study graphic** | Hero (blog), single slide (LinkedIn), story (Instagram) | Blog, LinkedIn, Instagram |
| **Product screenshot** | Hero (landing), post (X, LinkedIn), email header | Website, social, email |
| **Quote graphic** | Square (X, LinkedIn), 4:5 (Instagram) | X, LinkedIn, Instagram |

**Workflow**: Design at largest needed size; export platform-specific crops. Use consistent colors, fonts, logo placement (see **brand-visual-generator**).

---

## 5. Visual-First Content Planning

- **Plan images in content calendar**: Don't add visuals as afterthought; visuals drive engagement
- **Batch by theme**: Create visuals for a topic cluster or campaign together for consistency
- **Repurposing column**: In calendar, note which core piece becomes which visual format for which channel
- **Asset library**: Organize by campaign/theme; tag for reuse

---

## 6. Format-Specific Notes

### Infographics

- **Dimensions**: 800–1200px width; height varies by content
- **Export**: PNG for web; PDF for download
- **Repurpose**: Slice into 3–5 slides for LinkedIn carousel; single stat for X/Instagram

### Social Post Images

- **Text overlay**: Keep minimal; many platforms deprecate text-heavy images
- **Branding**: Logo in corner; consistent with **brand-visual-generator**
- **Alt text**: Add for LinkedIn, Pinterest, X (accessibility + Pinterest SEO); see **image-optimization** for alt best practices

### Article / Blog Images

- **Hero**: Often LCP candidate; optimize per **image-optimization**
- **In-article**: Support narrative; alt text, captions per **image-optimization**
- **Screenshots**: Annotate when helpful; keep file size low

---

## Output Format

- **Visual plan** (what images for what content)
- **Specs** by context (platform dimensions, format)
- **Repurposing** map (one visual → multiple outputs)
- **References** to platform skills and image-optimization

## Related Skills

### Content & Strategy

- **content-marketing**: Content types, formats, repurposing; visual content is part of content mix
- **content-strategy**: SEO topic clusters; article visuals
- **copywriting**: Copy pairs with visuals; headlines for image posts

### Platform (Image Specs)

- **twitter-x-posts**: X post image specs
- **linkedin-posts**: LinkedIn image specs
- **pinterest-posts**: Pinterest Pin dimensions, alt text
- **reddit-posts**: Reddit image post context

### Website & SEO

- **image-optimization**: Web images (alt, captions, WebP, LCP, responsive); central skill for image SEO
- **open-graph, twitter-cards**: Link preview images
- **hero-generator**: Hero section visuals

### Other

- **brand-visual-generator**: Typography, colors, imagery tone; visual consistency
- **video-marketing**: Video thumbnails; video as visual format
- **video-optimization**: Video SEO; VideoObject; video sitemap; YouTube prioritization

---
name: video-marketing
description: When the user wants to plan video marketing, create video scripts, or optimize for short-form or long-form video. Also use when the user mentions "video marketing," "video script," "short-form video," "long-form video," "TikTok script," "Reels script," "YouTube script," "video hook," or "video content strategy." For on-site video SEO, use video-optimization.
metadata:
  version: 1.0.1
---

# Content: Video Marketing

Guides video marketing strategy and script creation for short-form and long-form content. Short-form commands ~82% of internet traffic with 2.5× more engagement than long-form; 71% of viewers decide within 3 seconds whether to continue. Use this skill when planning video content, writing scripts, or optimizing for platforms.

**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 Sections 3 (Value Proposition), 4 (Audience), 11 (Content Strategy).

Identify:
1. **Format**: Short-form (TikTok, Reels, Shorts) vs long-form (YouTube, webinar)
2. **Goal**: Awareness, consideration, conversion, education
3. **Platform**: TikTok, Instagram Reels, YouTube Shorts, YouTube long-form

## Short-Form vs Long-Form

| Format | Length | Use | Platforms |
|--------|--------|-----|-----------|
| **Short-form** | 15–60 sec | Hooks, tips, UGC-style; 90% watch daily | TikTok, Reels, Shorts |
| **Long-form** | 3–15+ min | Deep dives; tutorials; Gen Z discovers via short, engages with long | YouTube |

**Optimal short-form length**: 31–60 seconds for higher completion rates.

## Critical First 3 Seconds

71% of viewers decide within 3 seconds whether to continue. Hook types:

| Hook Type | Example |
|-----------|---------|
| **Story-driven** | "Three months ago, I had zero subscribers..." |
| **Contrarian** | "Everyone says X. Here's why they're wrong." |
| **Question** | "Why do 90% of startups fail at this?" |
| **Result-focused** | "I went from 0 to 10K in 30 days. Here's how." |

## Script Structure (Short-Form)

**Hook (0–3 sec)** → **Problem (3–15 sec)** → **Solution (15–45 sec)** → **CTA (final 5 sec)**

Achieves 70%+ completion for algorithmic boost. Frameworks: Hook-Value-CTA, AIDA, PAS, BAB.

## Platform-Specific Hooks

| Platform | Hook Length | Notes |
|----------|-------------|-------|
| **TikTok** | 2 seconds | High energy; 4,000-char captions for SEO |
| **Instagram Reels** | 3 seconds | Polished aesthetics; penalizes TikTok watermarks |
| **YouTube Shorts** | 3–5 seconds | Searchable titles; keyword-rich descriptions |

## UGC-Style Content

- **Authenticity > polish**: UGC-style generates 50%+ of engagement
- **Trust**: 86% of consumers trust brands publishing UGC more than polished ads

## Long-Form Script Structure

- **Hook** (0–30 sec): Promise; why watch
- **Intro** (30–60 sec): Context; what you'll cover
- **Body**: Sections with clear transitions
- **CTA**: Subscribe; link; next step
- **Outro**: Recap; repeat CTA

## Output Format

- **Format** (short vs long) recommendation
- **Hook** options (2–3 variants)
- **Script** (timestamped if long-form)
- **CTA** placement
- **Platform** optimization notes

## Related Skills

- **tiktok-captions**: TikTok caption, video specs, script
- **tiktok-ads**: TikTok ad creative
- **content-marketing**: Video as content format; repurposing
- **youtube-seo**: YouTube SEO, description, thumbnail (platform skill)
- **video-optimization**: Website video SEO; VideoObject; video sitemap; Google prioritizes YouTube

---
name: translation
description: When the user wants to translate content, create translation workflows, manage terminology, or optimize translation quality. Also use when the user mentions "translate," "translation," "localization copy," "glossary," "terminology," "style guide translation," "machine translation," "human translation," "TMS," or "multilingual content." For strategy, use localization-strategy.
metadata:
  version: 1.0.1
---

# Content: Translation

Guides translation workflow, terminology, style, and quality for multilingual content. Covers when to use human vs machine translation, glossary and style guide creation, and SEO considerations. For i18n implementation, hreflang, and URL structure, see **localization-strategy**.

**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.

## Scope

- **Workflow**: Brief → translate → review
- **Terminology**: Glossary creation and management
- **Style guide**: Voice, tone, formatting per language
- **Human vs MT**: When to use each; post-editing
- **Quality**: QA, consistency, SEO
- **Market-specific**: Terminology by region

## Initial Assessment

**Check for project context first:** If `.claude/project-context.md` or `.cursor/project-context.md` exists, read it for brand voice, target markets, and product terminology.

Identify:
1. **Content type**: Product UI, marketing copy, blog, landing page, docs
2. **Target language(s)**: Priority locales
3. **Existing assets**: Glossary, style guide, translation memory (TM)

---

## 1. Translation Workflow

### Brief → Translate → Review

| Phase | Purpose | Output |
|-------|---------|--------|
| **Brief** | Context, audience, tone, glossary reference, style guide | Translator brief document |
| **Translate** | First pass; use glossary + TM when available | Draft translation |
| **Review** | Native speaker review; consistency, brand voice, SEO | Final translation |

### Translator Brief

Include in every project:
- **Context**: What the content is for (landing page, product UI, blog)
- **Audience**: Target market, user persona
- **Tone**: Formal, casual, technical
- **Glossary**: Link or attach; mandatory terms
- **Style guide**: Reference or key rules
- **Constraints**: Character limits (UI), SEO keywords to include naturally

### Content-Type Workflow

| Content Type | Approach | Notes |
|--------------|----------|-------|
| **Product UI** | Glossary-critical; short strings; consistency | Use TM; avoid machine translation |
| **Marketing copy** | Brand voice; cultural adaptation | Human translation; see terminology |
| **Blog / Article** | SEO; natural keyword placement | Re-research keywords in target language; don't translate keyword lists |
| **Landing page** | Conversion-focused; CTA clarity | Human; test localized CTAs |
| **Technical docs** | Precision; glossary | TM + glossary; consider MT + post-edit for high volume |

---

## 2. Glossary & Terminology

### Glossary Purpose

- **Consistency**: Same term translated the same way across all content
- **Brand**: Product names, feature names, approved phrasing
- **Compliance**: Safety, legal, regulated terms
- **Cost**: Reduces rework; accelerates review

### Glossary Structure

| Field | Purpose |
|-------|---------|
| **Source term** | Original (e.g., English) |
| **Target term** | Approved translation |
| **Context** | Where it appears; usage note |
| **Do not translate** | Brand names, product names (when applicable) |

### Market-Specific Terminology

| Term | English | Chinese | Notes |
|------|---------|---------|------|
| **Generative AI** | Generative AI, GenAI | AIGC (人工智能生成内容) | Use "AIGC" for China; "Generative AI" for English |
| **Influencer** | Influencer | KOL (关键意见领袖) | "KOL" common in Chinese marketing |
| **User** | User | 用户 | Context-dependent |
| **Dashboard** | Dashboard | 控制台, 仪表盘 | Choose one; document in glossary |

**Principle**: Don't translate terminology lists; research how target market searches and speaks. See **keyword-research** for multi-language keyword research.

---

## 3. Style Guide (Translation)

### Elements to Define

| Element | Purpose |
|---------|---------|
| **Voice** | Brand personality; formal vs casual |
| **Tone** | Varies by content type (support = helpful; marketing = persuasive) |
| **Register** | Formal (您) vs informal (你) in languages that distinguish |
| **Punctuation** | Quotation marks, spacing (e.g., no space before colon in French) |
| **Formatting** | Dates, numbers, units; locale-specific |
| **Forbidden** | Terms or phrases to avoid |

### Per-Language Considerations

- **Chinese**: Simplified vs Traditional; measure word usage
- **German**: Formal (Sie) vs informal (du); compound nouns
- **Japanese**: Honorifics; keigo for formal contexts
- **Arabic**: RTL; formal vs dialect

---

## 4. Human vs Machine Translation

### When to Use Human Translation

| Scenario | Reason |
|----------|--------|
| **Product UI** | Terminology, UX clarity, brand |
| **Marketing copy** | Persuasion, cultural nuance, CTAs |
| **Landing pages** | Conversion; tested copy |
| **Legal, compliance** | Accuracy, liability |
| **Brand-critical** | Taglines, campaign copy |

### When Machine Translation (MT) May Be Acceptable

| Scenario | Condition |
|----------|-----------|
| **High-volume, low-stakes** | Internal docs, user-generated content |
| **Draft / triage** | MT + human post-edit (MTPE) |
| **Real-time** | Chat, support; with disclaimer |

### Avoid

- **Raw MT for product/marketing**: Terminology errors, cultural misfires, poor SEO
- **MT without post-edit** for customer-facing content
- **Translating keyword lists** instead of re-researching in target language

---

## 5. Translation Memory (TM) & TMS

### Translation Memory

- **What**: Stores approved source↔target sentence pairs
- **Benefit**: Consistency; reuse; lower cost per word; faster turnaround
- **Best practice**: Maintain TM; clean duplicates; align with glossary

### Translation Management System (TMS)

- **Use for**: Centralized workflow; glossary + TM integration; vendor management
- **When**: Multiple languages; ongoing translation; team collaboration

---

## 6. Quality & SEO

### Quality Checklist

- [ ] Glossary terms used correctly
- [ ] Style guide followed
- [ ] No untranslated strings
- [ ] Numbers, dates, units localized
- [ ] Character limits respected (UI)
- [ ] Native speaker review completed

### SEO for Translated Content

- **Keywords**: Re-research in target language; don't translate from source
- **Metadata**: Title, description translated; see **title-tag**, **meta-description**
- **Hreflang**: Technical implementation in **localization-strategy**; translation produces the content
- **Thin content**: Avoid publishing many low-quality translated pages at once; can trigger penalties. See **localization-strategy** Multilingual Risks.

---

## 7. Integration with Localization

| Topic | Skill |
|-------|-------|
| **i18n implementation** | localization-strategy |
| **URL structure, hreflang** | localization-strategy |
| **Translation workflow, glossary, style** | This skill (translation) |
| **Keyword research by market** | keyword-research; localization-strategy |

When adding a new locale: create glossary, style guide, then translate. See **localization-strategy** for technical checklist (hreflang, sitemap, metadata).

---

## Output Format

- **Translator brief** (context, audience, glossary, style)
- **Glossary** additions or updates
- **Style guide** notes for target language
- **Human vs MT** recommendation
- **Quality** checklist

## Related Skills

### Strategy & Technical

- **localization-strategy**: i18n, hreflang, URL structure, pricing by market; translation produces content for localized pages
- **content-strategy**: Multilingual content planning; avoid thin translations
- **content-marketing**: Content types and formats; translation as one channel adaptation

### SEO & Content

- **keyword-research**: Multi-language keyword research; don't translate keyword lists
- **page-metadata**: Hreflang implementation
- **title-tag, meta-description**: Translate metadata per locale
- **copywriting**: Source copy to translate; brand voice
- **image-optimization**: Localize image filenames for translated pages

### Pages

- **article-page-generator**: Article structure; translate with SEO in mind
- **landing-page-generator**: Landing page copy; human translation for conversion

---
name: podcast-marketing
description: When the user wants to plan, create, or market a podcast. Also use when the user mentions "podcast," "podcast strategy," "podcast SEO," "show notes," "podcast distribution," "Spotify podcast," "Apple Podcasts," "podcast discoverability," "PodcastEpisode schema," or "podcast repurposing." For show notes, use article-content.
metadata:
  version: 1.0.1
---

# Content: Podcast

Guides podcast strategy, content creation, distribution, marketing, and SEO. Podcasts compete in a crowded space (3M+ active shows, 500M+ listeners globally); discoverability is the primary challenge. Discovery channels: ~32% search engines, ~28% podcast apps, ~24% social media, ~16% word-of-mouth.

**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 for audience, positioning, and content strategy.

Identify:
1. **Stage**: Planning, launching, growing
2. **Format**: Interview, solo, co-hosted, narrative
3. **Niche**: Target audience, listener personas
4. **Goals**: Downloads, authority, lead gen, repurposing

## Content Strategy

| Element | Guideline |
|---------|-----------|
| **Niche focus** | Define audience through listener personas; tailored content cuts through noise |
| **Quality over gimmicks** | Sticky, unique, valuable content; most hosts see major growth after 5–6 months of consistency |
| **Episode structure** | Intro, main content, CTA; consistent format aids retention |

## Distribution & Discovery

| Channel | Share | Optimization |
|---------|-------|---------------|
| **Search engines** | ~32% | Transcripts, show notes, SEO-optimized titles/descriptions |
| **Podcast apps** | ~28% | Title, description, cover art; category selection |
| **Social media** | ~24% | Clips, quotes, repurposed content |
| **Word-of-mouth** | ~16% | Cross-promotion, guest appearances |

**Multi-channel**: Repurpose across platforms to multiply discovery surface.

## SEO for Podcasts

Search engines cannot listen to audio. Text-based content is essential:

| Element | Guideline |
|---------|-----------|
| **Transcripts** | Full or key-moment transcripts; indexable, accessible |
| **Show notes** | SEO-optimized; pull organic search traffic; include keywords naturally |
| **Titles** | ≤60 chars; keywords; engaging language |
| **Descriptions** | Episode-specific; keywords; voice-search friendly |
| **Backlinks** | Build links to show notes, guest posts, directory listings |

**Schema**: Use **PodcastEpisode** and **PodcastSeries** for rich results. See **schema-markup** for implementation.

## Cross-Promotion & Partnerships

| Tactic | Use |
|--------|-----|
| **Feed drops** | Swap episodes with similar-sized podcasts |
| **Ad swaps** | Promote each other's shows |
| **Guest appearances** | Tap into pre-existing engaged audiences |

## Repurposing

| Format | Use |
|--------|-----|
| **Clips** | Short-form for social (TikTok, YouTube Shorts, X) |
| **Blog posts** | Expand show notes; pillar content |
| **Newsletter** | Episode summaries, key takeaways |
| **Quotes** | Pull quotable moments for social |

## Output Format

- **Strategy** (niche, format, distribution mix)
- **SEO checklist** (transcripts, show notes, schema)
- **Launch checklist** (cover art, description, category, RSS)
- **Repurposing plan** (clips, blog, newsletter)

## Related Skills

- **schema-markup**: PodcastEpisode, PodcastSeries schema
- **video-marketing**: Video content; podcast-to-video repurposing
- **copywriting**: Show notes, episode descriptions, social copy
- **content-marketing**: Content strategy, repurposing framework
- **youtube-seo**: If publishing podcast to YouTube

---
name: copywriting
description: When the user wants to write or optimize short-form marketing copy—headlines, CTAs, ad copy, landing page copy, email copy. Also use when the user mentions "copywriting," "headline," "CTA copy," "ad copy," "landing page copy," "sales copy," "conversion copy," "PAS," "AIDA," "BAB," "copy formula," or "differentiation." For long-form article bodies (blog posts, guides), use article-content.
metadata:
  version: 1.2.0
---

# Content: Copywriting

Guides **short-form marketing copy**—ads, landing pages, email, CTAs. Copywriting frameworks (PAS, AIDA, BAB) provide structure for conversion-focused copy. For **article body content** (blog posts, guides, long-form), see **article-content**.

**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 Sections 2 (Positioning), 3 (Value Proposition), 8 (Brand & Voice).

Identify:
1. **Context**: Ad, landing page, email, CTA, or general
2. **Goal**: Awareness, consideration, conversion, retention
3. **Audience**: ICP, stage, pain points

## Copywriting Frameworks

| Framework | Structure | Best For |
|-----------|-----------|----------|
| **PAS** | Problem → Agitation → Solution | Direct-response; sales pages; landing pages |
| **AIDA** | Attention → Interest → Desire → Action | Story-driven; ads; emails; editorials |
| **BAB** | Before (problem) → After (outcome) → Bridge (how) | Transformation; testimonials; case studies |
| **FAB** | Features → Advantages → Benefits | Product pages; feature lists |
| **4 U's** | Useful, Urgent, Unique, Ultra-specific | Headlines; subject lines |

### PAS (Problem, Agitation, Solution)

- **Problem**: Identify the reader's pain point clearly
- **Agitation**: Intensify the emotional impact; make the problem feel urgent
- **Solution**: Present your product/service as the answer

### AIDA (Attention, Interest, Desire, Action)

- **Attention**: Grab with a powerful headline or opening
- **Interest**: Build engagement through facts, storytelling, or emotional appeals
- **Desire**: Highlight benefits and how the product solves problems
- **Action**: Include a clear call-to-action

### BAB (Before, After, Bridge)

- **Before**: Current problem state
- **After**: Desired outcome
- **Bridge**: How your solution bridges the gap

## Headline Formulas

| Formula | Example |
|---------|---------|
| **How to [outcome]** | "How to Double Your Conversions in 30 Days" |
| **[Number] Ways to [benefit]** | "7 Ways to Reduce Churn Without Hiring" |
| **[Who] + [benefit]** | "For Marketers Who Want to Ship Faster" |
| **[Problem]? Here's [solution]** | "Struggling with SEO? Here's the Fix" |
| **[Before] → [After]** | "From 0 to 10K Users in 90 Days" |
| **The [adjective] [noun] for [audience]** | "The Ultimate Guide for SaaS Founders" |

**Rules**: Front-load keywords; keep under 60 chars for SERP; avoid clickbait; match ad-to-page alignment.

**Information gain (differentiation)**: Copy that restates what competitors say adds zero value. Lead with unique angle, proprietary data, or contrarian insight. "What does this headline/promise add that others don't?" See **article-content** for full information gain strategy in long-form.

## Copy by Context

| Context | Focus | Skills |
|---------|-------|--------|
| **Ad copy** | Hook, benefit, CTA; platform limits | paid-ads-strategy, google-ads, meta-ads |
| **Landing page** | Headline, value prop, CTA; above fold | landing-page-generator, hero-generator |
| **Email** | Subject line, preview, body, CTA | email-marketing |
| **CTA** | Value-focused; action verb; avoid "Submit" | cta-generator |
| **Article / blog** | Headline formulas, CTA copy; body → **article-content** | article-content, article-page-generator |

## Ad copy vs Landing page copy

| Element | Ad | Landing Page |
|---------|-----|--------------|
| **Promise** | Must match page headline | Same promise; expand on it |
| **Length** | Concise; platform limits | Enough to explain value |
| **CTA** | Click-through; "Learn More" | Conversion; "Start Free Trial" |

**Avoid**: Ad promise not visible on page; mismatch increases bounce.

## CTA Copy Best Practices

- **Value-focused**: "Start Free Trial" not "Submit"
- **Action verb**: "Get," "Try," "Download," "Join"
- **Specific**: "Get Your Free Audit" not "Click Here"
- **A/B test**: Color, copy, placement, size

## Output Format

- **Framework** (PAS, AIDA, BAB) recommendation
- **Headline** options (2–3 variants)
- **Body** copy structure
- **CTA** copy options
- **A/B test** suggestions (if applicable)

## Related Skills

- **article-content**: Article body creation; applies PAS, AIDA, BAB to long-form; headline formulas for article titles
- **landing-page-generator**: Landing page copy and structure
- **hero-generator**: Hero headline, subheadline, CTA
- **cta-generator**: CTA design and copy
- **paid-ads-strategy**: Ad copy frameworks (PAS, BAB, Social Proof)
- **email-marketing**: Email subject lines, body copy
- **branding**: Brand voice, tone consistency

---
name: article-content
description: When the user wants to write, generate, or create article body content—blog post body, long-form content, how-to guide, listicle. Also use when the user mentions "write article," "article content," "blog post content," "article body," "long-form content creation," "generate article," "article draft," "how-to guide content," "listicle content," "information gain," or "content density." For single post page structure, schema, and SEO metadata, use article-page-generator. For blog index/listing page, use blog-page-generator. For short ad, landing, or email copy, use copywriting.
metadata:
  version: 1.1.0
---

# Content: Article Content

Guides creation of **article body content**—the actual text (intro, body, conclusion) for blog posts, guides, and long-form pieces. Focus on **what to write**. For **where it goes** (page structure, schema, metadata), see **article-page-generator**. For short conversion copy (ads, landing pages, CTAs), see **copywriting**.

**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.

## Scope

- **Article body**: Introduction, body sections, conclusion, CTA
- **Content structure**: Hook, QAE pattern, paragraph length, scannability
- **Word count**: By article type and search intent
- **Writing frameworks**: AIDA, PAS, BAB applied to articles
- **GEO elements**: TL;DR, Key Takeaways, answer-first

## Article Types & Word Count (2025)

**Quality over length**: Google prioritizes comprehensive coverage of search intent, not word count. Match length to topic depth and intent.

| Type | Word count | Use case |
|------|------------|----------|
| **News / announcements** | 300–600 | Product updates, breaking news, FAQs |
| **Short-form** | 500–800 | Landing pages, product pages (scannable) |
| **Standard articles / how-tos** | 1,000–1,500 | Single topic; actionable; listicles |
| **Listicles** | 1,200–2,000 | "Top 10," "Best X"; numbered lists boost CTR ~70% |
| **Cluster articles** | 800–2,500 | Subtopic; links to pillar |
| **Pillar / cornerstone** | 2,000–3,500+ | Comprehensive; cluster hub; 6–12 sections |
| **Competitive keywords** | 1,800–2,500 | Page-one SEO posts avg ~2,400 words |

**Intent-based** (Google 2025): Validate 1,200–2,000; Explore 2,000–3,500; Compare 600–1,200; Do 900–1,500; Know 300–800. Informational ~40% longer than transactional.

**Avoid**: Under 300 words (thin); over 7,000 (often underperforms due to reduced focus).

## Content Creation Workflow

### Four Inputs

Article content rests on **four inputs**. See **article-page-generator** for full workflow.

| Input | Purpose |
|-------|---------|
| **Product** | Connection, features, CTA placement |
| **Keywords** | Target keyword, primary/secondary |
| **Article intent** | Informational, commercial, transactional |
| **Competitor articles** | Structure to adopt, content gaps, length target |

### Information Gain (Content Density Over Word Count)

**Information gain** = net new information a page provides beyond what exists in top-ranking results. Google evaluates unique value, not comprehensiveness. Content density (unique entities, data points, insights per 100 words) matters more than word count. Skyscraper Technique (longer = better) no longer differentiates; AI made comprehensiveness cheap.

**Four sources of information gain**:
- **Counter-narratives**: Why "best practice" fails in certain contexts; evidence-backed
- **Temporal freshness**: Data or developments after competitors' content and LLM cutoff
- **SME perspectives**: Direct quotes, practitioner experience; not repackaged advice
- **Proprietary data**: Original surveys, internal benchmarks, user behavior patterns

**Avoid consensus content**: Restating common facts across top 10 results = zero information gain. Audit SERP before writing; list the "consensus layer"; identify gaps (unanswered questions, outdated data, underserved segments). Lead with what is new; structure answer-first.

**Density check**: Count unique data points, original insights, specific claims. If ratio of new information to word count is low, cut filler. High-density content (800-1,500 words with 3+ original points) often outperforms long rehashed guides.

### TL;DR or Key Takeaways (GEO)

Choose one; place after intro. Content with these elements is cited ~35% more by AI.

| Format | Spec |
|--------|------|
| **TL;DR** | 50–100 word bold summary paragraph |
| **Key Takeaways** | 5–7 bullet points |

See **generative-engine-optimization** for full GEO strategy.

### Introduction

**Length**: 40–120 words; 2–3 paragraphs. Readers decide in ~8 seconds; hook must work instantly.

| Element | Guideline |
|---------|-----------|
| **Hook** | First 1–2 sentences: pain point, stat, or question; curiosity gap; specific data or contrarian fact |
| **Primary keyword** | In first 100 words |
| **Expectations** | Set what reader will learn |

**Hook types**: "You're doing X wrong"; "97% of Y…"; bold question; challenge assumption. Well-crafted hooks boost CTR 30–50%.

### Body

| Element | Guideline |
|---------|-----------|
| **QAE pattern** | Question (H2) → Answer (2 sentences) → Evidence (data, examples, lists) |
| **Answer-first** | Direct answer in first 40–60 words after each H2 |
| **Answer blocks** | 100–200 words per section; direct answer + context + evidence |
| **Paragraph length** | 40–80 words; 2–4 sentences; avoid walls of text |
| **Break long blocks** | Lists, H3s, images, callout boxes every 2–3 paragraphs |
| **Scannability** | Front-load key info (F-pattern); **bold** key phrases; one idea per paragraph |

**Long-form (1,000+ words)**: Place engagement hooks every 500–600 words; mix 40–50% explanatory text, 20–25% examples, 10–15% data, 5–10% visuals.

### Conclusion

**Summary** + **CTA**: newsletter signup, related content, **product** (link to product/feature when relevant). Product-linked content ties to product naturally.

### Product Connection

Articles should tie to the product (problem it solves, features, use cases). Avoid purely generic content. Link to product/feature pages naturally in conclusion or when context fits.

## Writing Frameworks

Apply **copywriting** frameworks to article structure. See **copywriting** for full PAS, AIDA, BAB.

| Framework | Article use |
|-----------|-------------|
| **AIDA** | Intro (Attention); body (Interest, Desire); conclusion (Action/CTA) |
| **PAS** | How-to guides: Problem in intro; Agitation in body; Solution throughout |
| **BAB** | Case studies, transformation: Before → After → Bridge |

**Choose by audience**: AIDA for ready-to-buy; PAS for pain-driven; BAB for transformation seekers.

## Article Headlines

See **copywriting** for headline formulas (How to, Number, Problem→Solution). For article titles specifically:

- **Length**: 50–60 chars; see **title-tag**
- **Primary keyword** near start
- **Numbers** and power words boost CTR ~36%

## References & Citations

| Scenario | Practice |
|----------|----------|
| **Data or statistics** | Cite inline (e.g. "According to [Source](url), 72% of…") or in References section |
| **Expert quotes** | Attribute; link to source |
| **Reference section** | For 5+ citations; list at end before Related posts |
| **Format** | Inline links preferred; numbered refs [1], [2] for academic-style |

See **eeat-signals** for E-E-A-T, author bio, citations, YMYL.

## Content Quality

| Element | Guideline |
|---------|-----------|
| **Readability** | Grade 8–10 (Flesch-Kincaid); short sentences, clear language |
| **Depth** | Match type; comprehensive coverage over padding |
| **Originality** | Unique angle, data, examples; avoid thin or rehashed content |
| **Information gain** | What does this add that top 10 results don't? Counter-narrative, fresh data, SME quote, or proprietary insight |
| **E-E-A-T** | Author bio, citations, expert quotes — see **eeat-signals** |

## Content Audit Checklist

When auditing or optimizing article content:

| Dimension | Check |
|-----------|-------|
| **Hook** | Intro opens with pain point, stat, or question? |
| **Keyword in first 100 words** | Primary keyword present? |
| **QAE pattern** | H2s as questions? Answer-first (40–60 words) in each section? |
| **Word count** | Matches type? (300–600 news, 1,000–2,500 cluster, 2,500+ pillar) |
| **Paragraph length** | 40–80 words per paragraph? No walls of text? |
| **Product connection** | Ties to product? Natural links to features/pricing? |
| **CTA** | Placement (conclusion, mid-article); clarity; product link |
| **References** | Data/stats cited? Reference section for 5+ citations? |
| **Gaps** | What do top-ranking articles cover that this misses? |
| **Information gain** | At least one of: counter-narrative, fresh data, SME perspective, proprietary data? Or consensus rehash? |

See **competitor-research** for competitor analysis; **article-page-generator** for page structure and metadata.

## AI-Assisted Content

When content is AI-assisted: **human review** before publish; **verify facts** and add citations; **original insights** or data; avoid generic phrasing. See **eeat-signals** for E-E-A-T and AI content guidance.

## Output Format

- **Outline** (H2s with keyword placement)
- **TL;DR or Key Takeaways** (if SEO-driven)
- **Introduction** (hook + keyword)
- **Body** sections (QAE, answer-first)
- **Conclusion** (summary + CTA)
- **CTA copy** options

## Related Skills

- **article-page-generator**: Page structure, schema, metadata, layout; content goes here
- **copywriting**: Frameworks (PAS, AIDA, BAB); headline formulas; short conversion copy
- **content-marketing**: Article Orientations; content types
- **eeat-signals**: E-E-A-T; author bio; citations; citations format
- **keyword-research**: Keyword basis; search intent
- **competitor-research**: Content gaps; structure to adopt; SERP audit for information gain
- **content-optimization**: H2 keywords; Multimedia (tables, lists); keyword density
- **generative-engine-optimization**: GEO strategy; AI citation

---
name: url-slug-generator
description: When the user wants to create, optimize, or validate URL slugs for content pages. Also use when the user mentions "URL slug," "URL path," "blog URL," "article URL," "short URL," "clean slug," "permalink," "slug optimization," "URL structure," "SEO-friendly URL," "create URL slug," or "SEO slug." For site-wide URL policy, use url-structure.
metadata:
  version: 1.0.1
---

# Components: URL Slug

Guides creation of SEO-friendly URL slugs for blog posts, articles, and content pages. Research on 11.8M Google results shows shorter URLs tend to rank higher; position #1 URLs average 50–60 characters.

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

## Scope

- **URL slug**: The path segment after the base (e.g., `ai-people-search` in `/blog/ai-people-search`)
- **Applies to**: Blog posts, articles, guides, category pages, product pages

## Best Practices

### Length

| Guideline | Target |
|-----------|--------|
| **Slug length** | Under 60 characters total (including path prefix) |
| **Word count** | 3–5 words |
| **Principle** | Shorter = easier to read, share, remember; less truncation in SERPs; see **serp-features** |

**Example**: "The Complete Guide to AI Search Engine for Finding People" → `ai-people-search` (3 words) or `ai-search-finding-people` (4 words), not `ai-search-engine-finding-people-speed-discovery-outreach` (9 words, 51 chars).

### Format

| Rule | Do | Avoid |
|------|-----|-------|
| **Separators** | Hyphens (`-`) | Underscores (`_`), spaces, periods |
| **Case** | Lowercase only | Mixed case (causes duplicate content) |
| **Characters** | Letters (a-z), numbers (0-9), hyphens | Special chars |
| **Stop words** | Remove when possible: the, a, and, or, to | Keep when needed: "how-to" |

### Content

| Rule | Guideline |
|------|-----------|
| **Primary keyword** | Include near start; one focus per URL |
| **Descriptive** | Clear what page is about from slug alone |
| **No keyword stuffing** | One keyword mention is enough |
| **No dates** | Omit unless time-specific (news, annual roundups) |

### Non-ASCII Characters

| Scenario | Rule |
|----------|------|
| **Accented letters** | Convert to ASCII: é→e, ü→u, ñ→n, ç→c |
| **Non-Latin scripts** | Use UTF-8 percent-encoding if required; prefer ASCII for compatibility |
| **Example** | `jalapeno` not `jalapeño`; `cafe` not `café` |

### Common Mistakes

- **Copy-pasting full title**: Summarize instead — long title → short slug
- **Auto-generated IDs**: `/post/12847` — always customize
- **Tracking params in slug**: UTM, session IDs — use query params separately
- **Changing without redirect**: Always 301 from old to new slug

## Slug Generation Workflow

1. **Extract primary keyword** from title or target keyword
2. **Summarize** in 3–5 words (don't copy full title)
3. **Remove stop words** (the, a, and, or) unless needed for readability
4. **Lowercase, hyphenate**, validate length < 60 chars
5. **Check uniqueness** — no duplicate slugs site-wide

## Examples

| Title / Topic | ❌ Too long | ✅ Recommended |
|---------------|-------------|-----------------|
| AI Search Engine for Finding People: Speed vs. Discovery | `ai-search-engine-finding-people-speed-discovery-outreach` | `ai-people-search` or `ai-search-finding-people` |
| The Ultimate SEO Checklist for 2025 | `the-ultimate-seo-checklist-for-2025` | `seo-checklist-2025` |
| How to Increase Website Traffic | `how-to-increase-the-traffic-to-your-website` | `increase-website-traffic` |
| Best Running Shoes for Marathon Training | `best-running-shoes-for-marathon-training-in-2025` | `best-running-shoes-2025` |

## Output Format

When creating or auditing a slug:

- **Recommended slug** (3–5 words)
- **Character count** (slug only)
- **Primary keyword** included
- **Alternatives** if multiple valid options

- **Reference**: [Alignify URL optimization](https://alignify.co/zh/seo/url-optimization)

## Related Skills

- **url-structure**: URL hierarchy, site structure; references this skill for slug conventions
- **canonical-tag**: When changing slugs, set up 301 redirects
- **article-page-generator**: Article URL slugs
- **blog-page-generator**: Blog post URL slugs
- **glossary-page-generator**: Glossary term slugs
- **products-page-generator**: Product page slugs
- **customer-stories-page-generator**: Case study page slugs
- **resources-page-generator**: Resource page slugs
- **features-page-generator**: Per-feature page slugs

---
name: top-banner-generator
description: When the user wants to add, optimize, or audit a top announcement bar or sticky banner. Also use when the user mentions "announcement bar," "top banner," "sticky bar," "promo banner," "discount banner," "student discount banner," "header banner," "announcement bar design," "sticky header," "promo bar," "urgency banner," or "lead capture bar." For promos, use discount-marketing-strategy.
metadata:
  version: 1.1.1
---

# Components: Top Banner (Announcement Bar)

Guides top announcement bar and sticky banner design for conversion. Top banners answer visitor questions in ~3 seconds (trust, discount, free shipping, urgency) and can increase coupon redemption by 30-50% when used well.

**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 offers, messaging, and Section 12 (Visual Identity).

Identify:
1. **Goal**: Lead capture, promo, urgency, trust, free shipping
2. **Placement**: Above header (sticky) or below; dismissible or persistent
3. **Audience**: All visitors vs segmented (geo, returning, cart abandoners)

## Best Practices

### Use Cases

| Use | Example |
|-----|---------|
| **Lead capture** | Newsletter, lead magnet, demo request |
| **Promo** | Discount code, flash sale, free shipping threshold |
| **Urgency** | Limited-time offer, countdown |
| **Trust** | Guarantee, security, shipping info |
| **Launch** | Product launch, event, cross-sell |

### Discount Banner Types

| Discount Type | Banner Example | Related |
|---------------|----------------|---------|
| **Annual discount** | "Save 20% with annual billing" | discount-marketing-strategy |
| **Student/education** | "Students: 30% off today, 15% off ongoing" | education-program |
| **Startups/education** | "Startups: Special pricing — Apply now" | startups-page-generator |
| **BFCM / seasonal** | "Black Friday: 25% off — Use code BF25" | discount-marketing-strategy |
| **First-time** | "New users: 20% off first year" | discount-marketing-strategy |
| **Referral code** | "Get $10 off — Refer a friend" | referral-program |

**Placement**: Discount banner is P1 for student/education (homepage); pricing page also shows. See **education-program** for placement priority (registration P0, pricing P1, banner P1).

### Design

- **Clear hierarchy**: Message + CTA in ~400ms "blink test"
- **Minimal copy**: One line typical; link for "Learn more"
- **High contrast**: Stand out from page; CTA color distinct
- **Mobile-first**: 70%+ traffic on mobile; thumb-friendly close/CTA

### Technical

- **Desktop**: 1920x600px keeps content above fold; 16:9 common
- **Mobile**: 800x1200px (2:3 portrait); use separate assets, not scaled
- **Performance**: Optimize images; oversized banners hurt LCP and SEO

### Avoid

- Crowding the header; leave space for nav and logo
- Too many CTAs; one primary action
- Stale messaging; refresh every 2-4 weeks

## Output Format

- **Message** and CTA copy
- **Placement** (sticky top, below header)
- **Targeting** (all vs segment)
- **Design** notes (contrast, mobile)

## Related Skills

- **discount-marketing-strategy**: Promo/discount strategy; banner displays discount code; 30–50% redemption lift
- **education-program**: Student discount banner (P1 placement); "Students: X% off" copy
- **pricing-page-generator**: Discount banner supports pricing page; Special programs, promo placement
- **cta-generator**: Banner CTA design
- **newsletter-signup-generator**: Lead capture in banner
- **brand-visual-generator**: Colors, typography for banner
- **navigation-menu-generator**: Banner sits above or integrates with nav

---
name: social-share-generator
description: When the user wants to add, optimize, or audit social share buttons (share article to X, LinkedIn, Facebook, etc.). Also use when the user mentions "share buttons," "social share," "share to X," "share to LinkedIn," "social sharing," "share icons," "share widget," "native share," "Web Share API," or "share intent URLs." For link previews, use open-graph.
metadata:
  version: 1.0.1
---

# Components: Social Share Buttons

Guides implementation of **share buttons** that let users share the current page (article, post, product) to social platforms. Distinct from **social profile links** (footer links to your brand's X, LinkedIn, etc.) — share buttons share *this* content.

**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.

## Scope

- **Share buttons**: Share current page URL to X, LinkedIn, Facebook, WhatsApp, etc.
- **Not** social profile links (e.g. "Follow us on X") — those live in footer/nav

## Why It Matters

- Websites with visible social share icons tend to see higher social engagement
- Share buttons amplify reach; Open Graph and Twitter Cards control preview — see **open-graph**, **twitter-cards**

## Placement (Article Pages)

**Fewer, better-placed buttons outperform scattered placement.** Research: removing 80% of buttons and repositioning the remaining 20% at high-emotion moments can **3× conversion** on share actions.

| Placement | Best For | Notes |
|-----------|----------|-------|
| **After first paragraph** | Most articles | Catches speed-readers; visible early |
| **Sticky sidebar** | Long-form (desktop) | Always visible; consider hiding on mobile |
| **Below title / hero** | Short posts | High visibility |
| **End of article** | All | Natural completion point; pair with CTA |
| **Mid-article** (after key insight) | Long content | Place at friction points (after surprising stat, before CTA) |

**Avoid**: Dozens of icons; every platform when audience uses 2–3. Choose 3–5 platforms that match your audience (e.g. B2B: X, LinkedIn; B2C: X, Facebook, WhatsApp).

## Share URLs (Intent Links)

Use platform share/intent URLs so users share with one click:

| Platform | Share URL pattern |
|----------|-------------------|
| **X (Twitter)** | `https://twitter.com/intent/tweet?url={url}&text={text}` |
| **LinkedIn** | `https://www.linkedin.com/sharing/share-offsite/?url={url}` |
| **Facebook** | `https://www.facebook.com/sharer/sharer.php?u={url}` |
| **WhatsApp** | `https://wa.me/?text={url}%20{text}` |
| **Telegram** | `https://t.me/share/url?url={url}&text={text}` |

Encode `url` and `text` with `encodeURIComponent()`. Use page title or a short pre-written message for `text` — **platform-specific prompts with pre-written messages perform ~4× better than generic icons**.

## Platform Brand Guidelines (Icons)

Use official brand assets. Minimum sizes and color rules:

| Platform | Min size | Colors | Notes |
|----------|----------|--------|-------|
| **Facebook** | 16px | Blue #1877F2 or monochrome | No rotation, animation without permission |
| **X (Twitter)** | 32px | Black or white only | Use current X logo, not deprecated bird |
| **LinkedIn** | 21px height | Blue #0A66C2 or monochrome | Use "in" bug for icons |
| **Instagram** | 29×29px | Black, white, or official gradient | Glyph for social icons |

Source icons from official brand resource centers. Outdated or non-compliant icons reduce perceived shareability.

## Design & Technical

| Item | Guideline |
|------|-----------|
| **Format** | SVG preferred (scalable, small); PNG/WebP with fallback |
| **Performance** | Lightweight; avoid heavy share plugins that slow LCP |
| **Accessibility** | `aria-label="Share on X"`; keyboard accessible |
| **Mobile** | Touch targets ≥44×44px; consider native share API (`navigator.share`) on mobile |

## Native Share API (Mobile)

On supported browsers, `navigator.share` lets users share via system dialog (includes more apps). Fallback to intent links when unsupported:

```javascript
if (navigator.share) {
  navigator.share({ title, url, text }).catch(() => {});
} else {
  window.open(shareUrl, '_blank', 'noopener');
}
```

## Output Format

- **Placement** recommendation for page type
- **Platforms** to include (3–5)
- **Share URL** examples with placeholders
- **Icon** guidelines (size, source)
- **Accessibility** checklist

## Related Skills

- **article-page-generator**: Share buttons on article pages; placement after intro, end of article
- **blog-page-generator**: Share buttons on blog index and post cards
- **open-graph**: OG tags control share preview (og:image, og:title, etc.) — required for share buttons to show rich cards on Facebook, LinkedIn
- **twitter-cards**: Twitter Cards control X preview — required for share buttons to show rich cards when shared to X
- **footer-generator**: Footer has social *profile* links (Follow us); this skill is for *share* buttons (share this page)

---
name: toc-generator
description: When the user wants to add, optimize, or audit table of contents (TOC) for long-form content. Also use when the user mentions "TOC," "table of contents," "table of contents for article," "article TOC," "jump links," "content outline," "article navigation," "in-page navigation," "add TOC to blog," or "TOC for long content." For article SEO template, use article-page-generator.
metadata:
  version: 1.0.1
---

# Components: Table of Contents (TOC)

Guides TOC implementation for long-form articles, guides, and whitepapers. TOCs improve UX and SEO by enabling quick navigation and reducing bounce rates.

**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 content structure.

Identify:
1. **Content type**: Blog article, guide, whitepaper, documentation
2. **Length**: TOC most valuable for 1000+ word content
3. **Platform**: Web, mobile, both

## Placement Strategies

| Placement | Best For | Pros | Cons |
|-----------|----------|------|------|
| **After intro** | Most articles | Natural flow; visible early | Can scroll out of view |
| **Floating sidebar** | Very long content | Always visible | More complex; mobile challenges |
| **Collapsible** | Long articles | Less intrusive | May be overlooked |
| **Top of article** | Mobile-first | Accessible on all devices | Takes space |

## Technical Implementation

### Heading Structure

- One `<h1>` per page
- `<h2>` for major sections
- `<h3>` for subsections; avoid skipping levels
- Headings >=15 characters for SEO

### Jump Links

- Assign unique IDs to headings (e.g., `id="keyword-optimization"`)
- Use kebab-case for IDs
- Link TOC entries via anchor tags (`#section-id`)
- Descriptive anchor text; include target keywords naturally

### Semantic HTML

```html
<nav aria-label="Table of contents">
  <ol>
    <li><a href="#section-1">Section Title</a></li>
  </ol>
</nav>
```

## SEO Best Practices

| Practice | Purpose |
|----------|---------|
| **Schema.org TableOfContents** | Help search engines understand structure |
| **Keywords in headings** | Natural integration; avoid stuffing |
| **Jump links in SERP** | Google may feature TOC links; increases CTR; see **serp-features** |

## UX Guidelines

### Visibility & Interaction

- Clear visual hierarchy; indent nested items
- Highlight current section when scrolling (optional)
- Smooth scroll behavior for jump links

### Mobile

- Minimum 16px font size
- Touch targets >=44x44px
- Responsive layout; consider collapsible on small screens

### Accessibility

| Requirement | Practice |
|-------------|----------|
| **ARIA** | `aria-label="Table of contents"` on nav |
| **Keyboard** | All links keyboard-accessible |
| **Screen readers** | Proper heading structure; TOC aids skimming |

## Output Format

- **TOC structure** (sections, nesting)
- **Heading/ID mapping** suggestions
- **HTML/ARIA** notes
- **SEO** checklist

## Related Skills

- **tab-accordion**: Collapsible TOC uses same disclosure pattern; details/summary implementation
- **heading-structure**: TOC built from heading structure
- **content-optimization**: H2 structure, lists, tables for Featured Snippets
- **featured-snippet**: Featured Snippet optimization; TOC supports snippet structure
- **serp-features**: SERP features; jump links in results
- **article-page-generator**: TOC common in long-form article pages

---
name: sidebar-generator
description: When the user wants to design, optimize, or audit a sidebar for blogs, docs, or content pages. Also use when the user mentions "sidebar," "blog sidebar," "content sidebar," "side panel," "sidebar navigation," "related content," "sidebar CTA," "doc sidebar," or "sidebar widgets." For blog layout, use blog-page-generator.
metadata:
  version: 1.0.1
---

# Components: Sidebar

Guides sidebar design for content sites (blogs, docs). ~80% of users focus on the left; sidebars influence flow but can hurt conversion if overused. Posts without sidebars show 3.1x higher conversion; bottom-right sticky CTAs outperform sidebars (5.62% vs 0.58% CTR).

**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 content structure and conversion goals.

Identify:
1. **Content type**: Blog, docs, e-commerce
2. **Primary goal**: Navigation, CTA, related content
3. **Mobile**: Collapse to hamburger or hide on small screens

## Best Practices

### Placement

- **Left sidebar**: Prime for nav; 80% of users focus left
- **Right sidebar**: Secondary content, ads, related posts
- **Static vs sticky**: Static for content-focused; sticky for persistent CTA (subscription, cart)

### Conversion Reality

| Approach | Typical result |
|----------|----------------|
| **Sidebar CTA** | <1% opt-in for blog sidebars |
| **In-content CTA** | 3x+ higher conversion |
| **Bottom-right sticky** | 5.62% CTR vs 0.58% sidebar |
| **No sidebar** | 3.1x higher conversion vs with sidebar |

**Recommendation**: Prefer in-content CTAs or bottom-right sticky over sidebar CTAs. Use sidebar for nav and discovery, not primary conversion.

### Widget Guidelines

- **One high-value CTA** max; avoid clutter
- **Social proof**: Testimonials, logos
- **Popular/related posts**: Discovery, internal linking
- **Avoid**: Too many ads, affiliate links; reduces trust and speed

### Mobile

- **Collapse**: Hamburger or off-canvas drawer
- **57%+ mobile traffic**: Responsive design non-negotiable
- **Reduce clutter**: Hide or simplify sidebar on small screens

## Output Format

- **Placement** (left/right, static/sticky)
- **Widget** list (nav, CTA, related, social proof)
- **Mobile** behavior
- **Conversion** note (in-content vs sidebar CTA)

## Related Skills

- **toc-generator**: TOC often in sidebar for long content
- **cta-generator**: Sidebar CTA (use sparingly)
- **newsletter-signup-generator**: Sidebar signup; consider in-content instead
- **internal-links**: Related posts in sidebar

---
name: navigation-menu-generator
description: When the user wants to design, optimize, or audit site navigation menus. Also use when the user mentions "navigation," "nav menu," "header menu," "site structure," "menu design," "navbar," "main menu," "mega menu," "dropdown menu," "mobile menu," or "hamburger menu." For breadcrumbs, use breadcrumb-generator.
metadata:
  version: 1.0.1
---

# Components: Navigation Menu

Guides navigation menu design for SEO, UX, and accessibility. Navigation helps users find content and signals site structure to search engines.

**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 key pages and audience.

Identify:
1. **Site structure**: Main sections, hierarchy
2. **Primary goals**: Conversion paths, key pages
3. **Platform**: Web, mobile, both

## Structure & Organization

### Menu Size

- **Primary nav**: 7-9 items; avoid overwhelming users
- **Sub-navigation**: Up to 2 levels; deeper topics in sub-menus
- **Pattern**: Horizontal top nav or vertical side nav; avoid novel patterns

### Hierarchy

- Reflect sitemap structure; need not match exactly
- Prioritize what visitors need most
- Logical grouping by topic or task

## SEO Best Practices

| Practice | Purpose |
|----------|---------|
| **Semantic HTML** | `<nav>`, `<ul>`, `<li>`; proper landmark roles |
| **Descriptive anchor text** | Target keywords; avoid "Click here" |
| **Text links** | Prefer text over images; crawlers need readable links |
| **Initial render** | All nav HTML in first paint; no JS-only menus for critical links. See **rendering-strategies** |
| **Visible links** | Prefer visible over hidden; helps crawlers understand structure |

### Crawlability

- Sub-menus: Ensure HTML is in DOM (e.g., CSS-hidden, not JS-injected)
- Footer nav: Include secondary links
- Breadcrumbs: See **breadcrumb-generator** for implementation

## UX Guidelines

### Visibility & Location

- **Desktop**: Visible nav; avoid hiding behind hamburger when space allows
- **Expected placement**: Primary nav in header; footer nav at bottom
- **Current location**: Indicate active page/section in menu

### Accessibility

| Requirement | Practice |
|-------------|----------|
| **Labels** | Clear, intuitive wording |
| **Contrast** | 4.5:1 for link text |
| **Touch targets** | >=44x44px; adequate spacing |
| **Keyboard** | Full keyboard navigation; focus visible |
| **Screen readers** | Proper ARIA; skip links for long menus |

### Design

- Simple, clear; avoid covering entire screen with open menus on desktop
- Consistent across pages
- Mobile: Hamburger acceptable; ensure menu is usable when open

## Output Format

- **Structure** (primary items, sub-items)
- **Anchor text** suggestions
- **HTML/ARIA** notes
- **SEO** checklist
- **Accessibility** checklist

## Related Skills

- **website-structure**: Plan structure and nav hierarchy; nav reflects planned sections
- **xml-sitemap**: Nav should reflect discoverable pages
- **internal-links**: Nav is primary internal linking
- **site-crawlability**: Nav affects crawl paths
- **category-page-generator**: Category hierarchy in nav
- **footer-generator**: Footer nav complements header nav
- **logo-generator**: Logo typically sits in header with nav
- **breadcrumb-generator**: Breadcrumb navigation; BreadcrumbList schema
- **rendering-strategies**: Nav in first paint; no JS-only menus

---
name: footer-generator
description: When the user wants to design, optimize, or audit website footers. Also use when the user mentions "footer," "page footer," "site footer," "footer links," "footer navigation," "footer SEO," "footer design," "footer CTA," "multi-column footer," or "footer sitemap." For main nav, use navigation-menu-generator.
metadata:
  version: 1.0.1
---

# Components: Footer

Guides footer design for SEO, UX, and conversion. Footers provide secondary navigation, support crawlability, and engage users below the fold (66% of engagement happens there).

**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 key pages and audience.

Identify:
1. **Site type**: Marketing, e-commerce, SaaS, blog
2. **Footer goals**: Navigation, lead capture, trust, legal
3. **Platform**: Web, mobile, both

## Essential Footer Elements

### Navigation & Links

- Links to high-priority pages: About, Contact, Services, FAQs
- Related blog posts and internal content links
- XML or HTML sitemap links
- Product/service category links (e-commerce)
- **Avoid excessive links**: Google warns that too many internal links can harm SEO; link only to high-priority pages

### Business Information

- Physical address, phone, email
- Social media profile links (Follow us) -> distinct from **social-share-generator** (share this page)
- Copyright and legal information (Privacy Policy, Terms of Service)

### User Engagement

- Newsletter signup forms
- Call-to-action buttons
- Customer testimonials or support resources

## SEO Best Practices

| Practice | Purpose |
|----------|---------|
| **Strategic linking** | Link to important pages; avoid link bloat |
| **Descriptive anchor text** | Target keywords; avoid "Click here" |
| **Text links** | Prefer text over images for crawlers |
| **No dead ends** | Ensure pages link to other content |
| **Semantic HTML** | `<footer>`, proper landmark roles |

### Link Strategy

- Footer links help crawlers discover pages and understand site structure
- Too many links can dilute page context; keep focused
- Include sitemap link for comprehensive discovery

## UX Guidelines

### Placement & Visibility

- Footer at bottom; visible without dominating desktop view
- Mobile: Valuable for users who don't scroll to top
- Secondary navigation; complements header nav

### Organization

- Group links by category (Product, Company, Legal, Support)
- Use clear headings for each column
- Prioritize most-used links

### Accessibility

| Requirement | Practice |
|-------------|----------|
| **Contrast** | 4.5:1 for link text |
| **Touch targets** | >=44x44px on mobile |
| **Keyboard** | Full keyboard navigation |
| **Screen readers** | Proper heading hierarchy, landmark roles |

## Output Format

- **Footer structure** (columns, link groups)
- **Link list** with anchor text suggestions
- **SEO** checklist
- **Accessibility** checklist

## Related Skills

- **navigation-menu-generator**: Footer complements header nav
- **social-share-generator**: Footer has profile links (Follow us); social-share has share buttons (share this page) -> different use cases
- **xml-sitemap**: Footer can link to sitemap
- **internal-links**: Footer is secondary internal linking
- **newsletter-signup-generator**: Footer often hosts signup forms

---
name: breadcrumb-generator
description: When the user wants to add, optimize, or audit breadcrumb navigation. Also use when the user mentions "breadcrumbs," "breadcrumb trail," "breadcrumb nav," "breadcrumb links," "path navigation," "site breadcrumb," "BreadcrumbList schema," "location-based breadcrumb," "attribute-based breadcrumb," "site hierarchy display," "add breadcrumbs," or "breadcrumb SEO." For BreadcrumbList JSON-LD, use schema-markup. For main nav, use navigation-menu-generator.
metadata:
  version: 1.2.0
---

# Components: Breadcrumb Navigation

Guides breadcrumb implementation for SEO, UX, and GEO. Breadcrumbs show users their location in the site hierarchy and help search engines understand content taxonomy. Well-implemented breadcrumbs can increase CTR by 20–30%, reduce bounce rates by up to 30%, and strengthen internal linking.

**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.

## Scope

- **Breadcrumb UI**: Visual trail (Home > Category > Page)
- **BreadcrumbList schema**: JSON-LD structured data for rich results
- **Placement**: Typically below header, above main content

## Breadcrumb Types

| Type | Use case | Recommendation |
|------|----------|----------------|
| **Location-based** | Reflects site hierarchy (Home > Blog > SEO > Page) | **Recommended** — most SEO-friendly; clear structure |
| **Attribute-based** | Shows product attributes (Home > Electronics > Phone > iPhone 15) | E-commerce; product classification |
| **Path-based** | Shows user's browsing path | **Avoid** — different users, different paths; can cause confusion |

**Default**: Use location-based for most sites. Use attribute-based for e-commerce product pages.

## Initial Assessment

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

Identify:
1. **Site structure**: Hierarchy depth (e.g., Home > Category > Subcategory > Product)
2. **Page types**: Blog, e-commerce, docs, etc.
3. **Multi-category**: Products in multiple categories—need canonical path

## Best Practices

### Structure & Hierarchy

| Practice | Guideline |
|----------|-----------|
| **Depth** | 3–5 levels optimal; avoid very long trails |
| **Anchor text** | Keyword-rich, human-readable; descriptive |
| **Consistency** | Same pattern across all pages (blog, category, product) |
| **Canonical path** | For items in multiple categories, define one canonical breadcrumb to avoid diluted link equity |

### Schema (BreadcrumbList)

See **schema-markup** for BreadcrumbList requirements, JSON-LD example, and multiple paths. Schema must match visible breadcrumbs exactly.

### Placement & Design

| Practice | Guideline |
|----------|-----------|
| **Position** | Below nav bar or above page title; top of content area |
| **Visual** | Smaller font, lighter color; avoid competing with main content |
| **Separator** | Clear separator (>, /, ›); consistent across site |
| **Naming** | Match page title or nav menu; concise, descriptive |

### UX & Accessibility

| Practice | Guideline |
|----------|-----------|
| **Mobile** | Tappable; short, readable text; high contrast |
| **Long trails** | Horizontal scroll container rather than truncating |
| **Current page** | Last item non-linked; use `aria-current="page"` |
| **Screen readers** | `nav` with `aria-label="Breadcrumb"`; proper landmark |

### SEO Impact

- **Internal linking**: Breadcrumbs distribute link equity
- **Crawlability**: Helps crawlers understand taxonomy
- **GEO**: BreadcrumbList appears frequently on pages cited by Google AI Mode
- **Note**: Google removed visual breadcrumbs from mobile SERPs (Jan 2025) to save space, but schema and algorithmic value remain important for crawlers and AI. See **serp-features** for breadcrumb SERP display.

## Implementation

### Semantic HTML

```html
<nav aria-label="Breadcrumb">
  <ol itemscope itemtype="https://schema.org/BreadcrumbList">
    <li itemprop="itemListElement" itemscope itemtype="https://schema.org/ListItem">
      <a itemprop="item" href="https://example.com/"><span itemprop="name">Home</span></a>
      <meta itemprop="position" content="1" />
    </li>
    <li itemprop="itemListElement" itemscope itemtype="https://schema.org/ListItem">
      <a itemprop="item" href="https://example.com/category/"><span itemprop="name">Category</span></a>
      <meta itemprop="position" content="2" />
    </li>
    <li itemprop="itemListElement" itemscope itemtype="https://schema.org/ListItem" aria-current="page">
      <span itemprop="name">Current Page</span>
      <meta itemprop="position" content="3" />
    </li>
  </ol>
</nav>
```

**Implementation**: Generate BreadcrumbList from route segments or page metadata. Ensure `item` URLs are absolute. Use `next-seo` BreadcrumbJsonLd or custom component. See **schema-markup** for JSON-LD structure.

## When to Use Breadcrumbs

| Site type | Use case |
|-----------|----------|
| **E-commerce** | Category > Subcategory > Product |
| **Blog** | Home > Blog > Category > Post (see **article-page-generator** for article page structure) |
| **Docs** | Home > Docs > Section > Page |
| **Large sites** | Any site with 3+ level hierarchy |

**Skip** on flat sites (e.g., single-page, 1–2 level depth).

**Deep pages**: For 6+ levels, consider omitting middle levels; show only the most important categories to avoid clutter.

## Platform Notes

| Platform | Options |
|----------|---------|
| **WordPress** | Yoast SEO, Rank Math, Breadcrumb NavXT |
| **Next.js** | next-seo BreadcrumbJsonLd, custom from route segments |
| **Shopify, Drupal, Joomla** | Built-in or plugin support |

## Common Errors

| Error | Fix |
|-------|-----|
| Relative URLs in schema | Use absolute URLs (https://) |
| Schema doesn't match visible trail | Keep schema and UI in sync |
| Missing position | Include sequential position (1, 2, 3…) |
| Last item linked | Current page typically not a link |
| Too many levels | Limit to 5–7; omit middle levels for deep paths |
| Inaccurate path | Breadcrumb must reflect actual site structure |
| No schema | Add BreadcrumbList per **schema-markup**; otherwise no SERP breadcrumbs; see **serp-features** |

## Output Format

- **Structure** recommendation (levels, labels)
- **BreadcrumbList** JSON-LD — see **schema-markup** for structure; with absolute URLs
- **HTML** structure (semantic, accessible)
- **Placement** (below header, above main)
- **Validation**: [Rich Results Test](https://search.google.com/test/rich-results), [Schema Markup Validator](https://validator.schema.org/), Search Console enhanced report

## Related Skills

- **article-page-generator**: Article pages use breadcrumbs (Home > Blog > Category > Post)
- **schema-markup**: BreadcrumbList schema implementation; JSON-LD structure, requirements
- **navigation-menu-generator**: Header nav; breadcrumbs complement primary nav
- **internal-links**: Breadcrumbs are internal links; distribute link equity
- **site-crawlability**: Breadcrumbs help crawlers understand structure
- **category-page-generator**: Category hierarchy in breadcrumbs
- **products-page-generator**: Product pages often need breadcrumbs (Category > Product)
- **serp-features**: Breadcrumb SERP display; rich results

---
name: masonry
description: When the user wants to design, optimize, or audit masonry (Pinterest-style) layouts for content display. Also use when the user mentions "masonry layout," "masonry grid," "Pinterest layout," "waterfall layout," "brick layout," "varying height grid," "gallery layout," or "masonry SEO." For crawl and scroll UX, use site-crawlability.
metadata:
  version: 1.1.1
---

# Components: Masonry Layout

Guides masonry layout design for content with varying heights. Masonry stacks items in columns without distinct rows; items fill gaps like a brick wall. Best for image galleries, portfolios, and discovery-focused platforms.

**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.

## When to Use Masonry

| Use masonry when | Use grid when |
|------------------|---------------|
| **Varying heights** | Equal-height items |
| Image-heavy; varied aspect ratios | Products, templates (consistent) |
| Gallery, portfolio, showcase | Card grid |
| Discovery, browsing; visual-first | Structured browsing |

See **grid** for equal-height grid; **card** for card structure.

## Masonry vs Grid vs Bento vs Carousel

| Layout | Structure | Best for |
|--------|-----------|----------|
| **Grid** | Equal rows and columns; uniform items | Products, templates, features |
| **Masonry** | Columns; items stack without rows; gaps filled | Pinterest, Behance; varied content |
| **Bento** | Intentional sections; predefined sizes | Homepage, dashboard; Apple-style |
| **Carousel** | Slides; one/few visible; swipe/click | Testimonials, logos, featured items; see **carousel** |

## Masonry Structure

| Element | Purpose |
|---------|---------|
| **Columns** | 2–4 columns; fluid or fixed |
| **Items** | Varying heights; natural aspect ratio |
| **Gap** | Consistent horizontal and vertical spacing |
| **Order** | Top-to-bottom fill within columns |

## Implementation

- **CSS columns**: `column-count`; simple, no JS; but items flow top-to-bottom then next column
- **Masonry.js / libraries**: True masonry (left-to-right fill); may need JS
- **CSS Grid + `grid-auto-flow: dense`**: Approximate; no JS; see **grid** for dense grid

**Note**: Pure masonry can create accessibility challenges (screen reader order); ensure logical DOM order.

## SEO Considerations

**Masonry + infinite scroll = content not crawlable.** Masonry galleries often use infinite scroll or lazy load; crawlers cannot emulate scroll or "Load more" clicks, so content beyond the initial view is not discoverable.

| If you use | Then |
|------------|------|
| **Infinite scroll** | Provide paginated component pages with full URLs; implement pushState; see **site-crawlability** for search-friendly infinite scroll |
| **Lazy load** | Ensure content exists in HTML or is reachable via crawlable links |
| **Pagination** | Prefer for SEO-critical content; crawlers can follow next/prev links |

**Reference**: [Google – Infinite scroll search-friendly recommendations](https://developers.google.com/search/blog/2014/02/infinite-scroll-search-friendly)

## Best Practices

| Principle | Practice |
|-----------|----------|
| **Visual-first** | Thumbnails; minimal text |
| **Aspect ratio** | Preserve original; avoid forced cropping |
| **Lazy load** | Many images; load on scroll |
| **Performance** | Masonry can be heavy; consider grid for simpler cases |

## Use Cases

| Use case | Format | Page Skill |
|----------|--------|------------|
| **Showcase / Gallery** | User work; varied sizes | **showcase-page-generator** |
| **Portfolio** | Projects; mixed media | — |
| **Pinterest-style** | Pins; discovery | — |
| **Image-heavy blog** | Blog with varied images | **blog-page-generator** |

## Related Skills

- **site-crawlability**: Infinite scroll SEO; paginated component pages; search-friendly implementation
- **grid**: Equal-height grid; when masonry is overkill
- **carousel**: Carousel for slides/rotation; when masonry is overkill
- **card**: Card structure; masonry often uses cards
- **showcase-page-generator**: Gallery masonry
- **image-optimization**: Lazy load, aspect ratio, LCP

---
name: list
description: When the user wants to design, optimize, or audit list layouts for content display. Also use when the user mentions "list layout," "list design," "vertical list," "stacked list," "blog list," "article list," "documentation list," "search results layout," or "infinite scroll list." For blog index page, use blog-page-generator.
metadata:
  version: 1.1.1
---

# Components: List Layout

Guides list layout design for linear, stacked content display. Lists are compact, text-heavy; users scan by title or metadata. Used for blog indexes, documentation, search results, and dense content.

**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.

## When to Use List

| Use list when | Use grid when |
|---------------|---------------|
| Text-heavy; scan by title | Visual content; equal emphasis |
| Many items; compact display | Fewer items; browsing |
| Blog index, docs, search results | Products, templates, gallery |
| F-pattern reading (top-left, left column) | Discovery, exploration |

See **grid** for grid layout; **card** for card structure.

## List Structure

| Element | Purpose |
|---------|---------|
| **Items** | Single column; stacked vertically |
| **Per item** | Title, optional metadata (date, author), excerpt, link |
| **Spacing** | Consistent gaps; dividers or alternating background |
| **Density** | Compact (docs) vs relaxed (blog) |

## List Variants

| Variant | Use |
|---------|-----|
| **Simple list** | Title + link; minimal (nav, TOC) |
| **Rich list** | Title, excerpt, date, author | Blog index |
| **Table-like** | Columns for metadata (date, status) | Docs, admin |
| **With thumbnail** | Small image + text | Blog with thumbnails |

## Best Practices

| Principle | Practice |
|-----------|----------|
| **Scannable** | Clear titles; consistent hierarchy |
| **Compact** | Less vertical space than grid |
| **Link area** | Full row or title clickable |
| **Metadata** | Date, author, category; secondary styling |

## F-Pattern

Users read top-left first, then scan left column. Place primary content (titles) left-aligned; metadata secondary.

## Infinite Scroll

If using infinite scroll for list (e.g., blog index, search results): crawlers cannot access content loaded on scroll. Provide paginated component pages or use traditional pagination for SEO-critical content. See **site-crawlability** for search-friendly infinite scroll implementation.

## Responsive

- **Mobile**: Single column; full-width items
- **Touch targets**: ≥44×44px for touchable rows
- **Truncation**: Long titles; ellipsis or wrap by design

## Related Skills

- **site-crawlability**: Infinite scroll SEO; paginated component pages; search-friendly implementation
- **grid**: Grid vs list; when to use each
- **carousel**: Carousel for slides; when list is too long for space
- **card**: Card in list (e.g., blog with thumbnail)
- **toc-generator**: TOC as list; jump links
- **blog-page-generator**: Blog index list
- **article-page-generator**: Article list format
- **docs-page-generator**: Documentation list

---
name: grid
description: When the user wants to design, optimize, or audit grid layouts for content display. Also use when the user mentions "grid layout," "grid design," "multi-column grid," "CSS grid," "responsive grid," "card grid," "product grid," or "feature grid." For cards layout, use card.
metadata:
  version: 1.0.1
---

# Components: Grid Layout

Guides grid layout design for equal-hierarchy, multi-column content display. Grids display multiple items with equal emphasis; space-efficient and scannable. Used for products, templates, tools, features, blog indexes, and galleries.

**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.

## When to Use Grid

| Use grid when | Use list when |
|---------------|---------------|
| Visual content (images, thumbnails) | Text-heavy; scan by title |
| Equal emphasis across items | Compact; many items; dense info |
| Products, templates, gallery, features | Blog index, docs, search results |
| Browsing, discovery | Reading, scanning |

See **list** for list layout; **card** for card structure within grid.

## Grid Structure

| Element | Purpose |
|---------|---------|
| **Columns** | 1–4+ columns; adapt to viewport |
| **Gap** | Consistent spacing between items |
| **Items** | Equal or proportional sizing |
| **Responsive** | 1 col mobile → 2–4 cols desktop |

## Implementation

- **CSS Grid**: `repeat(auto-fill, minmax(min, 1fr))` or `repeat(auto-fit, minmax())` for fluid columns
- **Breakpoints**: e.g., 1 col <768px; 2 cols 768–1024px; 3–4 cols >1024px
- **Consistency**: Same padding, aspect ratios across items; see **card** for card structure

## Best Practices

| Principle | Practice |
|-----------|----------|
| **Equal hierarchy** | Items compete equally; no single dominant item |
| **Consistent sizing** | Same card/item dimensions in grid |
| **Gap consistency** | Uniform gap (e.g., 16px, 24px) |
| **No layout shift** | Reserve space for images; avoid CLS |

## Responsive

- **Mobile**: Single column; full-width items
- **Tablet**: 2 columns; touch targets ≥44×44px
- **Desktop**: 3–4 columns; hover states OK

## Infinite Scroll

If using infinite scroll with grid: crawlers cannot access content loaded on scroll. Provide paginated component pages for SEO-critical content. See **site-crawlability** for search-friendly implementation.

## Related Skills

- **site-crawlability**: Infinite scroll SEO; paginated component pages
- **card**: Card structure within grid; product, template, tool cards
- **list**: List layout vs grid; when to use each
- **masonry**: Masonry for varying heights (Pinterest-style)
- **carousel**: Carousel for slides/rotation; when grid is too dense
- **hero-generator**: Hero above; grid below for content sections
- **products-page-generator**: Product grid
- **template-page-generator**: Template grid
- **features-page-generator**: Feature grid

---
name: carousel
description: When the user wants to design, optimize, or audit carousel/slider layouts for content display. Also use when the user mentions "carousel," "slider," "carousel layout," "testimonial carousel," "gallery carousel," "quote carousel," "image slider," or "carousel accessibility." For hero-area patterns, use hero-generator.
metadata:
  version: 1.1.0
---

# Components: Carousel Layout

Guides carousel (slider) layout design for sequential content display. Carousels show one or few items at a time; users swipe or click to advance. Best when space is limited and multiple items need rotation—testimonials, quotes, logos, gallery highlights.

**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.

## When to Use Carousel

| Use carousel when | Use grid/list when |
|-------------------|---------------------|
| **Limited space** | Full catalog visible |
| One focus at a time; rotation desired | Browse, compare many items |
| Testimonials, quotes, logos, featured gallery | Products, templates, blog index |
| Above fold; hero or section highlight | Full listing; discovery |

See **grid** for equal-hierarchy display; **list** for text-heavy scan; **masonry** for varying-height gallery.

## Carousel vs Grid vs List vs Masonry

| Layout | Structure | Best for |
|--------|-----------|----------|
| **Grid** | Equal rows and columns; all visible | Products, templates, features |
| **List** | Single column; stacked | Blog index, docs, search results |
| **Masonry** | Columns; varying heights | Pinterest-style gallery |
| **Carousel** | Slides; one/few visible; swipe/click | Testimonials, logos, featured items |

## Best Practices

### Accessibility

- **Keyboard navigation**: Arrow keys to move; Enter/Space to activate; focus visible
- **User control**: Don't auto-advance too fast; allow pause; avoid auto-advance if `prefers-reduced-motion` is set
- **Announcements**: Screen reader users need to know current slide and total (e.g., "Slide 2 of 5")
- **Touch targets**: ≥44×44px for prev/next buttons on mobile

### Performance

- **Lazy load**: Load off-screen slides on demand; avoid loading all images upfront
- **Reserve space**: Reserve space for slides to avoid layout shift (CLS)

### SEO

- **Content in DOM**: All carousel content must be in the initial HTML at page load. Google does not simulate clicks; content loaded via AJAX on slide change is not discoverable. Same as **tab-accordion**.
- **Recommendation**: Server-render all slides in HTML; use CSS/JS only to show/hide. See **rendering-strategies**.

## Use Cases

| Use case | Format | Page Skill |
|----------|--------|------------|
| **Testimonials** | Quote carousel; multiple testimonials | **testimonials-generator** |
| **Showcase / Gallery** | Featured items; rotation | **showcase-page-generator** |
| **Press logos** | "As Seen In" logo strip or quote carousel | **press-coverage-page-generator** |
| **Community** | Banner carousel below hero | **community-forum** |

## Related Skills

- **grid**: Grid for full catalog; when carousel is too restrictive
- **list**: List for text-heavy scan
- **masonry**: Masonry for varying-height gallery
- **card**: Card structure within carousel slides
- **testimonials-generator**: Testimonial carousel; testimonials as content
- **showcase-page-generator**: Gallery format options (grid, masonry, carousel)
- **tab-accordion**: Similar SEO requirement—content in DOM at load
- **rendering-strategies**: SSR, SSG; content in initial HTML for crawlers

---
name: card
description: When the user wants to design, optimize, or audit card layouts for content display. Also use when the user mentions "card layout," "card component," "card grid," "product cards," "template cards," "tool cards," "feature cards," "gallery cards," "integration cards," or "card design." For grids, use grid.
metadata:
  version: 1.1.1
---

# Components: Card Layout

Guides card layout design for scannable, responsive content display. Cards are self-contained containers that group related content; used in grids for blog posts, products, templates, tools, features, galleries, and integrations.

**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.

## Card Anatomy

| Element | Purpose |
|---------|---------|
| **Container** | Border, background, shadow; consistent padding |
| **Image / Thumbnail** | Visual anchor; consistent aspect ratio (1:1, 4:3 common) |
| **Title** | Clear; keyword-rich where relevant |
| **Description / Metadata** | Supporting text; date, author, category |
| **CTA** | Action button or link; "View," "Use," "Connect," etc. |

**Principle**: One card = one topic. Keep each card focused for scannability.

## Card Types by Use Case

| Type | Typical Elements | Page Skill |
|------|------------------|------------|
| **Product card** | Image, name, price, CTA (Add to cart, View) | **products-page-generator** |
| **Template card** | Thumbnail, name, short description, "Use" or "Preview" CTA | **template-page-generator** |
| **Tool card** | Name, one-line benefit, CTA to tool page | **tools-page-generator** |
| **Feature card** | Name, benefit, optional screenshot | **features-page-generator** |
| **Gallery / Showcase item** | Thumbnail, title, creator, link | **showcase-page-generator** |
| **Integration card** | Logo, name, short description, "Connect" or "Install" | **integrations-page-generator** |
| **Blog / Article card** | Cover image, title, excerpt, date, author | **blog-page-generator**, **article-page-generator** |
| **Resource card** | Thumbnail, title, format (guide, webinar), CTA | **resources-page-generator** |

## Layout & Responsiveness

- **Grid**: CSS Grid `repeat(auto-fill, minmax())` or Flexbox; columns adapt to viewport
- **Mobile**: Single column on small screens; 2–4 columns on desktop
- **Consistency**: Same padding, spacing, and aspect ratios across cards
- **Hover**: Subtle elevation (shadow, translate-y); avoid scale that causes layout shift (CLS)

## Design Principles

| Principle | Practice |
|-----------|----------|
| **Visual hierarchy** | Title > description > CTA; clear flow |
| **Scannability** | Minimal text; benefit-led copy |
| **Consistency** | Same structure across all cards in a grid |
| **Action clarity** | One primary CTA per card; avoid choice overload |

## SEO & Schema

- **Cards themselves**: No specific schema; layout is UI
- **Content in cards**: Use appropriate schema for the page (Product, Article, ItemList, etc.); see **schema-markup**
- **Images**: Alt text on thumbnails; see **image-optimization**
- **Links**: Descriptive anchor text; internal linking; see **internal-links**

## Grid vs List vs Masonry vs Carousel

| Layout | Best for | Skill |
|--------|----------|-------|
| **Grid** | Visual content (products, templates, gallery); equal emphasis | **grid** |
| **List** | Text-heavy (blog index, docs); compact; scan by title | **list** |
| **Masonry** | Varying heights; image gallery, portfolio | **masonry** |
| **Carousel** | Limited space; testimonials, logos, featured rotation | **carousel** |

## Related Skills

- **products-page-generator**: Product cards, grid layout, category pages
- **template-page-generator**: Template cards, gallery structure
- **tools-page-generator**: Tool cards, toolkit hub
- **features-page-generator**: Feature grid/list
- **showcase-page-generator**: Gallery grid, per-item format
- **integrations-page-generator**: Catalog grid, integration cards
- **category-page-generator**: Product grid, consistent layout
- **grid**: Grid layout for card display; when to use grid
- **list**: List layout; cards in list format
- **masonry**: Masonry for varying-height cards (gallery)
- **carousel**: Carousel for card slides (testimonials, featured)
- **hero-generator**: Hero vs card—hero is single above-fold; cards are repeated units
- **brand-visual-generator**: Typography, spacing, visual consistency
- **image-optimization**: Card thumbnail optimization, alt text, LCP

---
name: trust-badges-generator
description: When the user wants to add or optimize trust badges, "Trusted by" logos, security seals, or social proof elements. Also use when the user mentions "trust badges," "trusted by," "security badges," "payment logos," "social proof," "trust seals," "SSL badge," "customer logos," "as seen in," or "trust signals." For press logos, use press-coverage-page-generator.
metadata:
  version: 1.0.1
---

# Components: Trust Badges

Guides trust badge design and placement for conversion. Trust badges borrow authority from third-party organizations to signal legitimacy and reduce purchase anxiety.

**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 key partners and certifications.

Identify:
1. **Site type**: E-commerce, SaaS, lead gen
2. **Available badges**: Security, payment, reviews, guarantees
3. **Placement goals**: Hero, checkout, product pages

## Badge Types & Impact

| Type | Best Placement | Conversion Impact |
|------|----------------|-------------------|
| **Security** (SSL, Norton, McAfee) | Checkout, payment forms | +15–10% for unfamiliar brands |
| **Payment logos** (Visa, PayPal, Stripe) | Checkout, cart | +8→2% trust |
| **Money-back guarantee** | Product, checkout | +6–10% |
| **Reviews/ratings** (Trustpilot, BBB) | Product, hero | +12→8% |
| **Privacy/compliance** (GDPR, CCPA) | Forms, checkout | Data-sensitive transactions |

**"Trusted by" logos**: Client/customer logos in hero or footer; social proof for B2B. **"As Seen In"** (press coverage): Publication logos; see **press-coverage-page-generator** for media mentions aggregation.

## Best Practices

### Quantity

- **3→ badge types max**; more can cause "badge bloat" and reduce conversions by 5→%
- Quality over quantity; use only legitimate, verifiable badges

### Placement

- **Highest leverage**: Cart and checkout (near payment fields)
- **Product pages**: Near add-to-cart button
- **Hero**: "Trusted by" logos for brand credibility
- **Footer**: Secondary trust signals

### Authenticity

- Use only real, verifiable badges
- Fake or irrelevant badges create skepticism
- Link to verification where appropriate

## Design Guidelines

- Consistent size and style; don't mix clashing visuals
- **Image optimization**: Alt text, format—see **image-optimization**
- Adequate spacing; avoid clutter
- Grayscale or muted for "Trusted by" logos (don't compete with primary content)
- Ensure badges are recognizable at display size

## Accessibility

- Provide `alt` text for badge images (e.g., "Norton Secured")
- Don't rely on badges alone for critical information

## Output Format

- **Badge recommendations** by type and placement
- **Placement map** (hero, product, checkout)
- **Quantity** guidance (avoid bloat)

## Related Skills

- **landing-page-generator**: Trust signals as step 2 (earn trust) in landing page flow
- **hero-generator**: "Trusted by" often in hero
- **testimonials-generator**: Complementary social proof
- **cta-generator**: Badges near CTAs increase conversion
- **pricing-page-generator**: Trust badges on pricing pages
- **image-optimization**: Badge image optimization (alt, format)
- **press-coverage-page-generator**: "As Seen In" publication logos; similar visual treatment; distinct (press = media coverage; trust-badges = security, payment, reviews)
- **brand-protection**: "Official website" badges to distinguish from impersonation sites