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

# 기술

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

파일 기반 규칙은 이 페이지를 참조하세요. 코드로 정의한 Skill은 [Agent Skill](https://mastra.zisheng.pro/ko/docs/agents/skills)을 참조하세요. `SKILL.md` 패키지 형식은 [Workspace Skill](https://mastra.zisheng.pro/ko/docs/workspace/skills)을 참조하세요.

## 빠른 시작

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

```markdown
---
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`](https://mastra.zisheng.pro/ko/reference/file-based-agents/instructions) | Model이 매 턴 지침을 확인해야 합니다.                     |
| 입력과 출력이 있는 호출 가능한 작업      | [`tools/`](https://mastra.zisheng.pro/ko/reference/file-based-agents/tools)                 | Model이 코드를 실행하거나 API를 호출하거나 부수 효과를 수행해야 합니다. |
| 관련이 있을 때 로드하는 상세 참조 또는 절차 | `skills/`                                                                                   | Model은 특정 작업에서만 전체 지침이 필요합니다.                |

## 스킬 형식

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

| 형식                                                                                                                                                                | 사용 시점                                                                                                |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| TypeScript/JavaScript 모듈                                                                                                                                          | 코드에서 [`createSkill()`](https://mastra.zisheng.pro/ko/reference/agents/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`](https://mastra.zisheng.pro/ko/reference/file-based-agents/config)의 `skills`와 병합됩니다. 이름이 충돌하면 `config.skills`가 우선하며 경고가 기록됩니다. `config.skills`가 함수이면 함수형 Skill을 정적으로 병합할 수 없으므로 검색된 Skill이 경고와 함께 무시됩니다.