schema-markup

Visión general de schema-markup skill

Qué hace schema-markup skill

La schema-markup skill te ayuda a añadir, corregir o mejorar datos estructurados en páginas reales usando patrones válidos de schema.org, con una clara preferencia por JSON-LD y por oportunidades de rich results visibles en Google. Resulta más útil cuando ya sabes qué página quieres marcar, pero necesitas decidir más rápido qué tipo de schema corresponde, qué propiedades son necesarias y contar con un ejemplo de código listo para implementar.

Quién debería instalar schema-markup

Esta schema-markup skill encaja bien para equipos de SEO, marketers de contenidos, desarrolladores web y propietarios de sitios que necesitan publicar datos estructurados sin tener que adivinar entre la documentación. Es especialmente útil para:

• sitios de marketing y homepages de SaaS
• plantillas de blog y artículos
• páginas de producto, software, FAQ, eventos y negocios locales
• equipos que están corrigiendo marcado inexacto o incompleto

El trabajo real que resuelve

La mayoría de los usuarios no busca una clase teórica sobre datos estructurados. Necesitan responder preguntas prácticas con rapidez:

• ¿Qué tipo de schema encaja con esta página?
• ¿Se pueden combinar varios tipos de schema?
• ¿Qué propiedades merece la pena añadir ahora?
• ¿Qué se puede implementar con seguridad sin exagerar ni afirmar de más?
• ¿Qué JSON-LD debería entrar hoy en la plantilla de la página?

La skill está diseñada en torno a esas decisiones, no solo como una lista de tipos de schema.

Qué diferencia a esta schema-markup skill

Su principal valor diferencial es que orienta hacia un marcado preciso y ajustado a la página, en lugar de empujar a “añadir todo el schema posible”. El repositorio también incluye un archivo útil, references/schema-examples.md, con ejemplos concretos para tipos habituales como Organization, WebSite, Article, Product, SoftwareApplication, FAQPage, HowTo, BreadcrumbList, LocalBusiness y Event. Eso hace que la skill sea mucho más accionable que un prompt genérico.

Principales límites que debes conocer antes de instalarla

No es un crawler, un validador ni un escáner de páginas en vivo. La schema-markup skill depende de los datos de la página que tú le proporciones. Si tu input es vago, la salida puede verse pulida y aun así ser incorrecta para la elegibilidad o la implementación. Además, se centra en la generación y selección de marcado, no en un diagnóstico más amplio de SEO técnico.

Cómo usar schema-markup skill

Instalar schema-markup skill

Instala desde el repo con:

npx skills add https://github.com/coreyhaines31/marketingskills --skill schema-markup

Si quieres evaluarla antes de instalar, revisa:

• skills/schema-markup/SKILL.md
• skills/schema-markup/references/schema-examples.md
• skills/schema-markup/evals/evals.json

Estos tres archivos te muestran casi todo lo importante: condiciones de activación, expectativas de salida y patrones de ejemplo.

Lee primero estos archivos

Empieza en este orden:

1. SKILL.md para entender el flujo de trabajo y las reglas de decisión
2. references/schema-examples.md para patrones de JSON-LD que puedes reutilizar
3. evals/evals.json para ver cómo es una “buena salida” en la práctica

Los evals son especialmente útiles porque dejan claro el comportamiento esperado: primero revisar el contexto, elegir los tipos de schema relevantes, usar @graph cuando haga falta, entregar JSON-LD completo y recomendar validación.

Mejor formato de input para usar schema-markup

La schema-markup skill funciona mejor cuando le das datos concretos a nivel de página, no solo un “añade schema”. Incluye:

• URL de la página o tipo de página
• propósito de la página
• entidades visibles en la página
• tipo de negocio
• rich result objetivo, si existe
• schema actual o errores existentes
• CMS o framework
• campos que realmente puedes completar

Una petición débil:

• “Add schema markup for SEO.”

Una petición sólida:

• “Create JSON-LD for our SaaS homepage. We are a project management platform. Visible elements include company name, logo, product overview, customer logos, pricing link, and site search. We want Organization, WebSite, and the most appropriate product-related type. We deploy in Next.js and can inject one script in the layout.”

Convierte un objetivo difuso en un prompt útil

Un buen prompt para schema-markup debería pedir cuatro salidas:

1. tipos de schema recomendados
2. razonamiento para cada elección
3. JSON-LD completo
4. notas de validación e implementación

Ejemplo de estructura del prompt:

• “Use the schema-markup skill.”
• “First determine the page type and rich result eligibility.”
• “Then recommend the minimal correct schema set.”
• “Generate production-ready JSON-LD.”
• “Flag any claims that are unsupported by visible content.”
• “Tell me where to place it in our template.”

Ese enfoque da resultados más fiables que pedir simplemente código de ejemplo.

Tipos de página que esta skill resuelve bien

Según los ejemplos y evals del repositorio, la schema-markup skill destaca sobre todo en:

• Organization y WebSite para homepages
• marcado de blog/artículo
• Product y SoftwareApplication
• FAQPage
• HowTo
• BreadcrumbList
• LocalBusiness
• Event
• implementaciones mixtas en una misma página con @graph

Si tu página encaja claramente en uno de estos casos, adoptarla es sencillo.

Cuándo usar @graph en schema-markup

Usa @graph cuando una misma página contenga legítimamente varias entidades o funciones de página, por ejemplo:

• homepage con Organization + WebSite
• homepage SaaS con Organization + WebSite + SoftwareApplication
• página de artículo con Article + BreadcrumbList

Esto importa porque muchos equipos o bien dividen el marcado de forma incómoda entre varios scripts, o bien saturan un solo tipo con propiedades que no corresponden. Los ejemplos de la skill y las expectativas de los evals apuntan a un modelado multi-tipo más limpio.

Flujo práctico de schema-markup para SEO de contenidos

Un flujo práctico de uso de schema-markup es:

1. identificar el propósito principal de la página
2. confirmar qué contenido es realmente visible
3. seleccionar el conjunto mínimo y válido de schema
4. generar el JSON-LD
5. implementarlo en la plantilla o componente de la página
6. validarlo en Google Rich Results Test y Schema.org Validator
7. comparar el marcado con el contenido real publicado

Para equipos de contenido SEO, esto evita el error habitual de añadir marcado orientado a rich results que no coincide con la página renderizada.

Consejos de implementación que cambian la calidad del resultado

Algunos datos mejoran el resultado de forma notable:

• proporcionar la URL canónica, la URL del logo y las URLs de imágenes
• especificar si las valoraciones, precios o FAQs son realmente visibles
• indicar si la página es transaccional, editorial, navegacional o local
• mencionar restricciones del framework, como Next.js, WordPress o inyección de scripts en el head
• decirle a la skill si el marcado debe ser mínimo o más completo

Sin esos detalles, el modelo puede elegir el tipo correcto pero quedarse corto en cobertura de propiedades.

Pasos de validación después de instalar schema-markup

Después de generar el marcado, valídalo con:

• Google Rich Results Test
• Schema.org Validator

Después, comprueba manualmente:

• que cada campo marcado exista en la página
• que las URLs sean absolutas
• que las fechas estén en formatos válidos
• que las imágenes sean rastreables
• que varias entidades no estén duplicadas de forma inconsistente entre plantillas

El repositorio insiste una y otra vez en priorizar la precisión, y esa es la mentalidad correcta para adoptar esta skill.

Patrones comunes del repositorio que conviene reutilizar

Merece la pena usar el archivo de ejemplos como librería de patrones, especialmente para:

• Organization con sameAs y contactPoint
• WebSite con SearchAction
• anidación completa de preguntas y respuestas en FAQ
• configuración de entidades tipo producto y software
• un ejemplo de implementación en Next.js

Eso significa que la guía de schema-markup no es solo conceptual; también sirve como kit de arranque.

FAQ de schema-markup skill

¿Es schema-markup mejor que un prompt normal de IA?

Por lo general, sí, si tu objetivo es obtener marcado listo para implementar. Un prompt normal puede generar JSON-LD sintácticamente válido, pero aun así elegir el tipo equivocado, omitir propiedades importantes o marcar elementos que no existen en la página. La schema-markup skill tiene criterios más claros sobre ajuste a la página, precisión y composición de varios schemas.

¿La schema-markup skill es apta para principiantes?

Sí, siempre que puedas describir la página con claridad. No necesitas conocimientos profundos de schema.org para obtener valor. Pero incluso los principiantes deben aportar datos reales de la página. La skill no hace magia: no puede inferir de forma segura detalles de negocio que faltan.

¿Puede schema-markup ayudar con marcado roto que ya existe?

Sí. De hecho, es uno de sus mejores casos de uso. Dale el marcado actual, el tipo de página y el contenido realmente visible. Pídele que identifique desajustes, elimine propiedades no respaldadas y reescriba el JSON-LD de forma limpia.

¿schema-markup garantiza rich results?

No. La schema-markup skill puede mejorar la elegibilidad y la calidad de la implementación, pero Google decide si muestra rich results. Importan el marcado correcto, la calidad de la página, el tipo de contenido y la demanda de búsqueda.

¿Cuándo no debería usar schema-markup?

No dependas solo de esta skill cuando necesites:

• una auditoría completa de SEO técnico
• crawling del sitio en vivo y a escala
• diagnóstico de rankings
• análisis de renderizado en JavaScript
• estrategia de contenidos amplia

Funciona mejor para decisiones de datos estructurados a nivel de página, no para troubleshooting SEO de todo el sitio.

¿schema-markup es útil para sitios SaaS y de marketing?

Sí. Los evals apuntan explícitamente a casos de uso en homepages como Organization, WebSite y modelados de tipo SoftwareApplication. Eso la hace más relevante para equipos modernos de B2B y SaaS que muchas guías de schema centradas solo en ecommerce.

Cómo mejorar schema-markup skill

Dale a schema-markup los datos de página que no puede inferir

La forma más rápida de mejorar la salida es proporcionar:

• propósito exacto de la página
• elementos visibles
• nombre de marca y URLs
• autor, publisher, fecha, precio, valoración, FAQ o datos de evento cuando corresponda
• qué puedes y qué no puedes afirmar legal o técnicamente

Esto reduce supuestos erróneos y mejora la completitud de las propiedades.

Pide primero la decisión de schema antes de pedir código

Una secuencia de prompt mejor es:

1. “Decide the correct schema types.”
2. “Explain why each fits.”
3. “List missing data needed for a complete implementation.”
4. “Then generate final JSON-LD.”

Esto detecta pronto una mala elección de tipo y hace que la schema-markup skill sea mucho más fiable en páginas con propósitos mixtos.

Evita el mayor modo de fallo: marcar de más

El error más común con schema es añadir marcado para cosas que no están claramente presentes en la página. Ejemplos:

• FAQPage para FAQs ocultas o no visibles para el usuario
• Review o datos de valoración sin evidencia visible
• Product en páginas genéricas de marca sin detalle real de producto
• HowTo en páginas que en realidad son posts de blog

Si usas schema-markup de forma conservadora, los resultados suelen ser mejores.

Mejora la salida multi-entidad con relaciones explícitas

Cuando pidas varios tipos, dile a la skill cómo se relacionan:

• “This page is the company homepage”
• “The article belongs to this publisher”
• “The software application is the main product described here”
• “Breadcrumbs are rendered above the H1”

Eso ayuda a que la skill produzca una salida @graph más limpia en lugar de entidades desconectadas.

Usa el archivo de ejemplos como referencia de calidad

Antes de publicar el resultado, compáralo con references/schema-examples.md. Revisa si tu salida incluye los patrones estructurales esperados para ese tipo. Es una de las formas más prácticas de mejorar el uso de schema-markup sin tener que leer todo schema.org.

Itera después del primer borrador en lugar de aceptarlo tal cual

Después de la primera salida, haz preguntas de seguimiento como:

• “Strip this to only required and high-value recommended properties.”
• “Rewrite for a blog post rather than a generic article.”
• “Convert this to a single @graph block.”
• “Adapt this for Next.js server-rendered injection.”
• “Audit this against the visible page content and remove unsupported fields.”

Esa segunda pasada suele ser el punto en el que la schema-markup skill queda realmente lista para producción.

Combina schema-markup con validación y comprobaciones de realidad en la SERP

Incluso un JSON-LD sólido debería contrastarse con:

• el contenido real renderizado de la página
• herramientas de validación
• si el rich result objetivo es realista para ese tipo de página

El mejor flujo de trabajo con schema-markup no es “generar una vez y pegar”, sino “generar, validar, conciliar y publicar”.