17장: 스킬 — AI에게 작업 방식 가르치기
스킬이란 무엇인가
스킬은 AI에게 특정 작업을 하는 방법을 가르치는 것입니다. 코드 리뷰를 할 때마다 "보안 문제가 있는지 확인해줘, 에러 처리도 봐줘, 가독성도 체크해줘"라고 말하는 건 번거롭습니다. 이걸 스킬로 만들어두면 /code-review처럼 한 번에 실행할 수 있습니다.
스킬을 만들 때는 Claude Code에게 시키면 됩니다. Claude Code가 .claude/skills/ 폴더 안에 SKILL.md 파일을 직접 만들어줍니다.
스킬이 좋은 또 다른 이유는 컨텍스트를 거의 소모하지 않는다는 점입니다. 스킬은 내용을 한꺼번에 올리지 않습니다. Claude Code가 시작할 때는 각 스킬의 description만 읽습니다. 스킬 하나당 한두 문장 분량입니다. 실제 지시 내용은 그 스킬을 호출할 때 컨텍스트에 올라옵니다. MCP가 연결하는 순간 수십 가지 함수 정의를 통째로 올리는 것과 다릅니다. 스킬을 여러 개 만들어둬도 컨텍스트는 거의 늘지 않습니다.
스킬 파일은 어떻게 생겼나
스킬은 두 부분으로 이루어집니다. 상단의 frontmatter와 그 아래 지시 내용입니다.
---
name: code-review
description: 코드 리뷰를 요청할 때 사용. 보안, 에러 처리, 가독성, 개선점을 순서대로 체크한다.
---
코드 리뷰 시 아래 순서로 진행한다.
1. SQL 인젝션, XSS 등 보안 취약점 확인
2. 예외 처리와 에러 응답이 적절한지 확인
3. 변수명, 함수 길이, 중복 코드 등 가독성 확인
4. 리팩토링이나 성능 개선 여지 제안
frontmatter는 ---으로 감싼 설정 영역입니다. name은 슬래시 커맨드 이름이 되고, description은 Claude Code가 읽는 설명입니다. 설명이 구체적일수록 스킬이 정확한 타이밍에 작동합니다.
자동 실행과 수동 실행
스킬은 두 가지 방식으로 실행됩니다. /code-review처럼 슬래시 커맨드로 직접 부르거나, Claude Code가 대화 흐름을 보고 스스로 불러오는 방식입니다. "이 코드 리뷰해줘"라고 하면 description을 읽고 code-review 스킬을 자동으로 적용합니다.
반대로 운영 배포처럼 자동으로 돌아서는 안 되는 스킬은 frontmatter에 disable-model-invocation: true를 넣어두면 됩니다. 그러면 Claude Code가 description조차 읽지 않아서 슬래시 커맨드로 직접 부를 때까지 컨텍스트 비용이 0입니다.
좋은 스킬의 조건
좋은 스킬의 핵심은 구체적인 단계입니다. 아래 두 스킬을 비교해보면 차이가 명확합니다.
나쁜 스킬
---
name: code-review
description: 코드 리뷰를 한다.
---
코드를 잘 리뷰해줘.
좋은 스킬
---
name: code-review
description: 코드 리뷰를 요청할 때 사용. 보안, 에러 처리, 가독성, 개선점을 순서대로 체크한다.
---
코드 리뷰 시 아래 순서로 진행한다.
1. SQL 인젝션, XSS 등 보안 취약점 확인
2. 예외 처리와 에러 응답이 적절한지 확인
3. 변수명, 함수 길이, 중복 코드 등 가독성 확인
4. 리팩토링이나 성능 개선 여지 제안
"잘 해줘"는 실행할 때마다 다른 결과를 냅니다. "이 4가지를 이 순서로"는 항상 같은 방식으로 작동합니다. 쓰다 보면 "이 작업은 항상 이 방식으로 해야 해"라는 패턴이 보이기 시작합니다. 그게 스킬로 만들 타이밍입니다.
팀과 함께 쓰기
스킬 파일은 프로젝트 폴더 안에 있기 때문에 git에 커밋하면 팀 전체가 쓸 수 있습니다.
git add .claude/skills/
git commit -m "add code-review skill"
팀원이 git pull하면 바로 같은 스킬을 쓸 수 있습니다. 팀이 합의한 코드 리뷰 기준, 커밋 컨벤션, 배포 절차 등을 스킬로 정의해두면 새 팀원도 처음부터 같은 방식으로 일합니다.
저장 위치에 따라 적용 범위가 달라집니다. .claude/skills/에 저장하면 해당 프로젝트에서만 작동하고, ~/.claude/skills/에 저장하면 내 모든 프로젝트에서 쓸 수 있습니다.
스킬 아이디어
기준은 하나입니다. Claude Code에게 같은 말을 반복하고 있다면 스킬로 만들 때가 된 겁니다.
커밋 메시지 작성이 대표적입니다. 팀마다 컨벤션이 다른데, "우리 팀은 feat:, fix: 형식으로 써줘"라고 설명하는 대신 스킬로 만들어두면 됩니다. 배포 전 체크리스트도 스킬로 만들 수 있습니다. "환경변수 확인했어? 마이그레이션 돌렸어?"처럼 실수하기 쉬운 항목을 스킬로 정의해두면 빠뜨리지 않습니다. 새 API 엔드포인트를 만들 때 설계 원칙, 에러 코드, 응답 형식 일관성을 체크하는 스킬도 유용합니다.
앞 장에서 다룬 Supabase 데이터 조회처럼 자주 반복하는 CLI 패턴도 스킬로 만들 수 있습니다. "미수금 항목 뽑아줘"라고만 해도 어떤 테이블에서 어떤 조건으로 조회할지 Claude Code가 알아서 처리합니다.
✏️ 실습: 코드 리뷰 스킬 만들기
1단계: 코드 리뷰 스킬을 만듭니다.
코드 리뷰 스킬을 만들어줘.
보안, 에러 처리, 가독성, 개선점 네 가지를 순서대로 체크하는 스킬이야.
2단계: Claude Code가 만든 .claude/skills/code-review/SKILL.md 파일을 직접 열어봅니다. frontmatter와 지시 내용이 어떻게 구성됐는지 확인하고, 마음에 안 드는 부분이 있으면 직접 수정해보세요.
3단계: 스킬을 실행해봅니다.
/code-review
4단계: 내 프로젝트에 맞는 스킬을 하나 더 만들어봅니다. 커밋 메시지 컨벤션이나 배포 전 체크리스트 중 더 필요한 걸 골라보세요.
참고자료