기술

파일 기반 Agent는 해당 Agent에서 기술을 발견합니다.skills/디렉토리에 저장하고 빌드 시 번들로 묶습니다. 스킬은 상시 Prompt에 모든 세부 정보를 입력하는 대신 관련성이 있을 때 Agent가 로드할 수 있는 재사용 가능한 절차 또는 참조 자료입니다.

파일 기반 규칙은 이 페이지를 참조하세요. 코드로 정의한 Skill은 Agent Skill을 참조하세요. SKILL.md 패키지 형식은 Workspace Skill을 참조하세요.

빠른 시작

가장 간단한 Skill은 skills/ 아래의 단일 Markdown 파일입니다. 파일 이름이 Skill 이름이 되고, description은 Agent에 Skill을 로드할 시점을 알려줍니다.

src/mastra/agents/weather/skills/temperature-units.md

---
description: Use when reporting temperatures or comparing forecast units.
---

Always report temperatures in Celsius and Fahrenheit. Include the user's preferred unit first when known.

기술 vs Tool vs 지침

요구 사항	사용 항목	이유
상시 적용되는 정체성, 어조 또는 규칙	instructions.md	Model이 매 턴 지침을 확인해야 합니다.
입력과 출력이 있는 호출 가능한 작업	tools/	Model이 코드를 실행하거나 API를 호출하거나 부수 효과를 수행해야 합니다.
관련이 있을 때 로드하는 상세 참조 또는 절차	skills/	Model은 특정 작업에서만 전체 지침이 필요합니다.

스킬 형식

Mastra는 세 가지 파일 기반 기술 형식을 지원합니다.

형식	사용 시점
TypeScript/JavaScript 모듈	코드에서 createSkill() 결과를 기본 내보내기하려는 경우
패키지형 SKILL.md 디렉터리	Skill에 지침과 references/ 아래의 지원 파일이 함께 있는 경우
단일 Markdown 파일	Skill이 frontmatter와 지침을 포함한 하나의 Markdown 파일인 경우
패키지형 Skill에서는 SKILL.md frontmatter에 description이 필수입니다. 단일 Markdown Skill도 frontmatter에 description이 필요합니다. Skill에 무엇이 포함되어 있는지만 설명하지 말고 언제 사용해야 하는지 작성하세요.

로드되는 내용

파일 기반 Agent 기술은 빌드 시 생성된 번들에 추가되므로 배포된 Agent는 디스크에서 해당 기술을 읽지 않습니다.

패키지 기술에 대해 Mastra는 다음과 같이 말합니다.

• SKILL.md에서 메타데이터와 지침을 확인합니다.
• 바로 아래의 references/ 파일을 지원 참조 콘텐츠로 사용합니다. 참조 파일은 파일 이름을 기준으로 포함됩니다. references/ 아래의 심볼릭 링크 파일과 디렉터리는 검색 과정에서 건너뜁니다.

구성 우선순위

검색된 Skill은 config.ts의 skills와 병합됩니다. 이름이 충돌하면 config.skills가 우선하며 경고가 기록됩니다. config.skills가 함수이면 함수형 Skill을 정적으로 병합할 수 없으므로 검색된 Skill이 경고와 함께 무시됩니다.