--- name: shopify-descripciones-para-ia description: "Reescribe descripciones de producto pobres en textos estructurados y con datos concretos (materiales, ajuste, usos y las palabras que de verdad buscan los compradores) para que los agentes de IA tengan qué citar. Úsala cuando tus fichas tengan descripciones cortas o vacías." --- ## Propósito Cuando un agente de IA decide si recomienda un producto, cita la descripción para justificar la elección. Una descripción de una línea o vacía no le da nada: no puede confirmar que el producto encaja con lo que busca el comprador y pasa al siguiente. Esta skill encuentra productos con descripciones pobres (por debajo de un mínimo de caracteres o sin atributos clave) y las reescribe en un texto estructurado: una frase inicial centrada en el beneficio y luego datos concretos (material, ajuste/tallas, medidas, usos, cuidado) tomados de los propios metacampos, opciones y tipo del producto. Corrige las descripciones de baja calidad en las fichas y refuerza los datos estructurados que los agentes leen de cada ficha. ## Requisitos - Sesión autenticada de Shopify CLI: `shopify store auth --store .myshopify.com --scopes read_products,write_products` - Las consultas se ejecutan con `shopify store execute`. - Permisos (scopes) de API necesarios: `read_products`, `write_products` ## 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 | Muestra las mutaciones sin ejecutarlas | Parámetros propios de esta skill: | Parámetro | Tipo | Obligatorio | Predeterminado | Descripción | |-----------|------|-------------|----------------|-------------| | collection_id | string | no | — | Limita el trabajo a una colección (GID) | | tag | string | no | — | Limita el trabajo a una etiqueta de producto | | min_chars | int | no | 120 | Se reescriben los productos cuya descripción, en texto plano, tenga menos caracteres que este valor | | overwrite | bool | no | false | Si es false, solo enriquece los productos por debajo de `min_chars`; si es true, reestructura todos los productos seleccionados | | brand_voice | string | no | — | Indicaciones opcionales de tono (p. ej., "sencillo, técnico, sin exageraciones") | ## Seguridad > ⚠️ El paso 3 (`productUpdate`) reemplaza `descriptionHtml` en productos publicados. Es contenido que el comerciante pudo haber escrito a mano. Ejecuta siempre con `dry_run: true`, exporta el antes y el después, y haz que una persona apruebe las reescrituras antes de guardarlas. Por defecto solo se tocan los productos por debajo de `min_chars`. ## Pasos 1. **OPERACIÓN:** `products` — consulta **Entradas:** `first: 100`, filtro opcional; campos `descriptionHtml`, `title`, `productType`, `options`, `tags`, `metafields(first: 30)`; pagina los resultados. **Resultado esperado:** Los productos cuya descripción, sin etiquetas HTML, está por debajo de `min_chars`, junto con los datos estructurados disponibles para enriquecerla. 2. **CÁLCULO (sin API):** para cada producto con descripción pobre, redacta un `descriptionHtml`: una frase de beneficio y una lista corta de datos construida SOLO con información real del producto (sin inventar especificaciones), respetando `brand_voice`. Muestra una vista previa del antes y el después. 3. **OPERACIÓN:** `productUpdate` — mutación **Entradas:** `{ id, descriptionHtml }` por cada producto aprobado. **Resultado esperado:** Producto actualizado; recoge los `userErrors`. ## Operaciones GraphQL ```graphql # products:query — validada con api_version 2025-01 query EnrichProducts($first: Int!, $after: String, $query: String) { products(first: $first, after: $after, query: $query) { edges { node { id title descriptionHtml productType tags options { name values } metafields(first: 30) { edges { node { namespace key value type } } } } } pageInfo { hasNextPage endCursor } } } ``` ```graphql # productUpdate:mutation — validada con api_version 2025-01 mutation EnrichProductDescription($input: ProductInput!) { productUpdate(input: $input) { product { id descriptionHtml } userErrors { field message } } } ``` ## 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": "shopify-descripciones-para-ia", "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 `human`: cantidad de productos enriquecidos y un CSV con el antes y el después (`product, old_len, new_len, new_description`). `json`: `{ products_enriched, products_skipped, errors, output_file }`. ## Manejo de errores | Error | Causa | Solución | |-------|-------|----------| | `THROTTLED` | Límite de solicitudes de la API | Espera 2 s y reintenta hasta 3 veces | | `userErrors` con contenido | HTML no válido o largo del campo | Registra el mensaje, omite el producto y sigue | | No hay datos para enriquecer | El producto tiene muy poca información | Omítelo; recomienda correr primero `shopify-metacampos-para-ia` | ## Buenas prácticas - Enriquece con datos que la tienda ya tiene (metacampos, opciones, tipo): nunca inventes materiales, certificaciones ni medidas. - Pon primero los atributos por los que buscan los compradores; los agentes le dan mucho peso a la primera frase al emparejar lo que busca la persona. - Combínala con `shopify-metacampos-para-ia`: los metacampos estructurados hacen que las descripciones sean más completas y que las máquinas puedan filtrarlas. - Haz siempre que una persona apruebe las diferencias de la simulación para los productos estrella o más vendidos antes de guardar.