---
name: shopify-auditoria-imagenes
description: "Solo lectura: encuentra los productos y variantes sin imágenes o con menos fotos del mínimo que definas. Úsala cuando quieras saber qué productos necesitan fotos antes de publicarlos o promocionarlos."
---

## Propósito
Revisa todos los productos activos y sus variantes para encontrar imágenes faltantes o insuficientes. Marca los productos sin ninguna imagen, las variantes sin imagen asignada y los productos que no llegan a la cantidad mínima de imágenes. Solo lectura: no ejecuta mutaciones.

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

## Parámetros

| Parámetro | Tipo | Obligatorio | Por defecto | Descripción |
|-----------|------|-------------|-------------|-------------|
| store | string | sí | — | Dominio de la tienda (p. ej., tu-tienda.myshopify.com) |
| min_images | integer | no | 1 | Marca los productos con menos imágenes que este número |
| check_variants | bool | no | true | Marca también las variantes sin imagen asignada |
| status_filter | string | no | active | Estado de los productos a revisar: `active`, `draft` 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
   **Entradas:** `query: "status:<status_filter>"`, `first: 250`, selecciona `images`, `variants { image }`, cursor de paginación
   **Resultado esperado:** Productos con su cantidad de imágenes y la imagen asignada a cada variante; pagina hasta que `hasNextPage: false`

2. Marca los productos con `images.count < min_images` O `images.count == 0`

3. Si `check_variants` está activo: marca las variantes cuya `image` sea null

## Operaciones GraphQL

```graphql
# products:query — validado con api_version 2025-01
query ProductImageAudit($query: String!, $after: String) {
  products(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        title
        handle
        status
        images(first: 10) {
          edges {
            node {
              id
              url
              altText
            }
          }
        }
        variants(first: 50) {
          edges {
            node {
              id
              title
              sku
              image {
                id
                url
              }
            }
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
```

## Seguimiento de la sesión

**Claude DEBE mostrar esta salida en cada etapa. Es obligatorio.**

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

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

**Al terminar**, muestra:

Para `format: human` (por defecto):
```
══════════════════════════════════════════════
AUDITORÍA DE IMÁGENES DE PRODUCTOS
  Productos revisados:                  <n>
  Sin ninguna imagen:                   <n>
  Por debajo del mínimo (<min_images>): <n>
  Variantes sin imagen:                 <n>

  Productos que necesitan imágenes:
    "<título>" — 0 imágenes
    "<título>" — 1 imagen (por debajo del mínimo de <n>)
  Archivo: image_audit_<fecha>.csv
══════════════════════════════════════════════
```

Para `format: json`, muestra:
```json
{
  "skill": "shopify-auditoria-imagenes",
  "store": "<dominio>",
  "min_images": 1,
  "products_scanned": 0,
  "missing_all_images": 0,
  "below_minimum": 0,
  "variants_missing_image": 0,
  "output_file": "image_audit_<fecha>.csv"
}
```

## Formato de salida
Archivo CSV `image_audit_<YYYY-MM-DD>.csv` con las columnas:
`product_id`, `product_title`, `handle`, `image_count`, `issue`, `variant_id`, `variant_sku`, `variant_has_image`

## 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 |
| Ningún producto coincide con el filtro | Catálogo vacío o filtro de estado equivocado | Termina con 0 resultados |

## Buenas prácticas
- Los productos sin imágenes no se pueden vender en la mayoría de los canales de venta (Google Shopping, Meta, etc.): atiéndelos con urgencia.
- Para ropa o productos con variantes de color o talla, usa `min_images: 3` para asegurar al menos una foto de frente, una de espalda y una de ambiente por producto.
- Córrela después de cargar productos en lote para detectar las imágenes que no se subieron en la importación.
- Combínala con `shopify-calidad-fichas-producto` para tener un solo reporte completo de la calidad del catálogo.