--- name: shopify-metacampos-para-ia description: "Crea y llena metacampos estándar (material, características, cuidado, ajuste, especificaciones) para que los agentes de IA filtren tus productos según lo que pide cada comprador. Úsala cuando quieras que tu catálogo aparezca en búsquedas con requisitos concretos." --- ## Propósito Los agentes de IA responden búsquedas con condiciones —«leggings que no se transparentan al hacer sentadillas por menos de 60», «mocasines de eucalipto», «lana que se pueda lavar en lavadora»— filtrando por atributos estructurados. Si esos atributos solo están en el texto de la descripción (o en ninguna parte), el agente no puede filtrar y tus productos quedan por fuera de los resultados. Esta skill crea un conjunto pequeño y estándar de **definiciones de metacampos para agentes** (material, características clave, cuidado, ajuste, especificaciones) y las llena en todo el catálogo a partir de la información que ya tienen los productos, para que los agentes puedan emparejar productos con requisitos. Corrige tres problemas: productos sin metacampos en la ficha, variantes sin datos estructurados y tallas o especificaciones que no están en un formato estructurado. ## Requisitos - Sesión autenticada de Shopify CLI: `shopify store auth --store .myshopify.com --scopes read_products,write_products,read_metaobject_definitions,write_metaobject_definitions` - Las consultas se ejecutan con `shopify store execute`. - Permisos (scopes) de API necesarios: `read_products`, `write_products`, `read_metaobject_definitions`, `write_metaobject_definitions` (para las definiciones) ## 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 | |-----------|------|-------------|----------------|-------------| | namespace | string | no | agentic | Namespace de metacampos donde se crean y llenan los valores | | keys | string | no | material,features,care,fit,specs | Lista separada por comas de las claves de metacampo que deben existir | | collection_id | string | no | — | Limita el llenado a una colección (GID) | | tag | string | no | — | Limita el llenado a una etiqueta de producto | | populate_from | string | no | tags,options,description | Fuentes de las que se deducen los valores (no se inventa nada fuera de ellas) | ## Seguridad > ⚠️ El paso 2 (`metafieldDefinitionCreate`) y el paso 4 (`metafieldsSet`) modifican la estructura de la tienda y los datos de los productos. Agregar definiciones cuesta poco, pero si quedan en el namespace equivocado llenan el admin de ruido; además, los valores deducidos pueden estar mal. Ejecuta con `dry_run: true`, revisa las definiciones propuestas y la vista previa de valores, y llena solo los valores deducidos con alta confianza; deja el resto en blanco para que una persona los complete. ## Pasos 1. **OPERACIÓN:** `metafieldDefinitions` — consulta **Entradas:** `ownerType: PRODUCT`, `namespace: ` **Resultado esperado:** Qué claves objetivo ya tienen definición (esas se omiten). 2. **OPERACIÓN:** `metafieldDefinitionCreate` — mutación **Entradas:** una por cada clave que falte: `{ namespace, key, name, ownerType: PRODUCT, type: "single_line_text_field" | "list.single_line_text_field" }` **Resultado esperado:** Definiciones creadas; recoge los `userErrors` (p. ej., clave ya tomada). 3. **OPERACIÓN:** `products` — consulta **Entradas:** `first: 250`, filtro opcional; campos `tags`, `options`, `descriptionHtml` y los `metafields(namespace)` existentes; pagina los resultados. **Resultado esperado:** Los productos y la información de la que se deducen los valores de los atributos. 4. **OPERACIÓN:** `metafieldsSet` — mutación **Entradas:** lotes de `{ ownerId, namespace, key, value, type }` para los valores deducidos con confianza que hoy están vacíos. **Resultado esperado:** Metacampos guardados; recoge los `userErrors`. ## Operaciones GraphQL ```graphql # metafieldDefinitions:query — validada con api_version 2025-01 query AgenticMetafieldDefs($namespace: String!) { metafieldDefinitions(first: 50, ownerType: PRODUCT, namespace: $namespace) { edges { node { id namespace key name type { name } } } } } ``` ```graphql # metafieldDefinitionCreate:mutation — validada con api_version 2025-01 mutation AgenticMetafieldDefCreate($definition: MetafieldDefinitionInput!) { metafieldDefinitionCreate(definition: $definition) { createdDefinition { id namespace key } userErrors { field message code } } } ``` ```graphql # products:query — validada con api_version 2025-01 query AgenticMetafieldProducts($first: Int!, $after: String, $query: String, $namespace: String!) { products(first: $first, after: $after, query: $query) { edges { node { id title tags options { name values } descriptionHtml metafields(first: 20, namespace: $namespace) { edges { node { key value } } } } } pageInfo { hasNextPage endCursor } } } ``` ```graphql # metafieldsSet:mutation — validada con api_version 2025-01 mutation AgenticMetafieldsSet($metafields: [MetafieldsSetInput!]!) { metafieldsSet(metafields: $metafields) { metafields { id namespace key } userErrors { field message code } } } ``` ## 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 `human`: las definiciones creadas y un CSV con los valores llenados (`product, key, value, source`). `json`: `{ definitions_created, metafields_set, products_touched, 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 | | `TAKEN` en la definición | La clave ya está definida en otro lugar | Reutiliza la definición existente y sigue con el llenado | | `userErrors` al guardar | El tipo no coincide (p. ej., lista frente a valor único) | Convierte el valor al tipo de la definición, reintenta una vez y, si falla, omítelo | ## Buenas prácticas - Mantén el namespace pequeño y estándar (`agentic`) y el conjunto de claves acotado: tanto los agentes como los filtros de la tienda en línea se benefician de la consistencia. - Escribe solo valores que puedas deducir con alta confianza a partir de información real; un «material: cuero» equivocado engaña a todos los agentes. Deja en blanco los campos de baja confianza. - Usa `list.single_line_text_field` para atributos con varios valores (características, materiales), así los filtros muestran los productos que tengan cualquiera de esos valores. - Sigue con `shopify-descripciones-para-ia` para que el texto y los datos estructurados digan lo mismo.