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

# SkillSearchProcessor

`SkillSearchProcessor` 是一种**输入 Processor**，支持按需发现和加载 Skill。它不会像 `SkillsProcessor` 那样预先将所有 Skill 元数据注入系统提示词，而是为 Agent 提供两个元 Tool（`search_skills` 和 `load_skill`），使其能够按需查找和加载 Skill。当 Workspace 中有大量 Skill 时，这可以减少上下文 token 用量。

默认情况下，当你只将 `SkillSearchProcessor` 附加到具有 Skill 功能的 `Workspace` 的 Agent 时，该 Agent 会将 Skill 视为按需资源：

- 不会自动添加默认的预加载 `SkillsProcessor`。
- 公开 `search_skills` 和 `load_skill`，用于发现和加载指令。
- 隐藏功能重叠的 `skill` 和 `skill_search` Tool。
- `skill_read` 仍然可用，因此 Agent 可以读取 references、scripts 和 assets 等 Skill 支持文件。

如果显式地同时配置 `SkillsProcessor` 和 `SkillSearchProcessor`，Agent 会保留预加载的 `skill` 和 `skill_search` Tool，作为可选路径。

## 用法示例

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

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

## 构造函数参数

**options** (`SkillSearchProcessorOptions`): Skill 搜索 Processor 的配置选项

**options.workspace** (`Workspace`): 包含 Skill 的 Workspace 实例。通过 workspace.skills 访问 Skill。

**options.search** (`{ topK?: number; minScore?: number }`): 搜索行为的配置。

**options.search.topK** (`number`): 搜索结果中返回的最大 Skill 数量。

**options.search.minScore** (`number`): 将 Skill 纳入搜索结果所需的最低相关性分数。

**options.ttl** (`number`): thread 状态的存活时间（毫秒）。在此时长内无活动后，thread 状态将被清理。设置为 0 可禁用清理。

## 返回值

**id** (`string`): 设置为 'skill-search' 的 Processor 标识符

**name** (`string`): 设置为 'Skill Search Processor' 的 Processor 显示名称

**providesSkillDiscovery** (`'on-demand'`): 向 Agent 表明此 Processor 负责 Skill 发现和指令加载。

**processInputStep** (`(args: ProcessInputStepArgs) => Promise<ProcessInputStepResult>`): 处理每个步骤，注入搜索/加载元 Tool，并将之前加载的所有 Skill 指令作为系统消息注入。

## 扩展用法示例

```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],
})
```

Agent 的工作流程如下：

1. Agent 接收用户消息
2. Agent 使用关键字（例如 "api design"）调用 `search_skills`
3. Agent 查看结果，并使用 Skill 名称调用 `load_skill`
4. Skill 的指令会在下一轮以系统消息形式出现
5. Agent 遵循已加载 Skill 的指令

## Workspace 文件 Tool

`SkillSearchProcessor` 将 Skill 指令加载到对话中。它不会阻止 Workspace 文件 Tool 读取文件。

对于属于已加载 Skill 的支持文件（例如 `references/`、`scripts/` 或 `assets/` 下的文件），请使用 `skill_read`。

请将 `mastra_workspace_read_file` 等 Workspace 文件 Tool 留给显式的文件检查或编辑工作流。在正常任务执行期间，`load_skill` 成功后，Agent 无需再次读取同一个 `SKILL.md` 文件。

## 与 SkillsProcessor 的比较

|           | SkillsProcessor | SkillSearchProcessor |
| --------- | --------------- | -------------------- |
| 扩展方式      | 预先注入所有 Skill    | 按需发现                 |
| 上下文用量     | 随 Skill 数量增长    | 保持不变（仅包含已加载的 Skill）  |
| Agent 工作流 | Skill 始终可见      | Agent 按需搜索和加载        |
| 最适合       | 少量 Skill（< 10）  | 大量 Skill（10+）        |

## 相关内容

- [ToolSearchProcessor](https://mastra.zisheng.pro/reference/processors/tool-search-processor)
- [Processors](https://mastra.zisheng.pro/docs/agents/processors)
- [Workspace Skill](https://mastra.zisheng.pro/docs/workspace/overview)