Claude Code의 스킬(Agent Skills)은 자주 쓰는 작업 절차나 전문 지식을 하나의 패키지로 묶어 Claude에게 "필요할 때 알아서 꺼내 쓰게" 하는 기능입니다. 이 글은 스킬이 무엇이고, SKILL.md로 어떻게 만들고 어디에 두는지 정리합니다. (기준 시점: 2026년 6월. 세부 사양은 변동될 수 있으니 공식 문서에서 최신 정보를 확인하세요.)
스킬이란 무엇인가
스킬은 Claude의 기능을 확장하는 모듈식 능력입니다. 각 스킬은 지침(instructions), 메타데이터, 그리고 선택적 리소스(스크립트·템플릿)를 함께 묶습니다. Claude는 작업과 관련이 있다고 판단되면 해당 스킬을 자동으로 사용합니다. 중요한 설계는 동적 로딩입니다 — 평소엔 스킬 목록만 가볍게 유지하고, 실제로 관련된 스킬의 내용만 그때그때 컨텍스트로 불러옵니다. 덕분에 스킬이 많아도 컨텍스트가 불필요하게 무거워지지 않습니다.
SKILL.md 구조
스킬은 SKILL.md 파일로 정의합니다. 파일은 YAML frontmatter + Markdown 본문으로 구성되며, frontmatter의 description이 Claude가 언제 이 스킬을 호출할지를 결정합니다. 따라서 설명을 구체적으로, 관련 키워드를 담아 쓰는 것이 중요합니다.
.claude/skills/summarize-changes/SKILL.md
---
name: summarize-changes
description: git 작업 트리의 커밋되지 않은 변경을 요약하고 위험한 부분을 표시한다
---
# 변경 요약
1. 현재 작업 트리의 diff를 확인한다.
2. 변경을 사람이 읽기 쉽게 요약한다.
3. 위험해 보이는 변경에 표시를 단다.위는 git 변경을 요약하는 스킬의 예시입니다. 스킬은 폴더 단위로 저장되며, 폴더 이름이 곧 스킬 이름이 됩니다. 본문에는 Claude가 따라야 할 절차를 자연어로 적습니다.
어디에 두나 — 네 가지 소스
Claude Code는 여러 위치를 스캔해 사용할 수 있는 스킬 목록을 만듭니다.
- 개인(전역):
~/.claude/skills/<이름>/SKILL.md— 내 모든 프로젝트에서 쓰는 스킬. - 프로젝트:
.claude/skills/<이름>/SKILL.md— 특정 저장소 안에서만 쓰는 스킬(팀과 공유 가능). - 플러그인: 설치한 Claude Code 플러그인이 함께 제공하는 스킬.
- 내장: 모든 세션에서 기본 제공되는 스킬(예:
/code-review,/batch,/debug,/loop,/claude-api).
자동 호출 vs 직접 호출
스킬은 두 가지 방식으로 작동합니다. ① Claude가 description을 보고 관련 있다고 판단하면 자동으로 불러오거나, ② 사용자가 슬래시 명령으로 직접 호출합니다(예: /summarize-changes). frontmatter로 누가(사용자/Claude) 호출할지 제어할 수 있습니다.
참고: 기존의 커스텀 슬래시 명령은 스킬에 통합되었습니다. .claude/commands/deploy.md와 .claude/skills/deploy/SKILL.md는 둘 다 /deploy를 만들고 동일하게 작동하며, 기존 commands/ 파일도 계속 동작합니다. 스킬은 여기에 지원 파일 디렉토리, 호출 제어 frontmatter, 자동 로드 같은 기능을 더한 것입니다.
한 번 정의해 여러 곳에서
Claude Code의 스킬은 Agent Skills 오픈 표준을 따르며, 이 표준은 여러 AI 도구에서 공통으로 동작합니다. 공식 안내에 따르면 claude.ai 웹과 Claude 데스크톱 앱도 스킬을 지원하므로, 한 번 정의한 스킬을 여러 환경에서 공유할 수 있습니다. (Claude Code는 표준에 호출 제어, 서브에이전트 실행, 동적 컨텍스트 주입 같은 기능을 추가로 제공합니다.)
정리
핵심: ① 스킬은 지침·리소스를 묶은 모듈식 능력으로 관련 시 자동 로드된다, ② SKILL.md(YAML frontmatter + 본문)로 정의하고 description이 호출 시점을 결정한다, ③ 개인·프로젝트·플러그인·내장 네 소스에서 불러온다, ④ 오픈 표준이라 여러 도구에서 공유된다. 만드는 법·모범 사례는 Claude Code 공식 스킬 문서를 참고하세요.
쓸 만한 스킬을 어디서 구하는지는 Claude 스킬 라이브러리에서 정리했습니다.
이 글은 Claude/Claude Code 공식 문서를 토대로 작성한 입문 설명입니다. 경로·명령·기능은 업데이트될 수 있으므로, 실제 사용 전 공식 문서에서 최신 사양을 확인하세요. (공식 출처: docs.claude.com, code.claude.com)