---
name: shopify-auditoria-seo
description: "Solo lectura: revisa productos, colecciones y páginas en busca de títulos SEO o metadescripciones que faltan o son muy cortos. Úsala cuando quieras saber qué fichas de tu tienda necesitan mejor SEO para aparecer en Google."
---

## Propósito
Revisa todos los productos activos, las colecciones y las páginas, y marca los registros a los que les falta o tienen demasiado corto el título SEO (`seo.title`) o la metadescripción (`seo.description`). Genera una lista priorizada de vacíos de SEO ordenada por potencial de tráfico (productos → colecciones → páginas). Solo lectura: no ejecuta mutaciones.

## Requisitos
- Sesión autenticada de Shopify CLI: `shopify store auth --store <tu-tienda>.myshopify.com --scopes read_products,read_content`
- Las consultas se ejecutan con `shopify store execute`.
- Permisos (scopes) de API: `read_products`, `read_content`

## Parámetros

| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|-----------|------|-------------|----------------|-------------|
| store | string | sí | — | Dominio de la tienda (p. ej., tu-tienda.myshopify.com) |
| min_title_length | integer | no | 10 | Marca los títulos SEO más cortos que esto (caracteres) |
| min_description_length | integer | no | 50 | Marca las metadescripciones más cortas que esto (caracteres) |
| scope | string | no | all | Qué revisar: `products`, `collections`, `pages` o `all` |
| format | string | no | human | Formato de salida: `human` o `json` |

## Seguridad

> ℹ️ Skill de solo lectura: no ejecuta mutaciones. Puedes correrla en cualquier momento.

## Pasos

1. **OPERACIÓN:** `products` — consulta (si `scope` incluye productos)
   **Entradas:** `query: "status:active"`, `first: 250`, selecciona `seo { title, description }`, cursor de paginación
   **Resultado esperado:** Todos los productos activos con sus campos SEO; pagina hasta `hasNextPage: false`

2. **OPERACIÓN:** `collections` — consulta (si `scope` incluye colecciones)
   **Entradas:** `first: 250`, selecciona `seo { title, description }`, cursor de paginación
   **Resultado esperado:** Todas las colecciones con sus campos SEO

3. **OPERACIÓN:** `pages` — consulta (si `scope` incluye páginas)
   **Entradas:** `first: 250`, selecciona `seo { title, description }`, cursor de paginación
   **Resultado esperado:** Todas las páginas con sus campos SEO

4. Marca los registros: título faltante, descripción faltante, título < `min_title_length`, descripción < `min_description_length`

## Operaciones GraphQL

```graphql
# products:query — validada con 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
    }
  }
}
```

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

```graphql
# pages:query — validada con 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
    }
  }
}
```

## Seguimiento de la sesión

**Claude DEBE mostrar lo siguiente en cada etapa. Es obligatorio.**

**Al iniciar**, muestra:
```
╔══════════════════════════════════════════════╗
║  SKILL: Auditoría de SEO                     ║
║  Tienda: <dominio de la tienda>              ║
║  Inicio: <AAAA-MM-DD HH:MM UTC>              ║
╚══════════════════════════════════════════════╝
```

**Después de cada paso**, muestra:
```
[N/TOTAL] <CONSULTA|MUTACIÓN>  <OperationName>
          → Parámetros: <resumen breve de las entradas clave>
          → Resultado: <cantidad o desenlace>
```

**Al terminar**, muestra:

Para `format: human` (predeterminado):
```
══════════════════════════════════════════════
AUDITORÍA DE SEO
  Productos revisados:    <n>  |  Sin SEO: <n>
  Colecciones revisadas:  <n>  |  Sin SEO: <n>
  Páginas revisadas:      <n>  |  Sin SEO: <n>

  Vacíos principales (productos):
    "<título>" — falta: descripción
    "<título>" — título demasiado corto (<n> caracteres)
  Archivo: seo_audit_<fecha>.csv
══════════════════════════════════════════════
```

Para `format: json`, muestra:
```json
{
  "skill": "shopify-auditoria-seo",
  "store": "<dominio>",
  "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, "missing_title": 0, "missing_description": 0 }
  },
  "output_file": "seo_audit_<fecha>.csv"
}
```

## Formato de salida
Archivo CSV `seo_audit_<AAAA-MM-DD>.csv` con las columnas:
`type`, `id`, `title`, `handle`, `seo_title`, `seo_description`, `issue`

## Manejo de errores
| Error | Causa | Solución |
|-------|-------|----------|
| `THROTTLED` | Se superó el límite de solicitudes de la API | Espera 2 segundos y reintenta hasta 3 veces |
| Tienda vacía | No hay productos, colecciones ni páginas | Termina con el resumen: 0 registros |

## Buenas prácticas
- Empieza por corregir las metadescripciones que faltan en los productos más vendidos: las descripciones aparecen en los fragmentos de los resultados de búsqueda y afectan directamente la tasa de clics.
- Un buen título SEO tiene entre 50 y 60 caracteres; las metadescripciones deberían tener entre 120 y 160. Ajusta `min_title_length` y `min_description_length` a estas metas.
- Ejecútala cada mes como parte de la rutina de orden del catálogo, sobre todo después de importaciones masivas de productos, que a menudo dejan vacíos los campos SEO.
- Después de corregir los vacíos, combínala con `shopify-calidad-fichas-producto` para tener una visión completa de la calidad del catálogo.