Agent skills

Skills are reusable instructions that teach agents how to perform specific tasks. They follow the Agent Skills specification.

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 instead.

Quickstart

Define a skill inline and attach it to an 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.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:

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...',
  },
})

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 for the full API.

Filesystem path skills

Point to skill directories on disk without a 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.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.

Dynamic skills

For per-request skill resolution, pass a function:

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.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:

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 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):

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

note

Visit .getSkill() reference and .listSkills() reference for the full API.

Related

• Workspace skills
• createSkill() reference
• .getSkill() reference
• .listSkills() reference
• Agent skills specification