Frontmatter del post: los 22 campos que valida markeup-frontmatter

La skill markeup-frontmatter —«Genera y valida los 22 campos YAML del frontmatter»— 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.

El frontmatter es la ficha técnica de cada nota; esta skill decide qué campo lleva qué y cuáles de verdad impiden publicar.

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.

Ficha de la skill

Dato	Valor
Skill	markeup-frontmatter
Responsabilidad	Genera y valida los 22 campos YAML del frontmatter.
Versión	1.3.0
Autoría	uriszarernesto-blip · licencia MIT
Plataformas	linux · macos
Tags del canon	astro · frontmatter · yaml · seo · slug · markeup
Skills relacionadas	markeup-context · markeup-content · markeup-wikilinks · markeup-seo
Fuente	~/.hermes/skills/markeup/markeup-frontmatter/SKILL.md

Instrucciones del canon

Astro Post Frontmatter (Atomo 1)

Responsabilidad unica: producir y validar el bloque YAML de cabecera de un post. No redacta el cuerpo (eso es markeup-content) ni decide wikilinks (eso es markeup-wikilinks).

Cuando usar

• Antes de crear cualquier nota nueva.
• Para auditar los 22 campos de una nota existente.
• Cuando el build falle por frontmatter invalido.

Primero lee markeup-context (rutas + reglas).

Los 22 campos (fuente: rules/frontmatter-spec.md)

#	Campo	Tipo	Obligatorio	Regla
1	concept	string	Si	Etiqueta CORTA (1-4 palabras, <=60 car.). Se PINTA sobre la foto: H2 de display, tarjetas, grafo, tooltips, alt
2	title	string	Si	Titulo LARGO SEO, 50-75 caracteres (duro 40-90), palabra clave del concept al frente. Es el H1, <title>, og:title y schema.org
3	slug	string	Si	minusculas, guiones, sin acentos, <=3 palabras (se deriva del concept). Duro: forma valida
4	description	string	Si	140-200 caracteres (>=12 palabras; duro 100-260), extraida del cuerpo
5	type	string	Si	siempre post
6	lang	string	Si	siempre es-ES
7	draft	boolean	No	false para publicado
8	authors	array	Si	- Admin por defecto
9	pubDate	datetime	Si	YYYY-MM-DDTHH:mm:ss.000Z (UTC)
10	updatedDate	datetime	Si	mismo formato; igual a pubDate al crear
11	categories	array	Si	una de las 5 validas: Humano, Documentación, Literatura, Opinión, Máquina
12	tags	array	Si	2-6, minusculas, con guiones, sin tildes
13	featured	boolean	Si	true solo si es destacado (max 3-5 en el vault)
14	allowComments	boolean	Si	normalmente true
15	share	boolean	Si	normalmente true
16	image	string	Si	/img/<slug>.webp o /img/placeholder.webp
17	imageAlt	string	Si	texto alternativo descriptivo
18	canonicalUrl	string	No	dejar vacio (canonicalUrl:) si es original
19	aliases	array	Recomendado	2-3 variantes del titulo
20	noIndex	boolean	Si	normalmente false
21	hideTOC	boolean	Si	normalmente false
22	hideCoverImage	boolean	Si	normalmente false

concept vs title (crítico desde 2026-09-24). El concept es la etiqueta corta que se PINTA sobre la foto (display del post, tarjetas, grafo, tooltips); el title es el título SEO de 50-75 caracteres y es el H1 de la página, además de <title>, og:title y schema.org. Confundirlos es el error más grave: un title corto no posiciona y una etiqueta larga no cabe en una tarjeta. La autoridad es rules/seo-spec.md; el gate, npm run validate:seo.

Severidad (2 niveles, 2026-09-25). Solo 4 campos son duros —title, slug, description y categories—: si faltan o no son válidos, npm run validate:frontmatter sale con ERROR (exit 1) y la publicación se detiene. El resto de los 22 campos son recomendados: si faltan, es AVISO (exit 0; con --strict pasan a fallar).

Detalle campo por campo, con ejemplos validos e invalidos: references/field-reference.md. Plantilla lista para rellenar: templates/post-frontmatter.yaml.

Nota de schema: src/content.config.ts tambien acepta showTOC (legado). No lo generes: la spec usa hideTOC. El schema tiene defaults para casi todo, pero eso oculta errores: escribe los 22 campos explicitos. Los 4 duros tienen que estar siempre; de los recomendados, si falta alguno el validador solo avisa.

Por que aliases es critico

El linter scripts/mjs/validate-wikilinks.mjs construye su universo de destinos validos con slugs + aliases del frontmatter. Es decir: los aliases son destinos de wikilink enlazables. Genera aliases aqui, antes de resolver wikilinks, y comunicaselos a markeup-wikilinks.

Reglas de aliases (frontmatter-spec.md):

• 2-3 variantes del titulo.
• Una debe ser el titulo sin puntuacion.
• Otra, una version abreviada.
• Ejemplo para “Aura: capas del campo sutil, vibración y equilibrio energético”: El Aura, aura, Aura.

Generacion del slug

title -> minusculas -> quitar acentos -> quitar caracteres especiales
      -> espacios a guiones -> colapsar guiones -> recortar extremos

Ejemplo: "Aura: capas del campo sutil, vibración y equilibrio energético" -> el-aura.

Prohibido: .md, acentos, signos de puntuacion, mayusculas. Maximo recomendado 80 caracteres (una forma invalida —mayuscula, espacio o tilde— es ERROR: rompe la URL).

Generacion de fechas

• Formato exacto: YYYY-MM-DDTHH:mm:ss.000Z (UTC, sufijo Z).
• pubDate = primera publicacion. updatedDate = ultima modificacion significativa (no cuenta corregir typos).
• Al crear: ambas identicas.

Validacion (ejecutar siempre)

Checklist de auto-validacion antes de entregar:

• Los 22 campos presentes (los 4 duros son obligatorios; el resto, recomendados).
• concept corto (1-4 palabras, <=60 car.) y title 50-75 caracteres, sin confundirlos.
• title arranca por la clave del concept (ver rules/seo-spec.md).
• description 140-200 caracteres (>=12 palabras) y extraida del cuerpo.
• Indentacion de 2 espacios; nunca tabs.
• Strings con caracteres especiales entre comillas dobles.
• categories contiene exactamente una de las 5 validas.
• tags en minusculas, sin #, sin tildes, 2-6 elementos.
• slug coincide con image (/img/<slug>.webp).
• Fechas en ISO 8601 UTC.
• canonicalUrl presente y vacio si el post es original.

Comandos de verificacion (solo lectura, no requieren tty):

cd ~/markeup
npm run validate:seo          # GATE: falla solo con ERROR (clave, duplicado, provisional, rango duro)
npm run validate:frontmatter  # GATE: falla si falta un campo duro (avisa del resto)
npm run validate:slugs        # colisiones de slug/alias

Errores comunes

Sintoma	Causa	Correccion
Invalid time value	pubDate no parseable	Usa ISO 8601 con Z
Campo ignorado	Nombre mal escrito (pubdate, image_alt)	Respeta camelCase exacto
Build falla en coleccion	type fuera del enum	post (o note/draft/idea)
Tags duplicados	Tag ya existente con otra grafia	Revisa memory/vault-index.md antes

Comportamiento segun el contexto

• Obsidian: entrega el YAML completo en un bloque de codigo yaml.
• Telegram: NO vuelques las 21 lineas. Envia titulo, slug, categoria y tags (<= 5 lineas).
• VS Code / Cline: muestra el YAML y el diff si modificas una nota existente.
• Hermes CLI: YAML completo, sin comentarios, listo para escribir.

Referencias

• templates/post-frontmatter.yaml - plantilla con los 22 campos.
• references/field-reference.md - detalle y ejemplos por campo.
• markeup-context - rutas y reglas canonicas (dependencia obligatoria).

---

¿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.