# Agent skills

Skills are reusable instructions that teach agents how to perform specific tasks. They follow the [Agent Skills specification](https://agentskills.io).

You can attach skills directly to an agent without setting up a workspace, filesystem, or sandbox. This is useful when you want portable, code-defined capabilities that travel with your agent definition.

## When to use agent-level skills

Use agent-level skills when:

- You want self-contained agents that don't depend on a workspace
- Skills are defined in code and don't need filesystem discovery
- You're building packages or libraries that ship agent capabilities
- You need per-request skill resolution based on context

For filesystem-based skill discovery across a project, use [workspace skills](https://mastra.ai/docs/workspace/skills) instead.

## Quickstart

Define a skill inline and attach it to an 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.5',
  instructions: 'You are a code review assistant.',
  skills: [codeReview],
})
```

The agent automatically gets `skill`, `skill_read`, and `skill_search` tools so it can discover and load skills during conversations.

## Defining inline skills

Use `createSkill()` to create skills entirely in 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...',
  },
})
```

The `references` field bundles supporting documents that the agent can read with the `skill_read` tool, just like `references/` files in a filesystem skill.

> **Note:** Visit [`createSkill()` reference](https://mastra.ai/reference/agents/createSkill) for the full API.

## Filesystem path skills

Point to skill directories on disk without a 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.5',
  skills: [
    './skills/code-review', // path to a SKILL.md directory
    './skills/testing', // another filesystem skill
    createSkill({
      /* ... */
    }), // inline skill
  ],
})
```

Filesystem paths use `LocalSkillSource` under the hood, which reads `SKILL.md` files following the same format as [workspace skills](https://mastra.ai/docs/workspace/skills).

## Dynamic skills

For per-request skill resolution, pass a function:

```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.5',
  skills: ({ requestContext }) => {
    const role = requestContext.get('userRole')
    if (role === 'developer') return [devSkill]
    return [supportSkill]
  },
})
```

The resolver function receives `{ requestContext }` and returns a `SkillInput[]` array or a `Promise<SkillInput[]>`.

## Merging with workspace skills

When an agent has both `skills` and a workspace with skills configured, they merge. Agent-level skills take precedence on name conflicts:

```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 agent = new Agent({
  id: 'reviewer',
  model: 'openai/gpt-5.5',
  workspace,
  skills: [customReview], // agent-level "code-review" wins
})
```

## Programmatic skill access

Use `agent.getSkill()` and `agent.listSkills()` to access skills from application code (e.g., in workflows or API routes):

```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}`)
}
```

> **Note:** Visit [`.getSkill()` reference](https://mastra.ai/reference/agents/getSkill) and [`.listSkills()` reference](https://mastra.ai/reference/agents/listSkills) for the full API.

## Related

- [Workspace skills](https://mastra.ai/docs/workspace/skills)
- [`createSkill()` reference](https://mastra.ai/reference/agents/createSkill)
- [`.getSkill()` reference](https://mastra.ai/reference/agents/getSkill)
- [`.listSkills()` reference](https://mastra.ai/reference/agents/listSkills)
- [Agent skills specification](https://agentskills.io)