Introducing Skill Search for Mastra Agents

Your Mastra agents can now load skills on demand with SkillSearchProcessor to reduce context bloat, token usage and cost.

The processor exposes two built-in tools:

• search_skills: Finds matching skills by keyword using vector, bm25 or hybrid search.
• load_skill: Loads a skill's instructions into the active thread.

By default, workspaces use a SkillsProcessor, which loads skills eagerly, exposing every skill to an agent on every turn. As a conversation progresses, context can become bloated, and token usage often increases. Now with a SkillSearchProcessor, skills load on demand: the agent searches for skills and only loads what it needs, keeping context windows smaller and reducing token usage.

When the agent needs a skill, it calls search_skills, finds matches, then uses load_skill to pull the instructions into context. Subsequent turns receive the same instructions. Loaded skills stay in thread state for a configurable TTL (default 1 hour) before they're cleaned up. There's a small latency cost for the first lookup of each skill, but following turns run with reduced token usage.

Get started

Install the latest Mastra core package:

npm install @mastra/core

Configure a Workspace with a filesystem, skills directory, and a search mode.

Create a SkillSearchProcessor, attach a workspace and configure the search settings: topK caps search results, minScore sets a minimum relevance threshold, and ttl controls how long loaded skills stay in thread state before cleanup.

Attach both the workspace and the processor to an agent:

import { Agent } from "@mastra/core/agent";
import { LocalFilesystem, Workspace } from "@mastra/core/workspace";
import { SkillSearchProcessor } from "@mastra/core/processors";
 
const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: "./workspace" }),
  skills: ["skills"],
  bm25: true // search mode
});
 
const skillSearch = new SkillSearchProcessor({
  workspace,
  search: { topK: 5, minScore: 0 },
  ttl: 3_600_000 // 1 hour
});
 
export const agentOnDemand = new Agent({
  id: "agent-on-demand",
  name: "Agent (on-demand)",
  instructions: /* ... */,
  model: "anthropic/claude-opus-4-7",
  inputProcessors: [skillSearch],
  workspace
});

SkillSearchProcessor adds search_skills and load_skill to the agent's tool set. It runs before the LLM call to find and inject the required skills. On subsequent turns, it re-injects any previously loaded skills.

For more information and full configuration options, see:

• SkillSearchProcessor reference
• ToolSearchProcessor reference
• Workspace reference
• Workspace skills
• Processors overview