@mastra/core/dist/docs/references/reference-processors-skill-search-processor.md

Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack.

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

By default, when you attach only `SkillSearchProcessor` to an agent with a skill-enabled `Workspace`, the agent treats skills as on-demand:

- The default eager `SkillsProcessor` is not auto-added.
- `search_skills` and `load_skill` are exposed for discovery and instruction loading.
- Overlapping `skill` and `skill_search` tools are hidden.
- `skill_read` remains available so the agent can read supporting skill files such as references, scripts, and assets.

If you explicitly configure `SkillsProcessor` alongside `SkillSearchProcessor`, the agent preserves the eager `skill` and `skill_search` tools as an opt-in path.

## Usage example

```typescript
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

**options.workspace** (`Workspace`): Workspace instance containing skills. Skills are accessed via workspace.skills.

**options.search** (`{ topK?: number; minScore?: number }`): Configuration for the search behavior.

**options.search.topK** (`number`): Maximum number of skills to return in search results.

**options.search.minScore** (`number`): Minimum relevance score for including a skill in search results.

**options.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'

**providesSkillDiscovery** (`'on-demand'`): Signals to the agent that this processor owns skill discovery and instruction loading.

**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

```typescript
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

## Workspace file tools

`SkillSearchProcessor` loads skill instructions into the conversation. It does not block workspace file tools from reading files.

Use `skill_read` for supporting files that belong to a loaded skill, such as files under `references/`, `scripts/`, or `assets/`.

Reserve workspace file tools such as `mastra_workspace_read_file` for explicit file inspection or editing workflows. During normal task execution, the agent does not need to read the same `SKILL.md` file after `load_skill` succeeds.

## 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](https://mastra.ai/reference/processors/tool-search-processor)
- [Processors](https://mastra.ai/docs/agents/processors)
- [Workspace Skills](https://mastra.ai/docs/workspace/overview)