| name | social-seo |
| description | Implement SEO and social sharing for web games and apps. Adds meta tags, Open Graph, Twitter cards, social card images, PWA support, share buttons, and shareable result links. |
| disable-model-invocation | true |
| argument-hint | ["phase1|phase2|phase3|all"] |
Social & SEO Implementation Skill
Implement comprehensive SEO and social sharing capabilities for web-based projects. See reference.md for detailed templates, code snippets, and platform-specific notes.
Arguments
phase1 - Foundation only (meta tags, social card, robots.txt, sitemap)
phase2 - Foundation + Enhancement (adds PWA, structured data, share buttons)
phase3 - All phases including shareable result links
all - Same as phase3
- No argument - Ask user which phases to implement
Step 1: Gather Required Information
Before implementing, collect this information from the user:
| Information | Example | Used For |
|---|
| App/Game name | "My App" | Title, OG tags, structured data |
| Tagline | "A Short Tagline" | Meta description, social cards |
| Full description | "A compelling 150-char description..." | Meta description (150-160 chars) |
| Production domain | myapp.example.com | Canonical URL, OG URLs, sitemap |
| Brand/Studio name | "My Studio" | og:site_name, JSON-LD author |
| Primary brand color | #3b82f6 | theme-color, PWA colors |
| Secondary/background color | #1e40af | PWA background_color |
Use AskUserQuestion to gather any missing information.
Step 2: Determine Project Structure
- Find the main HTML file (usually
index.html)
- Identify existing
<head> content to preserve
- Note the project root for asset placement
Phase 1: Foundation (Essential)
1.1 HTML Meta Tags
Add to <head> (ensure <html lang="en"> is set):
<title>[Game Name] - [Tagline]</title>
<meta name="description" content="[150-160 char description]">
<link rel="canonical" href="https://[domain]">
<meta name="theme-color" content="[primary-color]">
<link rel="icon" type="image/png" href="favicon.png">
<link rel="apple-touch-icon" href="apple-touch-icon.png">
<meta property="og:type" content="website">
<meta property="og:url" content="https://[domain]">
<meta property="og:locale" content="en_US">
<meta property="og:title" content="[Game Name] - [Tagline]">
<meta property="og:description" content="[Description]">
<meta property="og:image" content="https://[domain]/social-card.jpg">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta property="og:image:alt" content="[Alt text]">
<meta property="og:site_name" content="[Brand Name]">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="[Game Name] - [Tagline]">
<meta name="twitter:description" content="[Description]">
<meta name="twitter:image" content="https://[domain]/social-card.jpg">
1.2 Create Social Card Image (1200x630)
Using the pre-configured Playwright browser control (preferred method):
Do NOT install Playwright from npm or write Playwright scripts. Use only the
browser control tools already configured in this environment — either Playwright
MCP tools (e.g. browser_navigate, browser_screenshot) or Playwright CLI
commands (e.g. playwright-cli open, playwright-cli screenshot), whichever is
available.
- Create
social-card.html with project colors/branding (see reference.md §1.3 for HTML template)
- Capture using the pre-configured browser control tools:
- Navigate to
file:///[path]/social-card.html
- Resize the viewport to 1200 x 630
- Take a screenshot, saving as
social-card.png
- Convert to JPG:
magick social-card.png -quality 85 social-card.jpg (or convert on ImageMagick 6)
- Delete
social-card.html and social-card.png
If no browser control tools are available: Ask the user to provide a social card image (1200x630 JPG), or create one using an external design tool and place it in the project root as social-card.jpg.
1.3 Create Icon Files
| File | Size | Purpose |
|---|
favicon.png | 32x32 | Browser tab |
apple-touch-icon.png | 180x180 | iOS home screen |
Simple geometric icons: Write SVG directly. Complex graphics: Use browser control tools to screenshot HTML at each size. Transparency: Set HTML/body background to transparent, use PNG format. See reference.md §1.5 for details.
1.4 Search Engine Files
robots.txt:
User-agent: *
Allow: /
Sitemap: https://[domain]/sitemap.xml
Ask the user if they want to block AI training crawlers. If yes, see reference.md §1.4 for the full bot list. Tip: Allow search-only bots (OAI-SearchBot, PerplexityBot) while blocking training bots.
sitemap.xml (changefreq/priority are ignored by Google; only lastmod matters if consistently accurate):
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
<url>
<loc>https://[domain]/</loc>
<lastmod>[YYYY-MM-DD]</lastmod>
</url>
</urlset>
Phase 1 Checklist
Phase 2: Enhancement (Recommended)
2.1 Structured Data (JSON-LD)
Add to <head> after Twitter tags. Use "@type": ["VideoGame", "WebApplication"] for games (co-typing is required for Google rich results). See reference.md §2.1 for complete JSON-LD templates for games and web apps.
2.2 PWA Support
Create manifest.json with id, name, short_name, display, icons, screenshots, and shortcuts. Add <link rel="manifest"> and <meta name="mobile-web-app-capable"> to <head>. Create icon-192.png (192x192) and icon-512.png (512x512). See reference.md §2.2 for the complete manifest template.
2.3 Share Button
Implement Web Share API with clipboard fallback. Requirements: HTTPS (localhost exempt), user gesture trigger. Fallback chain: navigator.share() → navigator.clipboard.writeText() → selectable text element. See reference.md §2.3 for complete code.
Phase 2 Checklist
Phase 3: Shareable Result Links
Only implement if users share scores/achievements that others should view.
- Encode state into a short URL parameter (
?s=base36encoded)
- Parse parameter on page load, before normal initialization
- Display shared view (read-only — NEVER overwrite user's localStorage)
- Show "shared results" messaging so viewer knows it's not their data
- Provide "Play Now" CTA that cleans the URL parameter
See reference.md §3.3 for state encoding/decoding code and shared results landing page implementation. See reference.md §3.4 for localStorage safety wrapper.
Phase 3 Checklist
Testing
Remind user to test with these tools after deployment.
Platform Cache Notes
When updating social cards, add version parameter: social-card.jpg?v=2
Force refresh tools:
- Facebook/Threads: Sharing Debugger
- Twitter/X: Compose a draft post with the URL (public validator removed 2022)
- LinkedIn: Post Inspector
- Mastodon: No universal tool (each instance caches independently)
- Bluesky: Client-side fetching (no centralized cache to bust)
See reference.md Platform-Specific Notes for full platform quirks and cache behavior.