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 through its skills config, or configure them on a workspace. Attach them to the agent when the skills belong to that specific agent and you want to define them in code with no workspace required; use a workspace when you want skills discovered from the filesystem and shared across every agent that uses it. This page covers the agent-level approach — defining skills in code, loading them from files, and resolving them per request.

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, like references/ files in a filesystem skill. 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[]>.

See Request Context for more on using request context with agents and workflows.

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

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

Related

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