Systeme de SkillsCatalogue
doc-writer-agent
Ecrire et reviewer de la documentation professionnelle. 10 regles, 4 types Diataxis, templates, checklist de review, scoring.
Ecrit de la documentation au niveau Stripe, Cloudflare et Vercel. Applique automatiquement les regles de redaction extraites de l'analyse de 20 sites world-class.
Declencheurs
Tu peux l'invoquer avec :
- "ecris la doc"
- "write docs"
- "document this"
- "redige la doc"
- "doc-writer"
- "review this page"
Ce qu'il fait
1. Classifier (Diataxis)
Avant d'ecrire un mot, le skill identifie le type de la page :
| Type | Le lecteur demande | Ton |
|---|---|---|
| Tutorial | "Apprends-moi" | "Construisons ensemble..." |
| How-to | "Aide-moi a faire X" | "Lance cette commande" |
| Reference | "Quelles sont les options ?" | Neutre, factuel |
| Explanation | "Pourquoi ca marche ?" | "Ca fonctionne parce que..." |
2. Ecrire avec les 10 regles
| # | Regle |
|---|---|
| 1 | Max 25 mots par phrase |
| 2 | Max 3 phrases par paragraphe |
| 3 | Code d'abord, texte ensuite |
| 4 | Voix active, 2e personne ("tu") |
| 5 | Titres = verbes d'action |
| 6 | Zero filler words ("simplement", "juste") |
| 7 | Un concept par section |
| 8 | Definir le jargon a la premiere occurrence |
| 9 | Au moins 2 liens vers d'autres pages |
| 10 | Les exemples doivent fonctionner |
3. Reviewer avec la grille de scoring
| Critere | Poids |
|---|---|
| Diataxis compliance | 20% |
| Qualite d'ecriture | 20% |
| Exemples de code | 20% |
| Structure | 15% |
| Navigation | 15% |
| DX (search, TOC, dark mode) | 10% |
Le skill score de 0 a 100. Sous 70 = corriger avant publication.
Exemple d'utilisation
Toi : "ecris la doc pour le nouveau endpoint /api/agents"
doc-writer-agent :
1. Classifie → Reference (le lecteur consulte des faits)
2. Utilise le template API Reference
3. Ecrit : methode, params, exemple curl, reponse JSON, codes erreur
4. Passe la checklist (25 mots, voix active, liens, code teste)
5. Score : 85/100 → publieLes 10 peches capitaux
Le skill refuse de produire une page qui :
- Est un mur de texte (max 3 phrases/paragraphe)
- N'a pas d'exemples de code
- A des exemples qui ne fonctionnent pas
- Melange les types Diataxis
- N'a pas de liens croises
- Utilise du jargon non defini
- N'a pas de Getting Started
- Ignore le mobile
Fichier source
~/.claude/skills/doc-writer-agent/SKILL.md (330 lignes)Lecture liee
- Guide de redaction — les 38 regles completes
- Formats de contenu — les 10 templates
- Review et iteration — checklist et scoring