Guide de création de skills

Ce guide vous aide à créer des skills efficaces pour Apollo GraphQL et le développement GraphQL en suivant la spécification Agent Skills.

Qu'est-ce qu'un skill ?

Un skill est un répertoire contenant des instructions qui étendent les capacités d'un agent IA avec des connaissances spécialisées, des workflows ou des intégrations d'outils. Les skills s'activent automatiquement quand les agents détectent des tâches pertinentes.

Structure du répertoire

Un skill requiert au minimum un fichier SKILL.md :

skill-name/
├── SKILL.md              # Requis - instructions principales
├── references/           # Optionnel - documentation détaillée
│   ├── topic-a.md
│   └── topic-b.md
├── scripts/              # Optionnel - assistants exécutables
│   └── validate.sh
├── templates/            # Optionnel - modèles de config/code
│   └── config.yaml
└── assets/               # Optionnel - ressources statiques (images, schémas, fichiers de données)

Format SKILL.md

Frontmatter (requis)

---
name: skill-name
description: >
  Une description claire de ce que ce skill fait et quand l'utiliser.
  Incluez les conditions d'activation : (1) première condition, (2) deuxième condition.
license: MIT
compatibility: Fonctionne avec Claude Code et les assistants de codage IA similaires.
metadata:
  author: your-org
  version: "1.0.0"
allowed-tools: Read Write Edit Glob Grep
---

Champs du frontmatter

Règles de dénomination

• Utilisez uniquement des lettres minuscules, des chiffres et des tirets
• Ne commencez ni ne finissez par un tiret
• N'utilisez pas de tirets consécutifs (--)
• Doit correspondre au nom du répertoire parent

Bon : apollo-client, graphql-schema, rover Mauvais : Apollo-Client, -apollo, apollo--client

Bonnes pratiques pour la description

Rédigez des descriptions qui aident les agents à identifier quand activer le skill :

# Bon - déclencheurs et cas d'usage spécifiques
description: >
  Guide pour concevoir des schémas GraphQL en suivant les bonnes pratiques du secteur. Utilisez ce skill quand :
  (1) vous concevez un nouveau schéma ou une nouvelle API GraphQL,
  (2) vous examinez un schéma existant pour des améliorations,
  (3) vous décidez des structures de type ou de la nullabilité,
  (4) vous implémentez la pagination ou les modèles d'erreur.

# Mauvais - vague et peu utile
description: Aide avec les choses GraphQL.

Contenu du corps

Le corps markdown contient les instructions que suit l'agent. Structurez-le pour la clarté :

Sections recommandées

1. Overview - Brève explication du but du skill
2. Process - Workflow étape par étape (utilisez des cases à cocher pour les processus multi-étapes)
3. Quick Reference - Modèles et syntaxe courants
4. Security - Risques, atténuations et validation (si le skill touche à quelque chose de sensible sur le plan sécuritaire)
5. Reference Files - Liens vers la documentation détaillée
6. Key Rules - Directives importantes organisées par sujet
7. Ground Rules - Les à-faire et à-ne-pas-faire critiques

Exemple de structure

# Skill Title

Brève explication de ce que ce skill aide à faire.

## Process

Suivez ce processus quand vous travaillez sur [tâche] :

- [ ] Étape 1 : Rechercher et comprendre les exigences
- [ ] Étape 2 : Implémenter la solution
- [ ] Étape 3 : Valider le résultat

## Quick Reference

### Common Pattern

\`\`\`graphql
type Example {
  id: ID!
  name: String
}
\`\`\`

## Security

> **Risk: [brève description de ce qui peut mal tourner].**
> [Ce que l'utilisateur DOIT faire pour l'éviter.]

- ALWAYS [comportement par défaut sécurisé]
- NEVER [configuration dangereuse] en production

## Reference Files

- [Topic A](references/topic-a.md) - Guide détaillé pour le sujet A
- [Topic B](references/topic-b.md) - Guide détaillé pour le sujet B

## Key Rules

### Category One

- Règle concernant cette catégorie
- Autre règle

### Category Two

- Règle concernant cette catégorie

## Ground Rules

- ALWAYS faire cette chose importante
- NEVER faire cette chose problématique
- PREFER cette approche plutôt que celle-là

Contenu sensible sur le plan sécuritaire

Quand un skill génère une configuration, du code ou des recommandations qui pourraient causer des problèmes de sécurité s'ils sont mal utilisés, le skill DOIT rendre ces risques explicites et visibles au LLM. Un LLM ne peut pas déduire les implications sécuritaires du contexte seul — il a besoin de signaux clairement étiquetés.

Quand un skill a-t-il besoin de conseils sécuritaires ?

Si l'une de ces conditions s'applique, le skill est sensible sur le plan sécuritaire :

• Génère une config qui contrôle l'accès aux données (mise en cache, auth, CORS, permissions)
• Gère des secrets, des identifiants ou des tokens
• Produit du code qui s'exécute avec des privilèges élevés
• Contrôle quelles données sont partagées, publiques ou exposées aux utilisateurs
• Configure les liaisons réseau, les endpoints ou l'accès externe

Comment présenter la sécurité dans un skill

1. Section Security dédiée dans SKILL.md ou un fichier de référence, intitulée ## Security. Pas « Private data » ou « Customization » — utilisez le mot « Security » pour que le LLM reconnaisse la catégorie.

2. Avertissements explicites au point de risque — placez les conseils de sécurité à côté de la configuration ou du code qui crée le risque, pas dans un fichier séparé que le LLM ne chargerait peut-être pas :

   ### Response caching scope
   
   > **Security: risque de fuite de données.** Toutes les données mises en cache sont PUBLIC par défaut.
   > Les champs spécifiques à l'utilisateur DOIVENT utiliser `scope: PRIVATE` avec un `private_id`
   > configuré, ou ils seront partagés entre tous les utilisateurs.

3. Éléments de liste de contrôle de validation — chaque feature sensible en sécurité doit avoir des vérifications correspondantes dans la liste de contrôle de validation. Groupez-les sous un en-tête ## Security.

4. Ground rules — ajoutez des règles ALWAYS/NEVER pour le comportement critique en sécurité. Ce sont les signaux les plus forts pour le LLM.

5. Exiger le modèle de données — si la configuration de sécurité correcte dépend de la compréhension du modèle de données de l'utilisateur (ex: quels champs sont spécifiques à l'utilisateur), le skill doit instruire le LLM de demander à l'utilisateur avant de générer la config. Ne laissez pas le LLM deviner.

Anti-modèles

• Décrire une valeur par défaut sensible en sécurité (comme « public par défaut ») sans l'étiqueter comme un problème de sécurité
• Placer les conseils de sécurité uniquement dans des fichiers de référence qui se chargent à la demande — le SKILL.md lui-même doit contenir les avertissements clés
• Utiliser un langage doux (« vous pourriez envisager ») pour les exigences de sécurité strictes — utilisez « MUST » et « NEVER »
• Supposer que le LLM comprend quels champs d'un schéma sont privés — exigez une entrée utilisateur explicite

Divulgation progressive

Structurez les skills pour minimiser l'utilisation du contexte :

1. Métadonnées (~100 tokens) : name et description se chargent au démarrage pour tous les skills
2. Instructions (< 5000 tokens) : Le SKILL.md complet se charge quand le skill s'active
3. References (au besoin) : Les fichiers dans references/ se chargent uniquement quand nécessaire

Gardez SKILL.md sous 500 lignes. Déplacez la documentation détaillée vers les fichiers de référence.

Fichiers de référence

Utilisez references/ pour la documentation détaillée :

references/
├── setup.md          # Installation et configuration
├── patterns.md       # Modèles et exemples courants
├── troubleshooting.md # Solutions d'erreur
└── api.md            # Référence API

Les fichiers de référence doivent être :

• Focalisés sur un seul sujet
• Autonomes (lisibles sans autres fichiers)
• Moins de 300 lignes chacun

Liez aux références depuis SKILL.md :

## Reference Files

- [Setup](references/setup.md) - Installation et configuration
- [Patterns](references/patterns.md) - Modèles et exemples courants

Scripts

Utilisez scripts/ pour les assistants exécutables que les agents peuvent exécuter :

scripts/
├── validate.sh       # Commandes de validation
├── setup.py          # Automatisation de configuration
└── check-version.sh  # Vérification de version

Les scripts doivent être autonomes, inclure la gestion des erreurs et avoir un commentaire d'utilisation en haut. Pré-approuvez-les dans allowed-tools (ex: Bash(./scripts/validate.sh:*)).

Templates

Utilisez templates/ pour les fichiers de configuration, le code du modèle ou le code de démarrage :

templates/
├── config.yaml       # Configuration par défaut
├── config-v2.yaml    # Variante spécifique à la version
└── example-app/      # Projet de démarrage

Les templates sont copiés ou adaptés par l'agent — pas exécutés directement.

Style d'écriture

Suivez Apollo Voice pour tout le contenu du skill :

Ton

• Accessible et utile
• Opiniâtre et faisant autorité (prescrire le « happy path »)
• Direct et orienté vers l'action

Langage

• Utilisez l'anglais américain
• Gardez le langage simple ; évitez les idiomes
• Utilisez le présent et la voix active
• Utilisez des verbes à l'impératif pour les instructions

Formatage

• Utilisez la casse de phrase pour les en-têtes
• Utilisez la police de code pour les symboles, commandes, chemins de fichiers et URLs
• Utilisez le gras pour les éléments d'interface que les utilisateurs cliquent
• Utilisez des tirets (-) pour les listes non ordonnées

À éviter

• « Simply », « just », « easy » (peut être condescendant)
• Des expressions vagues comme « cliquez ici »
• Les points-virgules (utilisez des points à la place)
• « We » sauf si cela se réfère clairement à Apollo

Fichiers de référence

Pour des conseils spécifiques à Apollo GraphQL :

• Apollo Skills - Modèles et exemples pour les skills Apollo GraphQL

Versioning

Utilisez la versioning sémantique ("X.Y.Z") pour le champ version dans les métadonnées :

metadata:
  author: apollographql
  version: "1.0.0"

• Major (X) : Changements breaking qui altèrent comment le skill se comporte ou s'active (ex: déclencheurs renommés, sections supprimées, ground rules modifiées)
• Minor (Y) : Nouveau contenu ou capacités rétro-compatibles (ex: fichiers de référence ajoutés, nouvelles sections, exemples étendus)
• Patch (Z) : Petits correctifs qui ne changent pas le comportement (ex: corrections de typo, ajustements de formulation, correctifs de formatage)

Commencez les nouveaux skills à "1.0.0".

Liste de contrôle pour les nouveaux skills

Avant de publier un skill, vérifiez :

• [ ] name correspond au nom du répertoire et suit les règles de dénomination
• [ ] description énonce clairement ce que le skill fait et quand l'utiliser
• [ ] SKILL.md fait moins de 500 lignes
• [ ] Les fichiers de référence sont focalisés et font moins de 300 lignes chacun
• [ ] Les instructions sont claires et actionables
• [ ] Les exemples de code sont corrects et testés
• [ ] Les ground rules utilisent le format ALWAYS/NEVER/PREFER
• [ ] Le contenu suit les directives Apollo Voice

Ground Rules

• ALWAYS inclure les conditions de déclenchement dans la description (utilisez une liste numérotée)
• ALWAYS utiliser des cases à cocher pour les processus multi-étapes
• ALWAYS lier vers les fichiers de référence pour la documentation détaillée
• NEVER dépasser 500 lignes dans SKILL.md
• NEVER utiliser des descriptions vagues qui n'aident pas les agents à identifier quand s'activer
• PREFER les exemples spécifiques plutôt que les explications abstraites
• PREFER les conseils d'opinion plutôt que l'énumération de plusieurs options
• USE allowed-tools pour pré-approuver les outils que le skill a besoin
• NEVER inclure Bash(curl:*) dans allowed-tools car il donne un accès réseau sans restriction et active les modèles curl | sh d'exécution de code à distance
• ALWAYS inclure une section ## Security quand le skill génère une config ou du code qui contrôle l'accès, la mise en cache, auth, secrets ou exposition de données
• NEVER enterrer les conseils critiques en sécurité uniquement dans les fichiers de référence — les avertissements clés doivent apparaître dans SKILL.md où le LLM les verra toujours
• ALWAYS instruire le LLM de demander à l'utilisateur son modèle de données avant de générer une config sensible en sécurité (ex: quels champs sont spécifiques à l'utilisateur, quelles données sont publiques)
• USE des avertissements en bloc de citation explicites (> **Security: ....**) à côté de la config ou du code qui crée des risques de sécurité
• ALWAYS ajouter des éléments de liste de contrôle de validation pour chaque feature sensible en sécurité, groupés sous un en-tête ## Security