에이전트 스킬
더 많은 작업
- Agent Skills; 에이전트 스킬
- AI 에이전트가 필요할 때만 불러 쓰는 지침·스크립트·자료 꾸러미. SKILL.md 파일이 든 폴더 하나가 스킬 하나다
에이전트 스킬(Agent Skills)은 AI 에이전트에게 특정 작업을 하는 방법을 가르치기 위해 지침, 실행 스크립트, 참고 자료를 한 폴더에 묶어 두는 형식이다. 폴더 안의 SKILL.md 파일에 이름과 설명, 작업 지침을 적고, 필요하면 스크립트와 문서 파일을 곁들인다. 에이전트는 평소에는 스킬의 이름과 설명만 알고 있다가, 작업이 그 설명과 맞을 때 본문을 읽고, 본문이 가리키는 파일은 정말 필요할 때 연다.[1]
앤트로픽이 2025년 10월 16일 클로드 앱, 클로드 코드, API에 '스킬'(Skills)로 처음 도입했고, 2025년 12월 18일 여러 플랫폼에서 함께 쓸 수 있는 공개 표준으로 내놓았다.[2] 이후 OpenAI 코덱스, 깃허브 코파일럿, 커서, 제미나이 CLI 등 많은 에이전트 도구가 같은 형식을 읽는다.[3]
같은 프롬프트를 대화마다 붙여 넣는 대신, 회사나 팀의 업무 절차와 문서 양식, 도메인 지식을 버전 관리되는 폴더로 만들어 두고 에이전트가 알아서 꺼내 쓰게 한다는 것이 핵심이다. 범용 에이전트를 특정 업무의 전문가로 바꾸는 "입사 안내서"에 비유된다.[4]
스킬은 최소한 SKILL.md 하나가 든 폴더다. 나머지 하위 폴더는 권장 관례일 뿐 자유롭게 둘 수 있다.[1]
pdf-processing/
├── SKILL.md 필수: 머리말 + 지침
├── scripts/ 선택: 실행할 코드
├── references/ 선택: 필요할 때 읽을 문서
└── assets/ 선택: 템플릿, 그림, 데이터 파일
SKILL.md는 YAML 머리말(frontmatter)과 마크다운 본문으로 이루어진다.
---
name: pdf-processing
description: PDF에서 글과 표를 뽑고, 양식을 채우고, 여러 파일을 합친다. PDF 파일이나 양식, 문서 추출 이야기가 나오면 쓴다.
---
# PDF 처리
## 빠른 시작
pdfplumber로 글을 뽑는다. 양식 채우기는 references/FORMS.md를 본다.
양식 검증은 scripts/validate.py를 실행한다.
공개 규격의 머리말 필드는 다음과 같다.[1]
| 필드 | 필수 | 제약과 뜻 |
|---|---|---|
| name | 예 | 1~64자. 영문 소문자, 숫자, 하이픈만. 하이픈으로 시작·끝나거나 연달아 쓸 수 없다. 폴더 이름과 같아야 한다 |
| description | 예 | 1~1024자. 무엇을 하는지와 언제 써야 하는지를 함께 적는다. 에이전트가 스킬을 고르는 근거가 된다 |
| license | 아니요 | 라이선스 이름이나 동봉한 라이선스 파일 |
| compatibility | 아니요 | 최대 500자. 필요한 제품, 시스템 패키지, 네트워크 접근 같은 환경 요건 |
| metadata | 아니요 | 규격에 없는 속성을 담는 문자열 키·값 목록(작성자, 버전 등) |
| allowed-tools | 아니요 | 미리 허용할 도구 목록(실험적). 지원 여부는 도구마다 다르다 |
본문 형식에는 제한이 없다. 단계별 지침, 입출력 예시, 예외 상황을 적는 것이 권장되며, 본문은 500줄 이하로 줄이고 긴 참고 자료는 별도 파일로 빼라고 권한다. 다른 파일은 스킬 폴더 기준 상대 경로로 가리키고, 참조는 SKILL.md에서 한 단계 깊이까지만 두는 것이 좋다.[1]
스킬 방식의 중심 설계 원리는 점진적 공개(progressive disclosure)다. 모든 내용을 처음부터 컨텍스트 윈도우에 넣지 않고 세 단계로 나눠 필요한 만큼만 불러온다.[5]
| 단계 | 불러오는 때 | 내용 | 규모 |
|---|---|---|---|
| 1. 메타데이터 | 에이전트 시작 시 항상 | 모든 스킬의 name, description | 스킬당 약 100토큰 |
| 2. 지침 | 작업이 설명과 맞아 스킬이 선택될 때 | SKILL.md 본문 | 5,000토큰 미만 권장 |
| 3. 자원 | 지침이 가리키고 실제로 필요할 때 | 참고 문서, 템플릿, 스크립트 | 읽기 전까지 0 |
표의 규모는 공개 규격과 클로드 문서의 권장치다.[1][4] 이 구조 덕분에 스킬을 수십 개 설치해도 평소 맥락 비용은 설명 몇 줄에 그치고, 스킬 하나에 큰 API 문서나 데이터를 넣어도 쓰지 않으면 비용이 들지 않는다.
스크립트는 읽는 것이 아니라 실행하는 것이라는 점도 특징이다. 에이전트는 스크립트를 셸에서 돌리고 그 출력만 맥락으로 받는다. 정렬, 양식 검증처럼 코드로 하는 편이 토큰으로 생성하는 것보다 싸고 정확한 일은 스크립트로 맡겨 결과를 결정적으로 만든다.[5][4] 그래서 스킬은 파일 시스템과 코드 실행 환경이 있는 에이전트를 전제로 한다.
| 장치 | 무엇을 주나 | 언제 맥락에 들어가나 | 주요 용도 |
|---|---|---|---|
| 에이전트 스킬 | 절차적 지식(어떻게 하는지)과 그에 딸린 스크립트·자료 | 설명만 상시, 본문과 파일은 필요할 때 | 반복 업무 절차, 문서 양식, 사내 규칙, 도메인 지식 |
| AGENTS.md, CLAUDE.md 같은 지침 파일 | 프로젝트 전반의 규칙 | 세션 시작 때 항상 전부 | 빌드·테스트 명령, 코드 스타일 |
| 도구 호출 | 실행할 수 있는 함수 하나하나 | 도구 정의가 요청마다 들어감 | 계산, 검색, 외부 API 호출 |
| MCP | 외부 시스템의 도구·데이터를 연결하는 표준 통로 | 연결된 서버의 도구 정의(도구에 따라 지연 로딩) | 데이터베이스, 사내 서비스, SaaS 연결 |
| 하위 에이전트 | 별도 맥락과 권한을 가진 보조 에이전트 | 결과 요약만 본 대화로 돌아옴 | 출력이 많은 조사, 병렬 작업 |
MCP가 에이전트에게 손발(외부 도구 접근)을 준다면 스킬은 그 손발을 어떤 순서로 어떻게 쓰는지 알려 주는 업무 지식에 해당한다. 앤트로픽도 스킬이 MCP 서버와 보완 관계로 쓰이며, 외부 도구가 얽힌 복잡한 작업 흐름을 가르치는 데 쓰일 수 있다고 설명한다.[5] 클로드 코드에서는 스킬을 하위 에이전트 안에서 실행하게 하거나(context: fork), 하위 에이전트가 시작할 때 특정 스킬을 미리 읽게 할 수 있다.[6]
공개 규격 사이트는 클로드, 클로드 코드, ChatGPT·코덱스, 깃허브 코파일럿, VS Code, 커서, 제미나이 CLI, Junie, OpenCode, OpenHands, Amp, goose, Factory, Roo Code, Kiro 등 수십 개 도구를 지원 목록에 올려 두었다.[3] 주요 도구의 스킬 위치는 다음과 같다.
| 도구 | 프로젝트 스킬 | 사용자 스킬 | 비고 |
|---|---|---|---|
| 클로드 코드 | .claude/skills/이름/SKILL.md | ~/.claude/skills/ | 조직 관리 스킬, 플러그인 스킬도 있다. /이름으로 직접 부르거나 클로드가 스스로 고른다[6] |
| 클로드 앱·API | 설정에서 zip 업로드 / /v1/skills API | 코드 실행 도구가 필요하다. PowerPoint, Excel, Word, PDF용 기본 스킬 제공[4] | |
| OpenAI 코덱스 | .agents/skills (현재 폴더부터 저장소 루트까지) | $HOME/.agents/skills | 관리자(/etc/codex/skills), 내장 스킬. $이름으로 부르거나 자동 선택[7] |
| 깃허브 코파일럿 | .github/skills, .claude/skills, .agents/skills | ~/.copilot/skills, ~/.agents/skills | 클라우드 에이전트, 코드 리뷰, CLI, VS Code·JetBrains 에이전트 모드[8] |
| 제미나이 CLI | .gemini/skills 또는 .agents/skills | ~/.gemini/skills 또는 ~/.agents/skills | 같은 단계에서는 .agents 쪽이 우선[9] |
.agents/skills라는 도구 중립 경로를 여러 도구가 함께 읽기 때문에, 한 저장소에 스킬을 한 벌만 두고 여러 에이전트에서 쓸 수 있다.
공개 규격은 최소한의 필드만 정하고, 도구마다 확장 필드를 덧붙인다. 클로드 코드는 사용자만 부를 수 있게 하는 disable-model-invocation, 모델만 쓰게 하는 user-invocable: false, 하위 에이전트에서 돌리는 context: fork, 모델·추론 강도 지정, 그리고 스킬을 읽기 전에 셸 명령을 실행해 결과를 본문에 끼워 넣는 동적 맥락 주입 문법을 지원한다. 예전의 사용자 정의 슬래시 명령(.claude/commands/)은 스킬로 합쳐졌다.[6] 코덱스는 agents/openai.yaml로 화면 표시 정보와 호출 정책을 따로 적는다.[7]
스킬은 지침과 실행 코드로 에이전트의 행동을 바꾸므로, 남이 만든 스킬을 설치하는 것은 소프트웨어를 설치하는 것과 같은 위험을 진다. 앤트로픽 문서는 직접 만들었거나 앤트로픽이 제공한 것처럼 신뢰할 수 있는 출처의 스킬만 쓰라고 권하며 다음 위험을 든다.[4][5]
- 악성 스킬은 설명과 다른 목적으로 도구를 부르거나 코드를 실행해 데이터를 빼내거나 시스템에 무단 접근할 수 있다.
- 외부 URL에서 내용을 받아 오는 스킬은 그 내용에 숨은 지시가 섞일 수 있다(간접 프롬프트 인젝션). 처음에는 믿을 만했던 스킬도 외부 의존성이 바뀌면 오염될 수 있다.
- 민감한 데이터에 접근할 수 있는 스킬은 정보를 외부로 흘리도록 설계될 수 있다.
- 따라서 SKILL.md뿐 아니라 동봉된 스크립트, 그림, 자료 파일까지 모두 살펴보고, 예상 밖의 네트워크 호출이나 파일 접근이 없는지 확인해야 한다.
실행 환경도 도구마다 다르다. 클로드 API의 스킬은 네트워크가 막힌 격리 컨테이너에서 돌아가지만, 클로드 코드의 스킬은 사용자 컴퓨터의 다른 프로그램과 같은 네트워크 권한을 가진다.[4]
- ↑ 1.0 1.1 1.2 1.3 1.4 1.5 Agent Skills, Specification
- ↑ Anthropic, Claude 블로그 Skills 발표, 2025-10-16 (2025-12-18 갱신)
- ↑ 3.0 3.1 Agent Skills, Overview
- ↑ 4.0 4.1 4.2 4.3 4.4 4.5 Claude 개발자 문서, Agent Skills overview
- ↑ 5.0 5.1 5.2 5.3 Barry Zhang, Keith Lazuka, Mahesh Murag, Equipping agents for the real world with Agent Skills, Anthropic Engineering, 2025-10-16
- ↑ 6.0 6.1 6.2 Claude Code 문서, Extend Claude with skills
- ↑ 7.0 7.1 7.2 OpenAI 코덱스 문서, Build skills
- ↑ GitHub Docs, About agent skills
- ↑ Gemini CLI 문서, Agent Skills