Agent 스킬 설계와 생성

1 스킬이란

스킬(Skill)은 AI Agent가 특정 전문 영역의 업무를 수행하는 데 필요한 지식, 실행 방법, 참고 자료를 하나로 묶은 재사용 가능한 지식 패키지이다.

정의: Skill

Agent가 특정 태스크를 수행할 때 로드하는 마크다운 기반 지침서 + 부속 자원의 묶음이다. 시스템 프롬프트에 모든 지식을 한꺼번에 넣는 대신, 필요한 시점에 필요한 스킬만 동적으로 로드하여 컨텍스트 효율성과 태스크 정확도를 동시에 확보한다.

스킬은 복잡한 프로그래밍으로 구성되지 않는다. 핵심은 마크다운(.md) 파일이며, 부가 자원은 필요에 따라 선택적으로 구성한다. 이 구조 덕분에 개발자뿐 아니라 도메인 전문가도 자신의 업무 노하우를 Agent에게 전달할 수 있다.

1.1 스킬이 필요한 이유

문제	스킬 없이	스킬 적용 시
컨텍스트 과부하	모든 지침을 시스템 프롬프트에 포함 → 토큰 한도 초과, 지시 망각	필요한 스킬만 동적 로드 → 컨텍스트 효율적 활용
전문성 부재	범용 지식으로 도메인 태스크 수행 → 부정확한 결과	도메인 전문 지식을 스킬로 주입 → 전문가 수준 결과
결과 불일관	매번 다른 형식, 다른 품질의 산출물	정해진 체계와 템플릿 위에서 작업 → 일관된 품질 보장
재사용 불가	매 세션마다 동일한 지시를 반복 입력	스킬 한 번 작성 → 무한 재사용

LangChain이 공개한 스킬 세트 실험에서, 스킬 적용만으로 LangChain 관련 태스크 통과율이 25%에서 95%로 향상되었다. 모델을 교체하지 않고 올바른 컨텍스트를 올바른 시점에 제공하는 것만으로 성능이 4배 이상 개선된 사례이다.

스킬의 개념적 배경과 LangChain 스킬 세트 분석은 스킬 기반 Agent 패턴에서 상세히 다룬다. 본 포스트는 스킬을 직접 설계하고 생성하는 실전 절차에 초점을 맞춘다.

2 스킬의 구성 요소

스킬은 기본적으로 하나의 폴더이며, Agent가 업무를 수행하는 데 필요한 지침과 자원이 체계적으로 정리되어 있다.

2.1 폴더 구조

my-analysis-skill/                # 스킬 폴더
├── SKILL.md                      # 필수: 스킬의 메인 지침서
├── scripts/                      # 선택: 자동화 스크립트
│   └── validate_output.py
├── examples/                     # 선택: 참고할 성공 사례
│   └── sample_output.md
└── resources/                    # 선택: 템플릿, 참조 데이터
    ├── report_template.md
    └── industry_data.csv

구성 요소	역할	필수 여부
SKILL.md	스킬의 메인 지침서. 트리거 조건, 작업 절차, 규칙을 정의한다	필수
scripts/	반복적이거나 복잡한 처리를 자동화하는 스크립트	선택
examples/	Agent가 참고할 수 있는 성공적인 결과물 샘플	선택
resources/	템플릿, 기준 데이터, 참조 문서 등 업무 중 활용할 자료	선택

examples/의 중요성은 과소평가되기 쉽다. 좋은 예제가 주어지면 Agent는 산출물의 형식과 품질을 훨씬 빠르고 정확하게 맞출 수 있다. 추상적인 규칙 10줄보다 구체적인 예시 1개가 더 효과적인 경우가 많다.

2.2 SKILL.md의 내부 구조

SKILL.md는 크게 두 영역으로 구성된다.

---
name: data-analysis-report
description: >
  사용자가 CSV/Excel 데이터를 업로드하고 "분석해줘", "보고서 만들어줘"라고
  요청할 때 활성화된다. 탐색적 데이터 분석(EDA)을 수행하고
  구조화된 보고서를 생성한다.
---

## 작업 목표

업로드된 데이터에 대해 탐색적 데이터 분석을 수행하고,
재현 가능한 분석 보고서를 생성한다.

## 작업 절차

### Step 1: 데이터 검증
- 파일 형식 확인 (CSV, Excel, JSON)
- 컬럼명, 데이터 타입, 결측치 비율 파악
- 데이터 행/열 수 보고

### Step 2: 탐색적 분석
- 기술통계량 산출 (평균, 중앙값, 표준편차, 사분위수)
- 분포 확인 (정규성, 이상치)
- 변수 간 상관관계 분석

### Step 3: 보고서 생성
- 마크다운 형식으로 분석 결과 정리
- 핵심 발견사항 3~5개를 bullet으로 요약
- 후속 분석 제안 포함

## 규칙
- 원본 데이터를 수정하지 않는다
- 수치는 소수점 2자리까지 표시한다
- 이상치 제거 시 반드시 근거를 명시한다

영역	역할	핵심 포인트
프론트매터 (YAML)	스킬의 이름과 트리거 조건을 정의한다	description이 Agent가 “이 스킬을 지금 써야 하는가?”를 판단하는 기준이 된다
본문 (Markdown)	작업 목표, 절차, 규칙을 상세히 기술한다	숙련된 실무자의 인수인계 매뉴얼 수준으로 구체적일수록 좋다

프론트매터의 description은 단순한 설명이 아니다. Agent가 수많은 스킬 중에서 현재 태스크에 맞는 스킬을 자동으로 선택하는 트리거 역할을 한다. 따라서 “어떤 상황에서 이 스킬이 활성화되어야 하는가”를 구체적으로 기술해야 한다.

3 프로그레시브 디스클로저: 스킬의 작동 원리

스킬이 컨텍스트를 효율적으로 사용하면서도 높은 정확도를 달성할 수 있는 이유는 프로그레시브 디스클로저(Progressive Disclosure) 원리 덕분이다. 모든 정보를 한꺼번에 주입하는 대신, 필요한 순간에 필요한 만큼만 단계적으로 로드한다.

3.1 3단계 로드 과정

┌─────────────────────────────────────────────────────┐
│  1단계: 탐색 (Discovery)                             │
│  ─────────────────────────                           │
│  사용자 요청 분석 → 스킬 목록의 name/description만   │
│  확인하여 "어떤 스킬이 필요한가?" 판단               │
│  (전체 지침을 읽지 않으므로 컨텍스트 절약)            │
├─────────────────────────────────────────────────────┤
│  2단계: 활성화 (Activation)                          │
│  ─────────────────────────                           │
│  선택된 스킬의 SKILL.md 전체를 로드하여               │
│  작업 절차, 규칙, 예외 처리를 파악                    │
├─────────────────────────────────────────────────────┤
│  3단계: 실행 (Execution)                             │
│  ─────────────────────────                           │
│  스킬 지침에 따라 태스크 수행                         │
│  필요 시 scripts/, examples/, resources/ 참조         │
└─────────────────────────────────────────────────────┘

이 방식은 운영체제의 지연 로딩(Lazy Loading)과 동일한 원리이다. 프로그램이 시작될 때 모든 라이브러리를 메모리에 올리지 않고, 실제로 호출될 때 비로소 로드하여 메모리를 절약하는 것처럼, Agent도 현재 태스크에 필요한 스킬만 컨텍스트에 로드하여 토큰을 절약한다.

3.2 기존 방식 vs 스킬 기반 방식

[기존] 모든 문서를 시스템 프롬프트에 포함
       → 컨텍스트 과부하 → 지시 누락 → 성능 저하

[스킬] 태스크 분석 → 관련 스킬만 선택 로드 → 집중된 컨텍스트 → 높은 정확도

4 스킬 설계 실전 가이드

스킬을 직접 만드는 방법은 크게 두 가지이다.

4.1 방법 1: 백지 상태에서 설계

업무 요구사항을 분석하고 스킬을 처음부터 설계하는 정석적인 방법이다.

설계 단계:

1. 태스크 정의: Agent가 수행할 업무의 범위와 목표를 명확히 한다
2. 트리거 조건 설계: 어떤 요청이 들어올 때 이 스킬이 활성화되어야 하는지 정의한다
3. 작업 절차 분해: 전체 업무를 순차적인 단계(Step)로 분해한다
4. 규칙과 예외 정의: 각 단계에서 지켜야 할 규칙과 예외 상황 처리를 명시한다
5. 예시와 템플릿 준비: Agent가 참고할 수 있는 산출물 샘플을 작성한다

4.2 방법 2: 작업 세션에서 추출

실제로 Agent와 함께 태스크를 수행한 뒤, 그 과정을 스킬로 변환하는 방법이다. 경험상 이 방법이 스킬의 완성도가 가장 높다.

그 이유는 명확하다. 시행착오 과정과 Agent가 문제를 해결한 방법이 대화 컨텍스트에 고스란히 남아 있기 때문에, 생성되는 스킬의 에러 대처 능력이 크게 향상된다. 백지 상태에서는 예측하기 어려운 예외 상황이 실제 작업 과정에서 자연스럽게 드러나고, 이것이 스킬에 반영된다.

추출 절차:

1. Agent와 함께 태스크를 완수한다
2. 수행 과정에서 발생한 시행착오와 해결 방법을 확인한다
3. 성공적인 결과물을 examples/에 저장한다
4. 전체 과정을 SKILL.md의 작업 절차로 구조화한다

4.3 SKILL.md 작성 핵심 원칙

구성 요소	작성 핵심
이름 (Name)	스킬의 용도를 영문 하이픈 연결로 명확히 표현한다 (예: data-analysis-report, code-review-checklist)
설명 (Description)	어떤 키워드와 상황에서 이 스킬이 활성화되어야 하는지 구체적으로 기술한다. 트리거 정확도를 결정하는 가장 중요한 필드이다
작업 절차 (Workflow)	모호하게 뭉뚱그리지 않는다. “데이터 분석 후 보고서 작성”이 아니라 “Step 1: 컬럼명 검증 → Step 2: 결측치 비율 산출 → Step 3: 기술통계 산출 → Step 4: 보고서 생성”처럼 잘게 분할할수록 완성도가 높아진다
입출력 포맷	입력 데이터의 예상 형식과 산출물의 형식을 분명하게 명시한다
예외 처리	“데이터가 비어 있으면 에러를 발생시키지 말고 경고 메시지를 출력한다” 등 구체적인 예외 처리를 지시하면 스킬의 안정성이 보장된다

흔한 설계 실수

• Description이 너무 추상적: “데이터 관련 작업에 사용” → Agent가 언제 이 스킬을 선택해야 하는지 판단할 수 없다. “사용자가 CSV/Excel 파일을 업로드하고 분석, EDA, 보고서를 요청할 때 활성화”처럼 구체적으로 써야 한다.
• 절차가 뭉뚱그려져 있음: “데이터를 분석한다” → Agent가 어떤 분석을 어떤 순서로 해야 하는지 모른다. 단계별로 분해해야 한다.
• 예외 처리 누락: 정상 경로만 기술하면 예외 상황에서 Agent가 멈추거나 잘못된 결과를 산출한다.

5 스킬 등록과 관리

5.1 스킬 등록 방식

스킬의 저장 방식에 따라 크게 두 가지로 나뉜다.

방식	저장 위치	특징	적합한 상황
로컬 스킬	프로젝트 폴더 내	버전 관리(Git) 가능, 팀 공유 용이, IDE에서 직접 편집	Claude Code, Cursor 등 로컬 환경에서 개발할 때
클라우드 스킬	서비스 제공자 계정	로그인만 하면 어디서든 접근 가능, 디바이스 간 동기화	웹 기반 AI 서비스(Claude.ai 등)를 사용할 때
공개 레지스트리	skills.sh	커뮤니티가 공유한 검증된 스킬을 npx로 즉시 설치	범용 스킬을 빠르게 도입하거나 스킬 설계 참고용

로컬 스킬은 프로젝트 저장소에 스킬 폴더를 두고 Git으로 버전 관리하는 방식이다. 팀원과 스킬을 공유하고 리뷰할 수 있으며, 코드와 동일한 워크플로로 관리할 수 있다는 장점이 있다.

project-root/
├── src/
├── tests/
└── skills/                    # 스킬 저장소
    ├── code-review/
    │   ├── SKILL.md
    │   └── examples/
    ├── data-analysis/
    │   ├── SKILL.md
    │   ├── scripts/
    │   └── resources/
    └── report-generation/
        ├── SKILL.md
        └── examples/

5.2 공개 스킬 생태계: skills.sh

로컬·클라우드 방식이 자신이 만든 스킬을 관리하는 방법이라면, skills.sh는 커뮤니티가 만든 스킬을 발견하고 내려받는 공개 생태계이다. Vercel이 운영하는 오픈 소스 프로젝트로, Agent가 특정 도메인 업무를 수행하는 데 필요한 절차 지식을 패키지 형태로 공유한다.

skills.sh

• 정의: AI Agent용 재사용 가능한 스킬의 공개 레지스트리
• 운영: Vercel Labs (오픈 소스: github.com/vercel-labs/skills)
• 지원 Agent: Claude Code, GitHub Copilot, Cursor, Cline, Windsurf, Gemini, Codex 등 20개 이상

5.2.1 설치 방법

별도 설치 없이 npx로 즉시 실행한다.

# 단일 스킬 설치
npx skills add vercel-labs/agent-skills

# 특정 스킬 지정
npx skills add <owner/repo>

명령 실행 시 스킬 파일이 자동으로 내려받아져 해당 Agent의 컨텍스트에 로드된다.

5.2.2 주요 스킬 리더보드

리더보드는 익명 설치 횟수를 기준으로 순위화된다. 인기 스킬의 경향을 보면 스킬 생태계가 어떤 문제를 해결하려 하는지 파악할 수 있다.

순위	스킬명	게시자	설치 수
1	find-skills	vercel-labs	734K
2	vercel-react-best-practices	vercel-labs	252K
3	frontend-design	anthropics	206K
4	web-design-guidelines	vercel-labs	203K
5	remotion-best-practices	remotion-dev	178K

최신 리더보드는 skills.sh에서 확인한다.

5.2.3 텔레메트리

CLI는 기본적으로 어떤 스킬이 설치되었는지 익명 집계 데이터를 수집하여 리더보드 순위에 반영한다. 개인 정보나 사용 패턴은 수집하지 않는다. 수집을 원하지 않을 때는 환경변수로 비활성화한다.

DISABLE_TELEMETRY=1 npx skills add <owner/repo>

5.2.4 로컬·클라우드 방식과의 비교

방식	스킬 출처	주요 용도
로컬 스킬	직접 작성	팀 전용 도메인 지식 관리
클라우드 스킬	직접 작성	디바이스 간 동기화
skills.sh	커뮤니티	잘 검증된 범용 스킬을 빠르게 도입

직접 스킬을 설계하기 전에 skills.sh에서 유사한 스킬이 이미 존재하는지 확인하는 것이 효율적이다. 기존 스킬을 참고하면 SKILL.md의 구조와 description 작성법을 실제 사례에서 학습할 수 있다.

5.3 스킬 수 관리

스킬의 수는 Agent의 성능에 직접적인 영향을 미친다.

스킬 수	효과
0~5개	탐색 비용이 낮아 빠르게 활성화된다. 소규모 프로젝트에 적합하다
5~15개	적절한 범위. Description의 품질이 중요해진다
15개 이상	탐색 단계에서 혼란이 발생할 수 있다. 카테고리별 그룹화나 계층 구조가 필요하다

스킬 수가 많아지면 Agent가 1단계(탐색)에서 올바른 스킬을 선택하지 못할 확률이 높아진다. 이 경우 마스터 스킬을 두어 라우팅하는 계층적 구조를 도입한다.

master-guide.md          # 태스크 유형별 어떤 스킬을 로드할지 라우팅
├── skill-group-A/       # 데이터 분석 관련
│   ├── eda-skill/
│   └── report-skill/
└── skill-group-B/       # 코드 관련
    ├── review-skill/
    └── test-skill/

이 계층 구조 자체가 프로그레시브 디스클로저의 확장이다. Agent는 먼저 마스터 가이드에서 태스크 유형을 판단하고, 해당 그룹의 스킬만 탐색한다.

이 블로그 저장소 자체가 계층적 스킬 구조의 실전 사례이다. AGENT_GUIDE.md가 마스터 가이드 역할을 하고, 카테고리별 GUIDE.md와 guides/ 폴더의 스킬 파일이 태스크별 지침을 제공한다. 상세 분석은 스킬 패턴의 실전 적용: 블로그 지식 관리 시스템에서 다룬다.

6 스킬 품질 점검 체크리스트

스킬을 작성한 후 아래 항목을 점검한다.

점검 항목	질문	미충족 시 조치
트리거 명확성	Description만 읽고 “언제 이 스킬을 쓸지” 판단할 수 있는가	트리거 상황과 키워드를 구체적으로 보강한다
절차 완결성	도메인 지식이 없는 Agent도 절차만 따르면 태스크를 완수할 수 있는가	암묵적 전제를 명시적 단계로 분해한다
예외 처리	입력 데이터가 비정상일 때 Agent가 어떻게 행동해야 하는지 정의되어 있는가	주요 예외 경로를 추가한다
예시 품질	examples/의 산출물이 기대 수준을 대표하는가	정상 케이스와 엣지 케이스를 모두 포함한다
스킬 간 독립성	다른 스킬의 내용을 전제하지 않고 단독으로 작동하는가	의존하는 정보를 스킬 내부에 포함하거나 참조 경로를 명시한다

7 관련 주제

선행 지식

• 스킬 기반 Agent 패턴 – 스킬 개념, LangChain 스킬 세트 분석, 프로그레시브 디스클로저 원리
• 스킬 역분석: Agent용 시스템 프롬프트 작성 원리 – SKILL.md 내부의 프롬프트 엔지니어링 기법 8가지

후속 주제

• 스킬 패턴의 실전 적용: 블로그 지식 관리 시스템 – 계층적 스킬 구조의 실제 구현 사례
• MCP 기반 도구 통합 – 스킬이 외부 도구와 연동할 때 사용하는 표준 프로토콜
• 코드베이스 분석 Agent의 스킬 설계 – 복잡한 도메인에 스킬 패턴을 적용한 설계 사례