# 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

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

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

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