SEO on-page: auditar title y description con markeup-seo

La skill markeup-seo —«Audita el SEO on-page y la metadata de un post Astro»— es una de las habilidades que el sistema MarkeUP tiene escritas para Hermes Agent y para Cline. Esta página es su ficha pública: lo que sabe hacer, cuándo se usa y qué comandos ejecuta.

Es el texto que ve el buscador antes de entrar: la skill lo mide, lo compara con el resto del vault y propone correcciones.

El texto de la sección «Instrucciones del canon» está transcrito del fichero fuente —que se escribe sin tildes por convención de su propio gate—, así que es exactamente lo que lee el agente cuando le pides algo. La cabecera y esta entradilla sí están redactadas para leerlas.

Dato	Valor
Skill	`markeup-seo`
Responsabilidad	Audita el SEO on-page y la metadata de un post Astro.
Versión	1.3.0
Autoría	uriszarernesto-blip · licencia MIT
Plataformas	linux · macos
Tags del canon	seo · astro · metadata · og · canonical · markeup
Skills relacionadas	markeup-context · markeup-frontmatter · markeup-content
Fuente	`~/.hermes/skills/markeup/markeup-seo/SKILL.md`

Responsabilidad unica: auditar y corregir el SEO on-page y la metadata de un post. Trabaja sobre el frontmatter generado por markeup-frontmatter; no lo sustituye.

Al final del pipeline, antes de publicar.
Para revisar un post ya existente.
Cuando un post no aparece indexado o su CTR es bajo.

Primero lee markeup-context, rules/seo-spec.md (autoridad SEO) y rules/style-guide.md (sección SEO On-Page).

Estos criterios son vinculantes (acordados el 2026-09-24, revisados a la baja el 2026-09-25). El gate ejecutable es npm run validate:seo.

Severidad: modelo de 2 niveles (desde el 2026-09-25). Solo bloquea —ERROR, exit 1— lo que rompe el sitio o la URL: title/description/slug/categories ausentes, categoría inventada, fecha no interpretable, title duplicado, title que no arranca por la clave del concept y title/description fuera del rango duro. Todo lo demás —salirse del rango recomendado, fillers, ganchos retóricos, descripciones parecidas (Jaccard ≥ 0.5), concept largo, tags fuera de 2-6— es AVISO: se reporta y no bloquea la publicación. --strict convierte los avisos en fallo (sirve para perseguir 0 avisos, no para decidir si se publica).

Regla	Detalle
`title`	50-75 caracteres (duro 40-90: fuera de ahí sí es ERROR). Lo lee el buscador (`<title>`, `og:title`, `twitter:title`, schema.org). No lleva `
`description`	140-200 caracteres y ≥12 palabras (duro 100-260). Se extrae del cuerpo: nada inventado
Orden de trabajo	`cuerpo → description → title` (el título se deriva de la description)
Palabra clave al frente	La palabra con más carga del `concept` abre el `title`: `El Aura` → «Aura: …». 19 excepciones documentadas en `scripts/mjs/lib/seo-key.mjs` (`KEY_EXCEPCIONES`)
`concept` intacto	Nunca se renombra para cuadrar el SEO (decisión del propietario)
Keyword en los primeros 155 caracteres de la `description`	Google trunca por anchura: lo accesorio se pierde, la keyword no
Fillers prohibidos	`claves`, `origen y beneficios`, `beneficios`, `guía completa`, `exploración detallada`, `descubre`, `explora`, `adéntrate`, `sumérgete`, `el mundo de`, `todo lo que necesitas`, `en este artículo`, `aprende a`
Ganchos retóricos prohibidos al inicio	«Sin…», «Ni…», «No…», «Más allá de…», «Frente a…», «Lejos de…»
Sin canibalización	Ningún `title` repetido; ninguna `description` con Jaccard ≥ 0.5 respecto a otra
Sin títulos provisionales	Un `title` con sufijo tipo `

cd ~/markeup
npm run seo:brief -- --slug <slug>     # 1. brief: concept, clave, tags, H2, intro, cuerpo
# 2. redactar description (140-200) -> title (50-75) desde el cuerpo
# 3. anadir/editar la entrada en scripts/data/seo-meta.json
npm run seo:apply -- --apply           # 4. aplica SOLO title y description (idempotente)
npm run validate:seo                   # 5. GATE: exit 1 solo si hay ERROR (los avisos no bloquean)
npm run validate:frontmatter           # 6. los 22 campos (4 duros) + concept <= 60 (aviso)

scripts/data/seo-meta.json es la fuente de verdad revisable: { slug, key, title, description }. El aplicador nunca toca concept, slug, aliases ni el cuerpo: solo las dos líneas title: y description:.

#	Campo	Criterio	Verificacion
1	`title`	50-75 caracteres, palabra clave al inicio, estilo frase	Contar caracteres
2	`slug`	Corto, descriptivo, con guiones, sin acentos ni `.md`	Regex `^[a-z0-9-]+$`
3	`description`	140-200 caracteres, con palabra clave, atractiva para CTR	Contar caracteres
4	Primer parrafo	Contiene la palabra clave principal	Lectura
5	Headings	Sin H1 en el cuerpo (lo aporta la plantilla desde `title`); H2 para secciones; sin saltos	Leer estructura
6	`tags`	2-6, minusculas, con guiones, sin tildes, no redundantes	Contra `vault-index.md`
7	`image`	Existe el archivo en `src/content/posts/img/<slug>.webp`	`ls`
8	`imageAlt`	Descriptivo, con palabra clave si es natural	Lectura
9	`canonicalUrl`	Vacio si es original; con URL si es sindicado	Comprobar origen
10	`aliases`	2-3 variantes; ademas son destinos de wikilink	Comprobar unicidad
11	`noIndex`	`false` salvo que no deba indexarse	Boolean
12	`hideTOC`	`false` si el post tiene estructura de headings	Boolean
13	`hideCoverImage`	`false` si hay imagen de portada	Boolean
14	`featured`	`true` solo si es destacado (max 3-5 en el vault)	Contar en el vault

title        : 50-75 caracteres (duro 40-90: fuera de ahi, ERROR)
description  : 140-200 caracteres, >=12 palabras (duro 100-260: fuera de ahi, ERROR)
concept      : <= 60 caracteres (etiqueta corta de tarjeta y grafo)
slug         : <= 80 caracteres, <= 3 palabras recomendado

Dentro del rango recomendado no hay nada que corregir. Por debajo de 140 la description desaprovecha el snippet y por encima de 200 el buscador la trunca: en ambos casos es AVISO, no un bloqueo. Los limites viven en scripts/mjs/lib/frontmatter-spec.mjs (LIMITES), la misma fuente que usa npm run validate:frontmatter.

Los aliases del frontmatter cumplen doble funcion:

SEO/busqueda: variantes del titulo que ayudan a encontrar la nota.
Destinos de wikilink: el linter scripts/mjs/validate-wikilinks.mjs los indexa como slugs validos, de modo que [[variante-del-titulo|texto]] resuelve a este post.

Por eso deben ser unicos y no colisionar con otros slugs o aliases del vault.

Caso	Valor
Contenido original	vacio (`canonicalUrl:`)
Migrado de un blog antiguo / sindicado	URL absoluta de la fuente original

El schema acepta null, "" o ausencia y los normaliza a undefined.

Archivo fisico: src/content/posts/img/<slug>.webp.
Referencia en frontmatter: /img/<slug>.webp.
Sin imagen: /img/placeholder.webp + imageAlt generico pero util.
imageAlt debe describir la imagen, no repetir el titulo.

Flag	Default	Cuando cambiarlo
`noIndex`	`false`	`true` solo para paginas que no deben indexarse
`hideTOC`	`false`	`true` en posts muy cortos sin headings
`hideCoverImage`	`false`	`true` si no quieres portada
`featured`	`false`	`true` solo para 3-5 posts destacados del vault

showTOC existe en el schema pero es legado: no lo generes ni lo audites.

SEO AUDIT - <slug>

✅ OK
  title        62 caracteres, palabra clave al inicio
  slug         el-aura (valido, 2 palabras)

⚠️  AVISO (no bloquea la publicacion)
  description  132 caracteres (recomendado 140-200)
    -> Actual: "El aura es un concepto central de la bioenergetica."
    -> Sugerida (148): "El aura, ese campo sutil que la bioenergetica describe..."
  image        /img/el-aura.webp no existe en public/img/
    -> Accion: subir la imagen o usar /img/placeholder.webp

❌ ERROR (bloquea)
  title        no arranca por la clave del `concept` ("Aura")
    -> Accion: reescribir el `title` empezando por "Aura:" y dejar el `concept` intacto

Ordena siempre: ERROR primero, luego AVISO y por ultimo OK. Solo un ERROR bloquea la publicacion; un aviso se anota y se sigue (con --strict deja de ser aviso).

Obsidian: informe completo en bloque plegable > [!warning].
Telegram: solo los campos con problema y la sugerencia. Maximo 10 lineas.
VS Code / Cline: informe + diff del frontmatter corregido.
Hermes CLI: informe + aplicar correcciones si el usuario lo pide.

references/seo-checklist.md - checklist ampliado con ejemplos.
rules/style-guide.md - seccion SEO On-Page (autoridad del vault).
markeup-frontmatter - genera los campos que aqui se auditan.

¿Quieres saber cómo se piden estas cosas? La guía completa está en skills de Hermes Agent, con la chuleta de objetivos y los casos paso a paso.

SEO on-page

SEO on-page: auditar title y description con markeup-seo

Posts que enlazan a este artículo