---
name: shopify-esquema-organizacion
description: "Agrega al tema un bloque JSON-LD de Organization (nombre, logo, redes oficiales en sameAs, contacto) para que los agentes de IA verifiquen que tu tienda es una marca real y confiable. Úsala cuando quieras que la IA reconozca tu marca y la conecte con su identidad pública."
---

## Propósito
Los asistentes de IA revisan el JSON-LD `schema.org/Organization` de un sitio para confirmar que es la marca real (y no una falsificación o un revendedor) y para conectarlo con su identidad pública a través de `sameAs` (redes sociales oficiales, Wikipedia/Wikidata) y de un `contactPoint` legible por máquinas. Sin esto, los agentes dudan en recomendar la tienda o en enviarle compradores. Esta skill arma un bloque JSON-LD de Organization con los datos de la tienda y los enlaces sociales que le indiques, y lo inserta en el layout del tema mediante un snippet gestionado. Resuelve la falta de esquema Organization y de un contacto legible por máquinas, y ayuda a vincular la marca con su ficha de Wikidata (a través de `sameAs`).

## Requisitos
- Sesión autenticada de Shopify CLI: `shopify store auth --store <tu-tienda>.myshopify.com --scopes read_themes,write_themes`
- Las consultas se ejecutan con `shopify store execute`.
- Permisos (scopes) de API necesarios: `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., mitienda.myshopify.com) |
| format    | string | no          | human          | Formato de salida: `human` (predeterminado) o `json` |
| dry_run   | bool   | no          | true           | Muestra el snippet y la inserción sin escribir nada (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) |
| logo_url | string | no | — | URL absoluta del logo (si no se da, se toma de la configuración del tema cuando esté disponible) |
| same_as | string | no | — | Lista separada por comas de las URL de perfiles oficiales (Instagram, TikTok, LinkedIn, Wikipedia, Wikidata) |
| contact_email | string | no | — | Correo de atención al cliente para `contactPoint` (si no se da, se usa el contactEmail de la tienda) |
| contact_phone | string | no | — | Teléfono de atención opcional para `contactPoint` |

## Seguridad

> ⚠️ El paso 3 (`themeFilesUpsert`) escribe un snippet y edita `layout/theme.liquid` en el tema PUBLICADO. El cambio es aditivo (un `{% render %}` dentro de `<head>`), pero se publica de inmediato, y una edición mal formada en `theme.liquid` puede romper la tienda. La skill escribe el JSON-LD en su propio archivo de snippet e inserta una sola línea gestionada `{% render 'esquema-organizacion' %}` dentro de un bloque marcado con `# BEGIN/END`. Por defecto usa `dry_run: true`; duplica el tema antes de empezar.

## Pasos

1. **OPERACIÓN:** `shop` — consulta
   **Entradas:** ninguna
   **Resultado esperado:** Nombre de la tienda, dominio principal y correo de contacto: los campos básicos de Organization.

2. **OPERACIÓN:** `themes` — consulta
   **Entradas:** `roles: [MAIN]`, `theme.files(filenames: ["layout/theme.liquid", "snippets/esquema-organizacion.liquid"])`
   **Resultado esperado:** El layout actual (para insertar la etiqueta render) y si el snippet ya existe.

3. **OPERACIÓN:** `themeFilesUpsert` — mutación
   **Entradas:** escribe `snippets/esquema-organizacion.liquid` (el JSON-LD dentro de `<script type="application/ld+json">`) y actualiza `layout/theme.liquid` agregando el bloque gestionado `{% render %}` en `<head>` si no está. Se omite con `dry_run`.
   **Resultado esperado:** Archivos guardados; recoge los `userErrors`.

## Operaciones GraphQL

```graphql
# shop:query — validada con api_version 2025-01
query OrgSchemaShop {
  shop {
    name
    primaryDomain { url }
    contactEmail
  }
}
```

```graphql
# themes:query — validada con api_version 2025-01
query OrgSchemaTheme {
  themes(first: 1, roles: [MAIN]) {
    nodes {
      id
      files(filenames: ["layout/theme.liquid", "snippets/esquema-organizacion.liquid"]) {
        nodes {
          filename
          body { ... on OnlineStoreThemeFileBodyText { content } }
        }
      }
    }
  }
}
```

```graphql
# themeFilesUpsert:mutation — validada con api_version 2025-01
mutation OrgSchemaUpsert($themeId: ID!, $files: [OnlineStoreThemeFilesUpsertFileInput!]!) {
  themeFilesUpsert(themeId: $themeId, files: $files) {
    upsertedThemeFiles { filename }
    userErrors { filename code message }
  }
}
```

Contenido del snippet (`snippets/esquema-organizacion.liquid`):

```liquid
{%- comment -%} gestionado por shopify-esquema-organizacion {%- endcomment -%}
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "<nombre de la tienda>",
  "url": "<dominio principal>",
  "logo": "<logo_url>",
  "sameAs": [ "<same_as[0]>", "..." ],
  "contactPoint": {
    "@type": "ContactPoint",
    "contactType": "customer support",
    "email": "<contact_email>"
  }
}
</script>
```

## Seguimiento de la sesión

**Claude DEBE mostrar lo siguiente en cada etapa. Es obligatorio.**

**Al iniciar**, muestra:
```
╔══════════════════════════════════════════════╗
║  SKILL: <nombre de la skill>                 ║
║  Tienda: <dominio de la tienda>              ║
║  Inicio: <AAAA-MM-DD HH:MM UTC>              ║
╚══════════════════════════════════════════════╝
```

**Después de cada paso**, muestra:
```
[N/TOTAL] <CONSULTA|MUTACIÓN>  <OperationName>
          → Parámetros: <resumen breve de las entradas clave>
          → Resultado: <cantidad o desenlace>
```

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
  <Métrica>:        <valor>
  Errores:          0
  Archivo:          <nombre del archivo o "ninguno">
══════════════════════════════════════════════
```

Para `format: json`, muestra:
```json
{
  "skill": "shopify-esquema-organizacion",
  "store": "<dominio>",
  "started_at": "<ISO8601>",
  "completed_at": "<ISO8601>",
  "dry_run": false,
  "steps": [
    {
      "step": 1,
      "operation": "<OperationName>",
      "type": "query",
      "params_summary": "<texto>",
      "result_summary": "<texto>",
      "skipped": false
    }
  ],
  "outcome": {
    "metric_key": 0,
    "errors": 0,
    "output_file": null
  }
}
```

## Formato de salida
`human`: el JSON-LD generado y la diferencia del layout que muestra la única línea render insertada. `json`: `{ theme_id, json_ld, layout_modified: true|false, wrote: true|false, 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` | Detén la ejecución; entrega el snippet para pegarlo a mano |
| `userErrors` al actualizar el layout | Error de sintaxis Liquid | Escribe solo el snippet, omite la edición del layout y muestra la instrucción para agregar el `{% render %}` a mano |

## Buenas prácticas
- Pon en `sameAs` solo URL REALES y oficiales: un perfil equivocado le resta confianza a la marca en vez de sumarle. Los enlaces a Wikipedia/Wikidata son señales de identidad especialmente fuertes.
- Inserta el bloque con un snippet y una sola línea render gestionada; nunca pegues el JSON-LD directamente en `theme.liquid`, así las nuevas ejecuciones y la reversión quedan limpias.
- Usa una URL de `logo` absoluta y con HTTPS (un PNG cuadrado funciona mejor para los paneles de información de los buscadores).
- Duplica el tema primero y mantén `dry_run: true` hasta que hayas leído la diferencia del layout.