Ce fichier est destiné aux consommateurs de la compétence, pas aux contributeurs. Voir AGENTS.md pour le contexte de développement — comment cette compétence est construite, itérée et testée.
Initialisation d'un espace de travail de documentation
Cette compétence apprend à un agent IA comment initialiser un espace de travail de documentation à partir de zéro dans un répertoire vide (ou presque vide). Le résultat est une base de connaissances versionnée, basée sur le système de fichiers, entièrement autonome — appartenant à l'utilisateur, gratuite, sans dépendance à un fournisseur, et structurée de sorte que l'agent qui y travaille n'ait jamais à réfléchir à l'organisation, au formatage ou aux outils.
L'idée centrale
Un espace de travail initialisé contient son propre AGENTS.md — une "mini-compétence figée" par espace de travail et spécifique à un sujet, que l'agent lit à chaque entrée. AGENTS.md est créé à partir d'un modèle fourni par cette compétence. Une fois l'espace de travail existant, l'agent suit AGENTS.md, pas cette compétence. C'est tout l'intérêt : prédéfinir les règles une fois, puis ne jamais brûler de tokens à les redécouvrir.
Quand utiliser cette compétence
Utilisez cette compétence uniquement quand :
- L'utilisateur veut explicitement créer / mettre en place / initialiser / échafauder un espace de travail de documentation, un dossier de docs ou une base de connaissances.
- Le répertoire cible est vide ou presque vide (ou l'utilisateur a explicitement donné son accord malgré des fichiers existants).
- Le répertoire cible ne contient pas déjà un
AGENTS.md(ce qui signifierait qu'il est déjà initialisé).
Si AGENTS.md existe déjà à la cible : n'exécutez pas cette compétence. Lisez le AGENTS.md existant et suivez-le. L'utilisateur est déjà dans un espace de travail initialisé.
Quand NE PAS utiliser cette compétence
- L'utilisateur veut ajouter un document, modifier un document, lier des documents ou réorganiser un espace de travail existant — c'est le
AGENTS.mdde l'espace de travail qui régit cela. - L'utilisateur veut pousser vers GitHub, afficher l'espace de travail dans un navigateur ou configurer un hébergement — il s'agit de préoccupations différentes, de compétences différentes.
- L'utilisateur pose une question générique sur la documentation, l'écriture ou la prise de notes — aucune compétence nécessaire.
Ce que produit la compétence
Lorsqu'elle est invoquée, cette compétence crée un espace de travail contenant :
| Fichier / Répertoire | Objectif |
|---|---|
AGENTS.md | La "mini-compétence figée" par espace de travail. 95 % de règles, 5 % de résumé du sujet. L'agent lit ce fichier à chaque entrée. |
README.md | Aperçu de l'espace de travail. Introduction plus riche, index généré automatiquement, pointeur vers AGENTS.md. |
index.yaml | Ordre des documents pour le répertoire racine. Vide par défaut. |
.gitignore | Valeurs par défaut raisonnables : sauvegardes, fichiers système, fichiers d'éditeur, Node. |
package.json | Dépendances de développement : prettier, markdownlint-cli, js-yaml. Scripts npm pour les outils. |
.prettierrc | Configuration Prettier : ligne de 120 caractères, proseWrap preserve. |
.markdownlint.json | Configuration markdownlint avec les règles nitpick désactivées. |
scripts/ | Scripts utilitaires : format.js, validate.js, hash.js, reindex.js. |
assets/ | Répertoire vide pour les ressources partagées. Créé à la racine de l'espace de travail. |
Un dépôt Git est initialisé dans l'espace de travail si git est disponible. Les dépendances de développement sont installées si Node et npm sont disponibles.
Flux de travail d'initialisation
Suivez ces étapes dans l'ordre. Confirmez avec l'utilisateur à chaque étape indiquée. Ne présumez jamais.
Étape 1 — Confirmer l'emplacement cible
Demandez à l'utilisateur : « Je vais initialiser l'espace de travail de documentation dans <cwd>. Est-ce correct ? (oui / non / spécifier un chemin) »
- Si
oui: continuez avec le répertoire de travail courant comme cible. - Si
non: demandez le chemin correct, confirmez, puis continuez. - Si l'utilisateur a dit « dans ce dossier » ou similaire : supposez le répertoire de travail courant, mais confirmez quand même.
Étape 2 — Confirmer que la cible est vide (ou obtenir l'accord)
Listez le contenu du répertoire cible (en excluant les fichiers cachés comme .git).
Si vide : passez à l'Étape 3.
Si non vide :
- Montrez à l'utilisateur ce qui s'y trouve.
- Expliquez : « Ce répertoire n'est pas vide. Par défaut, cette compétence refuse d'initialiser dans un répertoire non vide. Je peux soit (a) abandonner, (b) vous confirmez que vous voulez que je continue quand même et je laisserai les fichiers existants intacts, ou (c) vous spécifiez un sous-répertoire où créer l'espace de travail. »
- Attendez une confirmation explicite. Si l'utilisateur ne donne pas une affirmation positive stricte, abandonnez.
- Si l'utilisateur dit « vas-y » ou « oui, continue » — enregistrez cela comme un accord et continuez.
Si AGENTS.md existe déjà à la cible : arrêtez-vous. L'espace de travail est déjà initialisé. Dites-le à l'utilisateur et proposez de lire le AGENTS.md existant.
Si git est déjà initialisé à la cible : sautez l'étape git init plus tard, mais continuez.
Étape 3 — Recueillir le résumé du sujet
Demandez à l'utilisateur : « À quoi sert cet espace de travail de documentation ? Décrivez le sujet en 1 à 2 courts paragraphes. Cela deviendra le résumé du sujet dans AGENTS.md et l'introduction dans README.md. »
Règles du résumé du sujet :
- 1 paragraphe (préféré), 2 paragraphes maximum
- Prose simple, pas de mise en forme, pas de listes
- Déclaration claire de ce que l'espace de travail documente
Si l'utilisateur donne une seule phrase : c'est bien, utilisez-la. Si l'utilisateur donne une description plus longue : condensez-la (avec sa confirmation) ou utilisez 2 paragraphes maximum. Si l'utilisateur dit « tu décides » ou « je ne sais pas encore » : demandez au moins une phrase — le résumé du sujet est la seule partie spécifique au sujet dans AGENTS.md, et l'espace de travail a besoin d'une certaine ancre.
Étape 4 — Exécuter le script d'initialisation
Une fois que vous avez :
- Le chemin cible
- La confirmation que le répertoire est approprié
- Le résumé du sujet
...exécutez le script d'initialisation :
node /assets/skill-scripts/bootstrap.js --target --topic ""
Le script va :
- Vérifier la disponibilité de Node.js (ignorer les artefacts dépendant de Node et avertir si non disponible)
- Vérifier la disponibilité de git (ignorer
git initsi non disponible) - Créer la structure de répertoires
- Instancier tous les modèles depuis
<skill-dir>/assets/templates/avec{{TOPIC_SUMMARY}}et{{CREATED}}substitués - Copier les scripts livrés avec l'espace de travail (
format.js,validate.js,hash.js,reindex.js) vers<target>/scripts/ - Exécuter
npm install(si Node + npm sont disponibles) - Exécuter
git init(si git est disponible) - Afficher un résumé de ce qui a été créé
Si le script échoue (par exemple, permissions, outil manquant), revenez à la création manuelle des fichiers en utilisant les modèles dans <skill-dir>/assets/templates/. Copiez manuellement chaque modèle vers la cible, substituez les espaces réservés, et créez le répertoire scripts en copiant depuis <skill-dir>/assets/workspace-scripts/.
Étape 5 — Dire à l'utilisateur ce qui a été créé
Une fois le script terminé, résumez :
- Quels fichiers et répertoires ont été créés
- Si
git inita été exécuté (ou ignoré, avec un rappel) - Si
npm installa été exécuté (ou ignoré, avec un rappel) - Que
AGENTS.mdest désormais le document directeur de cet espace de travail - Que l'espace de travail est prêt à être utilisé
Puis demandez : « Souhaitez-vous commencer à travailler sur la documentation, ou voulez-vous d'abord examiner la structure ? »
Modèles
Tous les fichiers modèles se trouvent dans <skill-dir>/assets/templates/. Le script d'initialisation les copie et les substitue.
| Modèle | Produit |
|---|---|
AGENTS.md.template | AGENTS.md |
README.md.template | README.md |
index.yaml.template | index.yaml |
_gitignore_.template | .gitignore (nom avec soulignements devient préfixé par un point) |
package.json.template | package.json |
_prettierrc_.template | .prettierrc |
_markdownlint.json_.template | .markdownlint.json |
Espaces réservés utilisés :
{{TOPIC_SUMMARY}}— remplacé par la description du sujet de l'utilisateur{{CREATED}}— remplacé par la date d'aujourd'hui (AAAA-MM-JJ)
Le script d'initialisation gère automatiquement la convention des noms avec soulignements (un fichier nommé _foo_.template devient .foo dans la sortie).
Scripts livrés avec l'espace de travail
Après l'initialisation, l'espace de travail contient ces scripts utilitaires dans scripts/ :
| Script | Objectif |
|---|---|
scripts/format.js | Exécute Prettier sur tous les fichiers .md/.html/.json/.yaml |
scripts/validate.js | Exécute markdownlint sur tous les fichiers .md |
scripts/hash.js | Calcule le hachage SHA-256 d'un fichier, l'écrit éventuellement dans assets/ et met à jour le manifeste |
scripts/reindex.js | Regénère la section d'auto-index dans README.md |
Tous sont invocables via npm :
npm run formatnpm run validatenpm run hashnpm run reindex
Références
Pour un contexte plus approfondi sur des sujets spécifiques, consultez le répertoire references/ :
references/asset-management.md— Comment ajouter, lier et migrer des ressources (stockage par adresse de contenu, manifeste, par document vs partagé)references/document-promotion.md— Comment promouvoir un document fichier unique en dossier lorsqu'il gagne des sous-documents
Ceux-ci sont chargés dans le contexte uniquement lorsque cela est pertinent. Le AGENTS.md principal couvre les cas courants ; les références sont pour les cas moins courants.
Rappels pour l'agent (pendant l'initialisation)
- Le résumé du sujet est le seul contenu spécifique au sujet fourni par l'utilisateur. Tout le reste est basé sur des modèles. Ne demandez pas la dénomination des fichiers, les styles de liens, les champs de métadonnées, le style des messages de commit, ou toute autre règle — ils sont intégrés dans les modèles.
- Si l'utilisateur demande quelque chose que les modèles ne prennent pas en charge, signalez-le. N'inventez pas de nouvelles conventions silencieusement. La bonne action est soit (a) noter cela pour une future révision du modèle, soit (b) l'implémenter comme une exception avec confirmation explicite.
- Après l'initialisation, cette compétence est terminée. La prochaine fois que l'utilisateur voudra faire quoi que ce soit dans l'espace de travail, l'agent lira
AGENTS.mdet le suivra. Cette compétence ne s'exécute plus à moins que l'utilisateur ne demande explicitement d'initialiser un autre espace de travail ou de réinitialiser celui existant.