SkillSearchProcessor

SkillSearchProcessor 是一種輸入處理器，可依需求探索並載入 Skill。它不會像 SkillsProcessor 一樣，預先將所有 Skill 中繼資料注入系統提示詞，而是提供兩個中繼 Tool（search_skills 和 load_skill），讓 Agent 能依需求尋找並載入 Skill。當 Workspace 中有許多 Skill 時，這能減少情境 token 用量。

根據預設，如果在啟用 Skill 的 Workspace 中只將 SkillSearchProcessor 附加至 Agent，Agent 會將 Skill 視為隨選資源：

• 不會自動加入預設會積極載入的 SkillsProcessor。
• 公開 search_skills 和 load_skill，用於探索及載入指示。
• 隱藏功能重疊的 skill 和 skill_search Tool。
• skill_read 仍可使用，讓 Agent 能讀取參考資料、指令碼和資產等 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 搜尋處理器的設定選項

SkillSearchProcessorOptions

workspace:

Workspace

包含 Skill 的 Workspace 執行個體。透過 workspace.skills 存取 Skill。

search?:

{ topK?: number; minScore?: number }

搜尋行為的設定。

search.topK?:

number

搜尋結果中最多回傳的 Skill 數量。

search.minScore?:

number

搜尋結果納入 Skill 所需的最低相關性分數。

ttl?:

number

對話串狀態的存留時間，以毫秒為單位。對話串閒置超過此時間後，系統會清除其狀態。設為 0 可停用清除。

回傳值

id:

string

設為 'skill-search' 的處理器識別碼

name:

string

設為 'Skill Search Processor' 的處理器顯示名稱

providesSkillDiscovery:

'on-demand'

向 Agent 表示此處理器負責 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

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
• 處理器
• Workspace Skill