add-seo

Plugin check: Run node "${CLAUDE_PLUGIN_ROOT}/scripts/check-version.js" — if it outputs a message, show it to the user before proceeding.

Add SEO

Add essential SEO assets to a Power Pages code site: robots.txt, sitemap.xml, and meta tags.

Prerequisite: This skill expects an existing Power Pages code site created via /create-site. Run that skill first if the site does not exist yet.

Core Principles

• Crawlability first: Every public page must be discoverable by search engines via a valid robots.txt and sitemap.xml before any other SEO work matters.
• Accurate metadata: Meta tags (title, description, Open Graph) must truthfully represent page content — misleading metadata harms rankings.
• Framework-aware placement: SEO assets must be placed in the correct location for the detected framework (public directory, layout component, etc.).

Initial request: $ARGUMENTS

Workflow

1. Phase 1: Verify Site Exists → Locate the Power Pages project
2. Phase 2: Gather SEO Configuration → Site URL, pages, preferences
3. Phase 3: Plan & Approve → Present SEO additions inline, get user approval
4. Phase 4: Add robots.txt → Create robots.txt in public directory
5. Phase 5: Add sitemap.xml → Generate sitemap.xml from site routes
6. Phase 6: Add Meta Tags → Add title, description, viewport, Open Graph, and favicon to index.html
7. Phase 7: Verify & Commit → Verify via Playwright, commit changes

Phase 1: Verify Site Exists

Goal: Confirm a Power Pages code site exists and understand its structure.

Actions

1.1 Locate Project

Look for powerpages.config.json in the current directory or immediate subdirectories to find the project root. Use your file-search tool (e.g., Glob with patterns powerpages.config.json and */powerpages.config.json) rather than a shell-specific command.

If not found: Tell the user to create a site first with /create-site.

1.2 Read Existing Config

Read powerpages.config.json to get the site name and config.

1.3 Detect Framework & Discover Routes

Read package.json to determine the framework and locate key files. See ${CLAUDE_PLUGIN_ROOT}/references/framework-conventions.md for the full framework → public directory → index HTML mapping and route discovery patterns.

Build a list of all routes (e.g., /, /about, /contact, /blog).

Output

• Project root path identified
• Framework detected (React, Vue, Angular, or Astro)
• Full list of discoverable routes

Phase 2: Gather SEO Configuration

Goal: Collect all SEO preferences from the user before making any changes.

Actions

Use AskUserQuestion to collect SEO preferences:

Call 1

| Question | Header | Options | |----------|--------|---------| | What is the production URL for your site? (e.g., <https://contoso.powerappsportals.com>) | Site URL | (free text — use single generic option so user types via "Other") | | Which pages should be excluded from search engine indexing? | Exclusions | None — index all pages (Recommended), Admin/auth pages only, Let me specify |

Call 2

| Question | Header | Options | |----------|--------|---------| | What meta description should appear in search results? | Description | (free text — use single generic option so user types via "Other") | | Add Open Graph tags for social media sharing? | OG Tags | Yes — add Open Graph and Twitter Card tags (Recommended), No — skip social tags |

Output

• Production URL confirmed
• Exclusion list finalized
• Meta description text
• Open Graph tag preference (yes/no)

Phase 3: Plan & Approve

Goal: Present the full SEO plan to the user and get explicit approval before making changes.

Actions

Present the SEO additions that will be made as a clear, inline summary:

1. robots.txt content — which paths will be allowed/disallowed
2. sitemap.xml content — all discovered routes with the production URL and priority assignments
3. Meta tags to add to index.html — title, description, viewport, charset, Open Graph, Twitter Card
4. Favicon — link tag and placeholder SVG

After presenting the plan, use AskUserQuestion to get approval:

| Question | Header | Options | |----------|--------|---------| | Here is the SEO plan. How would you like to proceed? | SEO Plan Approval | Approve and proceed (Recommended), I'd like to make changes |

If the user chooses "I'd like to make changes", ask what they want to change, update the plan accordingly, and present the revised plan for approval again.

Output

• User-approved SEO plan ready for implementation

Phase 4: Add robots.txt

Goal: Create a valid robots.txt that tells search engines which pages to crawl.

Actions

Create robots.txt in the public directory (<PROJECT_ROOT>/public/robots.txt):

User-agent: *
Allow: /

Sitemap: <PRODUCTION_URL>/sitemap.xml

If the user specified pages to exclude, add Disallow directives:

User-agent: *
Allow: /
Disallow: /admin/
Disallow: /auth/

Sitemap: <PRODUCTION_URL>/sitemap.xml

Output

• public/robots.txt created with correct directives

Phase 5: Add sitemap.xml

Goal: Generate a complete sitemap.xml listing all discoverable routes with proper priorities.

Actions

Create sitemap.xml in the public directory (<PROJECT_ROOT>/public/sitemap.xml).

Generate entries for each discovered route using the production URL:

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc><PRODUCTION_URL>/</loc>
    <lastmod><TODAY_DATE></lastmod>
    <changefreq>weekly</changefreq>
    <priority>1.0</priority>
  </url>
  <url>
    <loc><PRODUCTION_URL>/about</loc>
    <lastmod><TODAY_DATE></lastmod>
    <changefreq>monthly</changefreq>
    <priority>0.8</priority>
  </url>
  <!-- Additional routes... -->
</urlset>

Priority rules:

• Home page (/): 1.0
• Top-level pages: 0.8
• Sub-pages: 0.6

Exclusions: Do not include routes the user chose to exclude (e.g., /admin/, /auth/).

Output

• public/sitemap.xml created with all routes, correct URLs, and no placeholders

Phase 6: Add Meta Tags

Goal: Add comprehensive meta tags, Open Graph tags, and a favicon to the site's HTML.

Actions

6.1 Essential Meta Tags

Add or update meta tags in the site's index.html (location depends on framework — see Phase 1.3):

<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title><SITE_TITLE></title>
  <meta name="description" content="<META_DESCRIPTION>" />
  <meta name="robots" content="index, follow" />
  <link rel="canonical" href="<PRODUCTION_URL>/" />
  <link rel="sitemap" type="application/xml" href="/sitemap.xml" />
</head>

6.2 Open Graph Tags (if user opted in)

Add Open Graph and Twitter Card meta tags inside <head>:

<!-- Open Graph -->
<meta property="og:type" content="website" />
<meta property="og:title" content="<SITE_TITLE>" />
<meta property="og:description" content="<META_DESCRIPTION>" />
<meta property="og:url" content="<PRODUCTION_URL>/" />
<meta property="og:site_name" content="<SITE_TITLE>" />

<!-- Twitter Card -->
<meta name="twitter:card" content="summary" />
<meta name="twitter:title" content="<SITE_TITLE>" />
<meta name="twitter:description" content="<META_DESCRIPTION>" />

6.3 Favicon

Check if a favicon already exists in the public directory. If not, add a simple SVG favicon link:

<link rel="icon" type="image/svg+xml" href="/favicon.svg" />

Create a minimal placeholder public/favicon.svg using the site's primary color:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
  <rect width="100" height="100" rx="20" fill="<PRIMARY_COLOR>"/>
  <text x="50" y="70" font-size="50" text-anchor="middle" fill="white" font-family="system-ui, sa