Escribir Markdoc con agentes de IA

Las páginas de DeveloperHub se redactan en Markdoc, un superconjunto de Markdown con un conjunto de etiquetas personalizadas tipadas. Cuando editas páginas con un agente de programación con IA (en tu IDE, en un repositorio sincronizado con GitHub o en un flujo docs-as-code), el agente necesita generar el dialecto exacto de Markdoc de DeveloperHub. Si genera una forma no canónica, la edición cambia en el primer guardado o descarta contenido sin avisar.

@developerhub/dh-skills es un conjunto de código abierto de Agent Skills que enseñan a tu agente ese dialecto y la estructura de repositorio que DeveloperHub espera, de modo que las páginas que escribe se sincronizan sin pérdidas.

Qué es

El paquete incluye dos skills:

• write-markdoc documenta cada bloque y etiqueta en línea de DeveloperHub con su sintaxis exacta, atributos, valores predeterminados, valores permitidos y las reglas de ida y vuelta que mantienen una edición sin pérdidas.

• organize-docs-repo cubre la estructura del repositorio: dónde va cada archivo, los archivos de navegación y de configuración, las imágenes, las referencias de API y los registros de cambios, y cómo añadir, mover, anidar, agrupar, reordenar u ocultar páginas sin romper la sincronización.

Usan el formato portátil Agent Skills (Markdown con frontmatter YAML), por lo que funcionan con Claude Code, Cursor, Codex y otros agentes compatibles.

Cuándo usarlo

Recurre a él siempre que un agente, y no el editor, esté escribiendo tus páginas:

• Al editar páginas en un repositorio de GitHub Sync o en cualquier flujo docs-as-code.

• En cualquier tarea en la que quieras que el agente produzca Markdoc correcto y sin pérdidas a la primera.

El editor del producto ya conoce el formato, así que esta skill es para agentes que trabajan en tus páginas desde fuera de DeveloperHub.

Instalar la skill

Claude Code

El repositorio funciona también como marketplace de plugins de Claude Code. Es la única instalación que se mantiene al día a medida que evoluciona el formato:

Las skills llegan con espacio de nombres, como dh-skills:write-markdoc y dh-skills:organize-docs-repo.

Los marketplaces de terceros no se actualizan solos hasta que lo permites, así que actívalo una vez: ejecuta /plugin, abre la pestaña Marketplaces, selecciona developerhub y elige Enable auto-update. Después, Claude Code actualiza el plugin en segundo plano poco después de iniciar una sesión.

Cursor, Codex y otros agentes

Usa la CLI de skills, que añade las skills al directorio de skills de tu agente:

Esto copia los archivos, así que ejecuta npx skills update cuando quieras una versión más reciente.

También puedes copiar tú mismo las carpetas skills/write-markdoc y skills/organize-docs-repo del repositorio al directorio de skills de tu agente (.claude/skills/, .cursor/skills/, etc.).

El paquete también está en npm, para quien prefiera incluir los archivos como dependencia:

Uso

Una vez instaladas, tu agente detecta las skills automáticamente cuando una tarea implica tu documentación de DeveloperHub: escribir un callout, un bloque de código, una tabla, una imagen o pestañas; o cambiar la estructura, como añadir, mover o reordenar páginas. Le dan al agente la forma canónica de cada etiqueta y la estructura de archivos correcta, de modo que sus cambios se importan sin problemas y no alteran ni descartan contenido en el siguiente guardado.

Para la referencia sobre la que se construye write-markdoc, consulta Formato Markdoc, que lista cada bloque con un ejemplo.

Comentarios

¿Has detectado un error o quieres que un bloque se documente de otra manera? Abre una incidencia en el repositorio.