Implementación de Datos Estructurados de Schema.org — Habilidad de Flujo de Trabajo Completo
Esta habilidad proporciona una metodología integral para analizar sitios web, diseñar marcado schema.org y producir tickets listos para el desarrollador. Ha sido perfeccionada a través de proyectos reales que implementan datos estructurados en sitios web multilingües y multirregionales.
La metodología es agnóstica al cliente. Funciona para cualquier sitio web donde el objetivo sea una cobertura completa de schema.org con entrega al desarrollador a través de una herramienta de gestión de proyectos (JIRA, Wrike o similar).
Licencia: Esta habilidad se publica bajo la licencia Creative Commons Attribution 4.0 Internacional (CC BY 4.0). Eres libre de compartir y adaptar esta habilidad para cualquier propósito, siempre que des el crédito apropiado al autor original.
Auditorías relacionadas: la Fase 5 de esta habilidad verifica la salida en vivo contra la especificación diseñada en la Fase 2. Cuando la tarea, en cambio, es verificar una corrección reportada entre locales ("corregido para todos los idiomas", "desplegado en todas partes"), ejecuta una auditoría de validación JSON-LD, con las disciplinas de verificación de reclamos que esta habilidad no posee: la puerta de invalidación de caché, la enumeración de la población desde el índice del sitemap / el conjunto de hreflang en vivo y el control positivo. El final de la auditoría del trabajo de breadcrumb es una auditoría de navegación de breadcrumb; esta habilidad maneja su parte de tickets.
Cómo Funciona Esta Habilidad
Esta es una habilidad de proyecto, que generalmente se completa en 1 a 3 horas en 1 a 2 sesiones para la mayoría de los sitios web. Los sitios multilingües complejos con muchos tipos de página pueden llevar más tiempo. La habilidad define cinco fases de entrega secuenciales: Fase 0 (Configuración), Fase 1 (Descubrimiento), Fase 2 (Diseño de Schema), Fase 3 (Creación de Tickets) y Fase 4 (Regeneración y Entrega), seguidas de dos fases posteriores al despliegue que se ejecutan una vez que el desarrollador ha enviado el código: Fase 5 (Verificación Posterior al Despliegue) y Fase 6 (Medición de Impacto). Claude debe identificar en qué fase se encuentra el usuario y guiarlo a través de ella.
El usuario proporciona: Contexto del proyecto, comentarios sobre análisis y borradores de tickets, reglas específicas del proyecto y resolución de preguntas abiertas. Claude proporciona: Descubrimiento de tipos de página, análisis de HTML, diseño de schema, borradores de tickets (principal + secundario) y un conjunto final de tickets regenerados.
Nota de terminología: Esta habilidad usa "ticket" como término genérico para el entregable orientado al desarrollador. El formato real depende de la plataforma de gestión de proyectos elegida en la Fase 0 (tickets de JIRA, tareas de Wrike, etc.).
Archivos de referencia — cargar bajo demanda
Las Fases 1 a 6 residen en archivos de referencia, un archivo por fase. Cada puntero nombra su desencadenante. Estas cargas son pasos obligatorios: cuando comienza una fase, carga su archivo antes de hacer el trabajo — nunca improvises una fase desde este archivo principal. Si notas que una fase fue manejada sin cargar su archivo, dilo, cárgalo y vuelve a verificar el trabajo realizado hasta ahora contra él.
references/discovery.md— Fase 1: catálogo de tipos de página, triaje, verificación de la guía de Google, análisis por tipo de página (schema existente en los tres formatos, triaje condicional de schema, entrega de locales), guardado de datos reales, consolidación, clasificación. Cargar antes de construir el catálogo de tipos de página y antes de analizar el HTML de cualquier tipo de página.references/schema-design.md— Fase 2, secciones 2.1–2.7: schema global y específico de página, referencias cruzadas@id, deprecación vs eliminación, disposiciones de migración de formato, reglas de selección de propiedades, valores de propiedades multilingües, verificación de suposiciones, reglas del proyecto. Cargar antes de elegir tipos de schema o propiedades para cualquier tipo de página.references/ticket-writing.md— Fase 3: verificación previa, la plantilla de ticket, pautas para subagentes, las reglas numeradas de escritura de tickets (1–46), el ticket principal, la lista de verificación previa a la entrega, el flujo de trabajo de comentarios y Decisiones Comunes de Schema (§3.7). Cargar antes de redactar, revisar o verificar cualquier ticket, antes de informar a un subagente sobre tickets y cuando surja una decisión de §3.7 en el diseño.references/delivery.md— Fase 4: plan de regeneración, formato específico de la plataforma (Wrike, JIRA, editores de texto enriquecido, herramientas protegidas por WAF), el árbol de decisión del formato de entrega, pase editorial, verificaciones de consistencia entre tickets, empaquetado, Wrike XLS + pegado HTML. Cargar antes de la regeneración final y antes de formatear tickets para la herramienta de destino.references/post-deployment-verification.md— Fase 5: los desencadenantes del barrido de población completa, la lista de verificación previa al vuelo de la Fase 5, técnicas de verificación y recuperación entre idiomas, las cuatro categorías de hallazgos y el esqueleto del informe, comentarios de seguimiento, verificación de URL y valor de origen, reconciliación y diagnóstico de errores de GSC, falsos positivos de recuperación única, auditorías de cobertura desde exportaciones de rastreo. Cargar antes de verificar cualquier schema desplegado, antes de confirmar un ticket como completado, antes de responder a una discrepancia reportada por el cliente y antes de diagnosticar un error de datos estructurados de Search Console.references/measuring-impact.md— Fase 6: el desglose de la apariencia en la búsqueda, la declaración de expectativas, los canales medibles, la retención de datos. Cargar cuando el cliente pregunte qué lograron los datos estructurados, antes de obtener cualquier número de impacto.
Los números de sección (§1.2, §5.4) y los números de regla (Regla 35, antipatrón 21) son los mismos en todos los archivos, por lo que una referencia cruzada se resuelve a través de este mapa.
Fase 0: Configuración y Herramientas
Objetivo: Evaluar las herramientas y el acceso disponibles, configurar el flujo de trabajo más eficiente y recopilar las preferencias del proyecto antes de comenzar el trabajo de contenido.
0.1 Evaluar las Herramientas Disponibles
Antes de comenzar cualquier trabajo de análisis, determine qué capacidades están disponibles:
- Acceso al navegador (por ejemplo, Claude en la extensión de Chrome, herramientas de navegación de Cowork) — Permite a Claude navegar por páginas directamente, capturar HTML renderizado, extraer datos y verificar hechos de forma autónoma. Este es el flujo de trabajo más eficiente.
- Búsqueda web — Permite a Claude mapear la estructura del sitio, encontrar sitemaps y descubrir tipos de página sin acceso al navegador.
- Acceso al sistema de archivos — Permite guardar documentos de análisis y borradores de tickets de forma incremental.
- Acceso directo al sitio — Algunos sitios bloquean el acceso automatizado (errores 403). Si la recuperación web falla, el acceso al navegador o la carga manual de HTML son alternativas.
0.2 Guiar al Usuario Hacia el Acceso al Navegador
El análisis asistido por navegador es el flujo de trabajo principal recomendado para esta habilidad. Permite a Claude:
- Descubrir y mapear tipos de página de forma autónoma
- Capturar HTML renderizado de cualquier página sin copiar y pegar manualmente
- Extraer señales de detección, fuentes de datos y estructuras de plantilla en minutos
- Verificar hechos (patrones de URL, variantes de idioma, disponibilidad de campos) antes de escribir tickets
Si el acceso al navegador aún no está disponible, explique los beneficios y guíe al usuario a través de la configuración. El rol del usuario pasa de ser "recolector de HTML" (tedioso, de bajo valor) a "revisor y tomador de decisiones" (de alto valor, donde su experiencia en el dominio es importante).
Si el acceso al navegador no está disponible o el sitio bloquea completamente la navegación automatizada, recurra al flujo de trabajo manual descrito en la Fase 1.2.
Conciencia de costos: El acceso al navegador permite el análisis más exhaustivo, pero es significativamente más caro en el uso de tokens: las llamadas a herramientas de Chrome devuelven cargas útiles grandes que se combinan cuadráticamente a medida que crece la conversación. Reserve los flujos de trabajo del navegador para las fases de descubrimiento inicial y verificación, donde la inspección de páginas en tiempo real agrega valor genuino. Para tareas donde el inventario de tipos de página ya está establecido (por ejemplo, escribir tickets a partir de una auditoría completada), los flujos de trabajo sin navegador son igualmente efectivos y mucho más baratos. Cuando se use el navegador, prefiera llamadas dirigidas (get_page_text, find, javascript_tool para extracción quirúrgica) sobre llamadas pesadas (read_page para DOM completo, read_network_requests para tráfico completo).
0.3 Recopilar Preferencias del Proyecto
Antes de comenzar el trabajo de contenido, pregunte al usuario:
- Plataforma de gestión de proyectos — "¿En qué sistema se crearán estos tickets? (JIRA, Wrike, Asana, etc.)" Esto determina la terminología (tickets vs tareas vs elementos), las restricciones de formato (por ejemplo, Wrike no renderiza bloques de código anidados dentro de elementos de lista — ver §4.4 Pase de Formato Específico de la Plataforma en
references/delivery.md) y la convención de nomenclatura para los archivos entregables. - Estructura del ticket — "¿Su organización tiene una estructura de ticket o plantilla establecida para las tareas del desarrollador? En caso afirmativo, comparta una plantilla o pautas de creación de tickets. Adaptaré los tickets de schema para que coincidan con las convenciones de su equipo." Si no existe ninguna plantilla, use la estructura predeterminada de la habilidad.
- Saludo y tono — por ejemplo, "Hola equipo," con un tono entre pares, o formal.
- Reglas específicas del proyecto — Restricciones de privacidad, terminología, reglas de marca, etc. (También se pueden recopilar durante la Fase 2).
Fase 1: Descubrimiento y Catálogo de Tipos de Página
Objetivo: Crear un inventario completo de todos los tipos de página en el sitio web, con señales de detección, cobertura de schema existente y datos reales guardados para ejemplos de código de tickets.
Cargue references/discovery.md antes de comenzar esta fase. Contiene toda la fase:
- 1.1 Recopilar la Lista de Tipos de Página
- 1.1b Evaluación de Prioridad / Triaje
- 1.1c Verificar la Guía Actual de Google
- 1.2 Analizar Cada Tipo de Página
- 1.3 Guardar Datos Reales para Ejemplos de Código de Tickets
- 1.4 Documentar los Hallazgos
- 1.5 Identificar Oportunidades de Consolidación
- 1.6 Clasificar Cada Tipo de Página
Fase 2: Diseño de Schema
Objetivo: Decidir qué tipos de schema y propiedades usar para cada tipo de página, y cómo se relacionan los schemas entre sí en todo el sitio.
Cargue references/schema-design.md antes de elegir tipos de schema o propiedades. Contiene las secciones 2.1–2.7:
- 2.1 Diseñar el Schema Global/Compartido
- 2.2 Diseñar Schemas Específicos de Página
- 2.3 Diseñar Referencias Cruzadas
- 2.4 Deprecación vs Eliminación
- 2.4b Tickets de Migración de Formato — Disposición del Formato Existente
- 2.5 Aplicar Reglas de Selección de Propiedades
- 2.5b Valores de Propiedades Multilingües
- 2.6 Verificar Suposiciones Antes de Finalizar
- 2.7 Reglas Específicas del Proyecto
§2.8 permanece en este archivo principal porque cada ticket y cada verificación lo aplican:
2.8 Requisitos Técnicos Universales
Estos se aplican a todos los proyectos:
- El schema debe ser renderizado del lado del servidor — Presente en el HTML inicial devuelto por el servidor, no inyectado dinámicamente por JavaScript. Esta es una mejor práctica de SEO, no una preferencia específica del proyecto.
- Formato JSON-LD — Implementar siempre como
<script type="application/ld+json">en la sección<head>. - Etiquetas de script separadas — Cada tipo de schema obtiene su propia etiqueta
<script>. - Formato @context — Usar siempre
https://schema.org(sin barra inclinada al final). Aplicar esto de forma consistente en todos los tickets. - Emitir a través de un serializador JSON real — Nunca ensamblar manualmente JSON-LD mediante concatenación de cadenas/plantillas de valores del CMS. El JSON-LD construido manualmente es propenso a toda una clase de rupturas, más amplias que solo los caracteres no escapados: comillas no escapadas en valores interpolados, sustitución de comillas inteligentes/curvas (U+201C/U+201D/U+201E donde pertenece una
"recta) y errores estructurales como llaves sueltas o duplicadas (por ejemplo, un valor@idenvuelto en un conjunto adicional de llaves). Un serializador elimina toda la clase; las reglas de escape por sí solas no lo hacen. - Decodificar entidades HTML en valores de texto — Una propiedad de texto lleva el carácter decodificado (
',&), nunca la entidad HTML (',&) que un campo del CMS o la fuente de la página almacena. Cuando el campo de origen contiene texto codificado, la plantilla lo decodifica antes de serializar. - Fechas en ISO 8601, fechas-hora con desplazamiento de zona horaria — Cada propiedad de fecha y fecha-hora (
datePublished,dateModified,startDate,validFrom…) usa ISO 8601; una fecha-hora lleva su desplazamiento (YYYY-MM-DDThh:mm:ss+hh:mm), nunca una hora local sin formato o un formato de visualización copiado de la página.
Fase 3: Creación de Tickets
Objetivo: Producir tickets listos para el desarrollador — un ticket principal para schemas compartidos, un ticket secundario por tipo de página (o grupo consolidado).
Cargue references/ticket-writing.md antes de redactar, revisar o verificar cualquier ticket. Contiene toda la fase:
- 3.1 Verificación Previa al Vuelo
- 3.2 Plantilla de Estructura de Ticket
- 3.2b Pautas de Uso de Subagentes
- 3.3 Reglas de Escritura de Tickets
- 3.4 Escritura del Ticket Principal
- 3.5 Lista de Verificación Previa al Vuelo (Antes de la Entrega)
- 3.6 Flujo de Trabajo de Comentarios e Iteración
- 3.7 Decisiones Comunes de Schema
Fase 4: Regeneración Final y Entrega
Objetivo: Regenerar todos los tickets en una sola pasada, aplicando cada regla, decisión y corrección acumulada para la consistencia entre tickets.
Cargue references/delivery.md antes de la pasada de regeneración final. Contiene toda la fase:
- 4.1 Construir un Plan de Regeneración
- 4.2 Resolver Todas las Preguntas Abiertas Primero
- 4.3 Regenerar en Secuencia
- 4.4 Pase de Formato Específico de la Plataforma
- Árbol de Decisión del Formato de Entrega
- 4.5 Pase Editorial
- 4.6 Verificaciones de Consistencia entre Tickets
- 4.7 Empaquetar para la Entrega
- 4.8 Entrega de Wrike — Esqueleto XLS + Pegado de HTML
Fase 5: Verificación Posterior al Despliegue
Objetivo: Después de que el desarrollador haya desplegado el schema, confirmar que la salida en vivo coincide con la especificación, con especial atención a la cobertura multilingüe y la corrección del tipo numérico.
Cargue references/post-deployment-verification.md antes de verificar el schema desplegado, confirmar un ticket como completado o diagnosticar un error de Search Console. Contiene toda la fase:
- Preámbulo de la fase — nota de alcance (la verificación de corrección reportada va a una auditoría de validación JSON-LD), los dos desencadenantes para un barrido de población completa y el inventario de plantillas de tickets de todo el sitio
- Lista de Verificación Previa al Vuelo de la Fase 5 (Antes de Enviar el Informe)
- 5.1 Patrón de Verificación entre Idiomas
- 5.2 Categorías de Hallazgos de Auditoría
- 5.3 Cuándo Reabrir la Especificación
- 5.4 Verificación de URL — Procedimiento Previo a la Publicación
- 5.5 Verificación del Valor de Origen — Las Auditorías Espejo No Son Suficientes
- 5.6 Reconciliación de los Conteos de Errores de GSC con un Rastreo en Vivo
- 5.7 Falsos Positivos de Recuperación Única en Campos Renderizados Dinámicamente
- 5.8 Diagnóstico de "Datos Estructurados No Analizables / Tipo de Valor Incorrecto" de GSC en Varias URL del Mismo Tipo de Página
- 5.9 Auditoría de Cobertura desde Exportaciones de Rastreo
Fase 6: M
…[truncado para traducción]