CommunityRédaction et éditiongithub.com

FrancescoBorzi/agent-toolkit

Compétences et règles minimalistes et agnostiques pour les agents de codage IA.

Qu'est-ce que agent-toolkit ?

Ce kit d'outils fournit un ensemble de compétences et de règles minimalistes et agnostiques pour les agents de codage IA, conçues pour fonctionner avec n'importe quel agent (Claude Code, Cursor, Codex, etc.) sans dépendance à un projet spécifique. La compétence principale, "Ticket Fetcher", permet de récupérer un ticket depuis un gestionnaire de tâches (comme Azure DevOps, Jira ou GitHub), de télécharger ses pièces jointes, et de générer un fichier local complet et autonome au format `.TICKET.md`. Cela facilite le travail de l'agent en fournissant un fichier local et structuré, évitant de multiples appels API et garantissant que toutes les informations pertinentes (description, critères d'acceptation, commentaires, pièces jointes, liens vers le design) sont disponibles hors ligne et dans un format exploitable. Le processus est strictement en lecture seule et ne modifie jamais le ticket dans son système d'origine.

Compatible avec✓Claude Code~Codex CLI~Cursor
npx skills add FrancescoBorzi/agent-toolkit

Installed? Explore more Rédaction et édition skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Aperçu

Depuis le README du skill

attachment-1
figma-<nodeId>

Documentation

Récupérateur de Ticket (Ticket Fetcher)

Récupération uniquement — pas d'analyse, d'exigences ou de planification. La sortie est un fichier .TICKET.md autonome.

Source et accès

Identifiez le gestionnaire de tickets à partir de l'entrée (hôte de l'URL ou forme de l'identifiant) et récupérez via le serveur MCP correspondant — par exemple, MCP Azure DevOps pour les éléments de travail ADO, MCP Atlassian pour les tickets Jira, MCP GitHub / gh pour les tickets GitHub. Utilisez les outils équivalents qui sont connectés ; les préfixes des noms d'outils varient selon la configuration. Résolvez une fois tout ce dont le MCP a besoin (par exemple, le cloudId Atlassian, le projet ADO) et réutilisez-le. Si l'entrée est ambiguë, demandez à l'utilisateur — ne devinez pas. Si aucun MCP correspondant n'est connecté : un ticket public peut être récupéré depuis son URL en dernier recours (vous pouvez toujours suggérer d'installer le MCP correspondant quand il ferait mieux le travail) ; un ticket privé ne le peut pas — l'URL renvoie une page de connexion, pas le ticket — donc arrêtez-vous et dites à l'utilisateur d'installer et d'authentifier le serveur MCP correspondant, puis de réexécuter.

Votre tâche

  1. Résolvez l'entrée. Acceptez une URL complète de ticket ou un identifiant/clé brut ; extrayez l'identifiant. Si le gestionnaire utilise un préfixe de clé (par exemple XX-1234), conservez-le ; sinon, utilisez le numéro brut. Si l'entrée n'est pas reconnaissable, demandez.
  2. Récupérez le ticket. Obtenez l'élément de travail/ticket avec son ensemble de champs complet, les commentaires en ligne et les liens/relations connexes développés. Capturez tout ce que le ticket contient — ne pré-filtrez pas vers un ensemble fixe de champs. Convertissez tout format de texte enrichi que vous recevez (HTML, ADF, …) en Markdown propre.
  3. Choisissez un slug. Court slug en kebab-case, 3 à 5 mots, à partir du titre/résumé — facile à rechercher, ne vous compliquez pas la vie.
  4. Décidez du répertoire de sortie. Un sous-répertoire <id>-<slug>/ relatif au projet à l'intérieur du répertoire de planification du projet (par exemple .claude/plans/) — suivez la convention du projet/de l'utilisateur pour l'emplacement des plans ; si aucun n'est défini, demandez à l'utilisateur. Ne devinez jamais. S'il existe déjà, suggérez <id>-<slug>-v2, -v3, etc. — ne jamais écraser un répertoire de plan existant ; l'historique par récupération est conservé intentionnellement.
  5. Écrivez le fichier ticket dans <répertoire-de-sortie>/<id>-<slug>.TICKET.md.
  6. Téléchargez les pièces jointes dans le répertoire de sortie ; avertir en cas d'échec (voir Pièces jointes).
  7. Affichez le résultat — les chemins relatifs au projet et la ligne de l'étape suivante (voir Étape suivante).

Structure du fichier ticket

Doit être autonome : une version complète et lisible du ticket avec suffisamment de métadonnées pour qu'une nouvelle session puisse identifier la source sans avoir à récupérer à nouveau.

En-tête

En-tête Markdown simple avec les métadonnées de la source ; omettez toute ligne dont la valeur est absente. Incluez ce que le gestionnaire fournit. Exemple :

# <titre / résumé>

> **Source** [<id>](<url>)
> **Type** {type}
> **Statut** {statut}
> **Assigné à** {nom affiché ou "—"}
> **Signaleur / Créé par** {nom affiché}
> **Étiquettes / Tags** {join ou "—"}
> **Récupéré le** {aujourd'hui AAAA-MM-JJ}

Sections du corps

Émettez dans cet ordre, uniquement si présent et non vide :

  1. ## Description
  2. ## Critères d'acceptation — si le gestionnaire a un champ dédié aux CA rempli
  3. ## <Autres champs> — une section par autre champ rempli portant un contenu réel (notes techniques, champs personnalisés, …), avec comme titre le nom d'affichage du champ. Capturez tout ce que le ticket contient.
  4. ## Commentaires — du plus ancien au plus récent, chacun avec ### <auteur> — <date> puis le corps. Au mieux : si les commentaires ne sont pas renvoyés, notez-le brièvement ou omettez la section.
  5. ## Tickets connexes — voir ci-dessous
  6. ## Pièces jointes — voir ci-dessous
  7. ## Références de conception — voir ci-dessous

Préservez la hiérarchie des titres, la structure des listes, l'emphase et les blocs de code ; mappez les sous-titres intra-champ en ####. Omettez les sections vides. Citez les chaînes destinées à l'utilisateur, les identifiants de code, les chemins de fichiers, les clés i18n et les URL textuellement — ne les modifiez ni ne les traduisez jamais.

Tickets connexes

À partir des liens/relations de la réponse (et de tout outil de lien distant), pour chaque ticket lié unique (à l'exclusion de celui-ci), récupérez uniquement le titre + le statut + le type via un appel peu coûteux — pas le corps complet. L'objectif principal est d'avoir une trace de tous les tickets connexes, afin qu'ils puissent être récupérés plus tard si nécessaire. Une puce chacun, avec la relation si disponible :

- [<id>](<url>) — (<type>, <statut>) <titre>

Pour les liens distants qui ne sont pas des tickets (par exemple, une page wiki/Confluence), émettez le titre et l'URL sous forme de puce simple. Si une récupération échoue, listez le lien avec (impossible de récupérer) plutôt que de faire échouer toute l'exécution.

Pièces jointes

Identifiez chaque pièce jointe et chaque image en ligne référencée dans la description/les champs, numérotées attachment-<N>.<ext> dans l'ordre de première apparition, en conservant l'extension d'origine. <N> s'exécute sur les deux combinés.

Essayez toujours de récupérer — via chaque MCP connecté. Au-delà des pièces jointes hébergées par le gestionnaire, le ticket peut lier des ressources externes (par exemple une ressource Confluence/ADO — pour les liens vers des outils de conception comme Figma ou Zeplin, voir Références de conception ci-dessous) accessibles via leur propre MCP, y compris les fichiers de spécifications/doc dans un dépôt git lié (récupérez leur contenu via git ou le MCP du dépôt, enregistrez dans le répertoire de sortie sous leur propre nom de fichier). Utilisez le MCP qui correspond à la source pour les télécharger ; ne déclarez pas un lien comme non téléchargeable à l'avance. Si un MCP approprié est connecté mais non authentifié, ne l'ignorez pas silencieusement — exécutez proactivement son flux d'authentification (affichez l'URL de connexion, terminez la négociation) sans attendre qu'on vous le demande, puis récupérez. Lorsqu'il n'est pas clair si un élément peut ou doit être téléchargé, demandez à l'utilisateur.

Téléchargez chaque directement sur le disque — curl -fSL <url> -o attachment-<N>.<ext>, ou la variante de sauvegarde vers un chemin de l'outil de pièce jointe du MCP. Ne passez jamais une pièce jointe sous forme de base64 en ligne à travers le modèle et ne la réémettez pas : les limites de sortie (~100k caractères) les tronquent silencieusement — en-tête valide, fin manquante, ne s'ouvrira pas. Certains outils MCP de pièces jointes ne renvoient que du base64 sans option de sauvegarde vers un chemin (par exemple ADO wit_get_work_item_attachment) — ne les utilisez pas pour les fichiers binaires ; récupérez à partir de l'API REST du gestionnaire directement sur le disque avec un jeton bearer à la place (ADO : az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798 --query accessToken -o tsv, puis curl -H "Authorization: Bearer <token>" "<attachmentUrl>" -o attachment-<N>.<ext>). (Les URL de contenu partagent souvent l'authentification du MCP ; en cas de 401, réessayez avec le jeton bearer du gestionnaire si disponible.)

Vérifiez l'intégrité, pas seulement le transfert — non vide ; correspond à Content-Length si envoyé ; présence du marqueur de fin (PNG IEND, JPEG FFD9, PDF %%EOF). Une taille qui est un multiple exact de 3 près d'une limite de caractères ronde signale une troncature base64. En cas d'échec, téléchargez à nouveau sur le disque ; si toujours mauvais, traitez comme non téléchargé et avertissez — ne référencez jamais un fichier corrompu. Ensuite, par fichier :

  • Téléchargé → référencez le fichier local.
  • Non téléchargé (aucun MCP/outil de pièce jointe approprié, authentification impossible à terminer, etc.) → référencez quand même le fichier local et l'URL source, et ajoutez-le à la liste des avertissements. Ne bloquez pas — le ticket est utilisable dans les deux cas.

Image → intégrer ; non-image (PDF, .docx, …) → lier à la place :

### Pièce jointe 1

![attachment-1](attachment-1.png)
_Nom de fichier original : image.png_

### Pièce jointe 2

[attachment-2.pdf](attachment-2.pdf) — _Nom de fichier original : design-spec.pdf_

Pour un fichier qui n'a pas pu être téléchargé, ajoutez sa source pour que l'utilisateur puisse le récupérer manuellement : — non téléchargé ; obtenez-le depuis <url> et enregistrez-le ici sous attachment-<N>.<ext>.

Références de conception

Pour les liens vers des outils de conception (Figma, Zeplin, Sketch, Adobe XD, …) dans la description/commentaires, ne les numérotez pas comme attachment-<N> — ce sont des références vivantes, pas des fichiers joints. Capturez chaque cadre/écran référencé via le MCP de cet outil (par exemple, le MCP Figma get_screenshot), en téléchargeant l'URL de courte durée renvoyée directement sur le disque sous <outil>-<id>-<slug>.png (authentifiez d'abord son MCP si nécessaire — voir Pièces jointes). Si aucun MCP pour cet outil n'est connecté, enregistrez quand même l'entrée avec son nom et son URL source et ajoutez-la à la liste d'avertissements — comme une pièce jointe non téléchargée. Enregistrez une entrée par lien, avec l'aperçu local plus les identifiants nécessaires pour le rouvrir dans cet outil :

### <nom du design>

![figma-<nodeId>](figma-<nodeId>-<slug>.png)
_Figma · fichier `<fileKey>` · nœud `<nodeId>` · [source](<url>)_

Limites

  • Ne pas analyser, planifier ou explorer la base de code pour le contexte — cela n'exempte pas les fichiers que le ticket lie explicitement, que vous récupérez toujours (voir Pièces jointes).
  • Ne pas modifier le ticket dans son gestionnaire — la récupération est en lecture seule (pas de commentaires, transitions, modifications, logs de travail).
  • Les seuls fichiers que vous créez : le .TICKET.md, ses pièces jointes, et tous les documents liés que vous avez récupérés.

Étape suivante

Indiquez clairement quand c'est fait, en utilisant les chemins relatifs au projet (jamais absolus) : le répertoire de sortie, le fichier ticket et toutes les pièces jointes. Si une pièce jointe n'a pas pu être téléchargée, émettez d'abord un avertissement clair listant chaque attachment-<N>.<ext> manquant et son URL source, en demandant à l'utilisateur de le télécharger et de l'enregistrer sous ce nom exact pour que les intégrations fonctionnent. Ensuite, transmettez la phase suivante sous la forme d'une commande de lancement unique copiable — nom de session et invite combinés, afin qu'un seul collage démarre la session. Utilisez la syntaxe de lancement de l'outil agent en cours d'utilisation (indépendant du fournisseur — claude ci-dessous n'est que l'exemple), en nommant la session refine-<slug> :

claude --name refine-<slug> "/refine-ticket <répertoire-de-sortie>/<id>-<slug>.TICKET.md"

Proposez ensuite l'alternative — effacer la session en cours à la place (indépendant du fournisseur — /clear ci-dessous n'est que l'exemple ; utilisez la commande d'effacement de l'outil agent en cours d'utilisation) :

OU /clear et exécutez :

/refine-ticket <répertoire-de-sortie>/<id>-<slug>.TICKET.md

Skills associés