작업 공간 기술

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

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

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

Folder structure

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

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

SKILL.md체재

Skill을 만들 때 공식 Skill 명세를 따르세요. 다음은 코드 리뷰 Skill의 SKILL.md 예시입니다.

SKILL.md

---
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 검색을 활성화하세요.

src/mastra/workspaces.ts

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

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

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

src/mastra/workspaces.ts

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

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

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

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

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

다이나믹한 스킬

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

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을 활성화할 수 있습니다.

Example: local skill shadows an external package skill

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은 기술 콘텐츠를 검색하여 관련 지침을 찾을 수 있습니다.

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

맞춤형 스킬 소스

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

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을 참조하세요.

관련된

• Agent 기술
• Agent 기술 사양
• 작업공간 개요
• 검색 및 인덱싱
• createSkill()참조