Compétences de Workspace

Ajouté dans : @mastra/core@1.1.0

Les compétences sont des instructions réutilisables qui apprennent aux agents à effectuer des tâches précises. Elles suivent la spécification Agent Skills, un standard ouvert permettant de regrouper les capacités des agents.

Une compétence est un dossier contenant :

• SKILL.md : instructions et métadonnées destinées à l'agent
• references/ : documentation complémentaire (facultatif)
• scripts/ : scripts exécutables (facultatif)
• assets/ : images et autres fichiers (facultatif)

Folder structure

skills/
  code-review/
    SKILL.md
    references/
      style-guide.md
      pr-checklist.md
    scripts/
      lint.ts

Lorsque des compétences sont configurées dans un Workspace, les agents peuvent les découvrir et les activer au cours des conversations.

Format de SKILL.md

Lors de la création de votre compétence, suivez la spécification officielle des compétences. Voici un exemple de fichier SKILL.md pour une compétence de revue de code :

SKILL.md

---
name: code-review
description: Reviews code for quality, style, and potential issues
version: 1.0.0
tags:
  - development
  - review
---

# Code Review

You are a code reviewer. When reviewing code:

1. Check for bugs and edge cases
2. Verify the code follows the style guide in references/style-guide.md
3. Suggest improvements for readability
4. Run the linter using scripts/lint.ts

## What to look out for

- Unused variables and imports
- Missing error handling
- Security vulnerabilities
- Performance issues

Configurer les compétences

Activez la découverte des compétences en définissant l'option skills dans votre Workspace :

src/mastra/workspaces.ts

import { Workspace, LocalFilesystem } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  skills: ['skills'],
})

Vous pouvez indiquer plusieurs répertoires de compétences :

src/mastra/workspaces.ts

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  skills: [
    'skills', // Project skills
    'team-skills', // Shared team skills
  ],
})

Vous pouvez également transmettre le chemin direct d'un répertoire de compétence ou d'un fichier SKILL.md :

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  skills: ['path/to/my-skill'],
})

Les motifs glob permettent de découvrir des compétences dans des répertoires imbriqués :

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  skills: ['./**/skills'],
})

Compétences dynamiques

Pour définir à l'exécution des chemins de compétences en fonction du contexte, transmettez une fonction :

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  skills: ctx => {
    const paths = ['skills']
    if (ctx.requestContext?.get('userRole') === 'developer') {
      paths.push('dev-skills')
    }
    return paths
  },
})

Utilisation des compétences par les agents

Lorsque des compétences sont configurées dans un Workspace, les agents accèdent automatiquement aux outils de compétences. Les compétences disponibles sont répertoriées dans le message système afin que l'agent sache lesquelles sont à sa disposition et puisse charger n'importe laquelle à la demande.

L'agent dispose de trois outils de compétences :

• skill : charge l'intégralité des instructions d'une compétence et les renvoie dans le résultat de l'outil. L'agent l'appelle chaque fois qu'il a besoin des indications d'une compétence.
• skill_read : lit un fichier dans le répertoire references/, scripts/ ou assets/ d'une compétence.
• skill_search : effectue une recherche dans l'ensemble du contenu des compétences. Utilise BM25 ou la recherche vectorielle lorsqu'elle est configurée ; à défaut, utilise une correspondance textuelle simple.

Cette conception est sans état : aucun état d'activation n'est à suivre. Si les instructions de la compétence sortent du contexte de la conversation (en raison des limites de la fenêtre de contexte ou d'une compaction), l'agent peut rappeler skill pour les recharger.

Compétences portant le même nom

Lorsque plusieurs répertoires de compétences contiennent une compétence portant le même nom, elles sont toutes découvertes et répertoriées. L'agent voit chaque compétence dans son message système, accompagnée de son chemin et de son type de source, ce qui lui permet de les distinguer.

Lorsque l'agent active une compétence par son nom, les règles de départage suivantes déterminent celle qui est renvoyée :

1. Priorité du type de source : les compétences locales sont prioritaires sur les compétences gérées (.mastra/), elles-mêmes prioritaires sur les compétences externes (node_modules/).
2. Les conflits impossibles à résoudre génèrent une erreur : si deux compétences ont le même nom et le même type de source (par exemple, deux compétences locales nommées brand-guidelines), get() génère une erreur. Renommez-en une ou déplacez-la vers un autre type de source pour résoudre le conflit.
3. Échappatoire par le chemin : l'agent peut transmettre le chemin complet d'une compétence au lieu de son nom afin d'activer une compétence précise, sans appliquer les règles de départage.

Example: local skill shadows an external package skill

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  skills: [
    'node_modules/@myorg/skills', // external: provides "brand-guidelines"
    'skills', // local: also provides "brand-guidelines"
  ],
})

// get('brand-guidelines') returns the local copy (local > external)
// get('node_modules/@myorg/skills/brand-guidelines') returns the external copy

Recherche dans les compétences

Si BM25 ou la recherche vectorielle est activée dans le Workspace, les compétences sont automatiquement indexées. Les agents peuvent effectuer une recherche dans leur contenu pour trouver les instructions pertinentes.

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  skills: ['skills'],
  bm25: true,
})

Source de compétences personnalisée

Par défaut, les compétences sont lues depuis le système de fichiers du Workspace. Pour les cas d'utilisation avancés, fournissez une skillSource personnalisée afin de charger les compétences depuis un autre système de stockage.

VersionedSkillSource fournit les versions publiées des compétences depuis un magasin de blobs adressé par le contenu. Ainsi, les agents de production utilisent une version publiée précise sans accéder au système de fichiers actif :

import { Workspace, LocalFilesystem } from '@mastra/core/workspace'
import { VersionedSkillSource } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  skills: ['skills'],
  skillSource: new VersionedSkillSource(versionTree, blobStore, versionCreatedAt),
})

VersionedSkillSource accepte trois paramètres :

• versionTree (SkillVersionTree) : manifeste qui associe les chemins de fichiers relatifs aux entrées de blobs ({ entries: Record<string, { blobHash, size, mimeType?, encoding? }> }).
• blobStore (BlobStore) : instance d'un magasin de blobs adressé par le contenu qui contient le contenu réel des fichiers référencés par leur empreinte.
• versionCreatedAt (Date) : horodatage de publication de cette version de la compétence. Il sert de date de modification pour tous les fichiers de la version.

Lorsque skillSource est fournie, elle remplace le système de fichiers du Workspace pour la découverte des compétences.

Compétences au niveau de l'agent

Vous pouvez également associer des compétences directement à un agent, sans Workspace, à l'aide de createSkill() et de la configuration skills de l'agent. Lorsque des compétences existent à la fois au niveau de l'agent et du Workspace, elles sont fusionnées ; en cas de conflit de noms, celles de l'agent sont prioritaires.

Consultez Compétences des agents pour plus de détails.

Voir aussi

• Compétences des agents
• Spécification Agent Skills
• Présentation de Workspace
• Recherche et indexation
• Référence de createSkill()