Skip to main content

SkillsProcessor

The SkillsProcessor is an input processor that adds the available skills to the system message as an <available_skills> list, so the model knows which skills exist and can load one with the skill tool. The agent adds it automatically when its workspace or its own skills option provides skills, so you only configure it yourself to change how skills are presented.

With injectCatalog: false, it replaces the list with a short instruction to find skills with skill_search and load them with skill. Use this when the list costs too many tokens. See Turn off the skills list.

The skill, skill_search, and skill_read tools come from the agent, not from this processor, and stay available in both modes. To replace them with on-demand search_skills and load_skill tools instead, use SkillSearchProcessor. Configure one or the other, not both.

Usage example
Direct link to Usage example

import { SkillsProcessor } from '@mastra/core/processors'

const skills = new SkillsProcessor({
  workspace,
  format: 'markdown',
})

Constructor parameters
Direct link to Constructor parameters

options:

SkillsProcessorOptions
Configuration options. Provide either skills or workspace, not both. With injectCatalog: false, both are optional.
SkillsProcessorOptions

workspace?:

Workspace
Workspace whose skills are listed. Skills are read from workspace.skills.

skills?:

WorkspaceSkills
Skills registry to list, instead of a workspace.

injectCatalog?:

boolean
When false, injects an instruction to find skills with skill_search and load them with skill instead of listing every skill. The instruction is added whenever the agent exposes the skill_search tool, so it also covers skills configured on the agent.

format?:

'xml' | 'json' | 'markdown'
Format of the skills list in the system message. Has no effect with injectCatalog: false.

formatLocation?:

(skill: Skill) => string
Renders the location of each listed skill. Defaults to ${skill.path}/SKILL.md, a path on the server running the agent. Override it when the model works in a different filesystem, such as a sandbox. Rendered locations are registered as aliases, so the skill and skill_read tools still resolve them. Has no effect with injectCatalog: false.

blockingRefresh?:

boolean
When true, awaits the skills staleness check before the first step of each request so skill changes appear in the same turn. When false, the cached skills are served and revalidated in the background, so changes can lag by one turn plus the staleness cooldown.

Returns
Direct link to Returns

id:

string
Processor identifier set to 'skills-processor'. An agent that finds a configured input processor with this id doesn't add its own SkillsProcessor.

name:

string
Processor display name set to 'Skills Processor'

listSkills:

() => Promise<Array<{ name: string; description: string; license?: string }>>
Lists the skills from the configured source. Returns an empty array without a source.

processInputStep:

(args: ProcessInputStepArgs) => Promise<void>
Refreshes the skills on the first step, then adds the skills list or the skill_search instruction to the system message.

Extended usage example
Direct link to Extended usage example

src/mastra/agents/skill-agent.ts
import { Agent } from '@mastra/core/agent'
import { SkillsProcessor } from '@mastra/core/processors'
import { Workspace, LocalFilesystem } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './project' }),
  skills: ['skills'],
  bm25: true,
})

const agent = new Agent({
  id: 'skill-agent',
  name: 'skill-agent',
  instructions: 'You are a helpful assistant.',
  model: 'openai/gpt-6.1-sol',
  workspace,
  inputProcessors: [new SkillsProcessor({ injectCatalog: false })],
})

With the list turned off, the agent finds skills by searching. skill_search works without any search setup; for larger collections, configure BM25 or vector search on the workspace to improve ranking, as in the example above. The agent workflow is:

  1. Agent receives a user message
  2. Agent calls skill_search with keywords (e.g., "release notes")
  3. Agent reviews results and calls skill with the skill name
  4. Agent follows the loaded skill's instructions
On this page