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

# 작업 공간 기술

**추가된 항목:** `@mastra/core@1.1.0`

Skill은 Agent에게 특정 작업을 수행하는 방법을 알려 주는 재사용 가능한 지침입니다. Agent 기능 패키징을 위한 개방형 표준인 [Agent Skills 명세](https://agentskills.io)를 따릅니다. 스킬은 다음을 포함하는 폴더입니다.

- `SKILL.md`: Agent에 대한 지침 및 메타데이터
- `references/`: 지원 문서(선택 사항)
- `scripts/`: 실행 가능한 스크립트(선택 사항)
- `assets/`: 이미지 및 기타 파일(선택사항)

```plaintext
skills/
  code-review/
    SKILL.md
    references/
      style-guide.md
      pr-checklist.md
    scripts/
      lint.ts
```

작업 영역에 기술이 구성되면 Agent은 대화 중에 해당 기술을 검색하고 활성화할 수 있습니다.

## `SKILL.md`체재

Skill을 만들 때 공식 [Skill 명세](https://agentskills.io/specification)를 따르세요. 다음은 코드 리뷰 Skill의 `SKILL.md` 예시입니다.

```markdown
---
name: code-review
description: Reviews code for quality, style, and potential issues
version: 1.0.0
tags:
  - development
  - review
---

# Code Review

You are a code reviewer. When reviewing code:

1. Check for bugs and edge cases
2. Verify the code follows the style guide in references/style-guide.md
3. Suggest improvements for readability
4. Run the linter using scripts/lint.ts

## What to look out for

- Unused variables and imports
- Missing error handling
- Security vulnerabilities
- Performance issues
```

## 기술 구성

Workspace에서 `skills` 옵션을 설정하여 Skill 검색을 활성화하세요.

```typescript
import { Workspace, LocalFilesystem } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  skills: ['skills'],
})
```

여러 기술 디렉터리를 지정할 수 있습니다.

```typescript
const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  skills: [
    'skills', // Project skills
    'team-skills', // Shared team skills
  ],
})
```

기술 디렉터리에 대한 직접 경로를 전달할 수도 있습니다.`SKILL.md` file:

```typescript
const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  skills: ['path/to/my-skill'],
})
```

Glob 패턴을 사용하면 중첩된 디렉터리에서 기술을 검색할 수 있습니다.

```typescript
const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  skills: ['./**/skills'],
})
```

## 다이나믹한 스킬

컨텍스트 기반 런타임 기술 경로의 경우 함수를 전달합니다.

```typescript
const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  skills: ctx => {
    const paths = ['skills']
    if (ctx.requestContext?.get('userRole') === 'developer') {
      paths.push('dev-skills')
    }
    return paths
  },
})
```

## Agent가 스킬을 사용하는 방법

작업 영역에 기술이 구성되면 Agent은 자동으로 기술 Tool에 액세스할 수 있습니다. 사용 가능한 기술이 시스템 메시지에 나열되므로 Agent은 사용 가능한 기술을 알 수 있으며 Agent은 요청 시 모든 기술을 로드할 수 있습니다.

Agent에는 세 가지 기술 Tool이 있습니다.

- **`skill`**: Skill의 전체 지침을 불러와 Tool 결과로 반환합니다. Agent는 Skill 지침이 필요할 때마다 이를 호출합니다.
- **`skill_read`**: Skill의 `references/`, `scripts/` 또는 `assets/` 디렉터리에 있는 파일을 읽습니다.
- **`skill_search`**: 모든 Skill 콘텐츠를 검색합니다. 구성된 경우 BM25 또는 벡터 검색을 사용하고, 그렇지 않으면 기본 텍스트 일치 방식으로 대체합니다. 이 설계는 무상태 방식이므로 추적해야 할 활성화 상태가 없습니다. 컨텍스트 창 제한이나 압축으로 인해 Skill 지침이 대화 컨텍스트에서 벗어나면 Agent가 `skill`을 다시 호출하여 지침을 불러올 수 있습니다.

## 같은 이름의 스킬

여러 스킬 디렉터리에 동일한 이름의 스킬이 포함되어 있으면 해당 스킬이 모두 검색되어 나열됩니다. Agent는 각 기술의 경로 및 소스 유형과 함께 시스템 메시지의 모든 기술을 확인하여 이를 구분할 수 있습니다.

Agent가 이름으로 스킬을 활성화하면 순위 결정에 따라 반환되는 스킬이 결정됩니다.

1. **소스 유형 우선순위**: 로컬 Skill이 관리형(`.mastra/`) Skill보다 우선하며, 관리형 Skill은 외부(`node_modules/`) Skill보다 우선합니다.
2. **해결할 수 없는 충돌은 오류를 발생시킵니다.**: 두 Skill의 이름과 소스 유형이 모두 같은 경우(예: 두 로컬 Skill의 이름이 모두 `brand-guidelines`인 경우) `get()`에서 오류가 발생합니다. 충돌을 해결하려면 하나의 이름을 변경하거나 다른 소스 유형으로 이동하세요.
3. **경로 이스케이프 해치**: Agent는 이름 대신 Skill의 전체 경로를 전달하여 우선순위 결정을 완전히 우회하고 특정 Skill을 활성화할 수 있습니다.

```typescript
const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  skills: [
    'node_modules/@myorg/skills', // external: provides "brand-guidelines"
    'skills', // local: also provides "brand-guidelines"
  ],
})

// get('brand-guidelines') returns the local copy (local > external)
// get('node_modules/@myorg/skills/brand-guidelines') returns the external copy
```

## 스킬 검색

작업 공간에서 BM25 또는 벡터 검색이 활성화된 경우 스킬이 자동으로 인덱싱됩니다. Agent은 기술 콘텐츠를 검색하여 관련 지침을 찾을 수 있습니다.

```typescript
const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  skills: ['skills'],
  bm25: true,
})
```

## 맞춤형 스킬 소스

기본적으로 Skill은 Workspace 파일 시스템에서 읽습니다. 고급 사용 사례에서는 사용자 정의 `skillSource`를 제공하여 다른 백엔드에서 Skill을 불러올 수 있습니다. `VersionedSkillSource` 콘텐츠 주소 지정이 가능한 Blob 저장소에서 게시된 기술 버전을 제공하므로 프로덕션 Agent는 라이브 파일 시스템을 건드리지 않고 특정 게시된 버전을 사용합니다.

```typescript
import { Workspace, LocalFilesystem } from '@mastra/core/workspace'
import { VersionedSkillSource } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  skills: ['skills'],
  skillSource: new VersionedSkillSource(versionTree, blobStore, versionCreatedAt),
})
```

`VersionedSkillSource`세 가지 매개변수를 허용합니다:

- **`versionTree`** (`SkillVersionTree`): 상대 파일 경로를 Blob 항목에 매핑하는 매니페스트입니다(`{ entries: Record<string, { blobHash, size, mimeType?, encoding? }> }`).
- **`blobStore`** (`BlobStore`): 해시로 참조되는 실제 파일 콘텐츠를 보관하는 콘텐츠 주소 지정 가능 Blob 저장소 인스턴스입니다.
- **`versionCreatedAt`** (`Date`): 이 Skill 버전이 게시된 시각입니다. 해당 버전에 포함된 모든 파일의 수정 시간으로 사용됩니다. `skillSource`가 제공되면 Skill 검색에 Workspace 파일 시스템 대신 이를 사용합니다.

## Agent 수준의 기술

`createSkill()`과 Agent의 `skills` 구성을 사용하여 Workspace 없이 Agent에 Skill을 직접 연결할 수도 있습니다. Agent 수준 Skill과 Workspace 수준 Skill이 모두 있으면 두 항목이 병합되며, 이름이 충돌할 경우 Agent 수준 Skill이 우선합니다. 자세한 내용은 [Agent Skill](https://mastra.zisheng.pro/ko/docs/agents/skills)을 참조하세요.

## 관련된

- [Agent 기술](https://mastra.zisheng.pro/ko/docs/agents/skills)
- [Agent 기술 사양](https://agentskills.io)
- [작업공간 개요](https://mastra.zisheng.pro/ko/docs/workspace/overview)
- [검색 및 인덱싱](https://mastra.zisheng.pro/ko/docs/workspace/search)
- [`createSkill()`참조](https://mastra.zisheng.pro/ko/reference/agents/createSkill)