¿Qué hace WolfMarkDown?
Un flujo de trabajo de publicación para agentes que convierte la salida desordenada de IA en Markdown profesional, listo para revisar y conservar.
Juicio del agente para la estructura. Herramientas deterministas para la verificación.
Los agentes de IA pueden producir investigaciones, planes y documentación útiles, pero a menudo dejan atrás comparaciones aplanadas, encabezados inconsistentes, andamios de chat copiados, bloques de código rotos e identificadores técnicos alterados.
WolfMarkDown proporciona al agente un flujo de trabajo de publicación disciplinado:
- el agente decide el significado, la estructura, la sanitización y la composición;
- las herramientas deterministas formatean y validan el Markdown resultante;
- el contenido protegido, la reversión y los límites de publicación se verifican antes de conservar el resultado.
El resultado no es un motor mágico de reparación de Markdown. Es un flujo de trabajo de agente con verificación determinista en torno al artefacto.
Por qué existe WolfMarkDown
Prettier es un excelente impresor de Markdown. No puede decidir si un bloque aplanado contiene una tabla comparativa, si una oración corta es un encabezado, o si un mensaje de agente copiado pertenece al documento.
WolfMarkDown hace esas decisiones explícitas y conservadoras. Repara la estructura clara, preserva el material genuinamente ambiguo e informa lo que se recuperó. No verifica los hechos de la fuente ni aprueba la publicación.
| Capacidad | Solo Prettier | WolfMarkDown |
|---|---|---|
| Formateo determinista de Markdown | Sí | Sí |
| Reparar estructura semántica del documento | No | Sí |
| Eliminar andamios copiados de conversaciones de IA | No | Sí |
| Reconstruir tablas comparativas mal formadas | No | Sí |
| Proteger URLs, código, hashes, versiones e identificadores | No | Sí |
| Verificar análisis GFM y equilibrio de bloques de código | No | Sí |
| Ejecutar markdownlint antes de publicar | No | Sí |
| Verificar idempotencia | No | Sí |
| Restaurar el original después de una limpieza fallida | No | Sí |
| Rechazar publicar una composición fallida | No | Sí |
WolfMarkDown no reescribe prosa que ya es buena solo para que suene diferente. El objetivo es la limpieza semántica mínima necesaria con verificación determinista de que el resultado es seguro de conservar.
Instalar
npx skills add WolfMarkTools/WolfMarkDown --skill wolfmarkdown
La CLI skills instala la habilidad canónica wolfmarkdown/ para el host compatible con Agent Skills seleccionado. También se puede ejecutar desde un clon del repositorio:
npm ci --prefix wolfmarkdown
node wolfmarkdown/scripts/install.mjs
Para una instalación no interactiva de Claude Code:
npx skills add WolfMarkTools/WolfMarkDown \
--skill wolfmarkdown \
-g \
-a claude-code \
-y
El instalador repara las dependencias de tiempo de ejecución solo cuando es necesario, configura el descubrimiento compartido .agents/skills/wolfmarkdown, configura la ruta de compatibilidad de Claude Code, utiliza un enlace de directorio en Windows cuando es apropiado y se niega a sobrescribir rutas no relacionadas.
Uso rápido
Usa WolfMarkDown en docs/architecture.md.
Exporta esta investigación como Markdown usando WolfMarkDown.
Verifica docs/architecture.md con WolfMarkDown sin modificarlo.
Cuando un host expone comandos de barra, el mismo flujo de trabajo se puede invocar como:
/wolfmarkdown docs/architecture.md
/wolfmarkdown verify docs/architecture.md
La invocación en lenguaje natural es la interfaz portátil. La presentación del comando de barra es específica del host.
Operaciones
| Operación | Lo que hace WolfMarkDown |
|---|---|
| Componer | Crea un archivo .md real a partir del material fuente, elimina el andamiaje exclusivo del chat, lo formatea, lo verifica y publica solo después de SUPERADA. |
| Limpiar | Repara un archivo Markdown existente con los cambios semánticos mínimos necesarios y restaura el original si la verificación falla. |
| Verificar | Verifica Markdown sin modificarlo. |
| Doctor | Inspecciona las dependencias de tiempo de ejecución y el descubrimiento de habilidades sin modificar la instalación. |
| Configurar | Repara las dependencias de tiempo de ejecución solo cuando es necesario y configura el descubrimiento compartido de habilidades. |
Los objetivos típicos de limpieza incluyen la jerarquía de encabezados, listas mal formadas, tablas GFM rotas, bloques de código sin cerrar, comentarios de agente copiados, redacción dependiente de la conversación y ruido decorativo que no debería sobrevivir en la documentación.
Antes y después
Un borrador desordenado de un agente puede aplanar una comparación en un solo bloque:
Recomendación usar relay_v2 para el flujo de billetera externa.
Comparación Proveedor Modo Riesgo Privy Aprobación externa Media CDP Billetera embebida Alta.
Notas de implementación relay_v2 confirma getTransaction después del envío.
Después de que el agente haga explícita la estructura, WolfMarkDown puede publicar un documento como:
# Decisión del flujo de billetera
## Recomendación
Usar `relay_v2` para el flujo de billetera externa.
## Comparación
| Proveedor | Modo | Riesgo |
| --- | --- | --- |
| Privy | Aprobación externa | Media |
| CDP | Billetera embebida | Alta |
## Notas de implementación
`relay_v2` confirma `getTransaction` después del envío.
La salida recupera una tabla y encabezados, preserva los identificadores técnicos y no agrega información que estuviera ausente en la fuente. Este es un ejemplo estructural ilustrativo; el juicio semántico sigue siendo propiedad del agente.
Ejemplos
Los ejemplos públicos muestran a WolfMarkDown recuperando estructura de Markdown real creado por agentes sin inventar significado faltante.
- Ejemplo de Migración de App Móvil — un fixture completo de antes y después que cubre sanitización de envoltura de chat, tablas separadas por tabulaciones, viñetas Unicode, variables de entorno protegidas y una nota de base de datos intencionalmente ambigua.
- Entrada original — la salida de IA original antes de la reparación.
- Salida estructurada — el Markdown resultante con encabezados, tablas GFM, listas y un bloque de código
env.
El README del ejemplo registra el harness OpenCode, el modelo GLM-5.2 y el prompt exacto utilizado para la reproducción.
Estado de integración con hosts compatibles
WolfMarkDown tiene una única implementación canónica. La tabla distingue las rutas de descubrimiento probadas en el repositorio de la aceptación del host que aún necesita una prueba de humo dedicada.
| Host | Estado de integración | Ruta de descubrimiento |
|---|---|---|
| Codex | Ruta de descubrimiento e instalador probadas en el repositorio | .agents/skills compartido |
| Cursor | Ruta de descubrimiento e instalador probadas en el repositorio | .agents/skills compartido |
| Claude Code | Ruta de enlace de compatibilidad probada | .claude/skills |
| OpenCode | Aceptación del host pendiente | .agents/skills compartido cuando el host lo habilita |
| Gemini CLI | Aceptación del host pendiente | .agents/skills compartido cuando el host lo habilita |
| GitHub Copilot | Aceptación del host pendiente; la incorporación del plugin es evidencia histórica | Agent Skills o soporte de plugin habilitado por el host |
La aceptación del host no se infiere de la presencia de un binario o directorio. El modelo del host determina la calidad semántica; WolfMarkDown proporciona el flujo de trabajo y las comprobaciones deterministas.
Cómo funciona
Intención del usuario
↓
Juicio semántico del agente
↓
Mapa fuente y reparación semántica
↓
Análisis GFM + comprobaciones de encabezados/tablas
↓
Comprobaciones de bloques de código, frontmatter y espacios en blanco
↓
Comprobación de formato Prettier
↓
markdownlint
↓
Integridad de tokens protegidos (con una instantánea de la fuente) + idempotencia
↓
SUPERADA → conservar o publicar FALLIDA → restaurar o no publicar
Antes del formateo, el agente verifica si hay estructura semántica aplanada. Un documento puede ser Markdown válido y aun así ser una transformación fallida si perdió tablas, encabezados, listas o relaciones.
Límite de reparación semántica
El agente reconstruye encabezados, listas, tablas, párrafos y secciones hermanas solo cuando la fuente hace que la estructura sea clara. Una secuencia de líneas separadas por tabulaciones sin encabezado no es automáticamente una tabla, una oración corta no es automáticamente un encabezado, y una frase aislada Etiqueta: valor no es automáticamente un elemento de lista. Para documentos largos, el agente mantiene un mapa fuente y concilia el esquema completo, las relaciones entre secciones, los límites de las tablas y los valores protegidos antes de publicar. Si la fuente no se puede revisar por completo, preserva la incertidumbre e informa el límite en lugar de adivinar.
Verificación y límite de calidad
WolfMarkDown SUPERADA significa que el artefacto pasó las comprobaciones deterministas aplicables:
- el artefacto Markdown pasó las comprobaciones de formateo, análisis, lint, bloques de código e idempotencia;
- el agente hizo e informó decisiones estructurales basadas en la fuente;
- el contenido técnico protegido se preservó solo cuando se verificó la integridad contra una instantánea de la fuente sin modificar, como en Limpiar y Componer o con
--integrity-from; - las operaciones fallidas de Limpiar y Componer no dejaron un resultado publicado no verificado.
Una Verificación independiente sin una fuente de integridad informa que la integridad se omitió. Su SUPERADA no demuestra que los tokens protegidos se hayan preservado.
Detalles protegidos
Cuando una instantánea de la fuente sin modificar está disponible, las comprobaciones de integridad protegen el contenido técnico que incluye:
- URLs, código en línea y bloques de código;
- claves públicas, firmas, hashes, versiones e identificadores;
- rutas del sistema de archivos y variables de entorno contextuales;
- fechas, porcentajes y valores de moneda.
Esto es evidencia de calidad de Markdown, no aprobación de contenido. SUPERADA no establece corrección fáctica, integridad, actualidad, cumplimiento normativo ni autorización para publicar. No verifica afirmaciones.
Las comprobaciones deterministas son prueba de las propiedades del artefacto. No son un oráculo semántico y no reemplazan la responsabilidad del agente de dar cuenta de cada señal clara de la fuente.
Evidencia de la versión v0.2.1
- 82/82 pruebas de Node pasan.
- Las comprobaciones de propiedades semánticas ejecutables cubren encabezados, tablas GFM, tokens protegidos y preservación de tablas ambiguas.
skills-ref validate ./wolfmarkdownpasa.- Las comprobaciones del instalador, Doctor, reversión, colisión de destino, integridad e idempotencia siguen cubiertas.
Historial de incorporación de plugins externos
El paquete v0.1.1 de Agent Plugins pasó la incorporación automatizada de plugins externos de GitHub Awesome Copilot. Esta es evidencia histórica de empaquetado, no evidencia de aceptación del host para v0.2.1.
Detalles de la arquitectura
WolfMarkDown/
├── plugin.json
├── .agents/
│ └── skills/
│ └── wolfmarkdown → ../../wolfmarkdown
├── skills/
│ └── wolfmarkdown → ../wolfmarkdown
└── wolfmarkdown/
├── SKILL.md
├── config/
├── lib/
├── references/
├── scripts/
└── tests/
Decisiones del agente
El agente es dueño del enrutamiento de la intención, el mapeo de la fuente, la clasificación semántica, la sanitización de la conversación, la recuperación de encabezados/listas/tablas, el manejo de la ambigüedad y la composición.
Verificación determinista
Los scripts son dueños del formateo, lint de Markdown, análisis GFM, equilibrio de bloques de código, comprobaciones de frontmatter, integridad de tokens protegidos, idempotencia, instalación, comprobaciones de Doctor, reversión y evaluación semántica basada en propiedades. No reescriben el significado de la fuente.
Prettier es el único impresor final.
El ID de la habilidad de la máquina y el directorio del sistema de archivos están intencionalmente en minúsculas wolfmarkdown; el nombre del producto es WolfMarkDown.
Evaluaciones semánticas
El corpus de evaluación utiliza documentos sintéticos y propiedades estructurales en lugar de instantáneas de documentos completos frágiles. Ejecute un caso contra un candidato producido por el agente después del verificador normal:
node wolfmarkdown/scripts/evaluate-semantic.mjs \
--case ambiguous-structure-preservation \
source.md candidate.md
El evaluador verifica los encabezados esperados y los recuentos de tablas, la preservación de tokens protegidos y las propiedades de seguridad, como negarse a convertir una secuencia ambigua sin encabezado en una tabla. No infiere ni repara el candidato.
Comandos para desarrolladores
npm ci --prefix wolfmarkdown
npm test
npx --yes skills-ref validate ./wolfmarkdown
Comandos directos útiles:
node wolfmarkdown/scripts/doctor.mjs
node wolfmarkdown/scripts/format-markdown.mjs ruta/al/archivo.md
node wolfmarkdown/scripts/verify-markdown.mjs ruta/al/archivo.md
node wolfmarkdown/scripts/evaluate-semantic.mjs --help
Los casos semánticos residen en wolfmarkdown/tests/evals/. Las entradas de aceptación entre hosts residen en wolfmarkdown/tests/acceptance/.
Límites actuales
/wolfmarkdown setupsolo funciona después de que la habilidad sea detectable por el host.--modeno es compatible.- No se crean bifurcaciones de habilidades específicas del proveedor.
- Windows requiere permiso para crear el enlace de descubrimiento apropiado.
- La sanitización semántica sigue siendo juzgada por el agente por diseño.
- El verificador prueba las propiedades del artefacto Markdown; no certifica prosa arbitraria ni preparación para la publicación.
- La reparación de documentos largos depende de que el agente retenga y concilie su registro de documentos; la revisión incompleta de la fuente debe informarse en lugar de adivinarse.
Metadatos del repositorio
Temas de repositorio de GitHub recomendados:
ai-agents agent-skills markdown documentation claude-code codex cursor github-copilot
Los temas deben configurarse en la configuración del repositorio de GitHub. Son metadatos de descubrimiento, no evidencia de compatibilidad.
Contribuir
¿Encontraste un caso límite de Markdown que WolfMarkDown debería manejar mejor? Abre un issue.
Las solicitudes de extracción son especialmente útiles para fallos de Markdown reproducibles, casos límite de integridad, problemas de instalación entre plataformas, evidencia adicional de aceptación del host y mejoras enfocadas que preservan la arquitectura de implementación única.
Licencia
WolfMarkDown está disponible bajo la Licencia MIT.