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

# SkillSearch 프로세서

그만큼`SkillSearchProcessor`은**입력 프로세서**이는 주문형 기술 검색 및 로딩을 가능하게 합니다. 모든 스킬 메타데이터를 시스템 Prompt에 미리 삽입하는 대신(예:`SkillsProcessor`), Agent에게 두 개의 메타 Tool(`search_skills`그리고`load_skill`) 필요에 따라 기술을 찾아 로드할 수 있습니다. 이렇게 하면 작업 영역에 많은 기술이 있는 경우 컨텍스트 토큰 사용량이 줄어듭니다.

기본적으로 Skill이 활성화된 `Workspace`를 사용하는 Agent에 `SkillSearchProcessor`만 연결하면 Agent가 Skill을 온디맨드 방식으로 처리합니다.

- 기본 선행 로드 방식의 `SkillsProcessor`는 자동으로 추가되지 않습니다.
- 검색 및 지침 로드를 위해 `search_skills`와 `load_skill`이 노출됩니다.
- 기능이 겹치는 `skill` 및 `skill_search` Tool은 숨겨집니다.
- Agent가 참조, 스크립트, 자산과 같은 Skill 지원 파일을 읽을 수 있도록 `skill_read`는 계속 사용할 수 있습니다. `SkillSearchProcessor`와 함께 `SkillsProcessor`를 명시적으로 구성하면 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 검색 프로세서의 구성 옵션

**options.workspace** (`Workspace`): Skill을 포함하는 Workspace 인스턴스. Skill은 workspace.skills를 통해 접근합니다.

**options.search** (`{ topK?: number; minScore?: number }`): 검색 동작의 구성입니다.

**options.search.topK** (`number`): 검색 결과로 반환할 최대 Skill 수입니다.

**options.search.minScore** (`number`): 검색 결과에 Skill을 포함하기 위한 최소 관련성 점수입니다.

**options.ttl** (`number`): 스레드 상태의 TTL(밀리초)입니다. 이 기간 동안 활동이 없으면 스레드 상태가 정리됩니다. 정리를 비활성화하려면 0으로 설정하세요.

## 보고

**id** (`string`): 'skill-search'로 설정된 프로세서 식별자

**name** (`string`): 'Skill Search Processor'로 설정된 프로세서 표시 이름

**providesSkillDiscovery** (`'on-demand'`): 이 프로세서가 Skill 탐색 및 지침 로드를 담당한다는 것을 Agent에 알립니다.

**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 Workflow는 다음과 같습니다.

1. Agent가 사용자 메시지를 받습니다.
2. Agent가 키워드(예: "api design")와 함께 `search_skills`를 호출합니다.
3. Agent가 결과를 검토하고 Skill 이름과 함께 `load_skill`을 호출합니다.
4. 해당 Skill의 지침이 다음 턴에 시스템 메시지로 표시됩니다.
5. Agent가 로드된 Skill의 지침을 따릅니다.

## 작업공간 파일 Tool

`SkillSearchProcessor`기술 지침을 대화에 로드합니다. 작업 공간 파일 Tool이 파일을 읽는 것을 차단하지 않습니다.

`references/`, `scripts/`, `assets/` 아래의 파일처럼 로드된 Skill에 속하는 지원 파일에는 `skill_read`를 사용하세요. 명시적인 파일 검사 또는 편집 Workflow를 위해 `mastra_workspace_read_file`과 같은 Workspace 파일 Tool을 남겨 두세요. 일반적인 작업 실행 중에는 `load_skill`이 성공한 후 Agent가 동일한 `SKILL.md` 파일을 다시 읽을 필요가 없습니다.

## SkillsProcessor와 비교

|              | 기술프로세서          | SkillSearch프로세서       |
| ------------ | --------------- | --------------------- |
| 스케일링         | 모든 기술을 미리 주입    | 주문형 검색                |
| 컨텍스트 사용법     | 스킬 수에 따라 성장     | 상수(로드된 스킬만)           |
| 상담사 Workflow | 항상 보이는 기술       | Agent는 필요에 따라 검색 및 로드 |
|              | 기술이 거의 없음(< 10) | 다양한 기술(10+)           |

## 관련된

- [Tool검색프로세서](https://mastra.zisheng.pro/ko/reference/processors/tool-search-processor)
- [프로세서](https://mastra.zisheng.pro/ko/docs/agents/processors)
- [작업 공간 기술](https://mastra.zisheng.pro/ko/docs/workspace/overview)