🪴 디지털 가든

Agent Skills - AI 에이전트에게 전문성을 부여하는 방법

8 min read

Agent Skills: AI 에이전트에게 전문성을 부여하는 방법

AI 에이전트의 역량은 비약적으로 향상되고 있으나, 실제 환경(Real-world)에서 업무를 안정적으로 수행하기에는 컨텍스트가 부족한 경우가 많다. Skills는 이러한 문제를 구조적으로 해결하기 위해 제안된 패턴이다.

1. Skills의 정의

Skill은 AI 에이전트의 기능을 확장하기 위한 폴더 단위의 지식 패키지이다. 단순히 시스템 프롬프트에 설명을 추가하는 방식과 달리, Skill은 에이전트가 탐색, 활성화, 실행의 흐름에 따라 필요한 시점에만 관련 컨텍스트를 로드하도록 설계된다. 이를 통해 에이전트에게 새로운 기능을 추가하고, 반복 가능한 워크플로를 구축하며, 다양한 에이전트 간의 스킬 호환성을 확보할 수 있다.

2. 폴더 구조 및 작성 규격

스킬은 다음과 같은 표준화된 폴더 구조를 가진다.

my-skill/
├── SKILL.md          # [필수] 지시사항 및 메타데이터
├── scripts/          # [선택] 실행 가능한 코드
├── references/       # [선택] 기술 문서 및 참고 자료
└── assets/           # [선택] 템플릿, 리소스 등

SKILL.md 작성법

SKILL.md는 에이전트가 스킬을 이해하고 실행하는 핵심 문서이다. Frontmatter를 통해 기계가 읽을 수 있는 메타데이터를 제공해야 한다.

---
name: pdf-processing
description: Extracts text and tables from PDF files, fills forms, and merges documents.
license: Apache-2.0
compatibility: Requires pdfplumber. Python 3.8+
metadata:
  author: example-org
  version: "1.0"
allowed-tools: Bash(python:*)
---
 
# PDF Processing
 
## When to use this skill
사용자가 PDF 파일 작업을 요청할 때 이 스킬을 사용한다.
 
## Step-by-step instructions
1. 텍스트 추출을 위해 pdfplumber를 사용한다.
2. ...
  • name: 소문자, 숫자, 하이픈만 사용 가능하며 디렉토리명과 일치해야 한다.
  • description: 에이전트가 스킬 사용 여부를 판단하는 결정 경계(Decision Boundary)이다. 무엇을 하는지뿐만 아니라 언제 사용하지 말아야 하는지도 명시하는 것이 좋다.

3. 동작 원리: Progressive Disclosure

컨텍스트를 효율적으로 관리하기 위해 3단계 로딩 시스템을 사용한다.

flowchart LR
    A[사용자 요청] --> B{"에이전트<br/>탐색 단계"}
    B --> C["name + description<br/>목록 로드"]
    C --> D{"태스크 ↔ Skill<br/>매칭?"}
    D -- "매칭됨" --> E["SKILL.md 읽어서<br/>컨텍스트에 추가"]
    D -- "매칭 안됨" --> F[기본 동작]
    E --> G{"scripts / assets<br/>필요?"}
    G -- "필요" --> H["references & assets<br/>참조 후 코드 실행"]
    G -- "불필요" --> I[지시사항에 따라 실행]
    H --> I
    F --> I
    I --> J[응답 반환]
단계대상토큰 규모로드 시점
1. 탐색name + description~100 tokens에이전트 시작 시 (항상)
2. 활성화SKILL.md 전문< 5,000 tokens 권장스킬 활성화 시
3. 실행scripts/, references/필요한 파일만 로드실행 중 필요 시

4. Skills vs MCP (Model Context Protocol)

MCP와 Skills는 에이전트의 능력을 확장한다는 공통점이 있으나 그 역할이 다르다. 둘은 상호 보완적인 관계이다.

flowchart TB
    subgraph MCP["🔌 MCP"]
        direction LR
        M1[외부 API 연결]
        M2[실시간 데이터 조회]
        M3[도구 호출 표준화]
    end

    subgraph Skills["📁 Skills"]
        direction LR
        S1[도메인 지식 주입]
        S2[작업 절차 패키징]
        S3[에이전트 행동 가이드]
    end

    Agent["🤖 AI Agent"] --> MCP
    Agent --> Skills
구분SkillsMCP
목적에이전트에게 방법(How) 을 주입에이전트에게 도구(Tool) 를 제공
형태Markdown 기반 텍스트 지식서버-클라이언트 프로토콜
실행 주체에이전트 자신 (내부 추론)외부 서버 (함수 호출)
적합한 경우반복 절차, 도메인 전문 지식외부 API 연동, 실시간 데이터

5. Skills 작성 및 운영 팁

  1. 결정 경계의 명확화: description에 부정적 예시(Negative Examples)를 포함하여 오작동을 방지한다.
  2. 단일 책임 원칙: 하나의 스킬은 하나의 명확한 역할만 담당하도록 분리한다. (예: 데이터 정제와 데이터 분석을 별도 스킬로 분리)
  3. 경량화 유지: SKILL.md는 5,000 토큰 이내로 유지하며, 방대한 레퍼런스는 references/ 폴더로 분리하여 에이전트가 필요할 때만 읽도록 유도한다.
  4. 트리거 테스트: 작성 후 실제 프롬프트를 통해 의도한 대로 스킬이 활성화되는지 반드시 검증한다.

6. 주의사항 및 보안

Agent Skills는 코드 실행을 포함할 수 있으므로 보안에 유의해야 한다.

  • 출처 검증: 신뢰할 수 있는 저장소나 공식 파트너의 스킬만 설치한다.
  • 네트워크 감시: 스크립트가 인가되지 않은 외부 통신을 수행하는지 확인한다.
  • 민감 정보 보호: 스킬이 시스템의 API 키나 개인 정보에 직접 접근하지 않도록 제한한다.

📎 Reference

그래프 뷰