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 de trabajo de 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 se pierde 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 conviertan sin pérdidas en ambos sentidos. También pueden trasladar tu documentación existente a DeveloperHub desde otra herramienta.
El paquete es público y lo mantiene DeveloperHub: github.com/developerhub-io/dh-skills. Se distribuye bajo la licencia MIT.
Qué es
El paquete incluye tres skills:
write-markdoc documenta cada bloque de DeveloperHub y cada etiqueta en línea 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 abarca la estructura del repositorio: dónde va cada archivo, los archivos de navegación y configuración, las imágenes, las referencias de API, los bloques sincronizados, los registros de cambios y el aspecto de tu sitio (logotipo, favicon, colores y CSS personalizado), y cómo añadir, mover, anidar, agrupar, reordenar u ocultar páginas sin romper la sincronización.
migrate-docs traslada tu documentación desde otra herramienta, como Docusaurus, MkDocs, Sphinx, GitBook, Mintlify o ReadMe, a una carpeta que importas con Sincronización con GitHub. Consulta Importar desde cualquier herramienta con IA.
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, escriba tus páginas:
Al editar páginas en un repositorio de Sincronización con GitHub o en cualquier flujo de trabajo de docs-as-code.
En cualquier tarea en la que quieras que el agente produzca Markdoc correcto y sin pérdidas a la primera.
Al trasladar tu documentación a DeveloperHub desde otra herramienta.
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 actualizada a medida que evoluciona el formato:
Las skills llegan con espacio de nombres, como dh-skills:write-markdoc, dh-skills:organize-docs-repo y dh-skills:migrate-docs.
El plugin también conecta Claude Code con el servidor MCP del editor, de modo que Claude puede buscar, escribir y publicar páginas directamente en tus proyectos. La primera vez que Claude lo usa, inicias sesión en DeveloperHub y apruebas el acceso, y solo llega a los proyectos en los que un administrador ha activado el servidor.
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.
Como alternativa, copia tú mismo las carpetas de skills/ del repositorio en el directorio de skills de tu agente (.claude/skills/, .cursor/skills/, etc.). Copia las tres juntas, ya que migrate-docs depende de las otras dos.
El paquete también está en npm, para quien prefiera incluir los archivos como una dependencia:
Cómo usarlo
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 cambian ni pierden contenido en el siguiente guardado.
Para consultar la referencia en la que se basa write-markdoc, consulta Formato Markdoc, que enumera cada bloque con un ejemplo.
Migrar desde otra herramienta
Para trasladar tu documentación a DeveloperHub con migrate-docs:
Instala las skills y luego inicia una sesión nueva en tu agente.
Pide a tu agente que migre tu documentación a DeveloperHub e indícale dónde está: una carpeta o repositorio, una exportación o el sitio en vivo si no hay nada más.
Responde a sus preguntas sobre cómo estructurar tu contenido y revisa las primeras páginas que convierta.
Sube la carpeta que genere a un repositorio de GitHub y configura GitHub Sync con Primera sincronización establecida en Importar.
Para ver cada paso en detalle y qué hacer con el informe y las redirecciones que te entrega, consulta Importar desde cualquier herramienta con IA.
Comentarios
¿Has detectado un error o quieres que se documente un bloque de otra manera? Abre una incidencia en el repositorio.
Need help? Visit our community forums or contact us.