Skills des agents

Les skills sont des instructions réutilisables qui apprennent aux agents à effectuer des tâches précises. Elles suivent la spécification des skills d’agent.

Vous pouvez associer des skills directement à un agent au moyen de sa configuration skills, ou les configurer dans un workspace. Associez-les à l’agent lorsqu’elles sont propres à cet agent et que vous souhaitez les définir dans le code sans avoir besoin d’un workspace. Utilisez un workspace si vous souhaitez découvrir les skills depuis le système de fichiers et les partager entre tous les agents qui l’utilisent. Cette page présente l’approche au niveau de l’agent : définition des skills dans le code, chargement depuis des fichiers et résolution pour chaque requête.

Quand utiliser des skills au niveau de l’agent

Utilisez des skills au niveau de l’agent dans les cas suivants :

• Vous souhaitez des agents autonomes qui ne dépendent pas d’un workspace
• Les skills sont définies dans le code et ne nécessitent pas de découverte dans le système de fichiers
• Vous créez des packages ou des bibliothèques qui contiennent des capacités d’agent
• Vous avez besoin de résoudre les skills pour chaque requête en fonction du contexte

Pour découvrir des skills dans le système de fichiers à l’échelle d’un projet, utilisez plutôt les skills de workspace.

Démarrage rapide

Définissez une skill en ligne et associez-la à un agent :

src/mastra/agents/index.ts

import { Agent } from '@mastra/core/agent'
import { createSkill } from '@mastra/core/skills'

const codeReview = createSkill({
  name: 'code-review',
  description: 'Use when reviewing code changes.',
  instructions: `
    When reviewing code:
    1. Check for correctness and edge cases
    2. Verify style consistency
    3. Look for potential bugs
  `,
})

export const reviewer = new Agent({
  id: 'reviewer',
  model: 'openai/gpt-5.6-sol',
  instructions: 'You are a code review assistant.',
  skills: [codeReview],
})

L’agent obtient automatiquement les outils skill, skill_read et skill_search, qui lui permettent de découvrir et de charger des skills pendant les conversations.

Définir des skills en ligne

Utilisez createSkill() pour créer des skills entièrement dans le code :

src/mastra/skills.ts

import { createSkill } from '@mastra/core/skills'

export const releaseChecklist = createSkill({
  name: 'release-checklist',
  description: 'Use when preparing a release.',
  instructions: `
    ## Release Checklist
    1. Run the full test suite
    2. Update CHANGELOG.md
    3. Bump version numbers
    4. Create a git tag
  `,
  references: {
    'changelog-format.md': '# Changelog Format\nUse Keep a Changelog...',
  },
})

Le champ references regroupe les documents complémentaires que l’agent peut lire avec l’outil skill_read, à la manière des fichiers references/ d’une skill présente dans le système de fichiers. Consultez la référence de createSkill() pour découvrir l’API complète.

Skills issues de chemins du système de fichiers

Pointez vers des répertoires de skills sur le disque sans utiliser de workspace :

src/mastra/agents/index.ts

import { Agent } from '@mastra/core/agent'
import { createSkill } from '@mastra/core/skills'

export const agent = new Agent({
  id: 'my-agent',
  model: 'openai/gpt-5.6-sol',
  skills: [
    './skills/code-review', // path to a SKILL.md directory
    './skills/testing', // another filesystem skill
    createSkill({/* ... */}), // inline skill
  ],
})

Les chemins du système de fichiers utilisent LocalSkillSource en interne, qui lit les fichiers SKILL.md respectant le même format que les skills de workspace.

Skills dynamiques

Pour résoudre les skills à chaque requête, transmettez une fonction :

src/mastra/agents/index.ts

import { Agent } from '@mastra/core/agent'
import { createSkill } from '@mastra/core/skills'

const devSkill = createSkill({
  name: 'dev-tools',
  description: 'Developer productivity tools.',
  instructions: '...',
})

const supportSkill = createSkill({
  name: 'support-guide',
  description: 'Customer support guidelines.',
  instructions: '...',
})

export const agent = new Agent({
  id: 'dynamic-agent',
  model: 'openai/gpt-5.6-sol',
  skills: ({ requestContext }) => {
    const role = requestContext.get('userRole')
    if (role === 'developer') return [devSkill]
    return [supportSkill]
  },
})

La fonction de résolution reçoit { requestContext, tracingContext } et renvoie un tableau SkillInput[] ou une Promise<SkillInput[]>.

La fonction de résolution s’exécute une fois par RequestContext. Pendant l’exécution d’un agent, elle s’exécute dans un span resolve-skills, et tracingContext.currentSpan vous permet de créer des spans enfants pour votre propre traitement, comme le font les outils. Elle s’exécute également lors des lectures de métadonnées telles que agent.listSkills() et sur les endpoints d’agent du serveur. Dans ces cas, aucun span n’existe et tracingContext.currentSpan vaut undefined ; veillez donc à ce qu’elle soit rapide et protégez toute utilisation d’un span :

src/mastra/agents/index.ts

skills: async ({ requestContext, tracingContext }) => {
  const span = tracingContext?.currentSpan?.createChildSpan({
    type: 'generic',
    name: 'entitlements-lookup',
  })
  const skills = await fetchSkillsFor(requestContext.get('userId'))
  span?.end()
  return skills
}

Consultez la page Contexte de requête pour en savoir plus sur l’utilisation du contexte de requête avec les agents et les workflows.

Fusionner avec les skills du workspace

Lorsqu’un agent possède à la fois des skills et un workspace dans lequel des skills sont configurées, celles-ci sont fusionnées. En cas de conflit de noms, les skills définies au niveau de l’agent sont prioritaires :

src/mastra/agents/index.ts

import { Agent } from '@mastra/core/agent'
import { Workspace, LocalFilesystem } from '@mastra/core/workspace'
import { createSkill } from '@mastra/core/skills'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  skills: ['skills'], // provides "code-review" skill
})

const customReview = createSkill({
  name: 'code-review', // same name as workspace skill
  description: 'Custom review process.',
  instructions: '...',
})

export const reviewer = new Agent({
  id: 'reviewer',
  model: 'openai/gpt-5.6-sol',
  workspace,
  skills: [customReview], // agent-level "code-review" wins
})

Accéder aux skills par programmation

Utilisez agent.getSkill() et agent.listSkills() pour accéder aux skills depuis le code de l’application, par exemple dans des workflows ou des routes d’API :

src/routes/skills.ts

import { reviewer } from '../mastra/agents'

// Get a specific skill by name
const skill = await reviewer.getSkill('code-review')
if (skill) {
  console.log(skill.instructions)
}

// List all available skills
const allSkills = await reviewer.listSkills()
for (const meta of allSkills) {
  console.log(`${meta.name}: ${meta.description}`)
}

Consultez la référence de .getSkill() et la référence de .listSkills() pour découvrir l’API complète.

Ressources associées

• Skills de workspace
• Référence de createSkill()
• Référence de .getSkill()
• Référence de .listSkills()
• Spécification des skills d’agent