SkillSearchProcessor

SkillSearchProcessor est un Processor d’entrée qui permet de découvrir et de charger des Skills à la demande. Au lieu d’injecter dès le départ toutes les métadonnées des Skills dans le prompt système, comme le fait SkillsProcessor, il fournit à l’Agent deux méta-Tools (search_skills et load_skill) qui lui permettent de rechercher et de charger des Skills à la demande. Cela réduit l’utilisation des tokens de contexte lorsque les Workspaces contiennent de nombreux Skills.

Par défaut, lorsque vous associez uniquement SkillSearchProcessor à un Agent doté d’un Workspace prenant en charge les Skills, l’Agent considère les Skills comme disponibles à la demande :

• Le SkillsProcessor immédiat par défaut n’est pas ajouté automatiquement.
• search_skills et load_skill sont exposés pour la découverte et le chargement des instructions.
• Les Tools skill et skill_search qui font doublon sont masqués.
• skill_read reste disponible afin que l’Agent puisse lire les fichiers complémentaires d’un Skill, tels que les références, scripts et ressources.

Si vous configurez explicitement SkillsProcessor avec SkillSearchProcessor, l’Agent conserve les Tools immédiats skill et skill_search comme option activable.

Exemple d’utilisation

import { SkillSearchProcessor } from '@mastra/core/processors'

const skillSearch = new SkillSearchProcessor({
  workspace,
  search: {
    topK: 5,
    minScore: 0.1,
  },
})

Paramètres du constructeur

options:

SkillSearchProcessorOptions

Options de configuration du Processor de recherche de Skills

SkillSearchProcessorOptions

workspace:

Workspace

Instance de Workspace contenant les Skills. Ceux-ci sont accessibles au moyen de workspace.skills.

search?:

{ topK?: number; minScore?: number }

Configuration du comportement de recherche.

search.topK?:

number

Nombre maximal de Skills à renvoyer dans les résultats de recherche.

search.minScore?:

number

Score de pertinence minimal requis pour inclure un Skill dans les résultats de recherche.

ttl?:

number

Durée de vie de l’état du fil, en millisecondes. Après cette durée d’inactivité, l’état du fil est nettoyé. Définissez cette valeur sur 0 pour désactiver le nettoyage.

Valeur renvoyée

id:

string

Identifiant du Processor défini sur 'skill-search'

name:

string

Nom d’affichage du Processor défini sur 'Skill Search Processor'

providesSkillDiscovery:

'on-demand'

Indique à l’Agent que ce Processor gère la découverte des Skills et le chargement de leurs instructions.

processInputStep:

(args: ProcessInputStepArgs) => Promise<ProcessInputStepResult>

Traite chaque étape afin d’injecter les méta-Tools de recherche et de chargement, ainsi que les instructions de Skills précédemment chargées, sous forme de messages système.

Exemple d’utilisation avancée

src/mastra/agents/skill-agent.ts

import { Agent } from '@mastra/core/agent'
import { SkillSearchProcessor } from '@mastra/core/processors'
import { Workspace, LocalFilesystem } from '@mastra/core/workspace'

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

const skillSearch = new SkillSearchProcessor({
  workspace,
  search: {
    topK: 5,
    minScore: 0.1,
  },
})

const agent = new Agent({
  id: 'skill-agent',
  name: 'skill-agent',
  instructions:
    'You are a helpful assistant. Use search_skills to find relevant skills, then load_skill to load their instructions.',
  model: 'openai/gpt-5.6-sol',
  workspace,
  inputProcessors: [skillSearch],
})

Le fonctionnement de l’Agent est le suivant :

1. L’Agent reçoit un message de l’utilisateur
2. L’Agent appelle search_skills avec des mots-clés (par exemple, "api design")
3. L’Agent examine les résultats et appelle load_skill avec le nom du Skill
4. Les instructions du Skill apparaissent comme messages système au tour suivant
5. L’Agent suit les instructions du Skill chargé

Tools de fichiers du Workspace

SkillSearchProcessor charge les instructions des Skills dans la conversation. Il n’empêche pas les Tools de fichiers du Workspace de lire des fichiers.

Utilisez skill_read pour les fichiers complémentaires appartenant à un Skill chargé, par exemple ceux situés dans references/, scripts/ ou assets/.

Réservez les Tools de fichiers du Workspace, tels que mastra_workspace_read_file, aux Workflows qui nécessitent explicitement d’inspecter ou de modifier des fichiers. Lors de l’exécution normale d’une tâche, l’Agent n’a pas besoin de relire le même fichier SKILL.md une fois que load_skill a réussi.

Comparaison avec SkillsProcessor

	SkillsProcessor	SkillSearchProcessor
Montée en charge	Injecte tous les Skills dès le départ	Découverte à la demande
Utilisation du contexte	Augmente avec le nombre de Skills	Constante (uniquement les Skills chargés)
Fonctionnement de l’Agent	Skills toujours visibles	L’Agent recherche et charge selon ses besoins
Recommandé pour	Peu de Skills (< 10)	De nombreux Skills (10+)

Voir aussi

• ToolSearchProcessor
• Processors
• Skills du Workspace