스킬: 에이전트에게 완성된 능력을 장착하는 방법

같은 요청을 반복하곤 합니다. "변경 사항을 확인해 주세요. 이 파일들을 검토해 주세요. 이런 형식으로 맞춰 주세요. 그리고 여기는 건드리지 마세요." 매번 절차를 다시 설명하고, 그때마다 조금씩 달라집니다.

결과는 표현에 따라 들쭉날쭉합니다. 오늘은 훌륭했는데, 내일은 여러분이 조건의 절반을 빠뜨렸고, 에이전트는 들은 그대로 성실하게 해냈습니다.

이 문제는 에이전트의 메모리로는 해결되지 않습니다. 지침이 담긴 폴더로 해결됩니다. 스킬은 한 번 적어 둔 절차로, Claude Code가 스스로 연결하거나 여러분의 명령으로 연결할 수 있습니다. 이 폴더가 어디에 있는지, 스킬이 제대로 설치되었는지 확인하는 방법, 그리고 첫 실행 전 무엇을 확인해야 하는지 살펴봅시다.

스킬이란 무엇인가

파일과 필드를 자세히 살펴보기 전에, 먼저 감부터 잡아 봅시다.

목수를 생각해 봅시다. 목수는 익숙한 작업 순서를 한 번 적어 두고, 메모와 템플릿, 그리고 기계용 프로그램을 준비해 두었습니다. 이제는 짧게 말하면 됩니다. "다 치우고, 드릴 날 갈고, 다음은 고양이 의자니까 CNC 템플릿 돌려." 돌리면 바로 시작입니다.

기록된 절차는 전체 작업을 하나로 묶어 줍니다.

• 여러분의 규칙대로 정리합니다. 작업대를 치우고 공구를 늘어놓습니다. 매번 똑같이, 여러분이 익숙한 그대로요.
• 적어 둔 경계를 지킵니다. 톱이 아직 돌고 있으면 손대지 않습니다. 안전한 부분은 쓸데없이 묻지 않고 바로 합니다.
• 필요할 때 메모를 들여다봅니다. 드릴 날을 갈아야 하면 연마 규칙을 펼칩니다. 미리 외워 두지 않고, 필요한 순간에 꺼냅니다.
• 작업별 템플릿을 갖춰 둡니다. 책상에서 의자로 넘어가면, 준비해 둔 작업 도면을 꺼냅니다.
• 복잡한 일을 명령 하나로 시작합니다. 반복 재단 프로그램은 이미 옆에 있습니다. "고양이 의자 템플릿 찾아서 CNC로 돌려"라고만 하면 됩니다. 간격과 작업 순서는 기계가 지킵니다.

스킬도 같은 방식으로 구성되어 있습니다. 에이전트 손에 들린 또 하나의 도구가 아니라, 하나로 묶어 둔 절차입니다. 메인 지침은 순서와 경계를 담고, 참고 자료는 필요한 자리에서 세부 사항을 알려 주고, 템플릿은 초안을 보관하고, 스크립트는 반복되는 기계적인 작업을 실행합니다. 한 번 설명해 두면, 그다음부터는 호출만 하면 됩니다.

스킬 포맷 자체는 아무것도 격리하지 않습니다. 지침으로 작업 범위를 디자인 쪽으로 제한할 수는 있지만, CSS와 로직 사이에 기술적인 벽은 없습니다. 좋은 스킬은 작업 영역을 명확히 밝힙니다. 실행한 뒤에는 여러분이 변경된 파일을 살펴보고 페이지 동작을 확인합니다. "작동한다"와 "보기 좋다"는 서로 다른 층이고, 보장은 포맷이 아니라 확인에서 나옵니다.

스킬은 어디에 있는가

클라우드 속 마법 같은 건 없습니다. 스킬은 디스크에 있는 폴더이고, 바로 여러분의 프로젝트 안에 있습니다.

.claude/skills/web-design/SKILL.md

경로를 한 단계씩 보면 이렇습니다. 설정 폴더 .claude, 그 안의 skills, 그 안의 스킬 폴더(이름은 여러분이 정합니다), 그리고 그 안의 SKILL.md 파일입니다. 평범한 텍스트 파일이라 어떤 편집기로든 열 수 있습니다.

프로젝트와 홈 폴더에 있는 스킬은 파일 자체에서 다른 이름을 지정하지 않는 한(이 내용은 아래에서 다룹니다) 디렉터리 이름이 슬래시 명령어 이름이 됩니다. 그러니 채팅에서 어떻게 보일지 처음부터 생각하고 이름을 지으세요.

이제 가장 흔한 오해 하나를 바로잡겠습니다. 스킬은 하나의 파일이 아니라 폴더입니다. SKILL.md 옆에 무엇이든 있을 수 있습니다.

.claude/
└── skills/
    └── web-design/
        ├── SKILL.md      # 주 파일: 설명 및 지침
        ├── palettes.md   # 참고 자료, 필요할 때 에이전트가 열어 봄
        └── scripts/
            └── check.py  # 실행할 수 있는 스크립트

자동으로 고를 때 에이전트가 보는 것은 스킬의 이름과 짧은 설명뿐이고, 본문 전체는 보지 않습니다. SKILL.md는 스킬이 실행될 때 로드되고, 옆에 있는 참고 자료는 필요할 때 로드됩니다. 그래서 긴 메모가 미리 컨텍스트를 차지하지 않습니다.

평소 로컬 작업에서는 스킬의 출처 세 곳이 중요합니다.

기호 ~는 사용자의 홈 폴더를 뜻합니다. 명령에서는 그대로 쓰고, 폴더를 직접 열 때는 자신의 홈 디렉터리로 이동하면 됩니다.

처음 두 위치의 차이는 간단하니, 바로 짚고 넘어가겠습니다.

폴더를 프로젝트에 넣으면 스킬은 그 프로젝트에서만 작동합니다. 다른 프로젝트를 열면 거기에는 없습니다.

홈 폴더의 스킬은 모든 프로젝트에서 쓸 수 있습니다. 공통 절차에는 편리하지만, 생각지도 않은 곳에서 켜질 수 있습니다. 범용 스킬은 홈에, 프로젝트 전용 스킬은 프로젝트에 둡니다.

Claude Code를 별도의 학습용 프로필 ~/.claude-codegym/으로 실행한다면, 개인 스킬은 그 폴더 안의 skills/에 있습니다. 프로젝트 경로 .claude/skills/는 프로필과 상관없이 그대로입니다.

Description이 스킬의 작동 시점을 정한다

흔한 상황입니다. 폴더를 넣었고 파일도 제자리에 있는데, 에이전트는 예전과 똑같이 행동합니다. 고장 난 것은 없습니다. 에이전트가 이 스킬이 여기에 맞는다는 걸 알아차리지 못했을 뿐입니다.

선택하는 순간 에이전트가 손에 쥐고 있는 것이 무엇인지 보세요. 스킬 본문은 아직 읽지 않았고, 이름과 설명의 목록만 로드되어 있습니다. 그러니 판단 근거는 설명뿐, 다른 것은 없습니다.

프로젝트용 최소 스킬을 처음부터 끝까지 만들어 봅시다. 이름은 web-design입니다. 폴더 이름이 곧 이것이고, 명령 /web-design도 여기서 나옵니다. 여기서는 파일 안에 이름을 따로 적지 않습니다. 폴더가 이미 정해 두었으니까요.

.claude/skills/web-design/SKILL.md

내용은 이것뿐이고, 더 필요한 것은 없습니다.

---
description: 웹 인터페이스를 다듬습니다 - 현대적인 CSS, 부드러운 전환,
  통일된 색상 팔레트. 보기 좋게 또는 세련되게 만들어 달라고 할 때 사용합니다.
---

# 웹 디자인

은은한 그림자, 부드러운 전환, 공들인 타이포그래피를 사용해.
색상 팔레트는 일관되게 유지하고, 애니메이션은 호버와 요소 등장에 적용해.

맨 위의 세 개짜리 대시 줄 사이에는 메타데이터 블록이 있고, 그 아래는 평범한 지침 텍스트입니다. 필수 필드는 없지만, description은 늘 쓰는 게 좋습니다. 없으면 에이전트가 본문 첫 단락을 보고 스킬의 용도를 짐작하는데, 이건 복불복입니다.

좋은 설명은 두 가지 질문에 답합니다. 스킬이 무엇을 하는지, 그리고 언제 쓰는지. 그것도 여러분이 실제로 요청할 때 쓰는 단어로요.

# 조용함: 언제 적용할지 알 수 없음
description: 디자인을 도움

# 작동함: 무엇을 하는지, 언제 쓰는지 다 적혀 있음
description: 인터페이스를 다듬습니다 - CSS, 타이포그래피, 색상 팔레트.
  보기 좋게, 세련되게 만들거나 레이아웃을 고쳐 달라고 할 때 사용합니다.

설명은 스킬이 스스로 켜지는 시점을 정합니다. 하지만 입구가 이것 하나는 아닙니다. 스킬에는 이름이 있어서 직접 부를 수도 있습니다. /web-design을 입력하면 설명과는 아무 상관 없이 파일을 읽고 실행합니다.

완성된 스킬에서는 name 필드를 자주 보게 됩니다. 프로젝트와 홈 폴더의 스킬에서는 이 필드가 / 메뉴에 표시되는 명령을 정합니다. deploy-staging 폴더에 name: deploy가 있으면 /deploy로 호출합니다. 디렉터리 이름도 계속 사용할 수 있습니다. 플러그인에서는 name이 플러그인 이름 뒤에 오는 명령의 마지막 부분을 정할 수 있습니다.

정리하면 실행 경로는 두 가지이고, 그 뒤는 모두 같습니다.

왼쪽 갈래는 자동입니다. 요청이 설명과 맞아떨어지면 에이전트가 스킬을 가져다 씁니다. 오른쪽은 수동입니다. /web-design을 입력하면 설명과 상관없이 스킬이 실행됩니다.

스킬은 내장 명령어와 같은 / 메뉴에 나타납니다. 파일 .claude/commands/deploy.md와 스킬 .claude/skills/deploy/SKILL.md는 똑같은 명령어 /deploy를 만듭니다. 둘 다 있으면 스킬이 이깁니다.

설치하고 확인하기

폴더는 넣었습니다. 그런데 파일이 디스크에 그냥 놓여 있는 게 아니라 에이전트가 정말 알아봤는지는 어떻게 알까요?

/skills

이 명령은 스킬 목록을 열고 각 스킬의 출처를 보여 줍니다. 몇 글자 입력하면 목록이 걸러집니다. 내 폴더 이름이 보이고 상태가 on이면, Claude Code가 스킬을 인식했고 실행도 허용한다는 뜻입니다.

이름, 출처, on 상태가 보이면 스킬을 쓸 수 있다는 뜻입니다

보통 Claude Code는 새로 만들거나 고친 SKILL.md를 바로 알아챕니다. 목록에 이름이 없다면 차례대로 시도해 보세요.

스킬이 목록에는 있는데 저절로 켜지지 않나요? 이건 다시 불러오기로 해결되지 않습니다. description과 disable-model-invocation: true 필드를 확인하세요. 이 필드가 있으면 수동 호출만 남습니다. 요청을 다르게 표현하거나 이름으로 스킬을 호출해 보세요. 수동 호출이 된다면 설치에는 문제가 없습니다.

믿기 전에 확인할 것

여기서는 들뜬 마음을 조금 가라앉혀야 합니다. 스킬은 붙였다 뗐다 하는 테마나 그림이 아닙니다. 여러분의 에이전트가 여러분의 프로젝트에서 실행할 지침입니다.

메인 파일만이 아니라 폴더 전체를 확인해야 합니다. 먼저 네 가지부터 보세요.

• 설명 - 스킬에 기대한 것과 맞는지, 너무 넓게 작동하지는 않는지;
• 본문과 그 안의 링크 - 스킬이 무엇을 하라고 지시하는지, 옆의 어떤 파일을 열라고 하는지;
• scripts/ 폴더(있다면) - 어떤 명령이 실행되는지, 어떤 파일과 네트워크 주소에 접근하는지;
• allowed-tools 필드 - 스킬이 따로 묻지 않고 쓰도록 미리 허용하는 도구가 무엇인지.

---
name: pre-commit-style
description: 커밋 전에 프로젝트를 공통 스타일에 맞춤
allowed-tools: Read, Write, Edit, Glob
---

여기서 allowed-tools는 작업 계획을 설명하는 것도, 에이전트가 쓸 수 있는 도구 전체를 제한하는 것도 아닙니다. 이 필드는 스킬이 호출된 턴에 한해 나열된 도구를 미리 승인할 뿐입니다. 이름은 쉽게 풀이됩니다.

• Read - 파일 읽기;
• Write - 새 파일을 만들고 기존 파일을 통째로 덮어쓰기;
• Edit - 기존 파일 안의 내용 수정;
• Glob - 패턴으로 파일 찾기, 즉 프로젝트를 돌아다니며 무엇이 있는지 살펴보기.

처음과 마지막 도구는 보기만 합니다. Write와 Edit은 파일을 바꿀 수 있습니다. 지침이 그런 작업으로 이어지면, 이 턴에서는 따로 확인을 묻지 않을 수 있습니다. 다만 권한이 있다고 해서 에이전트가 꼭 그 도구를 쓰는 것은 아닙니다. 프로젝트의 일반적인 접근 규칙도 그대로 적용됩니다.

이 필드 자체가 나쁜 것은 아닙니다. 여러분이 딱 원하는 곳에서 불필요한 확인을 없애 줍니다. 하지만 도구 목록을 고른 사람은 스킬 작성자이니, 첫 실행 전에 확인해 두는 게 좋습니다.

마지막 하나는 덜 무섭지만 훨씬 자주 겪는 일입니다. 스킬은 에이전트의 방향을 잡아 줄 뿐, 결과를 보장하지 않습니다. 실행한 뒤에는 변경된 파일을 살펴보고 결과를 확인하세요. 디자인 스킬이 페이지를 더 보기 좋게 만들 수는 있어도, 버튼이 제대로 작동하는지는 아무도 대신 확인해 주지 않습니다.

완성된 스킬은 어디서 구할까

한번 써 보려고 SKILL.md를 처음부터 작성할 필요는 전혀 없습니다. 완성된 스킬은 대개 공개 저장소에서 찾거나 플러그인과 함께 받습니다.

가장 빠른 방법은 에이전트에게 알맞은 스킬을 찾아 달라고 하되, 확인 없이 설치하지는 않게 하는 것입니다. 이렇게 요청할 수 있습니다.

인터페이스 디자인용 스킬을 찾아 주세요. 출처, SKILL.md, 스크립트를 보여 주고,
어떤 파일과 도구를 쓰는지 설명해 주세요. 제가 확인하기 전까지는
아무것도 설치하지 마세요.

출처와 내용을 확인했다면, 폴더를 프로젝트의 .claude/skills/에 넣어 달라고 요청하고 /skills로 결과를 확인하세요.

직접 찾아보고 싶다면 Claude skills marketplace로 검색하면 됩니다. 카탈로그는 선택지를 찾는 데 도움이 되지만 안전을 보증하지는 않습니다. 설치 전에 내용을 읽어 보는 것은 여전히 필요합니다.

SKILL.md는 개방형 Agent Skills 표준을 따르므로, 기본 구조는 여러 에이전트에서 그대로 쓸 수 있습니다. 하지만 Claude Code는 자체 필드와 실행 방식을 더합니다. 스킬을 다른 도구로 옮겼다면, 그 도구가 실제로 어떤 기능을 지원하는지 확인하세요.

나만의 스킬은 에이전트와 함께 만들 수 있다

나만의 스킬을 만들 때가 됐다는 건 이론 없이도 알 수 있습니다. 같은 절차를 세 번째 설명하고 있을 때입니다. 작업 자체가 아니라 바로 행동 순서 말입니다. "이걸 살펴보고, 저걸 확인하고, 이런 형식으로 맞추고, 여기는 건드리지 마세요." 반복된다면 때가 된 겁니다.

여기서 좋은 소식이 있습니다. SKILL.md를 빈 페이지부터 쓸 필요는 없습니다. 초안은 에이전트가 만들 수 있고, 여러분은 어떤 절차인지, 그 절차에서 무엇을 원하는지 설명하면 됩니다. 평범한 대화처럼 보입니다.

커밋 준비용 스킬을 만들어 주세요. 무엇이 바뀌었는지 살펴보고,
불필요한 파일이 커밋에 들어가지 않았는지 확인하고,
우리 템플릿에 맞춰 커밋 메시지를 써야 합니다. 실행은 제가 원할 때 직접 하겠습니다.
요구 사항이 부족하면 먼저 질문해 주세요.

눈여겨보세요. 필드 이름은 하나도 말하지 않았고, 파일 구조에도 손대지 않았습니다. 요구 사항은 말로 전했고, 그것을 필드로 옮기는 건 에이전트의 몫입니다.

정보가 부족하면 에이전트가 질문합니다. 그렇게 해 달라는 요청이 없으면 곧바로 알아서 가정할 수도 있어서, 예시에 그 줄을 미리 넣어 두었습니다. 초안을 받으면 파일을 확인하고, /skills에서 스킬을 찾고, 시험 삼아 실행해 보세요.

절차를 직접 해 볼 수 있다면, 스킬로 묶기 전에 에이전트와 함께 한 번 해 보세요. 커밋 하나를 단계별로 진행해 보면 어디서 에이전트를 바로잡아야 했는지, 설명에 무엇이 빠졌는지 드러납니다. 실제로 한 번 돌려 보고 만든 스킬이 기억에 의존해 만든 스킬보다 정확합니다.

SKILL.md가 커질 때

첫 스킬은 거의 언제나 파일 하나로 나오고, 그래도 괜찮습니다. 비좁아지는 건 나중입니다. 절차에 세부 사항이 붙고, 대응표, 규칙 목록, 긴 예시 세 개가 안으로 들어오다 보면, 어느 날 네 화면짜리 파일을 열게 됩니다.

전부 한곳에 몰아넣을 필요는 없습니다. 이유는 앞에서 이미 말했습니다. 본문은 스킬이 실행되는 순간 통째로 로드됩니다. 그러니 네 화면짜리 참고 자료도, 그중 한 줄만 필요한 때조차 함께 딸려 들어갑니다.

그래서 세부 사항은 옆 파일로 빼고, SKILL.md에는 "이런 상황이면 이 파일을 열어" 같은 안내만 남깁니다. palettes.md와 scripts/가 있는 폴더는 이미 봤습니다. 안쪽은 이렇게 생겼습니다.

## 참고 자료

- 색상 팔레트와 색 조합 - [palettes.md](palettes.md) 참고
- 완성된 마크업 예시 - [examples.md](examples.md) 참고
- 명도 대비 확인: scripts/check.py 실행

참고 자료는 에이전트가 필요할 때 엽니다. 스크립트는 소스 전체를 대화에 자동으로 불러오지 않고도 실행할 수 있어서, 파일 크기가 컨텍스트를 거의 차지하지 않습니다. 그래도 남이 만든 스크립트는 처음 실행하기 전에 꼭 읽어 봐야 합니다. 실행되는 코드이고, 그 출력이 에이전트의 작업에 섞여 들어가기 때문입니다.

용도별로 나눠 두면 편합니다.

• SKILL.md - 절차 그 자체: 무엇을, 어떤 순서로 하고, 무엇을 하지 말아야 하는지. 호출 전에는 에이전트가 설명만 보고, 본문은 실행할 때 로드합니다;
• 참고 자료 - 표, 규칙, 긴 예시처럼 매번 필요하지는 않은 것들;
• scripts/ - 말로 설명하기보다 실행하는 편이 쉬운 것들. 남이 만든 스킬이라면 실행 전에 이 파일들을 확인합니다;
• 템플릿 - 스킬이 바탕으로 삼아 작업에 맞게 고치는 파일들.

여기서 거꾸로 남의 스킬에 대해서도 알 수 있는 게 있습니다. SKILL.md가 짧다고 "간단한 스킬"이라는 뜻은 아닙니다. 그 옆 폴더에 무엇이 들어 있는지 들여다보세요.

이것이 작업을 어떻게 바꾸는가

몇 줄로 정리하면 이렇습니다.

• 반복되는 요청이 폴더가 됩니다. 작업 순서를 한 번 설명해 두면, 그다음부터는 어느 세션에서든, 어느 날이든 똑같이 재현됩니다;
• 나만의 스킬을 빈 페이지부터 쓸 필요는 없습니다. 절차를 말로 설명하고, 빠진 부분은 물어봐 달라고 요청하고, 완성된 초안을 확인하면 됩니다;
• 자동 실행에서는 스킬이 description으로 선택되고, 수동 실행에서는 슬래시와 이름으로 선택됩니다. 스킬이 반응하지 않으면 먼저 목록에 보이는지, 자동 실행이 허용되어 있는지 확인하세요;
• /skills는 "제대로 설치됐나?"라는 질문에 답해 줍니다. 30초 확인이 30분 추측을 아껴 줍니다;
• 남이 만든 스킬은 설치하고 실행하기 전에, 관련 파일과 스크립트까지 함께 읽어 봅니다;
• 스킬은 에이전트의 일하는 방식을 바꾸지만, 수정 범위를 격리해 주지도, 결과 확인을 대신해 주지도 않습니다.