shopify-admin-seo-metadata-audit

name	shopify-admin-seo-metadata-audit
role	merchandising
description	Read-only: scans products, collections, and pages for missing SEO titles or meta descriptions.
toolkit	shopify-admin, shopify-admin-execution
api_version	2025-01
graphql_operations	["products:query","collections:query","pages:query"]
status	stable
compatibility	Claude Code, Cursor, Codex, Gemini CLI

Purpose

Scans all active products, collections, and pages and flags records with missing or short SEO titles (seo.title) and meta descriptions (seo.description). Produces a prioritized list of SEO gaps sorted by traffic potential (products → collections → pages). Read-only — no mutations.

Prerequisites

• Authenticated Shopify CLI session: shopify store auth --store <domain> --scopes read_products,read_content
• API scopes: read_products, read_content

Parameters

Parameter	Type	Required	Default	Description
store	string	yes	—	Store domain (e.g., mystore.myshopify.com)
min_title_length	integer	no	10	Flag SEO titles shorter than this (characters)
min_description_length	integer	no	50	Flag meta descriptions shorter than this (characters)
scope	string	no	all	What to scan: products, collections, pages, or all
format	string	no	human	Output format: human or json

Safety

ℹ️ Read-only skill — no mutations are executed. Safe to run at any time.

Workflow Steps

1. OPERATION: products — query (if scope includes products) Inputs: query: "status:active", first: 250, select seo { title, description }, pagination cursor Expected output: All active products with SEO fields; paginate until hasNextPage: false

2. OPERATION: collections — query (if scope includes collections) Inputs: first: 250, select seo { title, description }, pagination cursor Expected output: All collections with SEO fields

3. OPERATION: pages — query (if scope includes pages) Inputs: first: 250, select seo { title, description }, pagination cursor Expected output: All pages with SEO fields

4. Flag records: missing title, missing description, title < min_title_length, description < min_description_length

GraphQL Operations

# products:query — validated against api_version 2025-01
query ProductSEO($after: String) {
  products(first: 250, after: $after, query: "status:active") {
    edges {
      node {
        id
        title
        handle
        seo {
          title
          description
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

# collections:query — validated against api_version 2025-01
query CollectionSEO($after: String) {
  collections(first: 250, after: $after) {
    edges {
      node {
        id
        title
        handle
        seo {
          title
          description
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

# pages:query — validated against api_version 2025-04
query PageSEO($after: String) {
  pages(first: 250, after: $after) {
    edges {
      node {
        id
        title
        handle
        seoTitle: metafield(namespace: "global", key: "title_tag") { value }
        seoDescription: metafield(namespace: "global", key: "description_tag") { value }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Session Tracking

Claude MUST emit the following output at each stage. This is mandatory.

On start, emit:

╔══════════════════════════════════════════════╗
║  SKILL: SEO Metadata Audit                   ║
║  Store: <store domain>                       ║
║  Started: <YYYY-MM-DD HH:MM UTC>             ║
╚══════════════════════════════════════════════╝

After each step, emit:

[N/TOTAL] <QUERY|MUTATION>  <OperationName>
          → Params: <brief summary of key inputs>
          → Result: <count or outcome>

On completion, emit:

For format: human (default):

══════════════════════════════════════════════
SEO METADATA AUDIT
  Products scanned:     <n>  |  Missing SEO: <n>
  Collections scanned:  <n>  |  Missing SEO: <n>
  Pages scanned:        <n>  |  Missing SEO: <n>

  Top gaps (products):
    "<title>" — missing: description
    "<title>" — title too short (<n> chars)
  Output: seo_audit_<date>.csv
══════════════════════════════════════════════

For format: json, emit:

{
  "skill": "seo-metadata-audit",
  "store": "<domain>",
  "summary": {
    "products": { "scanned": 0, "missing_title": 0, "missing_description": 0, "short_title": 0, "short_description": 0 },
    "collections": { "scanned": 0, "missing_title": 0, "missing_description": 0 },
    "pages": { "scanned": 0,     
  
   

Output Format

CSV file seo_audit_<YYYY-MM-DD>.csv with columns: type, id, title, handle, seo_title, seo_description, issue

Error Handling

Error	Cause	Recovery
THROTTLED	API rate limit exceeded	Wait 2 seconds, retry up to 3 times
Empty store	No products/collections/pages	Exit with summary: 0 records

Best Practices

• Prioritize fixing missing meta descriptions on top-selling products first — descriptions appear in search result snippets and directly impact click-through rate.
• A good SEO title length is 50–60 characters; meta descriptions should be 120–160 characters. Adjust min_title_length and min_description_length to match these targets.
• Run monthly as part of a catalog hygiene routine, especially after bulk product imports which often omit SEO fields.
• After fixing gaps, pair with product-data-completeness-score for a comprehensive catalog quality view.