LOTS-O

Digital garden

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

개념 노트2026.02.23 · Updated 2026.06.1311 min read

TL;DR

  • AI 에이전트의 컨텍스트 부족 문제를 구조적으로 해결하는 패턴이다.
  • Markdown 폴더 구조를 통해 에이전트에게 특정 작업 절차와 도메인 지식을 주입한다.

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 PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.
license: Apache-2.0           # [선택]
compatibility: Requires pdfplumber. Python 3.8+   # [선택] 환경 요구사항이 있을 때만 (≤500자)
metadata:                     # [선택] 임의 key-value 메타데이터
  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: 소문자·숫자·하이픈만 사용 가능(최대 64자), 하이픈으로 시작/끝낼 수 없고 연속 하이픈(--)도 불가하며, 부모 디렉토리명과 일치해야 한다.
  • description: 에이전트가 스킬 활성화 여부를 판단하는 결정 경계(Decision Boundary)이다(최대 1024자).
    • 무엇을 하는지(What)와 언제 사용하는지(When)를 함께 기술 한다. 명세는 두 가지를 모두 포함하고, 에이전트가 매칭할 수 있는 구체적 키워드를 담을 것을 권장한다.
    • 단, What 요약에서 그치지 말고 트리거 조건(When, 예: “Use when …“)을 반드시 포함한다. When이 누락되면 활성화 정확도가 떨어진다.
    • 자세한 작성 규칙은 섹션 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. description를 발견 가능성(Discoverability) 중심으로 작성: description은 에이전트가 스킬 활성화 여부를 판단하는 핵심 지표이다. 작성 시 다음 원칙을 준수해야 한다.
    • 무엇을 하는지(What)와 언제 사용하는지(When)를 모두 명시 한다. 명세는 두 요소를 함께 담고, 매칭에 도움이 되는 구체적 키워드를 포함할 것을 권장한다.
    • What 요약에서 그치지 않는다. 트리거 조건(When)이 빠지면 에이전트가 언제 활성화해야 할지 판단하기 어려워 정확도가 떨어진다.
    • 부정적 예시(Negative Examples) 를 명시하여 의도치 않은 오작동(False Positive)을 방지한다.
    • 3인칭 시점으로 작성하며, 길이는 최대 1024자를 넘지 않도록 한다(불필요하게 장황하지 않게 간결히 유지).
# BAD: 너무 막연하여 에이전트가 언제 써야 할지 판단 불가
description: Helps with PDFs.
 
# BAD: What만 있고 트리거 조건(When)이 없음
description: Extracts text and tables from PDF files, fills forms, and merges documents.
 
# GOOD: What(기능) + When(트리거 조건)을 함께 명시
description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.
  1. 단일 책임 원칙 준수: 각 스킬은 하나의 명확한 목적과 역할만 수행하도록 설계해야 한다. (예: 데이터 정제 프로세스와 데이터 분석 프로세스는 별도의 스킬로 분리)
  2. 컨텍스트 경량화 유지: SKILL.md 본문은 권장 5,000 토큰(대략 500줄) 이내로 관리한다. 방대한 레퍼런스나 부가 데이터는 references/ 디렉토리로 분리하여, 에이전트가 필요 시점에만 선택적으로 로드할 수 있도록 구조화한다.
  3. 키워드 커버리지 확보: 에이전트의 검색 확률을 높일 수 있는 유의미한 키워드를 스킬 문서 전반에 전략적으로 배치한다. 주요 에러 메시지, 증상 표현(예: flaky, hanging), 그리고 관련 도구명 등을 포함하는 것이 효과적이다.
  4. 표준화된 네이밍 규칙 적용: 스킬 명칭은 동명사(gerund) 형태를 기본으로 사용한다. (예: creating-skills 권장, skill-creation 지양)
  5. 트리거 동작 검증: 스킬 작성 완료 후에는 다양한 프롬프트 시나리오를 통해, 설계한 의도대로 스킬이 정확히 활성화되는지 반드시 테스트해야 한다.

6. 주의사항 및 보안

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

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

Connections

Reference

Discussion

Comments

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

그래프 뷰

백링크