CPN 한국어 자습서 · 러닝패스 1 / 4 — Agent Skills
1장
Introduction to agent skills · What are skills?
Claude에게 일을 시키다 보면, 같은 설명을 자꾸 반복하게 되는 순간이 옵니다. 스킬(Skill)은 바로 그 반복을 없애 주는 기능입니다. 이 장에서는 스킬이 무엇인지, 실제로 어떻게 생겼고 어떻게 작동하는지를 처음부터 차근차근 살펴봅니다. 중간에 개발 용어가 나오면 그때마다 쉬운 말로 풀어 드리니, 모르는 단어가 있어도 걱정하지 마세요.
이 자습서를 보는 법
영어 영상을 먼저 본 뒤, 여기서 한국어로 따라 읽고 손으로 익히는 교재입니다. 점선 친 단어는 올리거나 탭하면 뜻이 나오고, 아래쪽엔 스킬이 작동하는 모습을 직접 눌러 보는 시뮬레이터가 있습니다. 읽은 만큼 ‘완료’를 누르면 위 진도 바가 찹니다.
#, - 같은 간단한 기호로 제목·목록을 표시하는 쉬운 글쓰기 방식입니다.개발자는 Claude에게 비슷한 부탁을 자주 반복합니다. PR고친 코드를 합치기 전에 “검토해 주세요”라고 올리는 요청.을 리뷰할 때마다 “이런 기준으로 봐 줘”라고 설명하고, 코드를 저장할 때마다 “커밋 메시지(저장 기록)는 이런 형식으로 써 줘”라고 알려줍니다. 매번 같은 말을 다시 하는 셈이죠.
스킬은 이 반복을 없앱니다. 한 번만 적어 두면, Claude가 그 상황이 올 때마다 알아서 적용합니다.
새 직원에게 매번 같은 지시를 내리는 대신, 업무 매뉴얼을 한 장 써서 건네는 것과 같습니다. 한 번 써 두면 다음부터는 알아서 그대로 합니다.
먼저 영상을 보세요. 영어가 어렵다면 아래 한국어를 같이 읽으면 됩니다. 자동 번역과 달리, 낯선 용어를 풀어서 옮겼습니다.
영상 대본 — 영어 영상을 보며 같이 읽으세요 (타임스탬프 기준).
SKILL.md 파일이 있습니다. 그중 ‘설명(description)’은 Claude가 이 스킬을 쓸지 판단하는 기준입니다. “이 PR을 리뷰해 줘”라고 하면, Claude는 그 요청을 가진 스킬들의 설명과 대조해 맞는 것을 찾아냅니다.~/.claude/skills에 두며, 모든 프로젝트에 함께 따라옵니다..claude/skills에 둡니다. 그 저장소를 클론하는 사람은 누구나 이 스킬을 자동으로 갖게 됩니다. 팀의 표준이 여기 담깁니다. 회사의 브랜드 가이드라인, 웹 디자인에 쓰는 폰트와 색상처럼요.CLAUDE.md 파일은 모든 대화에 로드됩니다. Claude가 늘 어떤 규칙을 지키게 하려면 그건 CLAUDE.md에 넣습니다. 반면 스킬은 요청과 맞을 때만 로드됩니다. 평소엔 이름과 설명만 올라와 있어 컨텍스트 윈도우Claude가 한 대화에서 한 번에 다루는 정보의 양. 가득 찰수록 효율이 떨어집니다.를 가득 채우지 않습니다. PR 리뷰 점검표가 디버깅 중에까지 올라와 있을 필요는 없으니까요. 실제로 리뷰를 요청할 때 비로소 로드됩니다.스킬은 어떤 작업의 방법을 Claude에게 한 번 가르쳐 두는 파일입니다. 정확히는 SKILL.md라는 이름의 마크다운 파일이고요. 한 번 만들어 두면 Claude가 필요할 때마다 그 내용을 꺼내 적용합니다.
조금 더 정확히 말하면, 스킬은 지침과 자료를 담은 ‘폴더’입니다. 그 폴더 안의 SKILL.md가 핵심이고, 필요하면 다른 파일이나 보조 프로그램(스크립트)을 함께 넣을 수도 있습니다.
막연하니 실제 스킬 하나를 열어 봅시다. 아래는 ‘PR을 리뷰하는 스킬(pr-review)’이 컴퓨터 안에 저장된 모습입니다.
파일 구조 — pr-review 폴더 안에 SKILL.md가 들어 있습니다.
.claude/ └─ skills/ ├─ commit-message/ └─ pr-review/ └─ SKILL.md
이 SKILL.md 파일을 편집기로 열면 이렇게 생겼습니다. (원문은 영어입니다. 복사해서 직접 열어볼 수 있어요.)
1 2 3 4 5 6 7 8 9 10 11 12 13 14
--- name: pr-review description: Reviews pull requests for code quality. Use when reviewing PRs or checking code changes. --- When reviewing code in this FastAPI project, check for: ## Code Quality 1. **Readability and clear naming** - descriptive names for variables, functions, classes 2. **Consistent patterns** - follow the existing router / schema / model patterns 3. **No hardcoded secrets** - use environment variables for keys and tokens ## FastAPI Specific 4. **Pydantic schemas** - proper models for request / response bodies
셋 중 description만 매칭에 쓰입니다. 본문은 발동된 뒤에 로드되고요 — 위의 두 시뮬레이터와 그대로 연결됩니다.
구조는 딱 두 부분입니다.
--- 사이에 적는 요약 정보. 여기에 이름·설명이 들어갑니다.). --- 사이에 들어가는 부분입니다. name은 스킬 이름, description은 “언제 이 스킬을 쓰는지”를 적습니다. Claude는 바로 이 description을 보고 스킬을 꺼낼지 말지 판단합니다.그럼 이 스킬은 실제로 어떻게 발동할까요? 아래에서 직접 눌러 보세요. 요청을 두 가지 준비했습니다. 같은 작업 폴더(commit-message·pr-review 두 스킬이 들어 있죠)에서, 요청이 다르면 Claude가 다른 스킬을 꺼낸다는 걸 보게 됩니다. (브랜치작업을 본 줄기에서 갈라 진행하는 ‘가지’. 여기서는 sg-221이라는 가지에 올라온 PR을 리뷰합니다. sg-221에 올라온 PR을 다루는 상황)
매칭 시뮬레이터 — 요청을 고르고 [실행]하면, Claude가 스킬을 고르는 과정이 보입니다.
요청을 하나 고르세요 — 사용자가 평범하게 부탁하는 말입니다
name: pr-review
Pull request를 코드 품질 기준으로 리뷰합니다. PR 리뷰나 코드 변경 점검 시 사용.
name: commit-message
변경 내용을 형식에 맞춰 커밋 메시지로 작성합니다. 커밋·저장할 때 사용.
고른 기준은 스킬 이름이 아니라 설명입니다. 사용자는 “pr-review를 써”라고 한 적이 없는데도, 뜻이 맞는 설명이 골라졌죠 — 이게 매칭이에요.
여기서 두 가지가 핵심입니다. 첫째, 사용자는 “○○ 스킬을 써”라고 따로 말하지 않았습니다. 그냥 평범하게 부탁했을 뿐이죠. 둘째, 그런데도 요청이 다르면 다른 스킬이 불려 왔습니다. Claude가 각 요청을 스킬들의 설명(description)과 대조해, 뜻이 맞는 스킬을 고른 겁니다. 이렇게 ‘뜻으로 골라 잇는 것’을 매칭이라고 합니다.
이렇게 상황을 알아차려 스스로 발동하는 것이 스킬의 가장 큰 특징입니다. 사람이 일일이 “이 매뉴얼 펴”라고 시키지 않아도, 알아서 맞는 매뉴얼을 꺼내 보는 셈이죠.
PR이 올라온 브랜치가 있는 저장소에서, Claude Code에 이렇게 입력해 보세요. (sg-221은 본인 브랜치 이름으로 바꾸세요.)
pr-review 같은 스킬이 있으면, 따로 지정하지 않아도 Claude가 알아서 불러옵니다.
스킬은 PC(Claude Code) 전용이라 모바일 앱에서는 발동하지 않습니다. 위 시뮬레이터로 발동 흐름을 익혀 두고, PC에서 직접 확인해 보세요.
스킬은 누가 쓰는지에 따라 두는 위치가 다릅니다.
~/.claude/skills(내 컴퓨터의 기본 폴더)에 둡니다. 어떤 프로젝트를 하든 늘 따라옵니다. 커밋 메시지 스타일, 문서 형식, 코드를 설명받는 방식 같은 개인 취향을 담습니다..claude/skills에 둡니다. 그 저장소를 복제(클론)해 가는 사람은 누구나 자동으로 받습니다. 회사 브랜드 가이드라인, 웹 디자인용 폰트·색상 같은 팀 표준을 담습니다.참고로 Windows에서는 개인 스킬이 C:\Users\<사용자>\.claude\skills에 위치합니다. 프로젝트 스킬은 코드와 함께 저장(버전 관리)되어 팀 전체가 같은 스킬을 공유합니다.
나만 보는 메모는 ‘내 수첩’에, 팀이 함께 쓰는 규칙은 ‘공용 게시판’에 둔다고 생각하면 됩니다.
위치 시뮬레이터 — 프로젝트를 바꿔 보면, 무엇이 따라오고 무엇이 안 따라오는지 보입니다.
내 컴퓨터 · 지금 프로젝트 A에서 작업 중
my-style
~/.claude/skills/
어디서나팀원의 컴퓨터
개인 스킬은 나를 따라 어느 프로젝트에서나 뜹니다. 프로젝트 스킬은 그 저장소 안에만 살고, 저장소를 클론하는 사람 모두에게 함께 가죠 — 단, 내 개인 스킬은 따라가지 않아요.
Claude의 동작을 조정하는 방법은 스킬 말고도 있습니다. 셋을 비교해 봅시다.
CLAUDE.md는 벽에 붙은 상시 공지, 스킬은 서랍 속 매뉴얼(필요할 때 꺼냄), 슬래시 커맨드는 내가 직접 누르는 호출 버튼입니다.
컨텍스트 윈도우 시뮬레이터 — 요청을 보내면, 그 스킬의 본문만 작업 기억으로 들어옵니다.
스킬 보관함평소엔 여기서 대기
pr-review
PR을 코드 품질 기준으로 리뷰…
＋ 본문(점검표)은 숨김 · 필요할 때만
commit-message
커밋 메시지를 형식에 맞춰 작성…
＋ 본문(형식 규칙)은 숨김 · 필요할 때만
컨텍스트 윈도우Claude의 작업 기억
— 여유 공간 —
스킬은 평소 이름 + 설명만 떠 있어 기억 공간을 거의 안 씁니다. 실제 본문은 매칭됐을 때만 로드되죠. 그래서 스킬이 수십 개여도 컨텍스트가 가득 차지 않습니다 — 반면 CLAUDE.md는 언제나 전체가 로드됩니다.
스킬은 ‘특정 상황에 반복적으로 쓰이는 규칙’에 가장 잘 맞습니다. 예를 들면:
판단 기준은 아주 간단합니다. 같은 설명을 Claude에게 자꾸 반복하고 있다면, 그것이 바로 스킬로 만들 신호입니다.
SKILL.md 파일에 담기고, 맨 위 라벨(이름·설명)로 ‘언제 쓸지’를 알린다.정답을 먼저 떠올려 본 뒤 골라 보세요. 맞히면 설명이 나옵니다.
Q1스킬은 어떻게 발동하나요?
맞아요. 스킬은 요청과 뜻이 맞을 때 Claude가 알아서 꺼냅니다. 직접 입력해 부르는 건 슬래시 커맨드죠.
Q2팀 전체가 함께 쓸 규칙은 어디에 두나요?
프로젝트 스킬이에요. 저장소를 클론하는 사람은 누구나 자동으로 받습니다. 개인 스킬은 내 컴퓨터에만 따라다녀요.
Q3Claude가 ‘어떤 스킬을 쓸지’ 정하는 기준은?
설명(description)이에요. Claude는 요청을 각 스킬의 설명과 대조해 뜻이 맞는 걸 고릅니다. 이름은 스킬을 가리키는 표지일 뿐이죠.
요청과 스킬 설명을 견주어 어느 스킬이 발동하는지 확인하고, 설명 문구를 고치면 결과가 어떻게 달라지는지 봅니다.
// 스킬 매칭 시뮬레이터 — 스킬은 요청과 맞을 때만 자동으로 발동한다.
// Claude는 요청을 읽고, 준비된 스킬들의 '설명(description)'과 견주어
// 가장 잘 맞는 하나를 꺼낸다. 매칭에 쓰이는 것은 오직 description이다.
//
// (실제 Claude는 문장의 '의미'로 매칭한다. 여기서는 그 개념을 로컬 로직으로
// 재현한다 — description에 담긴 말이 요청에 얼마나 겹치는지로 점수를 낸다.)
// 매칭에서 걸러 낼 흔한 말(불용어). 점수를 흐리지 않도록 제외한다.
const STOP = ["use","when","for","and","the","to","in","of","code","및","등","쓴다","한다","정리할","검토할"];
// description에서 매칭에 쓸 낱말만 추린다(소문자화 · 불용어 제거 · 2자 이상).
function keywords(text) {
const raw = text.toLowerCase().split(/[^0-9a-z가-힣]+/);
const out = [];
raw.forEach(function (w) {
if (w.length >= 2 && STOP.indexOf(w) === -1 && out.indexOf(w) === -1) out.push(w);
});
return out;
}
// 요청 한 줄을 스킬 하나의 description과 견준다. description의 낱말이 요청 문장
// 안에 들어 있으면 한 점(부분 일치 허용 — '리뷰'는 '리뷰해줘' 안에 들어 있다).
function score(request, skill) {
const req = request.toLowerCase();
const hits = keywords(skill.description).filter(function (k) {
return req.indexOf(k) !== -1;
});
return { skill: skill.name, score: hits.length, hits: hits };
}
// 요청 하나에 모든 스킬을 채점하고 가장 높은 하나를 고른다.
// 아무 스킬도 겹치지 않으면 — 발동 없음(Claude는 평소대로 답한다).
function match(request, skills) {
const scored = skills.map(function (s) { return score(request, s); });
scored.sort(function (a, b) { return b.score - a.score; });
const top = scored[0];
return { scored: scored, winner: top && top.score > 0 ? top.skill : null };
}
// ── 여기서부터 직접 고쳐 보세요 ──
// 작업 폴더에 놓인 스킬 두 개. description 문구를 바꾸면 매칭 결과가 달라집니다.
const skills = [
{ name: "pr-review",
description: "Reviews pull requests. PR·풀리퀘스트 리뷰, 코드 변경을 검토할 때 쓴다." },
{ name: "commit-message",
description: "Writes commit messages. 커밋 메시지 형식을 정리할 때 쓴다." },
];
// Claude에게 건네는 요청들. 문장을 바꿔 어느 스킬이 발동하는지 확인해 보세요.
const requests = [
"sg-221 브랜치 PR 좀 리뷰해줘",
"방금 고친 거 커밋 메시지 좀 써줘",
"오늘 부산 날씨 어때?",
];
// ── 여기까지 ──
requests.forEach(function (request) {
const result = match(request, skills);
console.log('요청: "' + request + '"');
result.scored.forEach(function (r) {
console.log(" " + r.skill + " — 점수 " + r.score +
" · 겹친 말: " + (r.hits.length ? r.hits.join(", ") : "없음"));
});
console.log(result.winner
? " → 발동: " + result.winner + " (description이 요청과 가장 많이 겹칩니다)"
: " → 발동 없음 — 맞는 스킬이 없으면 Claude는 평소대로 답합니다.");
console.log("");
});
다음 장에서는 스킬을 처음부터 직접 만들어 봅니다. SKILL.md 파일을 어떻게 쓰고, Claude가 그것을 어떻게 찾아내는지 손으로 따라 해 봅니다.