lggarrison/agent-skills

Configuration du dépôt

Un nouveau dépôt a besoin de la même base à chaque fois : une licence, un moyen de signaler des problèmes de sécurité, un README, des templates qui rendent les PR et les issues utiles, et une CI qui exécute les mêmes vérifications qu'un contributeur fait localement. Cette compétence est une checklist pour cette base et une façon de la parcourir.

Les règles du dépôt d'abord

Lisez ce que le dépôt a déjà avant d'ajouter quoi que ce soit : AGENTS.md / CLAUDE.md, CONTRIBUTING.md, les fichiers .github/ existants, le manifeste du paquet et ses scripts, et toute configuration CI. Là où ils définissent une convention (branche par défaut, licence, outils, emplacements de fichiers), suivez-la. Ne remplacez jamais un fichier existant pour qu'il corresponde à un template ici. Étendez-le, ou laissez-le et mentionnez l'écart.

Flux de travail

1. Définir la demande

• Bootstrap : un dépôt nouveau ou presque vide. Parcourez toute la checklist.
• Combler les lacunes : un dépôt existant manque de certains éléments. Ajoutez uniquement ce qui manque.
• Audit : signalez ce qui manque ou est faible, et ne modifiez rien.

2. Faire l'inventaire

Listez les fichiers de la checklist qui existent, et lisez le manifeste (package.json, pyproject.toml, go.mod, Cargo.toml, etc.) pour le langage, les scripts, et si le projet est publié. Trouvez la branche par défaut avec git remote show origin ou gh repo view --json defaultBranchRef. Ne demandez rien à l'utilisateur que vous pouvez apprendre de cette façon.

3. Demander les décisions importantes

Ce sont les décisions de l'utilisateur. Demandez une fois, en un court tour, et recommandez lorsque les preuves le soutiennent :

• Licence, et le nom du titulaire des droits d'auteur.
• Contact sécurité : signalement de vulnérabilité privé GitHub, une adresse e-mail, ou les deux.
• Contact du code de conduite, si vous en ajoutez un.
• Branche de base des PR, si ce n'est pas la branche par défaut.
• Publié ou non : vers un registre de paquets, ou comme artefact de version.
• Matrice CI : quels systèmes d'exploitation et versions d'exécution prendre en charge.

4. Écrire les fichiers

Parcourez la checklist de haut en bas, et sautez les sections qui ne s'appliquent pas.

• Récupérez le texte canonique ; ne le rappelez pas. Obtenez le texte de la licence avec gh api licenses/<spdx-id> --jq .body (par exemple mit ou apache-2.0), puis remplissez l'année et le titulaire. Obtenez un code de conduite à partir de sa source officielle, comme le Contributor Covenant.
• Adaptez les templates. Partez de templates/. Remplacez chaque <placeholder>, et changez les commandes pour celles qui existent dans ce dépôt. Un template qui liste un script que le dépôt n'a pas est pire qu'aucun template.
• Une seule liste de vérifications. La checklist du template de PR, CONTRIBUTING.md, le hook pre-commit, et la CI doivent tous nommer les mêmes commandes. Quand l'une change, changez les autres.
• Demandez avant de modifier les paramètres. La protection de branche, les rulesets, et le signalement privé de vulnérabilité sont des paramètres du dépôt, pas des fichiers. Proposez-les et appliquez-les uniquement lorsque l'utilisateur est d'accord.

5. Vérifier

• Chaque commande nommée dans un template, un hook ou un job CI s'exécute localement et réussit.
• Aucun <placeholder> n'est laissé dans aucun fichier.
• Les formulaires d'issue et les workflows sont du YAML valide. Les formulaires d'issue n'apparaissent que sur la branche par défaut, vérifiez-les donc là après le merge.
• Les liens fonctionnent, y compris l'URL de la politique de sécurité.
• Les propres vérifications de format et de lint du dépôt passent sur les nouveaux fichiers.

6. Rapporter

Dites ce que vous avez ajouté, ce que vous avez laissé intact et pourquoi, les paramètres de dépôt que vous avez proposés, et les décisions importantes encore en suspens.

Checklist

R est requis, rec est recommandé, et opt est optionnel.

Outils

• R git, et l'exécution du langage et le gestionnaire de paquets.
• rec Un gestionnaire de versions d'exécution (nvm, fnm, pyenv, etc.) correspondant au fichier de version épinglée.
• rec gh, authentifié avec gh auth login, pour les mainteneurs.

Légal et communauté

• R LICENSE.
• R SECURITY.md : versions prises en charge, comment signaler en privé, et à quoi les rapporteurs peuvent s'attendre après le signalement.
• rec CONTRIBUTING.md : configuration, les vérifications à exécuter, les conventions de branche et de commit, et comment les PR sont examinées.
• rec CODE_OF_CONDUCT.md, avec un vrai contact d'application.
• rec CHANGELOG.md au format Keep a Changelog.

Documentation

• R README.md : ce que c'est, comment l'installer, un exemple d'utilisation minimal, et des liens vers CONTRIBUTING.md, SECURITY.md, et la licence.
• opt AGENTS.md : le point d'entrée neutre pour les agents de codage. Donnez les commandes à exécuter et les règles à suivre, et créez des liens vers d'autres documents plutôt que de les répéter.
• opt RELEASING.md, pour les projets publiés. Voir Publication.

Hygiène de l'éditeur et de Git

• R .gitignore pour le langage, la sortie de build, et les fichiers d'environnement local.
• rec .gitattributes avec * text=auto eol=lf, pour éviter les changements de sauts de ligne entre les systèmes d'exploitation.
• rec .editorconfig pour le jeu de caractères, la nouvelle ligne finale, et l'indentation.

Templates et automatisation GitHub

Si le dépôt n'est pas sur GitHub, utilisez les équivalents de l'hôte.

• rec .github/PULL_REQUEST_TEMPLATE.md. Voir Templates.
• rec Formulaires d'issue dans .github/ISSUE_TEMPLATE/ : bug_report.yml, feature_request.yml, et un config.yml qui désactive les issues vides et redirige les rapports de sécurité vers le canal privé. Voir Templates.
• rec .github/dependabot.yml, avec une entrée pour chaque écosystème de paquets que le dépôt utilise, plus github-actions.
• R .github/workflows/ci.yml, exécutant les mêmes vérifications que le template de PR sur chaque PR et chaque push vers la branche par défaut.
• opt .github/release.yml, pour regrouper les notes de version générées par étiquette.
• opt .github/workflows/release.yml, pour les projets publiés uniquement.
• rec Protection de branche ou un ruleset sur la branche par défaut qui exige la CI. C'est un paramètre, demandez d'abord.

Node.js et TypeScript

Sautez cette section pour les autres langages, et appliquez les mêmes idées avec les outils de cet écosystème : une version d'exécution épinglée, un formateur, un linter, un exécuteur de tests, une seule commande "tout vérifier", et une matrice CI.

Exécution et métadonnées

• rec .nvmrc, et engines.node dans package.json, en accord l'un avec l'autre.
• R package.json repository, homepage, bugs, license, et author.
• rec "type": "module" pour l'ESM natif.

TypeScript (projets TypeScript uniquement)

• R typescript et un tsconfig.json, avec un npm run build qui compile.
• Ne convertissez pas un projet JavaScript en TypeScript. Pour un nouveau projet, l'utilisation de TypeScript est la décision de l'utilisateur.

Format et lint

• rec Prettier (.prettierrc.json, .prettierignore) et une configuration plate ESLint.
• rec Scripts lint, lint:fix, format, et format:check.

Tests unitaires

• R Un npm test qui exécute les tests unitaires.
• rec Vitest, avec les tests à côté du code (src/**/*.test.ts) et des fixtures partagées dans test/.

Tests de bout en bout (opt, pour les projets avec une UI ou des flux navigateur)

• rec @playwright/test, un playwright.config.ts, et des tests dans e2e/.
• rec Un script npm run test:e2e.
• rec playwright-report/, test-results/, et blob-report/ dans .gitignore.
• rec Un job CI qui installe les navigateurs avec npx playwright install --with-deps et télécharge le rapport en cas d'échec d'un test.
• opt Pour un CLI sans navigateur, exécutez les tests de bout en bout via une configuration Vitest séparée à la place.

Hooks Git (développement local uniquement)

• rec Husky avec un hook pre-commit qui exécute lint-staged.
• rec Un script prepare qui saute l'installation de Husky quand CI est défini ou NODE_ENV=production, afin que les installations en CI et en production ne plantent pas.
• opt Un hook pre-push qui exécute les tests unitaires.

Passage qualité

• rec Un script, comme check, qui exécute lint, format:check, les tests unitaires, le build, et les tests de bout en bout dans cet ordre. La CI et les contributeurs l'exécutent tous les deux.
• rec Une matrice CI sur les systèmes d'exploitation et versions de Node.js pris en charge.

Publication

Pour les projets publiés vers un registre de paquets. Ceux-ci sont optionnels pour tout le reste.

• rec Une liste d'autorisation "files" dans package.json (ou .npmignore), vérifiée avec npm pack --dry-run.
• rec Un script prepublishOnly qui exécute le build.
• rec Publication depuis la CI avec npm Trusted Publishing (OIDC, id-token: write), afin qu'aucun token de longue durée ne soit stocké comme secret.
• rec RELEASING.md couvrant comment les versions sont choisies (semver), comment une version est taguée, les vérifications qui bloquent un mauvais tag, et comment revenir en arrière.

Templates

Fichier	Copier vers
templates/PULL_REQUEST_TEMPLATE.md	.github/PULL_REQUEST_TEMPLATE.md
templates/ISSUE_TEMPLATE/bug_report.yml	.github/ISSUE_TEMPLATE/bug_report.yml
templates/ISSUE_TEMPLATE/feature_request.yml	.github/ISSUE_TEMPLATE/feature_request.yml
templates/ISSUE_TEMPLATE/config.yml	.github/ISSUE_TEMPLATE/config.yml

Les placeholders sont écrits <comme-ceci>. Par exemple, remplacez <runtime-version-command> par node --version, python --version, ou go version. Les autres commandes dans les templates sont des exemples d'un projet Node.js. Remplacez-les par celles du dépôt.