목차
이 글은 Anthropic 엔지니어링 블로그에 2025년 10월 16일 게재된 “Equipping agents for the real world with Agent Skills” 를 읽고, 내용을 정리한 글입니다. 원문: https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
한 줄로 말하면 #
도메인 지식을 폴더 하나로 묶어두고, 에이전트가 필요할 때만 꺼내 쓰게 하는 패턴.
어떤 문제를 해결하려 했나 #
Claude는 똑똑하지만, 회사마다 다른 절차·관행·내부 지식은 모릅니다.
“PDF 양식에서 특정 필드만 추출해 SAP에 넣어야 해” — 사내 절차 “고객 문의 분류 규칙은 11종, 등급마다 처리 SLA 다름” — 운영 규칙 “내부 보고서는 무조건 이 템플릿 사용” — 조직 표준
이런 정보를 매번 시스템 프롬프트에 다 적어두면, 컨텍스트가 시작부터 가득 차고 정작 작업할 여유가 안 남습니다. 게다가 모든 작업에 모든 지식이 필요한 것도 아니에요.
이 글의 답: Agent Skills. 도메인 지식을 폴더에 넣어두고, 에이전트가 “이 일에는 이 폴더가 필요해” 라고 판단해서 그때그때 꺼내 쓰는 구조입니다.
해결책: SKILL.md 폴더 + 점진적 공개 #
1. 스킬은 그냥 ‘폴더 하나’ #
스킬은 표준화된 구조의 폴더입니다.
pdf/
├── SKILL.md ← 필수. YAML 메타데이터 + 본문
├── reference.md ← 선택. 상세 참고
├── forms.md ← 선택. 양식 처리 절차
└── extract.py ← 선택. 실행 가능한 스크립트SKILL.md의 앞부분(YAML frontmatter)에는 이름과 짧은 설명만 있습니다.
---
name: pdf
description: PDF 양식 채우기·필드 추출·문서 가공
---이 메타데이터만 시스템 프롬프트에 미리 로드됩니다. 본문이나 추가 파일은 나중에 필요할 때 로드돼요.
2. 점진적 공개(Progressive Disclosure) #
핵심 패턴입니다. 두꺼운 매뉴얼을 통째로 외우게 하는 대신, 목차 → 챕터 → 부록 순으로 필요한 만큼만 펴 봅니다.
[1단계] 메타데이터만
- 시작 시 스킬 이름·설명만 보임
- "이 작업에 이 스킬을 쓸까?" 판단용
[2단계] SKILL.md 본문
- 실제 작업할 스킬이라고 판단되면 로드
- "어떻게 해야 하는지" 절차 확인
[3단계] 링크된 파일·스크립트
- 특정 상황 마주쳤을 때만 reference.md, forms.md 로드
- 코드 실행이 필요하면 extract.py 도구로 실행효과: 컨텍스트 창 크기를 신경 쓸 필요가 줄어듭니다. 에이전트가 파일시스템과 코드 실행 도구를 갖고 있으면, “필요한 페이지만 펴서 본다” 가 자연스러워져요.
3. 시스템 프롬프트·도구·MCP와 어떻게 다른가 #
비슷해 보이지만 역할이 다릅니다.
| 시스템 프롬프트 | 도구(Tool) | MCP | Skill | |
|---|---|---|---|---|
| 언제 로드 | 항상 (시작 시) | 항상 (정의) | 항상 (연결 시) | 필요할 때 |
| 담는 것 | 행동 가이드 | 외부 호출 인터페이스 | 외부 서버 묶음 | 절차·지식·스크립트 통째 |
| 유리한 점 | 즉시 적용 | 정확한 입출력 | 외부 시스템 연동 | 컨텍스트 절약 + 조직 지식 패키징 |
스킬은 “새 입사자에게 주는 온보딩 매뉴얼” 에 가장 가깝습니다. 평소엔 책장에 꽂혀 있다가, 그 일을 할 때만 펴 봅니다.
안전과 활용 #
스킬은 코드 실행을 포함할 수 있어서 보안이 중요합니다. 원문 권장은 간단해요.
- 신뢰할 수 있는 출처에서만 설치
- 모르는 스킬은 설치 전에 모든 파일을 직접 읽어 검토
- 외부 서비스로 데이터를 빼내려는 지시가 없는지 확인
지원 플랫폼: Claude.ai, Claude Code, Claude Agent SDK, Claude Developer Platform — 한 번 만들면 여러 곳에서 재사용 가능합니다.
핵심 결론 #
에이전트에 도메인 지식을 가르치는 방법을 고민할 때, 사람들은 본능적으로 “시스템 프롬프트에 다 적어두자” 라고 생각합니다. 이 글의 답은 다릅니다.
“지식을 다 외우게 하는 게 문제인 줄 알았는데, 사실은 ‘필요할 때만 펴 볼 수 있게’ 정리하는 게 진짜 문제였다.”
스킬은 시스템 프롬프트·도구·MCP 위에 얹는 조직 지식 패키징 레이어입니다. #10의 context engineering 원칙(필요한 것만, 필요할 때)이 그대로 구현된 패턴이에요.
내 작업에 적용한다면 #
시나리오 1 — 일반적인 데이터 분석 과정 #
분석 팀마다 자기들만의 불문율이 있습니다. 컬럼 명명 규칙, 이상치 처리 관행, 보고서 양식. 이걸 매번 새 분석가나 LLM에 처음부터 설명하는 게 큰 비용이에요.
[Before — 매번 다시 설명]
새 분석 시작 시 톤·규칙·양식을 처음부터 프롬프트에 적기
→ 길어진 프롬프트, 핵심 지시 묻힘
[skill 패턴 적용]
.claude/skills/
├── data-cleaning/SKILL.md ← 결측치·이상치 처리 표준
├── reporting-template/SKILL.md ← 보고서 양식·시각화 규칙
├── domain-terms/SKILL.md ← 사내 용어집·약어
└── eda-checklist/SKILL.md ← EDA 체크리스트
→ 분석 종류에 맞는 스킬만 자동 로드
→ 컨텍스트는 항상 가볍게핵심: 분석 팀의 암묵지를 폴더로 명문화하면, 신입·LLM·외부 협업자 모두 같은 출발점에 섭니다.
시나리오 2 — 웹 사이트를 자동으로 운영할 때 #
운영 자동화도 똑같습니다. 사이트마다 고유한 운영 규칙이 있는데, 매 작업마다 처음부터 적으면 비효율적이에요.
[Before — 한 시스템 프롬프트에 모든 운영 규칙]
"톤 가이드 + 금지 표현 + SEO 규칙 + 법적 주의 + 배포 절차…"
→ 5,000자 프롬프트, 정작 중요한 규칙이 묻힘
[skill 패턴 적용]
.claude/skills/
├── tone-guide/SKILL.md ← 글쓰기 톤·예시
├── seo-meta/SKILL.md ← SEO 메타·키워드 정책
├── legal-review/SKILL.md ← 금지 표현·고지 의무
├── deploy/SKILL.md ← 배포 절차·롤백 스크립트
└── incident/SKILL.md ← 인시던트 대응 절차
→ 글 작성 시: tone-guide + seo-meta 자동 활성
→ 배포 시: deploy + legal-review 자동 활성
→ 장애 시: incident만 활성핵심: 운영 자동화의 안정성은 “맥락에 맞는 매뉴얼이 그때 그때 펼쳐지는 구조” 에서 옵니다. 모든 운영 지식을 한 프롬프트에 우겨넣는 건 정확히 반대 방향이에요.
Anthropic 엔지니어링 블로그를 오래된 순서대로 읽고 정리합니다.
