> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt

# 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](https://agentskills.io).

Vous pouvez associer des skills directement à un agent au moyen de sa configuration `skills`, ou les configurer dans un [workspace](https://mastra.zisheng.pro/fr/docs/workspace/overview). 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](https://mastra.zisheng.pro/fr/docs/workspace/skills).

## Démarrage rapide

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

```typescript
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 :

```typescript
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()`](https://mastra.zisheng.pro/fr/reference/agents/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 :

```typescript
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](https://mastra.zisheng.pro/fr/docs/workspace/skills).

## Skills dynamiques

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

```typescript
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 :

```typescript
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](https://mastra.zisheng.pro/fr/docs/server/request-context) 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 :

```typescript
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 :

```typescript
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()`](https://mastra.zisheng.pro/fr/reference/agents/getSkill) et la [référence de `.listSkills()`](https://mastra.zisheng.pro/fr/reference/agents/listSkills) pour découvrir l’API complète.

## Ressources associées

- [Skills de workspace](https://mastra.zisheng.pro/fr/docs/workspace/skills)
- [Référence de `createSkill()`](https://mastra.zisheng.pro/fr/reference/agents/createSkill)
- [Référence de `.getSkill()`](https://mastra.zisheng.pro/fr/reference/agents/getSkill)
- [Référence de `.listSkills()`](https://mastra.zisheng.pro/fr/reference/agents/listSkills)
- [Spécification des skills d’agent](https://agentskills.io)