--- name: shopify-politicas-legibles description: "Revisa que tus políticas de envío, devoluciones, reembolsos, privacidad y términos existan como texto limpio que un agente de IA pueda leer. Úsala cuando quieras que los agentes de IA respondan las dudas del comprador y cierren la venta sin escalar." --- ## Propósito Antes de completar una compra para un comprador, un agente de IA revisa las políticas de la tienda: «¿Hacen envíos a donde estoy? ¿Cuántos días tengo para devolver?». Si las políticas de envío o de devoluciones no existen, están vacías o están enterradas en una imagen o un PDF, el agente no puede responder, pierde confianza y abandona la compra o manda al comprador a otra tienda. Esta skill audita las políticas de la tienda y se asegura de que las principales existan como contenido limpio, en texto plano o HTML, que un agente pueda leer y citar. Resuelve dos problemas concretos: una política de envíos que un agente no puede leer y una política de devoluciones que un agente no puede leer. ## Requisitos - Sesión autenticada de Shopify CLI: `shopify store auth --store .myshopify.com --scopes read_legal_policies,write_legal_policies` - Las consultas se ejecutan con `shopify store execute`. - Permisos (scopes) de API: `read_legal_policies` (o `read_online_store_pages`), `write_legal_policies` ## Parámetros Todas las skills aceptan estos parámetros universales: | 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 los textos de política propuestos sin escribirlos (activado por defecto, porque edita las políticas publicadas de la tienda) | Parámetros propios de esta skill: | Parámetro | Tipo | Obligatorio | Predeterminado | Descripción | |-----------|------|-------------|----------------|-------------| | policies | string | no | REFUND_POLICY,SHIPPING_POLICY | Lista separada por comas de los tipos de política que se deben asegurar: `REFUND_POLICY,SHIPPING_POLICY,PRIVACY_POLICY,TERMS_OF_SERVICE` | | mode | string | no | audit | `audit` (solo reporta lo que falta) o `apply` (escribe los textos que entregas o que se redactaron) | | bodies_dir | string | no | — | Carpeta con archivos `.html` que se usan como texto oficial cuando `mode: apply` | ## Seguridad > ⚠️ El paso 3 (`shopPolicyUpdate`) reemplaza el texto de una política legal PUBLICADA: es contenido con validez legal. NUNCA generes texto legal de forma automática. En `mode: apply` la skill solo escribe los textos que tú entregas en `bodies_dir`; no inventa redacción legal. Lo predeterminado es `mode: audit` + `dry_run: true`. Pide que el área legal u operaciones revise cada texto antes de usar `mode: apply`. ## Pasos 1. **OPERACIÓN:** `shop` — consulta **Entradas:** ninguna; lee `shopPolicies { type body url }` **Resultado esperado:** Qué políticas objetivo existen, están vacías o son solo una imagen (criterio aproximado: un texto muy corto o un texto que es solo un `` o un enlace). 2. **CÁLCULO (sin API):** clasifica cada política como OK / falta / pobre / solo imagen. En modo `audit`, detente aquí y reporta. En modo `apply`, carga el `.html` correspondiente desde `bodies_dir` para cada faltante y muestra una vista previa de antes y después. 3. **OPERACIÓN:** `shopPolicyUpdate` — mutación (solo en `mode: apply` y sin `dry_run`) **Entradas:** `shopPolicy: { id: , body: }` por cada faltante. **Resultado esperado:** La política actualizada; recoge los `userErrors`. ## Operaciones GraphQL ```graphql # shop:query — validado con api_version 2025-01 query PolicyAudit { shop { shopPolicies { id type body url } } } ``` ```graphql # shopPolicyUpdate:mutation — validado con api_version 2025-01 mutation PolicyUpdate($shopPolicy: ShopPolicyInput!) { shopPolicyUpdate(shopPolicy: $shopPolicy) { shopPolicy { id type url } 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-politicas-legibles", "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`: una tabla de políticas (`type, status, length, readable?`) más el veredicto de la auditoría; en modo `apply`, el antes y el después de cada política escrita. `json`: `{ policies:[{ type, status, readable }], updated, errors, output_file }`. ## Manejo de errores | Error | Causa | Solución | |-------|-------|----------| | `THROTTLED` | Límite de solicitudes de la API | Espera 2 segundos y reintenta hasta 3 veces | | `ACCESS_DENIED` | Falta `write_legal_policies` | Quédate en modo auditoría y reporta lo que falta para completarlo a mano | | A `bodies_dir` le falta un tipo | No hay un texto entregado para un faltante | Omite esa política y déjala en el reporte de faltantes | ## Buenas prácticas - Usa `mode: audit` por defecto: el valor principal de esta skill es encontrar políticas vacías o que son solo una imagen; escribir texto legal es una decisión humana. - Haz que las políticas sean concretas y fáciles de interpretar: indica el plazo de devolución en días, los tiempos de envío y las regiones en frases simples; eso es lo que citan los agentes. - Evita por completo las políticas que solo están en imagen o en PDF; los agentes (y muchos compradores) no pueden leerlas. - Guarda el texto oficial de cada política en `bodies_dir` con control de versiones, para que volver a aplicarlo después de editarlo quede registrado.