La documentación se tuerce antes de escribir una frase. Suele ocurrir cuando intentamos enseñar, resolver un problema y explicar conceptos en la misma página. Documentation Writer, una skill del repositorio oficial Awesome Copilot, corta ahí: primero obliga a decidir qué documento hace falta. GitHub la incorporó el 19 de febrero de 2026.
Elige qué documento necesitas
La skill sigue Diátaxis, un método que separa cuatro trabajos distintos. Un tutorial acompaña a quien aprende; una guía resuelve una tarea concreta; la referencia describe cómo funciona algo; y la explicación aporta contexto. La distinción evita esas páginas que empiezan como manual y terminan contando la historia completa del producto.
Antes de escribir, el asistente pregunta por el tipo de documento, la audiencia, el objetivo y lo que debe quedar fuera. Después propone un esquema y espera aprobación. Imagina que una API estrena webhooks: puedes pedir una guía para activar el primero, dirigida a quien ya conoce la API y limitada a autenticación y prueba. Así queda claro qué debe contar y qué no.
Instala y revisa el archivo
La documentación de GitHub pide GitHub CLI 2.90.0 o posterior para gestionar skills. Como la función sigue en versión preliminar, conviene mirar primero el contenido con gh skill preview github/awesome-copilot documentation-writer. Si encaja, el manual actual indica instalarla con gh skill install github/awesome-copilot documentation-writer.
También puedes copiar su carpeta a .github/skills, .claude/skills o .agents/skills. Es un solo archivo SKILL.md, sin scripts ni recursos adjuntos, y el repositorio usa licencia MIT. El formato abierto de Agent Skills permite reutilizar la carpeta en clientes compatibles, aunque cada uno decide qué rutas reconoce.
La letra pequeña está en las fuentes
Documentation Writer no navega por su cuenta. El archivo dice que sólo puede consultar una web si le das el enlace y se lo pides. Puede usar otros Markdown para imitar términos y tono, pero no debe copiarlos. Eso la hace útil para ordenar material que ya tienes; no sustituye comprobar una API, ejecutar ejemplos ni revisar el resultado con alguien que conozca el producto.
Tampoco hemos instalado o medido la skill para este artículo. Hemos revisado sus instrucciones, su historial y la documentación de instalación. Y hay otro límite práctico: exige aprobar el esquema antes de redactar. Para una corrección de dos líneas puede resultar lento; para rehacer una sección de documentación, ese minuto suele estar bien gastado.
Úsala cuando el texto mezcle funciones
Su caso más claro aparece cuando un README intenta enseñar a empezar, resolver incidencias y documentar cada parámetro a la vez. La skill ayuda a separar esas rutas y a decidir cuál necesita el lector ahora. También sirve a equipos de contenido que reciben notas técnicas desordenadas y deben convertirlas en una pieza concreta.
Su mejor idea es el freno inicial. Antes de producir párrafos, pregunta para quién son y qué trabajo deben hacer. Si la documentación falla justo ahí, añadir más texto sólo hace el problema más largo.
0 comentarios
Todavía no hay comentarios.
Deja un comentario