클로드 코드 스킬 만들기와 사용법: 마켓플레이스 설치까지

Claude Code(클로드 코드)로 같은 업무를 여러 번 맡기다 보면 한 번 정한 형식과 순서를 다음 작업에서도 그대로 쓰고 싶어집니다. 매번 지시를 처음부터 설명하기에는 아깝고 메모장에 보관하는 것만으로는 부족한 순간입니다. 두 가지 예시 상황으로 살펴보겠습니다. 아마 둘 다 겪어보셨을 겁니다.

첫 번째는 주간 보고의 형식과 제외 항목을 네 번에 걸쳐 다시 입력하는 상황입니다. 다음 주가 되어도 마찬가지로 똑같이 반복됩니다. 두 번째는 배포 순서를 프로젝트 메모에 적었지만 그 파일이 자동으로 읽히지 않는 상황입니다. 작업할 때마다 "이 파일을 읽고 적어 둔 순서대로 진행해 줘"라고 다시 알려줘야 합니다.

두 상황은 막히는 지점이 다릅니다. 첫 번째는 지시를 적어 둔 곳이 없어서 매번 처음부터 입력하는 문제입니다. 두 번째는 적어 두기는 했는데 필요한 순간에 읽히지 않는 문제입니다. 스킬은 이 둘을 함께 풀어줍니다. 스킬이 무엇인지부터 알아본 뒤 만드는 법, 쓰는 법, 남이 만든 스킬을 가져다 쓰는 법 순서로 살펴보겠습니다.

클로드 코드 스킬이란 무엇인가요?

게임에서 스킬은 캐릭터가 새로 배우는 기술입니다. PDF를 만들거나 녹음 내용을 읽는 것처럼 하나의 행동을 배울 수도 있고, 여러 동작을 이어 하나의 기술로 쓸 수도 있습니다. 매주 스프레드시트에서 지표를 모아 분석하고 보고용 PDF를 만드는 일은 여러 행동을 묶은 스킬에 해당합니다.

Claude Code의 스킬은 에이전트라는 캐릭터가 작업하다 꺼내 보는 비법서에 가깝습니다. 새로운 행동을 하는 방법이나 반복 절차를 적어 두면 필요한 순간에 알아서 펼쳐 봅니다.

스킬(Skill)

스킬(Skill)이란 Claude(클로드)가 새로운 일을 하거나 여러 단계의 작업을 같은 기준으로 수행하도록 방법을 적어 둔 파일입니다. Claude가 관련 있다고 판단하면 자동으로 로드하고 /스킬이름으로 직접 호출할 수도 있습니다.

스킬은 Claude Code만의 기능도 아닙니다. Anthropic(앤트로픽)이 만든 Agent Skills 형식은 개방형 표준으로 공개됐고 공식 지원 목록에는 40개가 넘는 도구가 올라와 있습니다. Cursor(커서), GitHub Copilot(깃허브 코파일럿), Gemini CLI(제미나이 CLI), ChatGPT(챗지피티), Codex(코덱스)가 같은 형식을 지원합니다. 이 글은 Claude Code에서 스킬을 쓰는 법에 집중하고 Agent Skills 표준 자체는 다음 글에서 다루겠습니다.

스킬은 개발자만 쓰는 코드 자동화가 아닙니다. 판단 기준은 코드를 쓰는지가 아니라 같은 설명과 절차를 반복하는지입니다. 매달 하는 정산, 매주 쓰는 보고서 양식, 자료를 정리하는 순서도 스킬로 만들 수 있습니다.

저는 GA4 지표를 매달 같은 형식의 리포트로 정리하는 일을 스킬로 옮겼습니다. 예전에는 매번 "이 기간으로, 이 지표를, 이런 순서로 정리해 줘"라고 다시 설명했는데, 그 절차를 적어 두니 명령 하나로 같은 형식의 결과가 나옵니다.

스킬은 SKILL.md 파일 하나입니다

개념을 알아봤으니 이제 실제 생김새를 보겠습니다. 스킬은 폴더 안에 든 파일 하나이고, 머리말에는 언제 쓸지, 본문에는 따라 할 절차를 적습니다. 같은 지침이나 체크리스트를 계속 채팅에 붙여넣고 있었다면, 그 내용을 이 문서에 옮겨 두고 에이전트가 알아서 꺼내 쓰게 만드는 것입니다.

프로젝트를 설명해 두는 CLAUDE.md 파일에 단계별 절차가 쌓일 때도 마찬가지입니다. CLAUDE.md는 세션이 시작될 때마다 통째로 읽히지만 스킬 본문은 실제로 쓸 때만 읽힙니다. 프로젝트에 관한 사실은 CLAUDE.md에 남기고 특정 작업에서만 필요한 절차는 스킬로 옮기는 편이 낫습니다.

예전에는 자주 쓰는 지시를 사용자 정의 명령어(/이름처럼 직접 호출하는 기능)로 따로 만들어야 했습니다. 지금은 그 기능이 스킬로 합쳐졌습니다. .claude/commands/deploy.md와 .claude/skills/deploy/SKILL.md는 모두 /deploy를 만들고 똑같이 작동합니다. 예전에 만들어 둔 파일도 그대로 쓸 수 있습니다.

Claude에게 말로 스킬 만들기

그럼 스킬은 어떻게 만드는 걸까요. 현시점(2026년 9월)에 가장 쉬운 방법은 Claude에게 만들어 달라고 요청하는 것입니다. 폴더와 파일을 처음부터 손으로 만들지 않아도 됩니다. 반복하는 업무와 원하는 결과를 평소 말하듯 설명하면 필요한 폴더와 SKILL.md 작성을 맡길 수 있습니다.

이미 반복하던 업무라면 지금 쓰는 지시와 결과물 형식을 그대로 묶어 달라고 설명하고 진행하면 됩니다.

"매주 지난주 작업 목록을 표로 정리하고 날짜는 빼고 마지막에 세 줄 요약을 붙이던 반복 작업을 스킬로 만들어 주세요."

아직 해보지 않은 업무라면 처음부터 혼자 설계하지 않아도 됩니다. 작업을 설명할 테니 같이 구체화하자고 말하면 Claude가 되물으면서 단계를 잡아 줍니다.

"앞으로 매주 반복할 업무를 스킬로 만들고 싶습니다. 작업 내용을 설명할 테니 함께 구체화해서 만들어 주세요."

어디에서 쓸지도 함께 말해야 합니다. 여러 프로젝트에서 계속 쓸 스킬이라면 "계정 전체에서 쓸 수 있게 전역으로 만들어 줘"라고 요청합니다. 이 차이는 뒤에서 따로 다루겠습니다.

만든 스킬 열어서 확인하기

Claude가 스킬을 다 만들었다고 하면 그냥 넘어가지 말고 구조를 파악해 보는 것이 중요합니다. "방금 만든 SKILL.md를 열어서 보여 줘"라고 요청하고 내용을 함께 읽어 봅니다. 특히 description에 사용자가 말할 요청 문구가 적혔는지, 본문의 작업 순서와 끝내는 조건이 원하는 대로인지 확인합니다. 만드는 명령을 외우는 것보다 파일의 구조를 이해해야 다음 작업에 맞게 고칠 수 있습니다.

말로 시키는 방법을 알아봤으니 직접 만드는 방법도 보겠습니다. 필요한 것은 폴더 하나와 파일 하나입니다. 경로는 이렇게 생겼습니다.

~/.claude/skills/내스킬이름/SKILL.md

스킬 이름으로 폴더를 만들고 그 안에 SKILL.md를 넣습니다. 별도 등록 절차는 없습니다. 폴더 이름이 그대로 슬래시 명령의 이름이 됩니다.

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

mkdir은 폴더를 만드는 명령이고 -p는 중간 폴더가 없으면 함께 만들라는 뜻입니다. 이 한 줄로 .claude 폴더부터 summarize-changes까지 한 번에 생깁니다. 이제 이 폴더 안에 SKILL.md를 만듭니다.

SKILL.md 구조: 머리말과 본문

SKILL.md는 머리말과 본문으로 나뉩니다. 위쪽 머리말은 프론트매터(front matter)라고 부릅니다. Claude가 이 스킬이 무엇이고 언제 필요한지 읽는 곳입니다. 아래쪽 본문은 스킬이 트리거된 뒤 Claude가 실제로 따라 하는 지시입니다.

두 부분의 경계는 --- 줄입니다. 머리말은 두 줄의 --- 사이에 넣고 그다음부터 본문을 씁니다.

---
머리말: 이 스킬이 무엇인지 Claude에게 알려 주는 자리
---

본문: Claude가 실제로 따라 할 지시

머리말에서 실질적으로 중요한 필드는 description입니다. 스킬이 하는 일과 사용자가 어떤 말을 했을 때 실행할지를 적습니다. 본문에는 실행할 명령과 작업 순서, 결과물의 형식, 끝내는 조건을 씁니다. 실제 내용을 채우면 이렇게 됩니다.

저라면 처음부터 빈 파일에 손수 쓰지 않겠습니다. Claude에게 만들게 한 뒤 열어서 구조를 파악하고 목적에 맞게 고쳐 가는 편이 빠릅니다. 무엇을 적을지 모르는 상태에서 빈 화면을 보는 것보다 채워진 것을 고치는 쪽이 배우기도 쉽습니다.

---
description: 커밋하지 않은 변경 사항을 요약하고 위험해 보이는 것을 짚어 줍니다. 무엇이 바뀌었는지 물어보거나, 커밋 메시지를 요청하거나, 변경 내용을 검토해 달라고 할 때 사용합니다.
---
 
## 현재 변경 사항
 
!`git diff HEAD`
 
## 지시
 
위 변경 사항을 두세 개의 불릿으로 요약하세요. 그다음 눈에 띄는 위험을 나열하세요.
예외 처리 누락, 하드코딩된 값, 함께 고쳐야 할 테스트 같은 것입니다.
변경 사항이 없으면 없다고 말하세요.

공식 문서 기준으로 머리말의 모든 필드는 선택이고 description만 권장됩니다. Claude는 평소에 이 설명을 보고 필요한 스킬인지 판단합니다. 자동 호출이 잘못될 때 가장 먼저 고칠 곳도 여기입니다.

!`git diff HEAD` 줄에는 명령어의 실행 결과가 들어갑니다. Claude가 파일을 보기 전에 Claude Code가 먼저 명령을 실행하고 그 출력으로 이 줄을 바꿔 둡니다. Claude는 "확인해 봐라"라는 지시가 아니라 실제 변경 내용을 받은 상태로 시작합니다.

전역 설치와 프로젝트 설치의 차이

프로젝트를 작업장이라고 생각하면 쉽습니다. 프로젝트 설치는 그 작업장 안에만 도구를 두는 것이라 다른 작업장으로 가면 따라오지 않고, 전역 설치는 내 계정에 두는 것이라 어디서 일하든 씁니다.

경로를 외울 필요는 없습니다. 앞의 ~가 내 계정 폴더라는 것만 알아 두면 됩니다.

여러 프로젝트에서 혼자 반복하는 업무라면 전역 설치가 편합니다. 특정 프로젝트의 규칙이거나 팀과 함께 써야 하는 절차라면 프로젝트 안에 두는 편이 맞습니다. 처음에는 전역으로 만들고 팀과 나눌 스킬이 생겼을 때 프로젝트 안으로 옮겨도 됩니다.

슬래시 명령과 자연어로 호출하기

만들었으면 이제 쓸 차례입니다. 부르는 방법은 두 가지입니다. 먼저 슬래시 명령으로 직접 호출해 보겠습니다.

/summarize-changes

자연어로 요청해도 됩니다.

내가 뭘 바꿨지?

이 문장이 description에 적은 상황과 맞으면 Claude가 스킬을 자동으로 트리거합니다.

방금 만든 스킬을 쓰려고 터미널을 다시 시작할 필요는 없습니다. Claude Code는 스킬 폴더의 변경을 실시간으로 감지해서 지금 열려 있는 세션에 바로 반영합니다. 다만 지금 세션이 시작된 뒤 처음으로 스킬 폴더 자체를 새로 만든 경우(예: 계정에 스킬을 하나도 안 써 본 상태에서 처음 만드는 경우)라면 이번만 재시작해야 감지됩니다.

자동 호출을 결정하는 description

Claude는 평소에 스킬 본문이 아니라 이름과 설명 목록만 들고 있습니다. 이 목록을 보고 현재 요청에 필요한 스킬을 판단합니다. 따라서 description에 작업 이름만 적지 말고 사용자가 실제로 말할 표현과 호출 시점을 구체적으로 적어야 합니다.

예를 들어 "변경 사항 요약"이라고만 쓰는 것보다 "무엇이 바뀌었는지 물어볼 때, 커밋 메시지를 요청할 때"라고 적는 편이 제때 호출됩니다.

설명에는 길이 제한이 있습니다. 목록에 들어가는 설명은 항목당 1,536자에서 잘립니다. 스킬이 많아지면 자주 쓰지 않는 스킬부터 설명이 더 줄어듭니다. 가장 중요한 용도와 호출 시점을 앞쪽에 적어야 하는 이유입니다.

본문도 짧게 씁니다. 공식 문서는 SKILL.md를 500줄 이하로 유지하라고 권합니다. 스킬이 한 번 로드되면 그 내용이 대화에 남아 세션 내내 컨텍스트를 쓰기 때문입니다. 내용이 길어지면 상세 자료를 같은 폴더의 다른 파일로 빼고 SKILL.md에서 reference.md처럼 필요한 파일을 가리키면 됩니다. 그 파일은 필요할 때만 읽힙니다.

지시는 지켰는지 확인할 수 있게 씁니다. 「팀 규칙을 지켜 주세요」보다 「함수 이름은 동사로 시작합니다」가 낫습니다. Claude가 해야 할 행동과 결과가 문장에 드러나기 때문입니다.

저라면 실행 횟수보다 끝내는 조건을 먼저 정하겠습니다. 팩트체크 스킬을 만들 때 처음에는 세 번 검증하라고 적었는데, 세 번째에도 고칠 것이 나오는 글이 계속 있었습니다. 그래서 횟수 대신 고칠 항목이 하나도 없는 회차가 나올 때까지로 바꿨습니다. 몇 번 할지가 아니라 무엇을 확인하면 끝낼지를 적어야 결과가 일정해집니다.

자동 실행 차단: 배포, 커밋, 발송

배포나 커밋, 메시지 발송처럼 Claude가 알아서 실행하면 곤란한 작업이 있습니다. 이런 스킬은 자동 호출을 막아 둡니다. Claude에게 "이 스킬은 내가 직접 부를 때만 실행되게 해 줘"라고 요청해도 되고, 머리말에 한 줄(disable-model-invocation: true)을 직접 넣어도 됩니다.

---
name: deploy
description: 애플리케이션을 프로덕션에 배포합니다
disable-model-invocation: true   # 이 줄이 자동 호출을 막습니다
---

이렇게 하면 사용자가 /deploy를 직접 입력할 때만 실행됩니다. Claude는 이 스킬이 있다는 사실 자체를 모릅니다. 코드가 준비됐다는 이유로 Claude가 배포를 시작하는 일을 막습니다.

반대 방향도 있습니다. user-invocable: false를 넣으면 Claude만 쓰고 사용자 메뉴에는 보이지 않습니다. 배경 지식처럼 사용자가 명령으로 실행할 필요가 없는 스킬에 씁니다.

호출이 안 되거나 너무 잦을 때

스킬이 자동으로 트리거되지 않으면 먼저 설치된 스킬이 뭐가 있어?라고 묻거나 /skills를 입력해 목록에 뜨는지 확인합니다. 목록에 있다면 description 문제일 가능성이 큽니다. 사용자가 자연스럽게 쓸 단어와 호출 시점을 설명에 넣어 보세요.

목록에 아예 없다면 프론트매터 형식이 깨졌을 수 있습니다. 이 경우 /스킬이름으로 직접 호출할 수 있어도 자동 호출은 되지 않을 수 있습니다.

반대로 너무 자주 트리거된다면 설명의 범위를 좁힙니다. 직접 호출할 때만 쓰고 싶다면 disable-model-invocation: true를 넣습니다. 설명이 잘리는 것 같다면 /doctor를 실행해 스킬 목록이 컨텍스트를 얼마나 쓰는지, 어느 스킬이 많이 차지하는지 확인할 수 있습니다.

기본 제공 스킬과 마켓플레이스

스킬은 남이 만든 것을 가져다 쓸 수도 있습니다. 이미 잘 만들어 둔 것이 있으면 굳이 처음부터 만들 이유가 없습니다.

Claude Code에는 처음부터 들어 있는 스킬이 있습니다. /doctor, /code-review, /debug, /batch, /loop, /claude-api가 대표적이고, 버전이 올라가면서 더 늘어납니다. 설치할 필요 없이 명령을 입력하면 바로 실행됩니다.

필요한 스킬이 없다면 공식 마켓플레이스에서 설치할 수 있습니다. 예를 들어 스킬을 만들고 다듬는 skill-creator 플러그인은 다음 명령으로 설치합니다.

/plugin install skill-creator@claude-plugins-official

공식 마켓플레이스는 Claude Code를 시작할 때부터 등록되어 있어서 보통은 이 명령만으로 됩니다. 마켓플레이스를 찾지 못한다는 메시지가 나오면 등록 정보가 오래됐거나 빠진 경우입니다. /plugin marketplace update claude-plugins-official로 먼저 새로 고치고, 그래도 안 되면 다음 명령으로 추가합니다.

/plugin marketplace add anthropics/claude-plugins-official

설치한 뒤에는 /reload-plugins를 실행해야 지금 세션에서 쓸 수 있습니다. 마켓플레이스에 없는 스킬은 공개된 SKILL.md를 폴더째 복사해 설치할 수도 있습니다.

이름이 겹치면 계정에 둔 스킬이 이깁니다

남이 만든 스킬을 받다 보면 내가 만든 것과 이름이 겹칠 수 있습니다. 다만 어떻게 받았는지에 따라 처리 방식이 다릅니다. 마켓플레이스에서 설치한 스킬은 애초에 겹치지 않습니다. /이름이 아니라 /플러그인이름:이름 형태로 따로 구분되기 때문입니다. 이름이 그대로 겹치는 경우는 공개된 SKILL.md를 폴더째 복사해 내 계정이나 프로젝트 폴더에 직접 넣었을 때입니다. 이때는 하나만 실행되는데, 내 계정에 둔 스킬이 프로젝트 안의 스킬을 덮습니다. 회사 계정으로 배포된 스킬이 있다면 그것이 내 것까지 덮습니다.

문제는 겹친 줄 모르는 채로 엉뚱한 스킬이 도는 경우입니다. 새 스킬을 받은 뒤 /skills로 목록을 확인하세요. 같은 이름이 보이면 둘 중 하나의 폴더 이름을 바꾸면 됩니다. 폴더 이름이 곧 명령 이름이라 폴더만 고치면 끝납니다.

내 스킬을 다른 사람과 나누기

스킬은 서비스 화면 안에만 저장되는 설정이 아니라 파일입니다. 폴더째 복사하면 다른 프로젝트로 옮길 수 있습니다. 같은 Agent Skills 형식을 지원하는 다른 AI 도구에서도 쓸 수 있습니다.

GitHub 저장소에 올리거나 스킬 마켓플레이스로 배포하는 길도 있습니다. 구체적인 배포 방법은 다음 글에서 따로 다루겠습니다.