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

# Agent 기술

기술은 Agent에게 특정 작업을 수행하는 방법을 가르치는 재사용 가능한 지침입니다. 그들은 다음을 따릅니다.[Agent Skills specification](https://agentskills.io).

`skills` 구성을 통해 Skill을 Agent에 직접 연결하거나 [Workspace](https://mastra.zisheng.pro/ko/docs/workspace/overview)에 구성할 수 있습니다. Skill이 특정 Agent에 속하고 Workspace가 필요하지 않은 코드에서 Skill을 정의하려면 Agent에 연결하세요. 파일 시스템에서 Skill을 검색하고 이를 사용하는 모든 Agent에서 공유하려면 Workspace를 사용하세요. 이 페이지에서는 코드로 Skill을 정의하고, 파일에서 불러오고, 요청별로 해석하는 Agent 수준 접근 방식을 다룹니다.

## Agent 수준 기술을 사용해야 하는 경우

다음과 같은 경우 Agent 수준 기술을 사용하세요.

- 작업 영역에 의존하지 않는 독립형 Agent를 원합니다.
- 기술은 코드에 정의되어 있으며 파일 시스템 검색이 필요하지 않습니다.
- Agent 기능이 포함된 패키지 또는 라이브러리를 구축 중입니다.
- 상황에 따라 요청별 기술 해결이 필요합니다.

프로젝트 전체에서 파일 시스템 기반 기술을 검색하려면 다음을 사용하세요.[workspace skills](https://mastra.zisheng.pro/ko/docs/workspace/skills) instead.

## 빠른 시작

스킬 인라인을 정의하고 이를 Agent에 연결합니다.

```typescript
import { Agent } from '@mastra/core/agent'
import { createSkill } from '@mastra/core/skills'

const codeReview = createSkill({
  name: 'code-review',
  description: 'Use when reviewing code changes.',
  instructions: `
    When reviewing code:
    1. Check for correctness and edge cases
    2. Verify style consistency
    3. Look for potential bugs
  `,
})

export const reviewer = new Agent({
  id: 'reviewer',
  model: 'openai/gpt-5.6-sol',
  instructions: 'You are a code review assistant.',
  skills: [codeReview],
})
```

Agent에는 대화 중 Skill을 검색하고 불러올 수 있도록 `skill`, `skill_read`, `skill_search` Tool이 자동으로 제공됩니다.

## 인라인 기술 정의

Skill 전체를 코드로 생성하려면 `createSkill()`을 사용하세요.

```typescript
import { createSkill } from '@mastra/core/skills'

export const releaseChecklist = createSkill({
  name: 'release-checklist',
  description: 'Use when preparing a release.',
  instructions: `
    ## Release Checklist
    1. Run the full test suite
    2. Update CHANGELOG.md
    3. Bump version numbers
    4. Create a git tag
  `,
  references: {
    'changelog-format.md': '# Changelog Format\nUse Keep a Changelog...',
  },
})
```

`references` 필드는 파일 시스템 Skill의 `references/` 파일처럼 Agent가 `skill_read` Tool로 읽을 수 있는 지원 문서를 묶습니다. 전체 API는 [`createSkill()` 레퍼런스](https://mastra.zisheng.pro/ko/reference/agents/createSkill)를 참조하세요.

## 파일 시스템 경로 기술

작업 영역 없이 디스크의 스킬 디렉터리를 가리킵니다.

```typescript
import { Agent } from '@mastra/core/agent'
import { createSkill } from '@mastra/core/skills'

export const agent = new Agent({
  id: 'my-agent',
  model: 'openai/gpt-5.6-sol',
  skills: [
    './skills/code-review', // path to a SKILL.md directory
    './skills/testing', // another filesystem skill
    createSkill({/* ... */}), // inline skill
  ],
})
```

파일 시스템 경로는 내부적으로 `LocalSkillSource`를 사용하며, [Workspace Skill](https://mastra.zisheng.pro/ko/docs/workspace/skills)과 동일한 형식의 `SKILL.md` 파일을 읽습니다.

## 다이나믹한 스킬

요청별 기술 해결을 위해 다음 함수를 전달합니다.

```typescript
import { Agent } from '@mastra/core/agent'
import { createSkill } from '@mastra/core/skills'

const devSkill = createSkill({
  name: 'dev-tools',
  description: 'Developer productivity tools.',
  instructions: '...',
})

const supportSkill = createSkill({
  name: 'support-guide',
  description: 'Customer support guidelines.',
  instructions: '...',
})

export const agent = new Agent({
  id: 'dynamic-agent',
  model: 'openai/gpt-5.6-sol',
  skills: ({ requestContext }) => {
    const role = requestContext.get('userRole')
    if (role === 'developer') return [devSkill]
    return [supportSkill]
  },
})
```

리졸버 함수는 `{ requestContext, tracingContext }`를 받아 `SkillInput[]` 배열 또는 `Promise<SkillInput[]>`을 반환합니다. 리졸버는 `RequestContext`마다 한 번 실행됩니다. Agent 실행 중에는 `resolve-skills` 범위 안에서 실행되며, Tool과 마찬가지로 `tracingContext.currentSpan`을 사용해 자체 작업을 위한 하위 범위를 만들 수 있습니다. 또한 리졸버는 `agent.listSkills()` 및 서버의 Agent 엔드포인트와 같은 메타데이터 읽기 작업에서도 실행됩니다. 이때는 범위가 존재하지 않아 `tracingContext.currentSpan`이 `undefined`이므로 빠르게 실행되도록 유지하고 범위 사용을 방어적으로 처리하세요.

```typescript
skills: async ({ requestContext, tracingContext }) => {
  const span = tracingContext?.currentSpan?.createChildSpan({
    type: 'generic',
    name: 'entitlements-lookup',
  })
  const skills = await fetchSkillsFor(requestContext.get('userId'))
  span?.end()
  return skills
}
```

Agent 및 Workflow에서 요청 컨텍스트를 사용하는 방법에 관한 자세한 내용은 [요청 컨텍스트](https://mastra.zisheng.pro/ko/docs/server/request-context)를 참조하세요.

## 작업 공간 기술과 병합

Agent에 `skills`와 Skill이 구성된 Workspace가 모두 있으면 두 항목이 병합됩니다. 이름이 충돌할 때는 Agent 수준 Skill이 우선합니다.

```typescript
import { Agent } from '@mastra/core/agent'
import { Workspace, LocalFilesystem } from '@mastra/core/workspace'
import { createSkill } from '@mastra/core/skills'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  skills: ['skills'], // provides "code-review" skill
})

const customReview = createSkill({
  name: 'code-review', // same name as workspace skill
  description: 'Custom review process.',
  instructions: '...',
})

export const reviewer = new Agent({
  id: 'reviewer',
  model: 'openai/gpt-5.6-sol',
  workspace,
  skills: [customReview], // agent-level "code-review" wins
})
```

## 프로그래밍 방식 기술 액세스

애플리케이션 코드(예: Workflow 또는 API 경로)에서 Skill에 접근하려면 `agent.getSkill()` 및 `agent.listSkills()`를 사용하세요.

```typescript
import { reviewer } from '../mastra/agents'

// Get a specific skill by name
const skill = await reviewer.getSkill('code-review')
if (skill) {
  console.log(skill.instructions)
}

// List all available skills
const allSkills = await reviewer.listSkills()
for (const meta of allSkills) {
  console.log(`${meta.name}: ${meta.description}`)
}
```

전체 API는 [`.getSkill()` 레퍼런스](https://mastra.zisheng.pro/ko/reference/agents/getSkill) 및 [`.listSkills()` 레퍼런스](https://mastra.zisheng.pro/ko/reference/agents/listSkills)를 참조하세요.

## 관련된

- [작업 공간 기술](https://mastra.zisheng.pro/ko/docs/workspace/skills)
- [`createSkill()`참조](https://mastra.zisheng.pro/ko/reference/agents/createSkill)
- [`.getSkill()`참조](https://mastra.zisheng.pro/ko/reference/agents/getSkill)
- [`.listSkills()`참조](https://mastra.zisheng.pro/ko/reference/agents/listSkills)
- [Agent 기술 사양](https://agentskills.io)