🪴 디지털 가든

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

10 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: Use when user requests PDF file operations such as text extraction, form filling, or document merging.
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)이다.
    • “Use when …”으로 시작하여 트리거 조건(When)만 기술 한다. 무엇을 하는지(What)나 절차(How)를 요약하면 에이전트가 SKILL.md 본문을 건너뛰는 문제가 발생한다.
    • 자세한 작성 규칙은 섹션 5 참고.

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. CSO(Claude Search Optimization) 원칙에 기반한 description 작성: description은 에이전트가 스킬 활성화 여부를 판단하는 핵심 지표이다. 작성 시 다음 원칙을 준수해야 한다.
    • “Use when …” 구문으로 시작 하여 명확한 트리거 조건(When)만을 명시한다.
    • 워크플로나 내부 절차(What/How)의 요약은 지양 한다. description에 워크플로가 포함될 경우 에이전트가 SKILL.md 본문을 참조하지 않고 축약된 실행을 시도하는 현상 존재.
    • 부정적 예시(Negative Examples) 를 명시하여 의도치 않은 오작동(False Positive)을 방지한다.
    • 3인칭 시점으로 작성하며, 가독성을 위해 500자 이내로 제한하는 것을 권장한다.
# BAD: 워크플로를 요약하여 에이전트가 본문을 건너뛰는 원인 제공
description: Extracts text and tables from PDF files, fills forms, and merges documents.
 
# GOOD: 명확한 트리거 조건만 기술
description: Use when user requests PDF file operations such as text extraction, form filling, or document merging.
  1. 단일 책임 원칙 준수: 각 스킬은 하나의 명확한 목적과 역할만 수행하도록 설계해야 한다. (예: 데이터 정제 프로세스와 데이터 분석 프로세스는 별도의 스킬로 분리)
  2. 컨텍스트 경량화 유지: SKILL.md 파일은 최대 5,000 토큰 이내로 관리해야 한다. 방대한 레퍼런스나 부가 데이터는 references/ 디렉토리로 분리하여, 에이전트가 필요 시점에만 선택적으로 로드할 수 있도록 구조화한다.
  3. 키워드 커버리지 확보: 에이전트의 검색 확률을 높일 수 있는 유의미한 키워드를 스킬 문서 전반에 전략적으로 배치한다. 주요 에러 메시지, 증상 표현(예: flaky, hanging), 그리고 관련 도구명 등을 포함하는 것이 효과적이다.
  4. 표준화된 네이밍 규칙 적용: 스킬 명칭은 능동형 동사(Gerund) 형태를 기본으로 사용한다. (예: creating-skills 권장, skill-creation 지양)
  5. 트리거 동작 검증: 스킬 작성 완료 후에는 다양한 프롬프트 시나리오를 통해, 설계한 의도대로 스킬이 정확히 활성화되는지 반드시 테스트해야 한다.

6. 주의사항 및 보안

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

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

Reference

Discussion

Comments

댓글은 승인 후 공개됩니다.

그래프 뷰