document-release

Descripción general de la skill document-release

Para qué sirve document-release

document-release es una skill de actualización de documentación posterior al lanzamiento que mantiene la documentación del proyecto alineada con lo que realmente se entregó. Lee la documentación, la compara con el diff reciente y ayuda a actualizar archivos como README.md, ARCHITECTURE.md, CONTRIBUTING.md, CLAUDE.md, CHANGELOG.md y VERSION cuando un release cambia la historia que cuenta el repositorio.

Quién debería usarla

La skill document-release es ideal para redactores técnicos, mantenedores de repositorios y agentes que necesitan convertir código ya fusionado en documentación precisa, con menos verificación manual. Resulta especialmente útil cuando el código ya está listo, pero la documentación sigue reflejando el comportamiento anterior.

Por qué importa en la práctica

La tarea principal no es redactar en genérico; es sincronizar el release. Esta skill es útil cuando necesitas una guía fiable de document-release que actualice el texto, elimine TODO obsoletos y mantenga las notas de versión coherentes con lo que se publicó, en lugar de inventar una narrativa nueva desde cero.

Cómo usar la skill document-release

Instálala y actívala correctamente

Usa el flujo de instalación de document-release en tu entorno de agente y luego invócala cuando se fusione un PR, se publique código o alguien pida “actualizar la documentación” o “sincronizar la documentación”. La skill está pensada para llamarse después de la implementación, no durante la redacción exploratoria.

Empieza con las entradas correctas

Los prompts más sólidos incluyen el diff publicado, los archivos afectados, el público objetivo y cualquier restricción del release. Una petición débil como “actualiza la documentación” obliga a la skill a adivinar; una petición más fuerte como “sincroniza la documentación por el cambio de nombre de la API en este PR fusionado y mantén un tono conciso en el changelog” le da el contexto que necesita para editar con precisión.

Lee primero estos archivos

Para usar document-release, empieza por SKILL.md y luego revisa los archivos a los que apunta en tu repo, especialmente README.md, ARCHITECTURE.md, CONTRIBUTING.md, CLAUDE.md y cualquier archivo de release o de versión. Consulta también SKILL.md.tmpl si quieres entender la estructura generada y qué debería mantenerse estable entre actualizaciones.

Consejos de flujo de trabajo que mejoran el resultado

Usa la skill para responder tres preguntas en este orden: qué cambió, qué documentación menciona ese comportamiento y qué debe reescribirse o eliminarse. Si el repo tiene TODO activos, ejemplos obsoletos o instrucciones versionadas, indícalo explícitamente en el prompt para que document-release pueda limpiarlos en lugar de conservarlos.

Preguntas frecuentes sobre la skill document-release

¿document-release es solo para lanzamientos finales?

No. La skill document-release también encaja con PR fusionados y cualquier cambio posterior al envío que haga que la documentación publicada se desvíe de la realidad. Es menos útil para lluvia de ideas antes de fusionar y más útil una vez que la fuente de verdad ya cambió.

¿En qué se diferencia de un prompt normal?

Un prompt normal puede producir una edición decente, pero document-release añade un flujo de trabajo centrado en el release: leer la documentación, cruzarla con el diff, actualizar los archivos afectados y mantener coherentes el tono y la terminología. Eso reduce la probabilidad de publicar instrucciones obsoletas o de omitir una doc dependiente.

¿Es adecuada para principiantes?

Sí, siempre que la persona pueda identificar qué se publicó y qué documentación debe reflejarlo. Los principiantes obtienen mejores resultados cuando aportan un resumen claro del cambio, la ruta del repositorio de destino y los archivos que esperan actualizar.

¿Cuándo no debería usarla?

No uses document-release cuando solo necesites un borrador rápido, un anuncio de producto o documentación especulativa para código que aún no está terminado. Tampoco encaja bien si no puedes acceder al historial del repo o a los archivos modificados, porque la skill depende de basar las ediciones en lo que realmente cambió.

Cómo mejorar la skill document-release

Dale a la skill un brief de release más preciso

La mayor mejora de calidad viene de nombrar exactamente el comportamiento entregado, la documentación afectada y el tono que quieres conservar. Por ejemplo: “Actualiza la documentación del nuevo flujo de autenticación, elimina los pasos de configuración obsoletos, mantén factual el changelog y no cambies las notas de arquitectura fuera de la sección afectada”.

Haz visibles los fallos más comunes

document-release funciona mejor cuando le adviertes sobre ejemplos obsoletos, comandos renombrados, referencias cruzadas rotas o cadenas de versión que deben moverse en conjunto. Si sabes que una doc es la fuente de autoridad y las demás derivan de ella, dilo; eso evita reescrituras innecesarias y mantiene la skill document-release enfocada.

Itera después del primer pase

Revisa la primera salida buscando tres cosas: enlaces faltantes, capturas de pantalla o ejemplos de código obsoletos, y deriva de terminología entre archivos. Luego devuelve solo las brechas que encontraste, para que el siguiente pase afine el resultado de instalación y uso de document-release sin volver a editar las secciones estables.

Usa la skill como una checklist de release

Para document-release en Technical Writing, trata la skill como un control de calidad posterior al lanzamiento: confirma que la documentación coincide con el comportamiento publicado, elimina TODO muertos y verifica las instrucciones versionadas. Las mejores entradas para la guía de document-release son lo bastante específicas como para que el modelo pueda reconciliar el diff con el repo en lugar de reescribir todo de forma genérica.