---
name: shopify-sku-duplicados
description: "Solo lectura: encuentra SKU o códigos de barras repetidos en todas las variantes de tus productos. Úsala después de una importación masiva o cuando el inventario no cuadre."
---

## Propósito
Revisa todas las variantes de productos e identifica SKU o códigos de barras duplicados: dos o más variantes que comparten el mismo identificador. Los SKU duplicados causan fallas en la sincronización del inventario, pedidos enrutados a donde no es y descuadres contables. Solo lectura: no hace 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 API: `read_products`

## Parámetros

| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|-----------|------|-------------|----------------|-------------|
| store | string | sí | — | Dominio de la tienda (p. ej., mitienda.myshopify.com) |
| check_skus | bool | no | true | Busca SKU duplicados |
| check_barcodes | bool | no | true | Busca códigos de barras duplicados |
| include_blank | bool | no | false | Marca las variantes con SKU vacío o null |
| 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:** `productVariants` — consulta
   **Entradas:** `first: 250`, selecciona `sku`, `barcode`, `product { title }` y el cursor de paginación
   **Resultado esperado:** Todas las variantes con sus valores de SKU y código de barras; pagina hasta `hasNextPage: false`

2. Arma en memoria un mapa de `sku → [variants]` y otro de `barcode → [variants]`

3. Reporta todas las claves que tengan más de una variante (duplicados)

4. Si `include_blank` está activo: marca además las variantes cuyo `sku` sea null o una cadena vacía

## Operaciones GraphQL

```graphql
# productVariants:query — validada con api_version 2025-01
query VariantIdentifiers($after: String) {
  productVariants(first: 250, after: $after) {
    edges {
      node {
        id
        sku
        barcode
        title
        product {
          id
          title
          handle
          status
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
```

## Seguimiento de la sesión

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

**Al iniciar**, muestra:
```
╔══════════════════════════════════════════════╗
║  SKILL: SKU y códigos de barras duplicados   ║
║  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 SKU / CÓDIGOS DE BARRAS DUPLICADOS
  Variantes revisadas:          <n>
  SKU duplicados:               <n> grupos
  Códigos de barras duplicados: <n> grupos
  SKU vacíos:                   <n>

  Grupos de SKU duplicados:
    SKU "ABC-123"  — lo usan 2 variantes:
      Producto A / Azul / L
      Producto B / Azul marino / XL
  Archivo: duplicates_<date>.csv
══════════════════════════════════════════════
```

Para `format: json`, muestra:
```json
{
  "skill": "shopify-sku-duplicados",
  "store": "<dominio>",
  "variants_scanned": 0,
  "duplicate_sku_groups": 0,
  "duplicate_barcode_groups": 0,
  "blank_skus": 0,
  "output_file": "duplicates_<date>.csv"
}
```

## Formato de salida
Archivo CSV `duplicates_<YYYY-MM-DD>.csv` con las columnas:
`issue_type`, `duplicate_value`, `variant_id`, `product_title`, `variant_title`, `sku`, `barcode`

## 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 |
| No se encontraron duplicados | Catálogo limpio | Termina con ✅ no se encontraron problemas |

## Buenas prácticas
- Ejecuta esta skill después de cada importación masiva de productos: las importaciones son la causa más común de SKU duplicados.
- Un SKU compartido entre productos solo es válido si usas el mismo SKU a propósito para reediciones o variantes; en la mayoría de los casos es un error de datos.
- Los SKU vacíos no son duplicados, pero pueden causar problemas con operadores logísticos (3PL) y sistemas de preparación de pedidos que exigen un SKU por variante: usa `include_blank: true` para verlos.
- Después de identificar los duplicados, corrige los SKU desde el admin de Shopify o con la mutación `productVariantsBulkUpdate`.