SkillSearchProcessor

The SkillSearchProcessor is an input processor that enables on-demand skill discovery and loading. Instead of injecting all skill metadata into the system prompt upfront (like SkillsProcessor), it gives the agent two meta-tools (search_skills and load_skill) that let it find and load skills on demand. This reduces context token usage when workspaces have many skills.

Usage example

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

const skillSearch = new SkillSearchProcessor({
  workspace,
  search: {
    topK: 5,
    minScore: 0.1,
  },
})

Constructor parameters

options:

SkillSearchProcessorOptions

Configuration options for the skill search processor

SkillSearchProcessorOptions

workspace:

Workspace

Workspace instance containing skills. Skills are accessed via workspace.skills.

search?:

{ topK?: number; minScore?: number }

Configuration for the search behavior.

search.topK?:

number

Maximum number of skills to return in search results.

search.minScore?:

number

Minimum relevance score for including a skill in search results.

ttl?:

number

Time-to-live for thread state in milliseconds. After this duration of inactivity, thread state will be cleaned up. Set to 0 to disable cleanup.

Returns

id:

string

Processor identifier set to 'skill-search'

name:

string

Processor display name set to 'Skill Search Processor'

processInputStep:

(args: ProcessInputStepArgs) => Promise<ProcessInputStepResult>

Processes each step to inject search/load meta-tools and any previously loaded skill instructions as system messages.

Extended usage example

src/mastra/agents/skill-agent.ts

import { Agent } from '@mastra/core/agent'
import { SkillSearchProcessor } 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 skillSearch = new SkillSearchProcessor({
  workspace,
  search: {
    topK: 5,
    minScore: 0.1,
  },
})

const agent = new Agent({
  name: 'skill-agent',
  instructions:
    'You are a helpful assistant. Use search_skills to find relevant skills, then load_skill to load their instructions.',
  model: 'openai/gpt-4o',
  workspace,
  inputProcessors: [skillSearch],
})

The agent workflow is:

1. Agent receives a user message
2. Agent calls search_skills with keywords (e.g., "api design")
3. Agent reviews results and calls load_skill with the skill name
4. The skill's instructions appear as system messages on the next turn
5. Agent follows the loaded skill's instructions

Compared to SkillsProcessor

	SkillsProcessor	SkillSearchProcessor
Scaling	Injects all skills upfront	On-demand discovery
Context usage	Grows with skill count	Constant (only loaded skills)
Agent workflow	Skills always visible	Agent searches and loads as needed
Best for	Few skills (< 10)	Many skills (10+)

Related

• ToolSearchProcessor
• Processors
• Workspace Skills