--- name: shopify-auditoria-agentes-ia description: "Califica qué tan fácil es para los agentes de compra con IA encontrar, leer y recomendar tu catálogo, y asigna a cada falla la skill que la corrige. Úsala antes de las demás skills para agentes de IA y repítela cada cierto tiempo." --- ## Propósito Hace un análisis de «preparación para el comercio con agentes de IA» desde dentro del admin de Shopify, con los datos completos del catálogo. Califica si los agentes de compra con IA (ChatGPT, Gemini, Perplexity, checkout con agentes) pueden ENCONTRAR, LEER y RECOMENDAR los productos de la tienda, y luego muestra una lista de fallas en orden de prioridad donde **cada falla indica la skill hermana para agentes de IA que la corrige**. Es de solo lectura: no cambia nada. Úsala primero (y de forma periódica) para decidir qué skills de corrección ejecutar. ## Requisitos - Sesión autenticada de Shopify CLI: `shopify store auth --store .myshopify.com --scopes read_products,read_files,read_content,read_online_store_pages` - Las consultas se ejecutan con `shopify store execute`. - Permisos (scopes) de API necesarios: `read_products`, `read_files`, `read_content` (temas), `read_online_store_pages` ## Parámetros Todas las skills aceptan estos parámetros generales: | Parámetro | Tipo | Obligatorio | Predeterminado | Descripción | |-----------|--------|-------------|----------------|-------------| | store | string | sí | — | Dominio de la tienda (p. ej., mitienda.myshopify.com) | | format | string | no | human | Formato de salida: `human` (predeterminado) o `json` | | dry_run | bool | no | false | Aquí no tiene efecto: esta skill nunca hace mutaciones | Parámetros propios de esta skill: | Parámetro | Tipo | Obligatorio | Predeterminado | Descripción | |-----------|------|-------------|----------------|-------------| | sample_size | int | no | 250 | Cuántos productos tomar como muestra para las revisiones de datos del catálogo | | min_description_chars | int | no | 120 | Umbral por debajo del cual una descripción cuenta como «pobre» | ## Pasos 1. **OPERACIÓN:** `shop` — consulta **Entradas:** ninguna **Resultado esperado:** Nombre de la tienda, dominio principal, enlaces a redes sociales (`sameAs`) y si existen las políticas; alimenta las revisiones de identidad y de políticas. 2. **OPERACIÓN:** `themes` — consulta **Entradas:** `roles: [MAIN]`, luego `theme.files(filenames: ["templates/robots.txt.liquid", "layout/theme.liquid", "assets/llms.txt", "templates/llms.txt.liquid"])` **Resultado esperado:** Si el tema publicado deja entrar a los rastreadores de IA (robots), incluye un bloque JSON-LD de Organization y publica un archivo llms.txt; alimenta las revisiones de visibilidad e identidad. 3. **OPERACIÓN:** `metafieldDefinitions` — consulta **Entradas:** `ownerType: PRODUCT` **Resultado esperado:** Qué atributos estructurados están definidos (material, especificaciones, características); alimenta la revisión de cobertura de metacampos. 4. **OPERACIÓN:** `products` — consulta (pagina hasta `sample_size`) **Entradas:** `first: 250`, campos: `descriptionHtml`, `category`, `media`, `metafields`, `variants{ barcode, sku, price }` **Resultado esperado:** Nivel de completitud por producto: largo de la descripción, cobertura de texto alternativo en las imágenes, presencia de código de barras/GTIN, categoría asignada y metacampos llenos. 5. **OPERACIÓN:** `files` — consulta **Entradas:** `first: 50`, `query: "media_type:IMAGE"` (muestra); confirma la cobertura de texto alternativo a nivel de archivo. **Resultado esperado:** Porcentaje de imágenes de producto con texto alternativo. 6. **CÁLCULO (sin API):** consolida los hallazgos en un puntaje de preparación de 0 a 100 repartido en cinco pilares —**Visibilidad** (robots/llms.txt), **Confianza** (esquema Organization, sameAs, políticas), **Legibilidad** (descripciones, texto alternativo, campos JSON-LD), **Estructura** (metacampos, categoría, códigos de barras), **Coincidencia** (riqueza de títulos, etiquetas y metacampos para responder a la intención de búsqueda)— y asigna a cada pilar que falle la skill que lo corrige. ## Operaciones GraphQL ```graphql # shop:query — validada con api_version 2025-01 query AgenticReadinessShop { shop { name myshopifyDomain primaryDomain { url } contactEmail shopPolicies { type body url } } } ``` ```graphql # themes:query — validada con api_version 2025-01 query AgenticReadinessTheme { themes(first: 1, roles: [MAIN]) { nodes { id name files(filenames: [ "templates/robots.txt.liquid", "layout/theme.liquid", "assets/llms.txt", "templates/llms.txt.liquid" ]) { nodes { filename body { ... on OnlineStoreThemeFileBodyText { content } } } } } } } ``` ```graphql # metafieldDefinitions:query — validada con api_version 2025-01 query AgenticReadinessMetafieldDefs { metafieldDefinitions(first: 100, ownerType: PRODUCT) { edges { node { namespace key name type { name } } } } } ``` ```graphql # products:query — validada con api_version 2025-01 query AgenticReadinessProducts($first: Int!, $after: String) { products(first: $first, after: $after) { edges { node { id title descriptionHtml category { id fullName } tags media(first: 10) { edges { node { ... on MediaImage { id image { altText url } } } } } metafields(first: 20) { edges { node { namespace key value } } } variants(first: 100) { edges { node { id sku barcode price } } } } } pageInfo { hasNextPage endCursor } } } ``` ```graphql # files:query — validada con api_version 2025-01 query AgenticReadinessFiles($first: Int!, $after: String) { files(first: $first, after: $after, query: "media_type:IMAGE") { edges { node { ... on MediaImage { id alt } } } pageInfo { hasNextPage endCursor } } } ``` ## Seguimiento de la sesión **Claude DEBE mostrar lo siguiente en cada etapa. Es obligatorio.** **Al iniciar**, muestra: ``` ╔══════════════════════════════════════════════╗ ║ SKILL: ║ ║ Tienda: ║ ║ Inicio: ║ ╚══════════════════════════════════════════════╝ ``` **Después de cada paso**, muestra: ``` [N/TOTAL] → Parámetros: → Resultado: ``` Si `dry_run: true`, antepón `[SIMULACIÓN]` a cada paso de mutación y no lo ejecutes. **Al terminar**, muestra: Para `format: human` (predeterminado): ``` ══════════════════════════════════════════════ RESUMEN DEL RESULTADO : Errores: 0 Archivo: ══════════════════════════════════════════════ ``` Para `format: json`, muestra: ```json { "skill": "", "store": "", "started_at": "", "completed_at": "", "dry_run": false, "steps": [ { "step": 1, "operation": "", "type": "query", "params_summary": "", "result_summary": "", "skipped": false } ], "outcome": { "metric_key": 0, "errors": 0, "output_file": null } } ``` ## Formato de salida Una tarjeta de puntaje de preparación. `human`: un puntaje general de 0 a 100, barras por pilar (Visibilidad / Confianza / Legibilidad / Estructura / Coincidencia) y una tabla de fallas en orden de prioridad donde cada fila es `falla → impacto → la skill para agentes de IA que hay que ejecutar`. `json`: `{ score, grade, pillars{...}, gaps:[{ pillar, finding, fix_skill }], sampled_products }`. Cada valor de `fix_skill` es el nombre de una skill hermana (p. ej., `shopify-texto-alternativo-imagenes`), para que quien opera la tienda pase directo a la corrección. ## Manejo de errores | Error | Causa | Solución | |-------|-------|----------| | `THROTTLED` | Límite de solicitudes de la API | Espera 2 s y reintenta hasta 3 veces | | `ACCESS_DENIED` al leer los temas | Falta el permiso `read_content` | Omite la parte del tema, marca Visibilidad y Confianza como «desconocido» y continúa | | Catálogo vacío | Tienda nueva o sin productos | Reporta «no hay productos para evaluar»; igual revisa el tema y las políticas | ## Buenas prácticas - Ejecútala PRIMERO y repítela después de cada skill de corrección: es el marcador que te dice qué falta y qué mejoró. - Toma una muestra, no recorras todo: 250 productos bastan para estimar los porcentajes de llenado; audita el catálogo completo solo cuando la muestra deje pilares en el límite. - Trata los productos sin `category` y sin `barcode` como las fallas de mayor impacto: resolverlas destraba a la vez la búsqueda por IA (Coincidencia) y el JSON-LD de producto (Legibilidad). - Esta skill es de solo lectura; nunca necesita `dry_run`. Las skills a las que te remite SÍ hacen cambios: ejecuta cada una primero con `dry_run: true`.