AI 스킬(Agent Skills) 완전 가이드: 에이전트에게 절차를 가르치는 법

AI 스킬(Agent Skills)은 에이전트가 특정 작업을 매번 같은 품질로 수행하도록, 절차적 지식과 워크플로를 하나의 버전 관리되는 폴더로 패키징한 재사용 단위입니다. 프롬프트를 매번 길게 붙여넣거나, 같은 설명을 반복하는 대신, "이런 요청이 오면 이렇게 처리하라"는 플레이북을 한 번 작성해 두고 에이전트가 알아서 꺼내 쓰게 만드는 것이 핵심입니다. 이 글은 실무 엔지니어를 대상으로 스킬의 구조, 동작 원리, 그리고 현장에서 자주 어긋나는 부분을 구체적으로 다룹니다.

이 가이드의 내용은 Claude·OpenAI 계열·Google 계열 세 AI로 교차 검증(3-AI cross-verification)하여 정확성을 확인했습니다. 특히 모델·추론 관련 용어는 2026년 6월 현재 기준으로 최신 표현만 사용합니다.

AI 스킬이란 무엇인가

스킬은 한 문장으로 정의하면 **"에이전트가 언제·어떻게 행동할지 알려주는, 버전 관리되는 절차적 지식 폴더"**입니다. 진입점은 SKILL.md 파일 하나이며, 이 파일은 두 부분으로 구성됩니다.

• YAML 프런트매터: name과 description. 여기서 description은 단순 설명이 아니라 **활성화 트리거(activation trigger)**입니다. 에이전트가 "이 요청에 이 스킬을 써야 하나?"를 판단하는 자동 라우팅 키입니다.
• 마크다운 본문: 원칙, 단계별 절차(step-by-step), 검증(verification) 방법.

상세 레퍼런스는 references/ 폴더에, 실행 스크립트는 scripts/ 폴더에 분리해 둡니다. 전형적인 디렉터리 구조는 다음과 같습니다.

my-skill/
├── SKILL.md          # 진입점: 프런트매터 + 절차 본문
├── references/
│   └── api-spec.md   # 길고 상세한 참고 문서
└── scripts/
    └── validate.py   # 상대경로로 자기완결적 실행

SKILL.md의 최소 형태는 이렇습니다.

---
name: changelog-writer
description: >
  릴리스 노트나 CHANGELOG 항목을 작성/갱신할 때 사용.
  "체인지로그", "릴리스 노트", "변경 이력 정리" 요청에 트리거.
---

# Changelog 작성 절차

## 원칙
- Keep a Changelog 포맷 준수, 사용자 영향 중심 서술.

## 단계
1. `git log` 최근 태그 이후 커밋 수집
2. Added/Changed/Fixed/Removed로 분류
3. CHANGELOG.md 상단에 새 버전 블록 삽입

## 검증
- 날짜·버전 형식, 깨진 링크 확인 후 보고

점진적 공개(Progressive Disclosure)

스킬 설계의 핵심 메커니즘은 점진적 공개입니다. 컨텍스트 윈도를 절약하기 위해, 정보를 한꺼번에 로드하지 않고 필요한 시점에만 단계적으로 불러옵니다.

단계	로드되는 것	비용
평상시(idle)	각 스킬의 name + description만	매우 저렴
요청이 매칭됨	해당 SKILL.md 본문 전체	보통
실제 실행 시	references/·scripts/ 등 보조 파일	필요할 때만

평상시에는 "이 스킬이 무엇을 하는지"라는 한두 줄만 메모리에 띄워 두고, 요청이 들어와 매칭될 때 비로소 절차 본문을 읽으며, 수백 줄짜리 API 레퍼런스는 정말 실행하는 순간에만 펼친다 — 이 게으른 로딩이 토큰 예산을 지킨다.

수십 개의 스킬을 설치해도 평상시 컨텍스트 점유가 작은 이유가 바로 이것입니다. 그래서 description은 짧고 명확하게, 본문은 필요한 만큼 자세히, 대용량 문서는 references/로 분리하는 원칙이 자연스럽게 도출됩니다.

토큰 예산을 정밀하게 따져야 한다면, 모델별 정확한 토크나이저를 쓰세요. 예컨대 Claude의 토큰 수는 OpenAI용 tiktoken으로 추정하면 부정확하며, Anthropic의 count_tokens API를 사용해야 정확합니다. 비용 최적화 전반은 LLM 토큰 비용 최적화 가이드에서 자세히 다룹니다.

베스트 프랙티스 체크리스트

실무에서 검증된 설계 규칙을 체크리스트로 정리합니다.

• 1. description은 구체적이고 배타적으로. 자동 라우팅의 유일한 단서입니다. "문서 작업"처럼 모호하면 오발동하고, 트리거 표현(예: "릴리스 노트", "PR 리뷰")을 넣으면 정확히 매칭됩니다.
• 2. 한 스킬 = 한 책임. 하나의 스킬에 여러 워크플로를 욱여넣지 마세요. 라우팅이 흐려지고 유지보수가 어려워집니다.
• 3. 개인용과 프로젝트용을 분리. 개인 스킬은 ~/.claude/skills에, 팀 공유 스킬은 저장소의 .claude/skills에 두고 버전 관리합니다. 후자는 코드처럼 리뷰·PR 대상이 됩니다.
• 4. 대용량 문서는 references/로. 수백 줄짜리 API 명세나 스타일 가이드를 SKILL.md 본문에 붙여넣지 마세요. 본문은 절차의 골격만, 세부는 참조 파일로.
• 5. 스크립트는 상대경로·자기완결적으로. scripts/ 안의 코드는 스킬 폴더만 통째로 옮겨도 동작하도록 작성합니다. 절대경로·외부 환경 의존은 이식성을 깨뜨립니다.
• 6. 검증 단계를 본문에 명시. "무엇을 했는가"뿐 아니라 "성공을 어떻게 확인하는가"까지 절차에 포함하면 에이전트의 결과 신뢰도가 올라갑니다.
• 7. skill-creator 메타 스킬을 활용. 스킬을 만드는 스킬을 두면, 새 스킬의 구조·프런트매터·디렉터리 규칙을 일관되게 찍어낼 수 있습니다.

흔한 오해와 실수

오해 1: 스킬이 MCP/도구를 대체한다

가장 흔한 착각입니다. 스킬은 도구(tool)나 MCP를 대체하지 않습니다. 역할이 다릅니다.

• 도구·MCP: 세상에 실제로 작용하는 채널입니다. 파일을 읽고, API를 호출하고, DB에 쿼리하는 실행 수단.
• 스킬: 그 채널을 언제·어떻게 쓸지 알려주는 상위 레벨의 절차적 플레이북.

비유하자면 도구는 "손과 발", 스킬은 "작업 매뉴얼"입니다. 매뉴얼이 있어도 손발이 없으면 아무것도 못 하고, 손발만 있고 매뉴얼이 없으면 우왕좌왕합니다. 둘은 보완 관계이며, 좋은 스킬은 "이 단계에서는 X MCP의 Y 도구를 이렇게 호출하라"처럼 도구 사용을 절차 안에 엮어 줍니다.

오해 2: SKILL.md에 모든 걸 담아야 한다

SKILL.md 본문에 전체 API 레퍼런스, 긴 예시, 모든 엣지 케이스를 다 붙여넣는 실수입니다. 이렇게 하면 점진적 공개의 이점이 사라지고, 매칭될 때마다 거대한 본문이 컨텍스트를 잡아먹습니다. 본문은 절차의 흐름만, 세부는 **references/**로 미루세요.

실수 3: description을 설명문처럼만 쓴다

"이 스킬은 코드 리뷰를 도와줍니다" 같은 일반적 서술은 라우팅 신호가 약합니다. 트리거가 될 만한 구체 표현과 적용 범위를 함께 적어야 합니다. 동시에 너무 광범위하면 엉뚱한 요청에도 발동하므로, 포함 조건과 제외 조건을 같이 명시하는 것이 안전합니다.

실수 4: 모델 동작을 옛 용어로 가정한다

스킬 본문에서 모델 추론을 제어하려 할 때, 더 이상 쓰지 않는 용어로 작성하면 안 됩니다. 현재 Claude의 추론은 고정된 budget_tokens(폐기됨)가 아니라 **적응형 사고(adaptive thinking)와 노력 수준(effort level: low~xhigh/max)**으로 제어합니다. 또한 은퇴한 모델(예: Claude 3.7, o1/o3-mini)을 "현행"처럼 인용하지 마세요. 2026년 6월 기준 대표 플래그십은 Claude Opus 4.8 / GPT-5.5 / Gemini 3.5 Flash입니다. 스킬은 오래 재사용되므로, 본문에 휘발성 모델명을 박아 두기보다 "현행 플래그십 모델"처럼 추상화하는 편이 수명이 깁니다.

스킬은 더 큰 에이전트 시스템의 한 구성요소입니다. 스킬·도구·컨텍스트 관리를 하나의 루프로 엮는 설계는 에이전트 하니스 엔지니어링 가이드에서 이어집니다. 이 세 편(스킬·하니스·토큰 비용)은 하나의 시리즈입니다.

마무리

AI 스킬은 "프롬프트를 매번 다시 쓰는" 단계에서 "절차를 자산으로 축적하는" 단계로 넘어가게 해 주는 핵심 도구입니다. 요점을 정리하면:

1. 구조: SKILL.md(프런트매터 + 절차 본문) + references/ + scripts/. description은 활성화 트리거다.
2. 동작: 점진적 공개로 평상시엔 이름·설명만, 매칭 시 본문, 실행 시 보조 파일을 로드해 컨텍스트를 아낀다.
3. 설계 원칙: 한 스킬 한 책임, 구체적·배타적 description, 대용량은 references/로, 스크립트는 자기완결적으로.
4. 경계: 스킬은 MCP/도구를 대체하지 않는다 — 도구는 실행 채널, 스킬은 사용법 플레이북이다.
5. 정확성: 적응형 사고·노력 수준 같은 최신 용어를 쓰고, 모델 토큰은 해당 모델의 토크나이저(Claude는 count_tokens API)로 센다.

먼저 팀에서 가장 자주 반복하는 작업 하나를 골라 작은 스킬로 만들어 보세요. description을 잘 다듬어 자동 라우팅이 정확히 발동하는지 확인하고, 본문이 비대해지면 references/로 분리하는 리듬을 익히면 됩니다. 그다음 시리즈의 나머지 두 편으로 에이전트 전체 설계와 비용 통제를 완성하시기 바랍니다.

참고 자료

• Anthropic, "Agent Skills" 공식 문서: https://www.anthropic.com
• Claude Code Skills 문서: https://code.claude.com/docs/en/skills
• Agent Skills 사양(spec) 문서