AI 에이전트 스킬 만들기, SKILL.md 폴더 하나로 시작하기

게시 2026.07.17 · 약 6분 분량

AI 에이전트 스킬은 SKILL.md 파일을 담은 폴더다. 에이전트가 특정 작업을 만나면 이 폴더의 지침과 스크립트를 불러와 능력을 확장한다. 만드는 법은 어렵지 않다. .claude/skills/<이름>/ 폴더에 SKILL.md를 하나 두고, 그 안에 YAML 머리말(name·description)과 마크다운 지침을 적으면 된다. 앤트로픽은 2025년 10월 16일 이 형식을 공개했고, 2025년 12월 18일 여러 도구가 함께 쓰는 개방형 표준으로 내놨다. 2026년 7월 기준 Agent Skills 공식 스펙과 클로드 코드 공식 문서에 형식이 정리돼 있다. 공식 스펙의 클라이언트 목록에는 OpenAI Codex·Gemini CLI·GitHub Copilot·Cursor·VS Code를 비롯해 40개가 넘는 제품이 올라 있다. 한 번 만든 스킬은 도구를 갈아타도 그대로 쓸 수 있다는 뜻이다. 이 글은 그 개방형 표준과 클로드 코드 구현을 기준으로 첫 스킬을 만드는 순서를 다룬다. 다른 프레임워크의 플러그인 체계는 범위 밖이다.

에이전트 스킬이란 무엇인가

에이전트 스킬은 지침과 스크립트, 참고 자료를 폴더 하나로 묶어 에이전트가 필요할 때만 꺼내 쓰는 패키지다. 핵심은 점진적 로딩(필요한 만큼만 단계별로 문맥에 불러오는 방식)이다. Agent Skills 공식 스펙은 이를 세 단계로 설명한다. 첫째, 메타데이터 단계에서는 모든 스킬의 name과 description만 시작 시 올라온다(스펙 기준 약 100토큰). 둘째, 작업에 맞는 스킬이 정해지면 그 SKILL.md 본문 전체를 읽는다(지침은 5000토큰 이하 권장). 셋째, scripts·references·assets 폴더의 파일은 실제로 필요할 때만 읽는다. 그래서 스킬이 수십 개여도 쓰지 않는 동안에는 토큰을 거의 먹지 않는다.

이 구조가 CLAUDE.md처럼 항상 문맥에 상주하는 지침과 다른 점이다. 에이전트가 어떤 종류로 나뉘는지는 세 가지 축으로 구분한 글에서 따로 다뤘다. 또 스킬은 ‘무엇을 어떻게 하라’는 지침 묶음이라, 외부 도구나 데이터를 연결하는 MCP 서버를 만들어 클로드에 붙이는 방식과는 역할이 다르다. 스킬은 절차와 규칙을, MCP는 도구 연결을 맡는다.

SKILL.md는 어떻게 구성하나

SKILL.md는 두 부분이다. ---로 감싼 YAML 머리말(파일 맨 위의 설정 블록)과 그 아래 마크다운 본문이다. 머리말은 에이전트가 이 스킬을 언제 쓸지 판단하는 정보이고, 본문은 실제로 따를 지침이다. Agent Skills 공식 스펙에 따르면 필수 필드는 name과 description 두 개다. name은 최대 64자에 소문자·숫자·하이픈만 쓰고 폴더명과 같아야 한다. 하이픈으로 시작하거나 끝날 수 없고 연속 하이픈도 안 된다. description은 최대 1024자로, 무엇을 하는지와 언제 쓰는지를 한 문장에 함께 담는다.

가장 단순한 SKILL.md는 머리말과 지침만으로도 동작한다.

---
name: summarize-changes
description: 커밋 안 한 변경을 요약하고 위험한 부분을 짚는다. 무엇이 바뀌었는지 묻거나 커밋 메시지가 필요할 때 쓴다.
---

## 지침

git diff의 변경을 두세 개 불릿으로 요약한 뒤, 빠진 에러 처리나 하드코딩된 값처럼 위험한 부분을 나열한다.

첫 스킬 폴더 만들기

스킬은 폴더 위치에 따라 쓰이는 범위가 갈린다. 클로드 코드 공식 문서 기준으로, 개인 스킬은 ~/.claude/skills/이름/에 두면 내 모든 프로젝트에서 쓰이고, 프로젝트 스킬은 저장소의 .claude/skills/이름/에 두면 그 프로젝트에서만 쓰인다. 팀과 공유하려면 후자를 버전 관리에 커밋한다.

순서는 이렇다. 먼저 폴더를 만든다.

mkdir -p ~/.claude/skills/summarize-changes

그 안에 SKILL.md를 저장하면 최소 구성은 끝난다. 지침이 길어지면 하위 폴더로 나눈다. 공식 스펙이 권장하는 폴더 구조는 다음과 같다.

summarize-changes/
├── SKILL.md # 필수: 메타데이터 + 지침
├── scripts/ # 선택: 실행 코드
├── references/ # 선택: 상세 문서
└── assets/ # 선택: 템플릿·리소스

이제 클로드가 description에 맞는 요청을 받으면 스킬을 자동으로 불러오고, 직접 부르고 싶으면 /summarize-changes처럼 슬래시 명령으로 실행한다.

description을 잘 써야 스킬이 뜬다

스킬이 자동으로 안 불려 오는 가장 흔한 원인은 description이 모호해서다. 에이전트는 사용자 요청을 각 스킬의 description과 대조해 무엇을 쓸지 고른다. 그래서 ‘PDF를 다룬다’ 같은 막연한 문장보다, ‘PDF에서 텍스트와 표를 뽑고 양식을 채운다. 사용자가 PDF나 문서 추출을 언급할 때 쓴다’처럼 기능과 사용 시점을 사용자가 실제로 쓸 법한 단어로 함께 적는 편이 잘 걸린다. Agent Skills 공식 스펙도 description에 관련 작업을 식별할 키워드를 넣으라고 권한다.

클로드 코드 공식 문서에 따르면, 스킬이 많아지면 목록에서 description과 when_to_use를 합친 텍스트가 1536자에서 잘린다. 그러니 핵심 용례를 앞쪽에 두는 편이 안전하다. 반대로 배포나 커밋처럼 클로드가 알아서 실행하면 곤란한 작업은 머리말에 disable-model-invocation: true를 넣어 수동 호출로만 제한한다.

검증하고 다듬기

형식이 스펙에 맞는지는 도구로 확인한다. Agent Skills 공식 스펙은 skills-ref 검증 도구를 안내하며, 다음 명령이 머리말 형식과 이름 규칙을 검사한다.

skills-ref validate ./summarize-changes

형식이 맞는 것과 의도대로 동작하는 것은 다른 문제다. 2026년 2월 공개된 벤치마크 논문 SkillsBench에 따르면, 8개 도메인 87개 과제에서 사람이 다듬은 스킬은 에이전트 평균 통과율을 16.6%포인트 올렸지만 에이전트가 스스로 작성한 스킬은 유의미한 개선이 없었다. 다듬는 품질이 성능을 가른다는 얘기다. 스킬이 제대로 작동하는지 보려면, 스킬을 켠 세션과 끈 세션에 같은 프롬프트를 넣어 결과를 비교한다. 앤트로픽 공식 문서는 이 비교 과정을 skill-creator 플러그인이 자동화한다고 안내한다. 마지막으로 본문은 500줄 이하로 유지하고, 길어진 참고 자료는 references 폴더의 별도 파일로 빼서 필요할 때만 읽히게 한다. 지침이 짧을수록 매번 드는 토큰 비용이 줄기 때문이다.

내려받은 스킬은 검사부터

스킬은 에이전트가 그대로 따르는 지침과 실행 스크립트의 묶음이라, 커뮤니티 디렉토리에서 내려받는 순간 공급망 위험도 함께 들어온다. 2026년 2월 보안 연구진은 공개 스킬 디렉토리 ClawHub에서 프롬프트 인젝션과 환경 변수 유출, API 키 탈취를 노린 악성 스킬 341건을 확인했다. 보안 기업 Snyk의 ToxicSkills 보고서도 공개 디렉토리에서 수집한 스킬 3,984건을 검사해 36%에서 최소 한 건의 보안 결함을 발견했다고 밝혔다. 악성으로 확정된 스킬의 91%는 프롬프트 인젝션 기법을 함께 썼다.

커뮤니티 스킬을 설치하기 전에는 세 가지를 지키는 편이 안전하다. SKILL.md 전문과 scripts/ 폴더의 모든 파일을 직접 읽고, 게시자 이력을 확인하고, 실제 작업 저장소가 아닌 일회용 프로젝트에서 먼저 돌려본다.