---
name: shopify-calidad-fichas-producto
description: "Solo lectura: califica de 0 a 100 qué tan completa está la ficha de cada producto (descripción, imágenes, SEO, peso, código de barras, costo y metacampos). Úsala para saber qué productos necesitan más trabajo antes de publicarlos."
---

## Propósito
Calcula un puntaje de completitud de datos (0–100) para cada producto activo según la presencia de campos clave: descripción, imágenes, título SEO, descripción SEO, peso de la variante, código de barras, costo y los metacampos que indiques. Produce una lista ordenada de los productos que necesitan más trabajo de datos. Solo lectura: no hace mutaciones. Un reporte de salud del catálogo en una sola pasada.

## 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 API: `read_products`

## Parámetros

| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|-----------|------|-------------|----------------|-------------|
| store | string | sí | — | Dominio de la tienda (p. ej., mitienda.myshopify.com) |
| status_filter | string | no | active | Estado de los productos a calificar: `active`, `draft` o `all` |
| required_metafields | array | no | [] | Lista de metacampos `namespace.key` obligatorios (p. ej., `["custom.material"]`) |
| format | string | no | human | Formato de salida: `human` o `json` |

## Seguridad

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

## Criterios de puntaje

| Campo | Puntos |
|-------|--------|
| Tiene descripción (no vacía) | 15 |
| Al menos 1 imagen | 15 |
| Tiene título SEO | 10 |
| Tiene descripción SEO | 10 |
| Al menos 1 variante con código de barras | 10 |
| Al menos 1 variante con costo | 10 |
| Al menos 1 variante con peso | 10 |
| Todos los metacampos obligatorios presentes | 20 (repartidos en partes iguales) |
| **Total** | **100** |

## Pasos

1. **OPERACIÓN:** `products` — consulta
   **Entradas:** `query: "status:<status_filter>"`, `first: 250`, selecciona todos los campos de completitud y el cursor de paginación
   **Resultado esperado:** Productos con todos los campos que se califican; pagina hasta `hasNextPage: false`

2. Califica cada producto según los criterios y ordénalos de menor a mayor puntaje

## Operaciones GraphQL

```graphql
# products:query — validada con api_version 2025-01
query ProductCompleteness($query: String!, $after: String) {
  products(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        title
        handle
        descriptionHtml
        images(first: 1) {
          edges {
            node {
              id
            }
          }
        }
        seo {
          title
          description
        }
        variants(first: 10) {
          edges {
            node {
              id
              barcode
              weight
              inventoryItem {
                unitCost {
                  amount
                }
              }
            }
          }
        }
        metafields(first: 20) {
          edges {
            node {
              namespace
              key
              value
            }
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
```

## Seguimiento de la sesión

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

**Al iniciar**, muestra:
```
╔══════════════════════════════════════════════╗
║  SKILL: Puntaje de fichas de producto        ║
║  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):
```
══════════════════════════════════════════════
REPORTE DE COMPLETITUD DE FICHAS DE PRODUCTO
  Productos calificados:  <n>
  Puntaje promedio:       <pct>/100
  Puntaje < 50:           <n> productos (requieren atención urgente)
  Puntaje 50–79:          <n> productos
  Puntaje ≥ 80:           <n> productos

  Productos con menor puntaje:
    "<título>"  Puntaje: <n>/100  Falta: descripción, título SEO
  Archivo: completeness_<date>.csv
══════════════════════════════════════════════
```

Para `format: json`, muestra:
```json
{
  "skill": "shopify-calidad-fichas-producto",
  "store": "<dominio>",
  "products_scored": 0,
  "avg_score": 0,
  "below_50_count": 0,
  "output_file": "completeness_<date>.csv"
}
```

## Formato de salida
Archivo CSV `completeness_<YYYY-MM-DD>.csv` con las columnas:
`product_id`, `title`, `score`, `has_description`, `image_count`, `has_seo_title`, `has_seo_description`, `has_barcode`, `has_cost`, `has_weight`, `missing_metafields`

## 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 equivocado | Termina con 0 resultados |

## Buenas prácticas
- Usa esta skill como filtro antes de lanzar: ejecútala antes de activar productos en borrador (DRAFT) para asegurarte de que todos los campos obligatorios estén llenos.
- Ajusta `required_metafields` a las necesidades de tu tienda (p. ej., `custom.material` para ropa, `custom.ingredients` para alimentos).
- Un puntaje por debajo de 50 suele indicar que al producto le falta contenido básico (descripción o imágenes) y conviene posponer su lanzamiento hasta corregirlo.
- Ejecútala cada mes para seguir la calidad del catálogo en el tiempo; las mejoras después de una jornada de contenido deberían notarse en el puntaje promedio.