跳到主要内容

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，作为可选路径。

用法示例
用法示例的直接链接

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

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

构造函数参数
构造函数参数的直接链接

options:

SkillSearchProcessorOptions
Skill 搜索 Processor 的配置选项
SkillSearchProcessorOptions

workspace:

Workspace
包含 Skill 的 Workspace 实例。通过 workspace.skills 访问 Skill。

search?:

{ topK?: number; minScore?: number }
搜索行为的配置。

search.topK?:

number
搜索结果中返回的最大 Skill 数量。

search.minScore?:

number
将 Skill 纳入搜索结果所需的最低相关性分数。

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 指令作为系统消息注入。

扩展用法示例
扩展用法示例的直接链接

src/mastra/agents/skill-agent.ts
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
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 的比较的直接链接

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