AI 코딩 에이전트를 두 개 이상 쓰다 보면 같은 설명을 도구마다 다시 붙여 넣게 됩니다. 배포 순서, 코드 리뷰 체크리스트, 보고서 양식 같은 것들입니다. 에이전트 스킬(Agent Skills)은 이런 절차를 폴더 하나에 담아 두고 에이전트가 필요할 때 꺼내 읽게 하는 형식입니다. 지금은 Claude Code, Codex, Antigravity가 모두 같은 SKILL.md 파일을 읽습니다.
그럼 한 번 만든 스킬은 어디서나 그대로 돌아갈까요. 파일 형식은 그대로 통합니다. 다만 폴더를 두는 자리, 도구마다 덧붙인 설정, 목록에 실리는 설명의 길이는 도구마다 다릅니다. 이 글은 스킬이 어떤 구조이고 왜 여러 도구가 같은 형식을 받아들였는지, 옮길 때 무엇이 같고 무엇이 다른지를 2026년 9월 25일 각 도구의 공식 문서 기준으로 정리합니다.
스킬은 SKILL.md가 든 폴더 하나입니다
명세상 스킬은 SKILL.md 파일이 든 폴더입니다. 필요하면 스크립트, 참고 문서, 템플릿을 같은 폴더에 함께 넣습니다.
pdf-processing/
├── SKILL.md # 필수: 메타데이터 + 지시
├── scripts/ # 선택: 실행할 코드
├── references/ # 선택: 필요할 때 읽을 문서
└── assets/ # 선택: 템플릿, 데이터SKILL.md는 YAML frontmatter와 Markdown 본문으로 나뉩니다. 명세가 드는 좋은 예를 우리말로 옮기면 이렇습니다.
---
name: pdf-processing
description: PDF에서 글과 표를 뽑고, PDF 양식을 채우고, 여러 PDF를 합칩니다. PDF 문서를 다루거나 사용자가 PDF·양식·문서 추출을 말할 때 씁니다.
---
(여기부터 에이전트가 따를 작업 지시)name은 64자 이내의 소문자·숫자·하이픈이고 폴더 이름과 같아야 합니다. description은 1,024자 이내로, 이 스킬이 무엇을 하고 언제 쓰는지를 적습니다. 선택 항목은 license, compatibility(필요한 환경), metadata, allowed-tools(미리 허용할 도구) 넷입니다. allowed-tools는 아직 실험 단계라 도구마다 지원이 다릅니다. 본문 형식에는 제한이 없습니다.
Anthropic은 스킬 만들기를 신입 직원에게 줄 온보딩 가이드를 쓰는 일에 비유합니다. 실제 업무에는 모델의 일반 지식 말고도 절차와 조직의 맥락이 필요하고, 그걸 파일과 폴더로 건네는 방법이 스킬이라는 설명입니다.
핵심은 필요할 때만 읽는 구조입니다
스킬이 여러 개 쌓여도 부담이 크지 않은 건 에이전트가 스킬을 세 단계로 나눠 읽기 때문입니다. 명세는 이 방식을 점진적 공개(progressive disclosure)라고 부릅니다.
- 발견: 에이전트가 시작할 때 설치된 모든 스킬의 이름과 설명만 읽습니다. 스킬당 약 100토큰입니다.
- 활성화: 지금 하는 일이 어떤 스킬의 설명과 맞으면 그 스킬의 SKILL.md 본문 전체를 읽습니다. 명세는 본문을 5,000토큰 미만, 500줄 이하로 두라고 권합니다.
- 실행: 본문을 따르다가 필요할 때만
scripts/의 코드를 실행하거나references/의 파일을 읽습니다.
Anthropic 엔지니어링 글은 이 구조 덕분에 파일 시스템과 코드 실행 도구를 가진 에이전트라면 스킬에 담을 수 있는 맥락이 사실상 무제한이라고 설명합니다. 쓰지 않는 스킬은 이름과 설명만 자리를 차지하니까요. 스크립트를 함께 두는 이유도 여기서 나옵니다. 목록을 정렬하는 일처럼 모델이 글자를 생성해서 풀기엔 비싼 작업은 코드를 돌리는 편이 싸고, 결과도 매번 같습니다.
이 구조는 CLAUDE.md 같은 상시 지침 파일과 스킬을 가르는 기준이기도 합니다. Claude Code 문서는 스킬 본문이 CLAUDE.md 내용과 달리 쓸 때만 로드된다고 적습니다. 그리고 같은 지시나 체크리스트를 대화마다 붙여 넣게 될 때, CLAUDE.md의 한 절이 사실보다 절차에 가까워졌을 때 스킬로 만들라고 권합니다. 짧은 사실은 상시 지침에, 긴 절차는 스킬에 두는 셈입니다.
그래서 호출을 좌우하는 건 설명(description)입니다. 에이전트가 스킬을 쓸지 판단하는 재료가 1단계에서 읽은 이름과 설명뿐이기 때문입니다. 명세가 설명에 ‘무엇을 하는지’와 ‘언제 쓰는지’를 함께 적으라고 하고, Helps with PDFs. 같은 한 줄을 나쁜 예로 드는 이유입니다.
왜 여러 도구가 같은 형식을 읽게 됐을까
Agent Skills는 Anthropic이 2025년 10월 Claude용으로 먼저 내놓았고, 같은 해 12월 18일 공개 표준으로 풀었습니다. 명세와 문서는 agentskills.io에 있습니다. 사이트는 이 형식을 Anthropic이 처음 만들어 공개 표준으로 내놓았고, 생태계의 기여에 열려 있다고 소개합니다.
지금은 경쟁 회사의 도구들이 이 형식을 자기 문서에 그대로 씁니다. OpenAI의 스킬 문서는 ChatGPT와 Codex의 스킬이 공개 agent skills 표준 위에 있다고 적습니다. 구글 Antigravity 문서도 스킬을 에이전트 능력을 확장하는 공개 표준으로 소개합니다. agentskills.io의 지원 도구 목록에는 9월 25일 기준 45개 항목이 올라 있고, Claude Code, ChatGPT & Codex, GitHub Copilot, VS Code, Cursor, Gemini CLI, Goose, Junie, OpenCode 등이 들어 있습니다.
형식이 이렇게 퍼진 이유를 공식 문서가 직접 설명하지는 않습니다. 다만 명세를 보면 짐작할 만한 점이 있습니다. 필수 항목이 두 개뿐이고 나머지는 폴더와 Markdown이라, 새 런타임이나 서버가 필요하지 않습니다. 파일을 읽을 줄 아는 에이전트라면 어디서든 지원할 수 있는 모양입니다. 이 문단은 명세의 모양에서 끌어낸 제 해석입니다.
옮길 때 같은 것과 다른 것
같은 것은 SKILL.md의 구조와 읽는 순서입니다. 세 도구 문서 모두 에이전트가 이름과 설명을 먼저 보고, 일과 맞으면 본문을 읽으며, 설명이 호출을 좌우한다고 설명합니다.
다른 것은 다섯 가지입니다.
폴더를 두는 자리
가장 먼저 부딪히는 차이입니다. 스킬 하나는 아래 폴더 안에 <이름>/SKILL.md로 들어갑니다.
- Claude Code: 프로젝트
.claude/skills/, 개인~/.claude/skills/ - Codex: 프로젝트
.agents/skills/, 개인$HOME/.agents/skills/ - Antigravity 2.0: 프로젝트
.agents/skills/, 전역~/.gemini/config/skills/
Codex와 Antigravity는 프로젝트 안의 .agents/skills를 함께 읽습니다. Antigravity는 예전 경로인 .agent/skills도 계속 인식합니다. 반면 Claude Code 문서가 나열한 위치에는 .agents/skills가 없습니다. 문서 기준으로는 같은 SKILL.md라도 .claude/skills에만 두면 Codex와 Antigravity가 찾지 못하고, .agents/skills에만 두면 Claude Code가 찾지 못합니다.
찾는 범위는 Claude Code와 Codex가 비슷합니다. 둘 다 시작한 폴더에서 저장소 루트까지 올라가며 스킬 폴더를 찾습니다.
도구가 덧붙인 설정
각 도구는 명세 위에 자기 기능을 얹었습니다. Claude Code는 호출 제어, 하위 에이전트 실행, 동적 컨텍스트 주입 같은 기능을 더했습니다. Codex는 표시 방식과 의존성을 적는 agents/openai.yaml 파일을 더합니다. Antigravity는 반대로 조금 느슨해서 name이 없으면 폴더 이름을 대신 씁니다.
문제는 이런 확장이 다른 곳에서 어떻게 처리되느냐입니다. Claude Code 문서는 claude.ai에 올리거나 Skills API로 쓰는 스킬에는 명세의 여섯 필드(name, description, license, compatibility, metadata, allowed-tools)만 쓸 수 있다고 적습니다. 다른 필드가 있으면 무시하지 않고 업로드가 Unexpected key(s) in SKILL.md frontmatter 오류로 실패합니다. 동적 컨텍스트 주입 같은 Claude Code 전용 본문 기능도 claude.ai 채팅이나 API에서는 동작하지 않습니다. 같은 회사 제품 사이에서도 이렇다면, 다른 회사 도구로 옮길 때 확장 기능이 따라올 거라고 기대하지 않는 편이 안전합니다.
목록에 실리는 설명의 길이
1단계에서 읽는 스킬 목록에도 자리 제한이 있습니다.
| 도구 | 스킬 목록 예산 | 넘치면 |
|---|---|---|
| Claude Code | 모델 컨텍스트 윈도우의 1%. 항목마다 description과 when_to_use를 합쳐 1,536자에서 자름 | 덜 쓰는 스킬부터 설명을 줄임 |
| Codex | 컨텍스트 윈도우의 최대 2%(윈도우를 모르면 8,000자) | 설명부터 줄이고, 그래도 넘치면 일부 스킬을 빼고 경고 |
Antigravity 문서는 이 예산을 따로 밝히지 않습니다. 스킬이 많아지면 설명 뒷부분부터 잘릴 수 있다는 점은 Claude Code와 Codex가 같습니다. 그래서 OpenAI 문서는 핵심 용도와 트리거 단어를 설명 앞쪽에 두라고 권합니다.
부르는 방법
에이전트가 설명을 보고 알아서 고르는 방식은 세 도구 모두에 있습니다. 직접 부르는 방법은 다릅니다.
- Claude Code:
/스킬-이름 - Codex CLI·IDE 확장:
$스킬-이름으로 언급하거나/skills - ChatGPT:
@로 선택 - Antigravity:
/스킬-이름
같은 도구 안에서도 표면마다 다릅니다
Claude Code에서 ~/.claude/skills에 둔 개인 스킬은 그 컴퓨터의 Claude Code 세션에서 씁니다. Cowork와 클라우드 세션은 내 컴퓨터 폴더를 읽지 않고 claude.ai 계정에 켜 둔 스킬을 불러옵니다. 9월 16일 Cowork가 채팅과 합쳐졌을 때 Anthropic이 Cowork에서 쓰던 스킬은 그대로 이어진다고 밝힌 것도 이 계정 쪽 스킬 이야기입니다.
OpenAI도 비슷합니다. 폴더에 둔 독립 스킬은 ChatGPT 데스크톱 앱, Codex CLI, IDE 확장에서 쓰고, 웹과 휴대폰의 ChatGPT(Chat·Work)에서는 플러그인에 묶인 스킬을 씁니다. 플러그인은 스킬과 MCP 서버 연결을 한 묶음으로 배포하는 단위입니다.
여러 도구에서 같이 쓰려면
위 차이에서 실무 기준 네 가지가 나옵니다. 문서에 적힌 사실에서 끌어낸 제 제안입니다.
- frontmatter에는 명세의 여섯 필드만 씁니다. 도구 전용 필드를 넣으면 어딘가에서는 무시되거나, claude.ai처럼 오류가 납니다. 전용 기능이 꼭 필요하면 그 도구 전용 스킬로 따로 둡니다.
- 원본 폴더는 하나만 둡니다. Claude Code와 Codex 문서는 둘 다 심볼릭 링크로 연결된 스킬 폴더를 따라 읽는다고 적습니다. 원본 하나를 두고
.claude/skills와.agents/skills에서 링크하면 고칠 곳이 한 군데로 줄어듭니다. Antigravity 문서에는 심볼릭 링크 이야기가 없어서 거기서도 되는지는 확인하지 못했습니다. - 설명 첫 문장에 무엇을 하는지와 언제 쓰는지를 넣습니다. 목록 예산에 걸려 뒤가 잘려도 앞부분은 남습니다.
- 스크립트가 필요로 하는 환경은
compatibility에 적습니다. 명세가 이 필드를 둔 이유가 필요한 제품, 시스템 패키지, 네트워크 접근을 밝히기 위해서입니다.
가져다 쓰기 전에 볼 것
스킬은 지시와 코드를 함께 담습니다. 남이 만든 스킬을 설치하는 일은 그 지시와 스크립트를 에이전트가 따르도록 허락하는 일에 가깝습니다. Anthropic은 악성 스킬이 환경에 취약점을 만들거나 데이터를 밖으로 빼내도록 지시할 수 있다며, 믿을 수 있는 출처의 스킬만 설치하라고 권합니다. 덜 믿는 출처라면 쓰기 전에 파일과 코드 의존성, 외부 네트워크에 연결하라는 지시를 먼저 읽어 보라고 합니다. 스킬 모음 저장소에서 폴더를 통째로 복사해 오기 전에 SKILL.md와 scripts/만이라도 열어 보시면 됩니다.
핵심만 정리하면
- 에이전트 스킬은 SKILL.md가 든 폴더이고, 에이전트는 이름과 설명만 먼저 읽은 뒤 필요할 때 본문과 파일을 읽습니다.
- Anthropic이 2025년 12월 공개 표준으로 풀었고, agentskills.io 목록 기준 45개 도구가 같은 형식을 지원합니다.
- 형식은 그대로 통하지만 폴더 위치(
.claude/skills와.agents/skills), 도구 전용 필드, 목록 예산, 부르는 방법은 도구마다 다릅니다. - 여러 도구에서 쓸 스킬은 명세 여섯 필드만 쓰고, 원본 하나를 링크로 공유하고, 설명 앞부분에 용도와 트리거를 둡니다.
- 남이 만든 스킬은 설치 전에 SKILL.md와 스크립트를 읽어 봅니다.
참고 자료
2026년 9월 25일 확인