서론

Microsoft Agents Framework로 에이전트를 만들기 시작하면 곧바로 마주하게 되는 과제는 "어떻게 도메인 지식(Domain Knowledge)을 안전하고 재사용하기 쉽게 전달할 것인가"입니다.

이번 기사에서는 샘플을 주제로, Agent Skills를 사용한 지식 부여 구현을 해설합니다.

이 샘플은 다음 패턴들을 하나의 앱에서 비교할 수 있다는 점이 포인트입니다.

• 파일 기반 스킬 (File-based skills)
• 코드 내에서 정의하는 인라인 스킬 (Inline skills)
• 양자를 조합한 믹스 구성 (Mix configuration)

Agent Skills의 개요

Agent Skills는 에이전트에게 "어떤 지식을, 어떤 역할로 사용하게 할 것인가"를 명시하는 메커니즘입니다.

단순히 긴 프롬프트 (Prompt)를 전달하는 것이 아니라, 스킬 단위로 책임을 나눔으로써 답변 품질과 유지보수성을 양립하기 쉬워집니다.

Microsoft Agents Framework에서는 주로 다음 3가지 패턴으로 스킬을 다룰 수 있습니다.

File-based skills

SKILL.md와 resources 하위의 파일을 사용하여, 지식을 파일로서 관리하는 방식입니다.

내용 업데이트를 코드 변경과 분리하기 쉬워, 운용 중의 개선 사이클을 돌리기 쉽다는 것이 장점입니다. -
Code-defined skills

C# 코드 내에서 스킬을 정의하고, 필요에 따라 함수나 외부 API 호출을 포함하는 방식입니다.

타입 안전성 (Type safety) 있게 제어할 수 있으므로, 업무 로직이나 동적 데이터 연동을 동반하는 케이스에 적합합니다. -
Class-based skills

스킬을 클래스 (Class)로 정의하여 재사용 가능하게 만드는 방식입니다.

여러 에이전트가 동일한 스킬 그룹을 재사용하고 싶을 때나, DI(Dependency Injection)·테스트·책임 분리를 명확히 하고 싶은 대규모 구현에서 효과를 발휘합니다.

File-based skills에서 사용하는 SKILL.md에는 프론트매터 (Frontmatter)의 name과 description이 필수입니다.

name에는 스킬을 고유하게 식별할 수 있는 이름을, description에는 "이 스킬이 무엇을 제공하며, 어떤 질문에서 사용해야 하는가"를 간결하게 작성합니다.

특히 description은 모델의 스킬 선택에 직결되므로, 대상 영역·할 수 있는 일·상정 질문을 구체적으로 포함하는 것이 중요합니다.

이와 같이 정적 지식 중심이라면 File-based, 실행 로직 중시라면 Code-defined, 재사용성과 구조화를 중시한다면 Class-based라는 기준으로 선택하면 정리가 쉬워집니다.

이번에는 1. File-based skills와 2. Code-defined skills의 구현 샘플을 예시로 보여드립니다.

Agent Skills를 이용한 샘플

이번 샘플은 Seattle 관광과 날씨 정보를 주제로, 스킬을 통해 에이전트의 답변 품질을 높이는 구성입니다.

• 모델 연결: Azure OpenAI
• 인증: Azure CLI 로그인된 사용자
• 프레임워크: Microsoft.Agents.AI
• 스킬 구성: 파일 / 인라인 / 믹스

프로젝트의 관전 포인트는, 동일한 에이전트 용도에 대해 스킬의 정의 방법만 교체해가며 동작을 비교할 수 있다는 점입니다.

프로젝트 구성

Sample12AgentSkillConsoleApp/
├─ Program.cs
├─ Sample12AgentSkillConsoleApp.csproj
...

csproj에서는 skills 하위 항목을 출력 디렉토리로 복사하도록 설정되어 있어, 실행 시에 스킬 파일을 읽어올 수 있습니다.

<ItemGroup>
<Content Include="skills\**\*">
<CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
...

3가지 구현 접근 방식

1. 파일 기반 스킬

먼저 UseFileSkills를 사용하여, skills 디렉토리에서 SKILL.md를 자동으로 발견합니다.

var fileSkillsProvider = new AgentSkillsProviderBuilder()
.UseFileSkills([skillsDirectory])
.Build();

이 방식의 장점은 스킬을 코드 변경 없이 교체하기 쉽다는 것입니다.

프롬프트 설계 담당과 구현 담당을 분업하기 쉬우며, 운용 중의 업데이트에도 적합합니다.

2. 인라인 스킬

다음으로 AgentInlineSkill을 사용하여 스킬 정의, 스크립트, 정적 리소스를 코드로 구성합니다.

var seattleTourismSkill = new AgentInlineSkill(
name: "seattle-tourism",
description: "Provides detailed tourism information about Seattle including attractions, restaurants, and events.",
...

이 방식은 타입 안전(Type-safe)하게 로직을 관리할 수 있다는 것이 강점입니다.

예를 들어 외부 API 호출이나 사내 규칙 적용을 일반적인 C#과 동일한 감각으로 구현할 수 있습니다.

3. 믹스 구성 (Mixed Configuration)

마지막으로, 파일 기반(File-based)과 인라인(Inline)을 동시에 사용합니다.

var mixedSkillsProvider = new AgentSkillsProviderBuilder()
.UseFileSkills([skillsDirectory])
.UseSkills(transportSkill)
...

이는 실제 운용에서 특히 유효합니다.

이유는 단순합니다. 변화하기 쉬운 지식은 파일로, 실행 로직은 코드로 역할 분담을 하기 쉽기 때문입니다.

SKILL.md 작성 방법

SKILL.md에는 프런트매터(Frontmatter)로 이름과 설명을 두고, 본문에 스킬의 동작을 기술합니다.

---
name: seattle-tourism
description: Provides detailed tourism information about Seattle including attractions, restaurants, and local events.
...

에이전트는 이 기술을 바탕으로 사용 가능한 컨텍스트(Context)로서 스킬을 해석합니다.

resources 하위의 마크다운(Markdown) 파일은 관광지 목록이나 레스토랑 정보와 같은 참조 지식으로 사용할 수 있습니다.

실행 방법

전제 조건으로 .NET 9 SDK와 Azure CLI 로그인이 필요합니다.

az login
$env:AZURE_OPENAI_ENDPOINT = "https://your-openai-endpoint.openai.azure.com/"
$env:AZURE_OPENAI_DEPLOYMENT_NAME = "gpt-4.1-mini"

실행은 다음과 같습니다.

cd Sample12AgentSkillConsoleApp
dotnet run

실행하면 다음과 같은 흐름으로 결과가 표시됩니다.

• 파일 기반 스킬로 관광지와 날씨를 문의
• 인라인 스킬로 레스토랑과 날씨를 문의
• 믹스 구성으로 이동 수단과 관광을 동시에 문의

구현상의 포인트

1. 스킬의 배치 해결 (Placement Resolution)

Program에서는 실행 경로에서 skills를 찾을 수 없는 경우, 프로젝트 상대 경로로 폴백(Fallback)합니다.

이를 통해 bin 실행 시와 IDE 실행 시의 차이에 강해집니다.

2. 스크립트 함수의 설명 부여

Description 속성이나 AddScript의 설명문을 통해 LLM이 함수를 선택하기 쉬워집니다.

함수 이름뿐만 아니라 용도 설명을 정성껏 작성하는 것이 중요합니다.

3. 빌더(Builder)를 통한 단계적 합성

AgentSkillsProviderBuilder를 중심으로 스킬 소스를 나중에 추가할 수 있어, 단계적인 확장이 용이합니다.

PoC(Proof of Concept)부터 운영 환경까지 동일한 설계 사상으로 키워나갈 수 있습니다.

운영 환경에서의 주의점

• 스킬의 책임을 분할할 것
  하나의 SKILL에 모든 것을 담기보다, 업무 단위로 나누는 것이 유지보수하기 쉽습니다.
• 동적 데이터는 스크립트를 통해 처리할 것
  고정 정보는 resources에, 변동 정보는 AddScript 측에 배치하면 최신성 관리가 쉬워집니다.
• 버전 관리를 명확히 할 것
  SKILL.md와 resources의 업데이트 이력을 추적할 수 있도록 하여, 답변 변화의 원인을 추적할 수 있게 해둡니다.

요약

Sample12AgentSkillConsoleApp은 Agent Skills의 도입 패턴을 짧은 시간 안에 비교할 수 있는 좋은 교재입니다.

• 빠르게 시작하려면 파일 기반
• 엄격하게 제어하려면 인라인
• 실제 운용에서는 믹스 구성이 현실적

특히, 지식 파일(Knowledge File)과 실행 로직(Execution Logic)을 분리하여 설계할 수 있다는 점은 에이전트의 품질과 유지보수성(Maintainability)을 동시에 확보하는 데 있어 큰 이점입니다.

참고 링크

Discussion