--- name: shopify-llms-txt description: "Genera y publica una guía /llms.txt (resumen de la marca, productos estrella, políticas clave y contacto) mediante una plantilla del tema, para que los asistentes de IA tengan un mapa claro de tu tienda. Úsala cuando quieras que la IA entienda qué vendes y dónde está lo importante." --- ## Propósito `llms.txt` es la convención que se está imponiendo para contarles a los asistentes de IA, en texto plano, qué es un sitio y dónde están sus páginas importantes: una puerta de entrada curada para los modelos. Esta skill arma un `llms.txt` con los datos de la propia tienda (frase que resume la marca, colecciones principales, productos estrella con sus URL, enlaces a las políticas de envío y devoluciones, contacto) y lo publica mediante una plantilla del tema para que se sirva en una ruta estable. Resuelve el problema de no tener un `llms.txt` (ni en la raíz ni en `/.well-known/`) y ayuda a que los agentes de IA descubran la tienda. ## Requisitos - Sesión autenticada de Shopify CLI: `shopify store auth --store .myshopify.com --scopes read_products,read_themes,write_themes` - Las consultas se ejecutan con `shopify store execute`. - Permisos (scopes) de API necesarios: `read_products`, `read_themes`, `write_themes` ## 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., tu-tienda.myshopify.com) | | format | string | no | human | Formato de salida: `human` (predeterminado) o `json` | | dry_run | bool | no | true | Muestra el llms.txt generado sin escribirlo (activado por defecto, porque edita el tema publicado) | Parámetros propios de esta skill: | Parámetro | Tipo | Obligatorio | Predeterminado | Descripción | |-----------|------|-------------|----------------|-------------| | theme_id | string | no | — | GID del tema (por defecto, el tema MAIN publicado) | | flagship_count | int | no | 12 | Cuántos productos principales listar | | flagship_collection_id | string | no | — | Colección de la que se toma la lista de productos estrella (si no, los más vendidos o los más recientes) | | brand_summary | string | no | — | Reemplaza la frase que resume la marca (si no, se deduce de los datos de la tienda y de la página de inicio) | ## Seguridad > ⚠️ El paso 4 (`themeFilesUpsert`) escribe una plantilla nueva en el tema PUBLICADO. El contenido es aditivo (un archivo y una ruta nuevos) y de bajo riesgo, pero se publica de inmediato. Por defecto usa `dry_run: true` para que revises primero el `llms.txt` generado. Se recomienda duplicar el tema antes de escribir. ## Pasos 1. **OPERACIÓN:** `shop` — consulta **Entradas:** ninguna **Resultado esperado:** Nombre de la tienda, dominio, correo de contacto y URL de las políticas: el encabezado y las secciones de contacto y políticas del llms.txt. 2. **OPERACIÓN:** `products` — consulta **Entradas:** `first: flagship_count`, opcionalmente `query: "collection_id:''"` (cuando se indica `flagship_collection_id`, ese conjunto curado es tu lista de productos estrella); en caso contrario, `sortKey: UPDATED_AT, reverse: true`; campos `title`, `onlineStoreUrl`, `description`. **Resultado esperado:** Lista de productos estrella con sus URL para la sección «Productos clave». (La consulta `products` de primer nivel no permite ordenar por más vendidos: usa la colección curada para tener los verdaderos más vendidos o, si no, los actualizados más recientemente como aproximación.) 3. **CÁLCULO (sin API):** arma el markdown del `llms.txt`: `# ` + una frase, `## Productos clave` (título — URL — una línea), `## Políticas` (URL de envíos, devoluciones y privacidad), `## Contacto`. Muestra el texto completo. 4. **OPERACIÓN:** `themeFilesUpsert` — mutación **Entradas:** `themeId`; escribe `templates/page.llms.liquid` (una plantilla de página que entrega el texto como `text/plain`) y, si se usa, una copia en `assets/llms.txt`; se omite con `dry_run`. **Resultado esperado:** Archivo(s) del tema creados o actualizados; recoge los `userErrors`. (Nota: muestra una instrucción de una línea para crear una página con la plantilla `llms` o para agregar una redirección desde `/llms.txt`.) ## Operaciones GraphQL ```graphql # shop:query — validada con api_version 2025-01 query LlmsTxtShop { shop { name primaryDomain { url } contactEmail shopPolicies { type url } } } ``` ```graphql # products:query — validada con api_version 2025-01 # La consulta `products` de primer nivel no tiene la clave de orden BEST_SELLING. # Pasa un filtro `collection_id:'…'` para usar un conjunto curado de productos # estrella; si no, recurre a los productos actualizados más recientemente. query LlmsTxtFlagship($first: Int!, $query: String) { products(first: $first, query: $query, sortKey: UPDATED_AT, reverse: true) { edges { node { id title onlineStoreUrl description } } } } ``` ```graphql # themeFilesUpsert:mutation — validada con api_version 2025-01 mutation LlmsTxtUpsert($themeId: ID!, $files: [OnlineStoreThemeFilesUpsertFileInput!]!) { themeFilesUpsert(themeId: $themeId, files: $files) { upsertedThemeFiles { filename } userErrors { filename code 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": "", "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`: el `llms.txt` generado completo y el paso posterior a la publicación (crear una página con la plantilla `llms` o agregar una redirección de `/llms.txt` → la página). `json`: `{ theme_id, llms_txt, wrote: true|false, follow_up, errors }`. ## 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` | Falta el permiso `write_themes` | Detente y entrega el llms.txt generado para que se pueda agregar a mano | | No hay productos estrella | Catálogo vacío o nuevo | Publica solo el encabezado, las políticas y el contacto | ## Buenas prácticas - Hazlo corto y con información valiosa: `llms.txt` es un mapa, no un volcado; enlaza a las páginas canónicas en vez de pegar su contenido. - Vuelve a generarlo cuando cambien los productos estrella o las políticas (puedes programarlo como una tarea periódica). - Combínala con `shopify-acceso-rastreadores-ia`: un llms.txt solo sirve si los rastreadores tienen permiso para entrar. - Después de publicar, agrega en la tienda una redirección de `/llms.txt` → la página para que quede en la ruta convencional.