metadata-validator
Especialista en validación y generación de metadatos YAML (frontmatter) para archivos markdown del proyecto SyV, garantizando coherencia con estándares
- Category: discovered
- Tags: github, community
- Version: 1.0.0
- Author: walid
- Downloads: 0
- Updated: 2025-11-22
Download the latest version (v1.0.0) from this page.
SKILL.md
---
name: metadata-validator
description: Especialista en validación y generación de metadatos YAML (frontmatter) para archivos markdown del proyecto SyV, garantizando coherencia con estándares
---
# Skill: Metadata Validator
## Competencia
Especialista en validación y generación de metadatos YAML (frontmatter) para archivos `.md` del proyecto "Subordinación y Valor", garantizando cumplimiento de estándares y coherencia.
## Cuándo se Activa
Automáticamente al:
- Crear o editar archivos `.md` en carpetas de contenido (`0_proyecto/`, `1_trasfondo/`, `2_atlas/`, `3_personajes/`, `4_diegesis/`, `5_aventuras/`)
- Ejecutar comando `/check-metadata`
- Ejecutar comando `/suggest-tags`
- Post-edición de archivos markdown (hook)
## Expertise
### Esquema de Metadatos Obligatorios
**Campos SIEMPRE requeridos**:
```yaml
---
titulo: Título del documento
carpeta: ruta/relativa/desde/raiz
descripcion: Breve descripción del contenido
---
```
### Campos Opcionales pero Recomendados
**Para todos los archivos**:
```yaml
tags:
- tag1
- tag2
- tag3
```
**Para cronología**:
```yaml
fecha: YYYY-MM-DD
region: Región, Subregión, Ciudad
```
**Para personajes** (IMPORTANTE):
```yaml
facciones:
- "Nombre Facción 1"
- "Nombre Facción 2"
alerta-spoilers: "Texto de advertencia sobre información sensible"
```
### Convenciones de Formato
1. **Idioma**: TODO en español, minúsculas
2. **Formato de claves**: kebab-case (palabras-separadas-por-guiones)
3. **Espaciado**: SIEMPRE espacio después de dos puntos (`:`)
4. **No tabs**: Solo espacios para indentación
5. **Arrays YAML**: Guiones con espacios (`- item`)
### Campos PROHIBIDOS
❌ **NUNCA usar campos en inglés**:
- `title` (usar `titulo`)
- `date` (usar `fecha`)
- `layout` (no usar)
- `author` (no usar)
- `tags` en inglés (usar español en contenido)
## Capacidades
### 1. Validar Metadatos Existentes
Verificar:
- ✅ Campos obligatorios presentes (`titulo`, `carpeta`, `descripcion`)
- ✅ Formato YAML correcto (sintaxis, espaciado)
- ✅ Campos en español y minúsculas
- ✅ Ruta en `carpeta` es relativa y correcta
- ✅ Tags apropiados (existen en corpus, no demasiado genéricos)
- ✅ Campos específicos por tipo (personajes: `facciones` obligatorio)
### 2. Generar Metadatos Completos
Para nuevos archivos:
1. Analizar contenido para extraer información
2. Determinar tipo de archivo (personaje/facción/cronología/etc.)
3. Generar frontmatter completo con campos apropiados
4. Sugerir tags relevantes basados en contenido
### 3. Sugerir Tags
Buscar en corpus tags existentes que puedan aplicar:
- Tags de ubicación (darsena, tuberias, cordoba, etc.)
- Tags de personajes (nombre-apellido)
- Tags de facciones (sia, arpistas, etc.)
- Tags de conceptos (anatema-mecanico, qia, etc.)
- Tags de períodos (caos, gran-guerra, actualidad-2178, etc.)
- Tags de tipo (cronologia, relato, faccion, personaje, etc.)
### 4. Corregir Errores Comunes
Detectar y corregir:
- Campos en inglés → Convertir a español
- Falta de espacio después de `:` → Agregar espacio
- Tabulaciones → Convertir a espacios
- Tags duplicados → Eliminar duplicados
- Campo `facciones` faltante en personajes → Agregar (vacío o poblado)
- Ruta absoluta en `carpeta` → Convertir a relativa
## Categorías de Tags
### Tags de Ubicación
```
# Ciudades principales
darsena, cordoba, mendoza, el-paramo
# Zonas de Dársena
tuberias, barrios-del-muro, barrio-norte, microcentro
zona-centro, zona-militar, isla-oriental, fuera-del-muro
# Lugares específicos
nueva-basilica, universidad-catolica, torres-hidroponicas
crater, zona-exclusion, rio-de-la-plata
# Regiones
argentina, buenos-aires, pantano, delta
```
### Tags de Personajes
```
# Formato: nombre-apellido (o apodo si es más conocido)
damian-diconte, francisco-de-la-cruz, padre-rafa
monsenor-miguel, hermana-superior-maria
paco-el-puntero, sor-sofia
```
### Tags de Facciones
```
# Oficiales
sia, iglesia, iglesia-de-darsena
ejercito, armada, prefectura, fuerzas-armadas
gremio, la-union
# Proscritas/Secretas
arpistas, guardianes, guardianes-de-la-memoria
criptografos, canales-ocultos, resistencia
umbanda, cazadores-de-pesadillas, shipibo-conibo
traficantes-de-almas
```
### Tags de Conceptos Centrales
```
anatema-mecanico, corpus-licitus
qia, inteligencia-artificial
fin-de-los-secretos, gran-guerra, gran-colapso
meteorito, crater
mision-s-a-n-t-a
herejia, tecnologia-prohibida
```
### Tags de Períodos Históricos
```
mundo-antiguo (2020-2029)
anos-del-caos (2029-2035)
gran-guerra (2036-2047)
fin-de-los-secretos (2048-2061)
edad-oscura (2062-2160)
confederacion-temprana (2161-2177)
actualidad-2178
```
### Tags de Tipo de Documento
```
cronologia, relato, carta, cronica, diario
faccion, personaje, arquetipo
atlas, mapa, tecnologia
constitucion, herejia
guia, aventura, investigacion
```
## Restricciones
### 1. Campos Obligatorios
- ❌ NUNCA omitir `titulo`, `carpeta`, `descripcion`
- ✅ SIEMPRE incluir estos tres campos
### 2. Idioma
- ❌ NUNCA usar campos en inglés
- ✅ SIEMPRE español y minúsculas
### 3. Formato YAML
- ❌ NO usar tabulaciones
- ✅ Solo espacios para indentación
- ❌ NO omitir espacio después de `:`
- ✅ `clave: valor` (espacio obligatorio)
### 4. Campo Facciones (Personajes)
- ❌ NUNCA omitir campo `facciones` en personajes
- ✅ SIEMPRE presente (puede estar vacío: `facciones: []`)
### 5. Ruta Carpeta
- ❌ NO usar rutas absolutas
- ✅ SIEMPRE relativa desde raíz del proyecto
- ✅ Ejemplos: `3_personajes/principales`, `1_trasfondo/cronologia`
## Workflows
### Validar Archivo Existente
1. Leer frontmatter del archivo
2. Verificar campos obligatorios
3. Validar formato YAML (sintaxis, espaciado)
4. Comprobar idioma de campos (español)
5. Verificar campos específicos según tipo:
- Personajes: `facciones` presente
- Cronología: `fecha` y `region` apropiados
6. Validar tags (existen, no redundantes, apropiados)
7. Generar reporte:
- ✅ Correctos
- ⚠️ Advertencias (mejoras sugeridas)
- ❌ Errores (deben corregirse)
### Generar Metadatos para Archivo Nuevo
1. Leer contenido del archivo
2. Determinar tipo (analizar ubicación y contenido):
- `3_personajes/` → personaje
- `1_trasfondo/facciones/` → facción
- `1_trasfondo/cronologia/` → cronología
- `2_atlas/` → ubicación/geografía
- `4_diegesis/` → relato/carta/crónica
3. Extraer información del contenido:
- Título (primer H1 o nombre archivo)
- Descripción (primer párrafo o resumen)
- Tags (conceptos clave mencionados)
4. Generar frontmatter completo:
```yaml
---
titulo: [Extraído/generado]
carpeta: [Ruta relativa]
descripcion: [Extraída/generada]
tags:
- [sugerencias basadas en contenido]
# Campos específicos según tipo
---
```
### Sugerir Tags
1. Leer contenido completo del archivo
2. Identificar menciones de:
- Ubicaciones (Dársena, Córdoba, Túberías, etc.)
- Personajes (nombres detectados)
- Facciones (SIA, Arpistas, Iglesia, etc.)
- Conceptos (Anatema, QIA, herejía, etc.)
- Años/períodos (detectar rango temporal)
3. Buscar tags EXISTENTES en corpus que coincidan
4. Ordenar por relevancia:
- Primero: Tags existentes (para mantener consistencia)
- Segundo: Nuevos tags sugeridos (solo si necesarios)
5. Advertir si tag parece demasiado genérico
6. Presentar lista con categorías:
```
Tags sugeridos (EXISTENTES):
- darsena
- sia
- damian-diconte
Tags nuevos (CREAR solo si necesario):
- [nuevo-concepto] (⚠️ Verificar si realmente necesario)
```
## Ejemplos de Validación
### Ejemplo 1: Frontmatter Correcto
```yaml
---
titulo: Damián DiConte
carpeta: 3_personajes/principales
descripcion: Detective veterano de la Dirección Nacional de Seguridad, cuya investigación lo traslada de Córdoba a Dársena.
tags:
- damian-diconte
- detective
- cordoba
- darsena
- investigacion
facciones: []
---
```
**Validación**: ✅ TODO CORRECTO
---
### Ejemplo 2: Frontmatter con Errores
```yaml
---
title: Damián DiConte
folder: c:\Users\gcave\Projects\Dev\syv\3_personajes\principales
description: Detective veterano...
tags:
- Damián
- Detective
---
```
**Errores detectados**:
- ❌ Campo `title` (inglés) → Usar `titulo`
- ❌ Campo `folder` (inglés) → Usar `carpeta`
- ❌ Ruta absoluta en `folder` → Usar relativa: `3_personajes/principales`
- ❌ Campo `description` (inglés) → Usar `descripcion`
- ❌ Tags con mayúsculas → Usar minúsculas kebab-case
- ❌ Campo `facciones` faltante (es personaje) → Agregar
**Corrección**:
```yaml
---
titulo: Damián DiConte
carpeta: 3_personajes/principales
descripcion: Detective veterano...
tags:
- damian-diconte
- detective
facciones: []
---
```
---
### Ejemplo 3: Personaje sin Campo Facciones
```yaml
---
titulo: Dr. Francisco de la Cruz
carpeta: 3_personajes/principales
descripcion: Decano de Historia, líder de los Guardianes de la Memoria
tags:
- francisco-de-la-cruz
---
```
**Error detectado**:
- ❌ Campo `facciones` OBLIGATORIO para personajes
**Corrección**:
```yaml
---
titulo: Dr. Francisco de la Cruz
carpeta: 3_personajes/principales
descripcion: Decano de Historia, líder de los Guardianes de la Memoria
tags:
- francisco-de-la-cruz
- guardianes
- arpistas
facciones:
- "Guardianes de la Memoria"
- "Arpistas"
---
```
---
## Notas de Uso
### Prioridad de Tags Existentes
SIEMPRE preferir tags que ya existen en el corpus para mantener consistencia.
Antes de crear un tag nuevo, verificar si alguno existente puede servir:
- ¿`detective` en lugar de `investigador`?
- ¿`sia` en lugar de `inquisicion`?
- ¿`darsena` en lugar de `ciudad-darsena`?
### Tags Demasiado Genéricos
Advertir si usuario intenta tags como:
- `personaje` (obvio en carpeta `3_personajes/`)
- `historia` (demasiado amplio)
- `importante` (subjetivo)
### Campo Alerta-Spoilers
Si el personaje/facción tiene información secreta marcada como "**Información secreta (no exponer a jugadores):**", considerar agregar:
```yaml
alerta-spoilers: "Este personaje/facción contiene información sensible que no debe revelarse prematuramente."
```
### Rutas Relativas Correctas
**CORRECTO**:
- `0_proyecto/guias-para-colaboradores`
- `1_trasfondo/cronologia`
- `3_personajes/principales`
**INCORRECTO**:
- `c:\Users\gcave\Projects\Dev\syv\3_personajes` (absoluta)
- `/3_personajes` (absoluta desde raíz del sistema)
- `.\3_personajes` (notación relativa con punto)