Skills

Les Skills sont le mécanisme principal pour regrouper et distribuer des connaissances métier aux agents IA dans CodeCourier. Chaque skill est une collection nommée de fichiers - documents markdown, exemples de code, références API, guides de bonnes pratiques - qui sont injectés dans le répertoire .claude/skills/ de la sandbox avant le démarrage de l’outil CLI. Lorsqu’un agent lit ces fichiers, il acquiert des connaissances de niveau expert sur une technologie ou un domaine de pratique spécifique.

Les Skills prennent en charge plusieurs fichiers, ce qui signifie qu’un seul skill peut contenir une base de connaissances complète et multi-documents plutôt qu’un unique fichier monolithique. Chaque skill est versionné indépendamment, ce qui vous permet de mettre à jour les connaissances métier sans toucher aux skills non liés.

Ce que sont les Skills

Considérez les skills comme la bibliothèque que vous remettez à un agent IA lorsqu’il s’installe pour travailler. Plutôt que d’espérer que les données d’entraînement de l’agent contiennent les bons patterns pour votre stack spécifique, vous fournissez des documents de référence sélectionnés, précis et à jour au démarrage de la session.

Exemples de skills et ce qu’ils contiennent :

Modèle de données des Skills

Les skills sont stockés dans trois tables liées dans la base de données :

// Core skill record
skills: {
  skillId: string       // unique identifier
  name: string          // display name (e.g., "frontend-design")
  description: string   // what this skill does and when to use it
  category: string      // grouping (e.g., "frontend", "testing", "backend", "security")
  fileCount: number     // number of files in the active version of this skill
  isEnabled: boolean    // whether this skill is selectable in the UI
}

// Individual files within a skill
skillFiles: {
  skillId: string
  path: string          // file path within the skill directory (e.g., "patterns.md")
  content: string       // full file content (markdown or code)
}

// Version history
skillVersions: {
  skillId: string
  version: number       // incrementing version number
  name: string          // name at time of publish
  description: string   // description at time of publish
  category: string      // category at time of publish
  fileCount: number     // number of files in this version
  status: "active" | "inactive"
  publishedAt: number   // Unix timestamp
  publishedBy: string   // user ID of publisher
}

Créer un skill personnalisé

Les skills personnalisés sont créés depuis la page de gestion des Skills. Accédez à la section skills de votre projet ou à la bibliothèque de skills globale depuis les paramètres de la plateforme.

# Convex Query Patterns

## Reading Data
Always use `useQuery` for reactive data subscriptions in React components.
Use `ctx.db.query` inside Convex server functions.

### Pagination
Never use `.collect()` on large tables. Use `.paginate()` instead:
```ts
const results = await ctx.db
  .query("posts")
  .order("desc")
  .paginate(opts); // opts.numItems controls page size
```

## Writing Data
All data mutations must go through Convex mutation functions.
Never write directly to the database from client code.

### Scheduling Background Work
Heavy operations go to `ctx.scheduler.runAfter` to avoid timeout:
```ts
await ctx.scheduler.runAfter(0, internal.tasks.processLargeDataset, {
  datasetId: args.datasetId,
});
```

## Validators
Use Convex's built-in validators for all mutation and action arguments.
Do NOT use Zod inside Convex functions.

Bonnes pratiques d’organisation des fichiers de skill

La façon dont vous organisez les fichiers au sein d’un skill affecte la facilité avec laquelle un agent peut naviguer dans les connaissances. Suivez ces recommandations :

• Un sujet par fichier - Un overview.md pour les concepts de haut niveau, un patterns.md pour les patterns de code, un anti-patterns.md pour les choses à éviter, et un api-reference.md pour les API spécifiques. Cela rend chaque fichier parcourable sans surcharger le contexte.
• Commencez par les règles les plus importantes - Les agents lisent les fichiers de manière séquentielle. Placez les contraintes les plus critiques en haut de chaque fichier, et non enfouies au milieu.
• Utilisez des exemples de code concrets - Les explications en markdown sont utiles, mais les extraits de code montrant un usage correct et incorrect sont encore plus efficaces.
• Gardez les fichiers individuels sous 500 lignes - Les fichiers très longs sont plus difficiles à traiter efficacement pour les agents. Divisez les grands documents de référence en plusieurs fichiers ciblés.
• Nommez les fichiers pour la découvrabilité - Utilisez des noms comme quick-reference.md, gotchas.md, examples.md afin que l’agent puisse déduire l’objectif du fichier à partir de son seul nom.

Versionner les Skills

Les skills suivent le même cycle de vie de versionnement que les Context Documents. Modifier les fichiers d’un skill crée un brouillon. La publication crée une nouvelle version, l’active et désactive la version précédente.

Scénarios clés qui devraient déclencher une nouvelle version de skill :

• Une bibliothèque publie une version majeure avec des changements d’API cassants
• Votre équipe adopte une nouvelle convention de codage que les agents doivent suivre
• Un agent a commis une erreur systématique qui peut être évitée avec une nouvelle règle dans le skill
• Vous découvrez qu’un pattern existant dans le skill est obsolète ou incorrect

Attribuer des Skills aux personas

Pour attribuer des skills à une persona, accédez à la page de détail de la persona et ouvrez l’onglet Skills. L’onglet affiche tous les skills activés du projet organisés en trois sections :

• Skills - Les packages de skill décrits dans ce guide
• Commands - Extensions de commandes slash Claude Code
• Scripts - Scripts shell/Python exécutables

Cochez les cases à côté de chaque skill que vous souhaitez rendre disponible pour cette persona. Les sélections sont enregistrées immédiatement et s’appliquent à toutes les sessions exécutées par cette persona à l’avenir.

Attribuer des Skills aux types de session

Les attributions de skills par défaut pour chaque type de session sont configurées dans l’onglet de configuration correspondant au sein des Paramètres du projet. Par exemple, pour configurer les skills par défaut de toutes les sessions Issue Discovery, accédez à /p/{id}/issues-setup et sélectionnez les skills souhaités dans les sections Skills, Commands et Scripts de cette page.

Ces valeurs par défaut de type de session s’appliquent à toute session de ce type où la persona en cours d’exécution n’a pas ses propres sélections de skills explicites.

Activer et désactiver les Skills

Les skills ont un flag isEnabled. Les skills désactivés n’apparaissent pas dans les cases de sélection des onglets Skills de persona ni dans les Paramètres du projet. Cela est utile pour les skills en développement ou que vous souhaitez masquer temporairement de l’interface de sélection sans les supprimer.

Désactiver un skill ne le retire pas des sandboxes auxquelles il a déjà été attribué - les attributions existantes sont préservées. La désactivation empêche uniquement le skill d’apparaître comme option sélectionnable pour les nouvelles attributions.

Prochaines étapes