document-release

Vue d’ensemble du skill document-release

À quoi sert document-release

document-release est un skill de mise à jour documentaire post-publication, conçu pour garder la documentation du projet alignée avec ce qui a réellement été livré. Il lit la documentation, la compare au diff récent et aide à mettre à jour des fichiers comme README.md, ARCHITECTURE.md, CONTRIBUTING.md, CLAUDE.md, CHANGELOG.md et VERSION lorsqu’une release modifie le récit du projet.

Qui devrait l’utiliser

Le skill document-release convient particulièrement aux rédacteurs techniques, aux mainteneurs de dépôt et aux agents qui doivent transformer du code fusionné en documentation exacte, avec moins de vérifications manuelles. Il est surtout utile quand le code est prêt, mais que la documentation reflète encore l’ancien comportement.

Pourquoi c’est important en pratique

L’objectif principal n’est pas d’écrire de manière générique ; c’est d’assurer la synchronisation des releases. Ce skill est utile quand vous avez besoin d’un guide document-release fiable pour mettre à jour les textes, supprimer les TODO obsolètes et garder les notes de version cohérentes avec ce qui a été livré, au lieu d’inventer un nouveau récit de toutes pièces.

Comment utiliser le skill document-release

L’installer et le déclencher correctement

Utilisez le flux d’installation de document-release dans votre environnement d’agent, puis déclenchez-le lorsqu’une PR est fusionnée, qu’un code est publié ou que quelqu’un demande de « mettre la doc à jour » ou de « synchroniser la documentation ». Ce skill est conçu pour être appelé après l’implémentation, pas pendant une phase de rédaction exploratoire.

Partir des bons inputs

Les meilleurs prompts incluent le diff livré, les fichiers concernés, le public visé et les contraintes de release. Une demande trop vague comme « mets la doc à jour » oblige le skill à deviner ; une demande plus solide comme « synchronise la doc pour le renommage de l’API dans cette PR fusionnée et garde le ton du changelog concis » lui donne le contexte nécessaire pour éditer avec précision.

Lire d’abord ces fichiers

Pour bien utiliser document-release, commencez par SKILL.md, puis inspectez les fichiers qu’il pointe dans votre dépôt, en particulier README.md, ARCHITECTURE.md, CONTRIBUTING.md, CLAUDE.md et tout fichier de release ou de version. Consultez aussi SKILL.md.tmpl si vous voulez comprendre la structure générée et ce qui doit rester stable d’une mise à jour à l’autre.

Conseils de workflow qui améliorent le résultat

Utilisez le skill pour répondre, dans cet ordre, à trois questions : qu’est-ce qui a changé, quels documents mentionnent ce comportement, et que faut-il réécrire ou supprimer. Si le dépôt contient des TODO actifs, des exemples obsolètes ou des instructions versionnées, signalez-les explicitement dans le prompt afin que le skill document-release puisse les nettoyer au lieu de les conserver.

FAQ du skill document-release

document-release sert-il seulement pour les releases finales ?

Non. Le skill document-release convient aussi aux PR fusionnées et à tout changement post-publication qui fait diverger la documentation publiée de la réalité. Il est moins utile pour le brainstorming avant fusion et beaucoup plus utile une fois que la source de vérité a changé.

En quoi est-ce différent d’un prompt normal ?

Un prompt normal peut produire une modification correcte, mais document-release ajoute un workflow centré sur la release : lire la documentation, recouper avec le diff, mettre à jour les fichiers touchés et garder une voix ainsi qu’une terminologie cohérentes. Cela réduit le risque de publier des instructions obsolètes ou d’oublier une documentation dépendante.

Est-ce adapté aux débutants ?

Oui, à condition que l’utilisateur puisse identifier ce qui a été livré et quels documents doivent refléter ce changement. Les débutants obtiennent les meilleurs résultats lorsqu’ils fournissent un résumé clair de la modification, le chemin du dépôt cible et les fichiers qu’ils s’attendent à voir mis à jour.

Quand ne faut-il pas l’utiliser ?

N’utilisez pas document-release si vous avez seulement besoin d’un brouillon rapide, d’une annonce produit ou d’une documentation spéculative pour du code non terminé. Ce n’est pas non plus un bon choix si vous n’avez pas accès à l’historique du dépôt ou aux fichiers modifiés, car le skill dépend d’un ancrage dans ce qui a réellement changé.

Comment améliorer le skill document-release

Donner au skill un brief de release plus précis

Le plus gros gain de qualité vient du fait de nommer exactement le comportement livré, les docs impactées et le ton à préserver. Par exemple : « Mets à jour la doc pour le nouveau flux d’authentification, supprime les étapes de configuration obsolètes, garde le changelog factuel et ne modifie pas les notes d’architecture en dehors de la section concernée. »

Signaler les modes de défaillance fréquents

document-release fonctionne mieux si vous l’avertissez des exemples obsolètes, des commandes renommées, des croisements cassés ou des chaînes de version qui doivent évoluer ensemble. Si vous savez qu’un document fait autorité et que les autres en dérivent, dites-le ; cela évite des réécritures inutiles et garde le skill document-release concentré.

Itérer après le premier passage

Relisez la première sortie en vérifiant trois points : les liens manquants, les captures d’écran ou exemples de code obsolètes, et la dérive de terminologie entre les fichiers. Puis ne renvoyez que les écarts repérés, ce qui aide le passage suivant à affiner le résultat d’installation et d’utilisation de document-release sans réécrire les sections stables.

Utiliser le skill comme checklist de release

Pour document-release en rédaction technique, traitez le skill comme un passage QA post-publication : vérifiez que la doc correspond bien au comportement livré, supprimez les TODO morts et contrôlez les instructions versionnées. Les meilleurs inputs pour le guide document-release sont suffisamment précis pour que le modèle puisse recouper le diff avec le dépôt au lieu de tout réécrire de manière générique.