> Discover all available pages from the documentation index: https://mastra.ai/llms.txt

# 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` isn't 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.

**options.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 catalog is served and revalidated in the background, so skill changes can lag by one turn plus the staleness cooldown (up to 30 seconds).

## 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({
  id: 'skill-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-5.6-sol',
  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 doesn't 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 doesn't 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/sandbox/skills)