Comandos del proyecto: validate, build y tools con markeup-cli

La skill markeup-cli —«Ejecuta la CLI del proyecto: tools, build y validadores»— 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 mapa de mandos del proyecto en un solo sitio: qué comando se ejecuta para cada tarea y qué se espera a cambio.

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-cli`
Responsabilidad	Ejecuta la CLI del proyecto: tools, build y validadores.
Versión	2.3.0
Autoría	uriszarernesto-blip · licencia MIT
Plataformas	linux · macos
Tags del canon	cli · markeup · tools · astro · build · deploy · vault
Skills relacionadas	markeup-context · markeup-audit · markeup-deploy
Fuente	`~/.hermes/skills/markeup/markeup-cli/SKILL.md`

Responsabilidad unica: ejecutar la CLI del proyecto. Prefiere la CLI sobre la edicion manual siempre que exista un comando para la operacion.

Refactor de la antigua skill markeup-cli (archivada en .archive/markeup-cli.legacy), con rutas y comandos verificados contra package.json.

Hay que ejecutar algo que ya tiene comando: generar, validar, indexar o construir.
Vas a tocar el vault a mano (renombrar, mover, borrar) y un comando lo hace sin riesgo.
Un gate sale en rojo y quieres el comando exacto que lo reproduce (y su pariente de seccion).
Necesitas el nombre real de un script: esta skill es la matriz; el detalle del subsistema vive en la skill del tema (markeup-seo, markeup-media, markeup-images…).

Nunca inventes un comando: si no esta en package.json, no existe. Preferir la CLI a la edicion manual siempre que la operacion tenga comando.

Ejecutar siempre desde la raiz del proyecto: ~/markeup
Los scripts npm run tools:* ya incluyen PYTHONPATH=src.
Si invocas python -m markeup_tools a mano, anade PYTHONPATH=src:

cd ~/markeup
PYTHONPATH=src python3 -m markeup_tools stats

El proyecto tiene un venv en src/.venv (Python 3.14 · PyYAML 6.0.3 · requests 2.34.2 · pip 26.2.1) y esta activo en la shell de trabajo, asi que npm run tools:* funciona tal cual, sin export PATH.

# Diagnostico: que interprete se resuelve y si tiene PyYAML
python3 -c "import sys, yaml; print(sys.executable, '| PyYAML', yaml.__version__)"

Interprete	PyYAML	Vale para `tools:*`
`src/.venv/bin/python3` (el del PATH con el venv activo)	si, 6.0.3	si (por defecto)
`/opt/homebrew/bin/python3`	si, 6.0.3	si (fallback fiable)
`/usr/bin/python3` (el del sistema)	no	no

Forma robusta (no depende de que el venv este activo ni del PATH heredado: util en launchd, cron y CI):

cd ~/markeup
PYTHONPATH=src src/.venv/bin/python3 -m markeup_tools stats

Si el venv no existe (clon nuevo), recrealo — las dependencias estan en requirements.txt (incluye pyyaml: src/markeup_tools/utils.py lo importa):

/opt/homebrew/bin/python3 -m venv src/.venv
src/.venv/bin/python3 -m pip install -r requirements.txt

Si tools:* falla con ModuleNotFoundError: No module named 'yaml', el interprete resuelto es el del sistema: usa el venv o Homebrew, y reporta esa causa exacta en vez de un error generico.

npm run tools:stats                    # contadores por categoria + top tags
npm run tools:huerfanos                # huerfanos prioritarios (tabla)
npm run tools:auditar                  # salud del vault
npm run tools:auditar -- --json        # salida JSON
npm run tools:index                    # regenera hermes/memory/vault-index.md
npm run tools:tagfix                   # normaliza tags (tildes, #, typos)
npm run tools:buscar -- "vivientes"    # busca texto en posts
npm run tools:backlinks -- el-aura     # backlinks de una nota
npm run tools:relacionadas -- el-aura  # notas relacionadas por score

# Categorias validas (una de las 5): Humano | Documentacion | Literatura | Opinion | Maquina

# Borrador (esqueleto, sin IA) - ideal para drafts desde chat/Telegram:
npm run tools:crear:borrador -- --tema "Mi tema" --categoria Humano

# Creacion con IA completa (Ollama local) - puede tardar minutos:
PYTHONPATH=src python3 -m markeup_tools crear --tema "Mi tema" --categoria Humano

# Ver que haria sin escribir (dry-run):
PYTHONPATH=src python3 -m markeup_tools crear --tema "..." --categoria Humano --dry-run

⚠️ crear y crear:borrador escriben en disco. Confirma con el usuario antes salvo que el punto de entrada sea Hermes CLI con --yes.

PYTHONPATH=src python3 -m markeup_tools vincular <slug-a> <slug-b>    # enlaces bidireccionales
PYTHONPATH=src python3 -m markeup_tools renombrar <slug> <nuevo-slug> # + actualiza backlinks
PYTHONPATH=src python3 -m markeup_tools conectar <slug>               # propone wikilinks nuevos
PYTHONPATH=src python3 -m markeup_tools relacionadas <slug>           # notas relacionadas

npm run validate:frontmatter   # 22 campos (4 duros: title/slug/description/categories) + tags, fechas, categoria ↔ carpeta
npm run validate:seo           # GATE SEO: title 50-75, description 140-200, clave al frente
npm run validate:slugs        # slugs validos
npm run validate:wikilinks    # REGLA DE ORO -> exit 1 si hay enlaces sin alias
npm run validate:icons        # iconos / OG
npm run validate:share        # metadata de compartir
npm run validate:media        # medios embebidos (sustituye a validate:audio, retirado el 2026-10-03)
npm run wikilinks:enrich        # dry-run de enriquecimiento
npm run wikilinks:enrich:apply  # aplica enriquecimiento

npm run seo:brief -- --cat Humano     # brief de trabajo (--tag, --pending, --slug)
npm run seo:apply -- --apply          # aplica title/description desde scripts/data/seo-meta.json
npm run validate:seo                  # GATE (autoridad normativa: rules/seo-spec.md)

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

npm run images        # procesa imagenes (sharp)
npm run og            # genera tarjetas OG
npm run build         # pipeline: validate:media + vendor:gsap + images + og + validate:books
                      #  + validate:diagrams + content:cache + astro + validate:graph + pagefind
npm run publish       # publica el sitio (bash scripts/sh/publish.sh; interactivo)
npm run deploy        # = publish.sh --yes (publicacion completa, sin confirmacion)
npm run deploy:dry    # = publish.sh --verify-only --yes (tests + gate + build, sin tocar git)
npm run deploy:check  # diagnostico del despliegue (no publica)
npm run preview       # previsualiza la build

⚠️ Correccion respecto a la skill antigua: el comando tools:deploy no existe; el real es npm run publish (script publish en package.json). Tampoco existen tools:deploy ni tools:build.

Prefiere la CLI sobre la edicion manual cuando exista un comando (crear, stats, index, backlinks, renombrar, vincular).
Tras crear o modificar notas, ejecuta siempre npm run tools:index.
Si modificaste tags manualmente, ejecuta npm run tools:tagfix.
Los comandos tienen modo no-interactivo via argumentos (--tema, --auto, --json). Sin tty no esperan input.
Si npm run build falla tras editar contenido, verifica el frontmatter con npm run tools:auditar y los wikilinks con npm run validate:wikilinks.
Para redaccion creativa elige los atomos de contenido (markeup-content, markeup-wikilinks), no la CLI.

Detalle completo (incluye flags y efectos en disco): references/command-matrix.md.

Obsidian: muestra el comando y su salida; no lo ejecutes sin confirmar si escribe.
Telegram: solo comandos de lectura de forma autonoma (stats, buscar, backlinks). Cualquier comando que escriba requiere confirmacion si.
VS Code / Cline: ejecuta y muestra la salida real de la terminal.
Hermes CLI: modo one-shot; reporta exit codes y salida.

cd ~/markeup
npm run validate:wikilinks   # exit 0 esperado

references/command-matrix.md - todos los comandos, flags y efectos.
markeup-context - dependencia obligatoria (rutas).
Codigo fuente de la CLI: src/markeup_tools/.

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

Comandos del proyecto

Comandos del proyecto: validate, build y tools con markeup-cli

Posts que enlazan a este artículo