SkillToolset

SkillToolset

SkillToolset 은 에이전트가 스킬(skill)을 **점진적으로 열어보는 방식(progressive disclosure)**으로 발견하고 읽을 수 있게 해 주는 도구예요. 스킬은 번들 파일과 함께 제공되는 재사용 가능한 지침 세트를 말하고요. 컨텍스트를 작게 유지하면서 여러 상세 스킬을 다룰 수 있게 도와줘요.

출처: 문서

본문

개요 (Overview)

스킬은 SKILL.md 파일(설명은 필수, 이름은 선택이며 기본값은 디렉토리 이름)을 담긴 디렉토리(또는 그에 해당하는 저장 단위)예요. SKILL.md 는 YAML frontmatter와 마크다운 본문 지침으로 구성돼요. 스킬에는 참조 문서, 예시, 템플릿 같은 추가 파일이 번들될 수 있어요.

SkillToolset 은 Agent가 Claude Code 같은 코딩 어시스턴트가 스킬을 노출하는 방식처럼 점진적 공개로 스킬을 쓰게 해 줘요. 모델은 먼저 각 스킬의 이름과 설명만 보고, 작업이 요구할 때 전체 지침을 로드하며, 지침이 파일을 참조할 때만 번들 파일을 가져와요. 이렇게 하면 상세한 스킬이 많아도 컨텍스트를 작게 유지할 수 있어요.

툴셋은 두 가지 도구를 노출해요:

  • load_skill: 요청 시 스킬의 전체 지침과 번들 파일 목록(manifest)을 반환해요. 발견된 모든 스킬의 이름과 설명은 웜업 시 이 도구의 설명에 미리 새겨져서, 모델은 시스템 프롬프트 주입 없이 어떤 스킬이 있는지 알 수 있어요.
  • read_skill_file: 스킬에 번들된 파일을 읽어요(경로 이탈 방지 보호 포함).

스킬은 툴셋이 웜업될 때 발견돼요 — Agent 가 실행 전에 자동으로 웜업해요. 툴셋을 구성하는 것만으로는 스킬을 읽지 않아요.

SkillToolset 은 SkillStore 로 뒷받침돼요. 내장 FileSystemSkillStore 로 로컬 디렉토리의 스킬을 로드하거나, SkillStore 프로토콜(list_skills, load_skill, read_skill_file + 직렬화 메서드)을 구현해 데이터베이스나 원격 API 같은 어떤 저장 시스템으로도 툴셋을 구성할 수 있어요.

참고: 도구 이름 load_skill 과 read_skill_file 은 고정되어 있어서, 하나의 Agent 는 최대 하나의 SkillToolset 만 쓸 수 있어요. 또 다른 도구셋과 연결(concat)하거나 도구를 추가하는 것도 지원하지 않아요. 다른 도구와 결합하려면 tools=[skills_toolset, other_tool] 처럼 Agent 에 함께 전달하면 되고, 여러 소스의 스킬을 제공하려면 단일 툴셋을 그들을 합치는 커스텀 스토어로 뒷받침하면 돼요.

스킬 형식 (Skill format)

FileSystemSkillStore 는 루트 디렉토리 아래에 스킬마다 하위 디렉토리 하나씩을 기대해요:

skills/
  pdf-forms/
    SKILL.md            # frontmatter (description required, name optional) + markdown instructions
    reference/forms.md  # optional bundled file

최소한의 SKILL.md 는 이렇게 생겼어요:

---
name: pdf-forms
description: Fill in PDF forms programmatically. Use when the user asks to complete or fill a PDF form.
---

# Filling PDF forms

1. Inspect the form fields first...
2. For the full field reference, read `reference/forms.md`.

웜업 시에는 각 SKILL.md 의 frontmatter만 읽어 카탈로그를 만들고, 지침 본문과 번들 파일은 에이전트가 해당 도구를 호출할 때 지연(lazy) 로드돼요.

멀티모달 스킬 자산 (Multimodal skill assets)

read_skill_file 은 텍스트 파일은 문자열로, 이미지는 ImageContent로, PDF는 FileContent로 반환해요. 이미지와 파일 결과는 문자열로 변환되는 대신 도구 결과의 content 일부로 모델에 전달돼요. 그래서 이런 입력을 지원하는 멀티모달 채팅 생성기(예: OpenAIResponsesChatGenerator)로 뒷받침된 Agent 는 참조 스크린샷이나 소개 PDF 같은 스킬의 시각 자산을 직접 읽을 수 있어요. 이미지도 PDF도 아닌 이진 파일은 오류와 함께 거부돼요.

번들 스크립트 실행 (Executing bundled scripts)

SkillToolset 은 스킬을 읽기만 해요 — load_skill 과 read_skill_file 은 어떤 것도 실행하지 않아요. 스킬이 실행 가능한 스크립트를 번들하고 있다면(예: 지침이 모델에게 실행하라고 알려주는 Python 헬퍼), 툴셋과 함께 스크립트 실행 도구를 직접 Agent 에 넘겨주세요:

agent = Agent(
    chat_generator=OpenAIChatGenerator(),
    tools=[skills_toolset, run_shell_command_tool],  # your own execution tool
)

그러면 에이전트가 read_skill_file 로 번들 스크립트를 읽고 실행 도구를 통해 돌릴 수 있어요. 이런 도구는 모델이 고른 명령을 실행하므로 신중하게 범위를 한정하세요 — 실행을 제한하거나, 샌드박스화하거나, Human in the Loop 확인 전략으로 보호하세요.

사용법 (Usage)

에이전트와 함께 쓰기

from haystack.components.agents import Agent
from haystack.components.generators.chat import OpenAIChatGenerator
from haystack.dataclasses import ChatMessage
from haystack.skill_stores.file_system import FileSystemSkillStore
from haystack.tools import SkillToolset

store = FileSystemSkillStore("skills/")
skills_toolset = SkillToolset(store)

agent = Agent(chat_generator=OpenAIChatGenerator(), tools=skills_toolset)

# The agent sees the available skills in the `load_skill` tool description,
# loads the matching skill, and follows its instructions.
result = agent.run(messages=[ChatMessage.from_user("Fill in this PDF form for me.")])
print(result["last_message"].text)

발견된 스킬 확인 (Inspecting discovered skills)

skills 프로퍼티는 발견된 모든 스킬의 메타데이터를 스킬 이름 → SkillInfo 매핑으로 반환해요(필요하면 툴셋을 먼저 웜업해요):

from haystack.skill_stores.file_system import FileSystemSkillStore
from haystack.tools import SkillToolset

skills_toolset = SkillToolset(FileSystemSkillStore("skills/"))
for name, info in skills_toolset.skills.items():
    print(f"{name}: {info.description}")

더 알아보기 (Learn more)