본문으로 건너뛰기

Ch10. 스킬 (Skills) — 자주 시키는 일을 한 단어로

이 장을 끝내면 할 수 있는 것: 자주 시키는 일을 SKILL.md 한 장으로 묶어, 다음번엔 키워드 한 마디로 자동 호출되도록 만들 수 있다.

1. 한 번 가르치면 매번 안 가르쳐도 되는 게 스킬이다​

Ch4에서 CLAUDE.md로 "이 폴더의 규칙"을 적어뒀다. 그 폴더 안에서 시작하는 모든 대화에 그 규칙이 자동 적용된다.

**스킬(Skill)**은 한 단계 더 나아간다. 폴더 단위가 아니라 작업 단위로 묶어둔 매뉴얼이다.

예를 들어 "주간 회의록을 5줄 요약 + 다음 액션 표로 정리하기"라는 일을 매주 한다. 매번 4공식을 새로 적는 대신, 이 절차를 한 번 SKILL.md 한 장으로 적어두면 — 다음번 회의록을 던지는 순간 Claude가 알아서 그 매뉴얼을 꺼내 따른다.

  • 스킬 — 자주 시키는 작업의 절차를 마크다운 파일로 적어둔 것. 트리거 조건이 맞으면 Claude가 자동 로드.
  • SKILL.md — 스킬의 정의 파일. 마크다운 본문 + 위에 짧은 메타정보(YAML frontmatter)로 구성.
  • 자동 트리거 — 사용자가 명시 호출하지 않아도, description의 키워드가 메시지에 등장하면 Claude가 스스로 그 스킬을 불러온다.

이 장이 책에서 다뤄질 가치는 한 가지다 — 스킬 5개가 익숙해진 순간부터 같은 일에 들이는 시간이 1/5로 준다. 매주 1시간 작업이 12분으로.

ch10-skills-folder

.claude/skills/ 폴더 안에 여러 스킬 폴더(skill-name/SKILL.md 구조)가 보이는 화면

2. 무엇과 어떻게 다른가​

2-1. 4공식 vs CLAUDE.md vs 스킬​

축4공식 (매번 적기)CLAUDE.md스킬
적용 범위한 메시지한 폴더 안 모든 대화모든 폴더, 키워드 매치 시
호출 방식매번 4줄자동 (폴더 진입 시)자동 (메시지 키워드 매치 시)
누가 만드나사용자 직접사용자사용자 또는 마켓플레이스
재사용×그 폴더에서만모든 폴더, 평생
만드는 시간30초 (매번)5분 (한 번)10분 (한 번)

핵심 차이: 4공식은 매 메시지, CLAUDE.md는 한 폴더, 스킬은 온 컴퓨터. 위로 갈수록 한 번 들이는 시간이 길지만 평생 절약하는 시간이 길다.

2-2. SKILL.md의 표준 구조​

---
name: meeting-summarizer
description: 주간 회의록 1페이지를 5줄 요약 + 다음 액션 표로 정리하는 스킬.
             "회의록 정리", "이번 주 미팅 요약" 같은 표현이 나오면 반드시 사용.
---

# meeting-summarizer — 주간 회의록 한 장 요약 스킬

## 절차
1. 입력 폴더(data/)의 가장 최신 meeting-*.md 1장을 읽는다
2. 핵심 5줄을 추출 (불릿 5개)
3. "다음 액션" 항목을 (담당자 / 액션 / 기한) 3컬럼 표로 정리
4. output/summary-YYYYMMDD.md 로 저장

## 출력 형식
- 한국어 존댓말
- 5줄 요약은 불릿
- 액션 표 마지막에 "다음 회의" 한 줄 추가
- 참석자 실명 대신 직책으로 표기 (예: 한지훈 → PM)
부분설명
--- ~ --- (YAML frontmatter)name과 description. description이 자동 트리거의 핵심
본문구체적 절차. 4공식의 ROLE·CONTEXT·TASK·FORMAT을 풀어쓴 매뉴얼

3. ⚠️ 처음 사람들이 자주 막히는 곳​

함정 1. description이 약해 자동 트리거 안 됨​

가장 흔한 실패. SKILL.md는 만들었는데 메시지를 던져도 Claude가 알아채지 못한다. 원인은 description이 너무 모호하거나 짧아서.

나쁜 예:

description: 회의록 처리 스킬

좋은 예:

description: 주간 회의록 1페이지를 5줄 요약 + 다음 액션 표로 정리하는 스킬.
             "회의록 정리", "이번 주 미팅 요약", "월요일 회의 정리" 같은 표현이 나오면 반드시 사용.

규칙: description은 하는 일 + 구체적 트리거 표현을 모두 담는다. 모호함을 피하고 적극적으로 — Claude가 빠뜨리지 않게 명확하게 — 적는다.

ch10-bad-vs-good-description

좌: 약한 description SKILL.md, 우: 강한 description SKILL.md 두 화면 비교

함정 2. 본문이 500줄 초과 — 컨텍스트 무거움​

스킬은 자동 로드되기 때문에 본문이 무거우면 매번 그 분량이 컨텍스트에 들어간다. 500줄을 넘기면 다른 스킬·작업의 여유 공간이 줄어든다 (Ch8 토큰 절약과 같은 원리).

대처:

  • 핵심 절차만 SKILL.md에 (보통 100~200줄로 충분)
  • 부가 자료(예시 파일·참조 문서)는 같은 폴더 안 references/에 두고, SKILL.md에서 "필요할 때 references/x.md를 읽어" 라고만 안내

함정 3. 너무 좁은 스킬 — 한 번 쓰고 안 쓰게 됨​

"2026년 5월 첫째 주 보고서 작성 스킬" 같은 너무 좁은 스킬은 한 번 쓰고 만다. 스킬은 3번 이상 반복될 일일 때만 만든다.

기준: "이 일을 다음 분기에도 또 할 것 같다" — YES면 스킬, NO면 4공식 한 번으로 끝.

4. 5분 미니 실습 — 첫 SKILL.md 작성 (회의록 정리 스킬)​

전제​

  • Ch4를 끝내 CLAUDE.md를 한 번 작성해봤다
  • 매주 반복하는 작업 1개를 정한다 (회의록 정리, 메일 분류, 일정 표 만들기 등)

단계​

  1. 사용자 스킬 폴더를 만든다.

    • macOS / WSL: mkdir -p ~/.claude/skills/meeting-summarizer
    • Windows PowerShell: New-Item -ItemType Directory -Path "$HOME\.claude\skills\meeting-summarizer"

    ✓ 체크포인트: 그 경로에 폴더가 만들어졌다.

  2. 그 폴더 안에 SKILL.md 파일을 만든다.

  3. SKILL.md에 다음 템플릿을 채운다.

    ---
    name: meeting-summarizer
    description: 주간 회의록 1페이지를 5줄 요약 + 다음 액션 표로 정리하는 스킬.
                 "회의록 정리", "이번 주 미팅 요약" 같은 표현에 반드시 사용.
    ---

    # meeting-summarizer — 회의록 한 장 요약 스킬

    ## 절차
    1. 회의록 본문을 읽는다
    2. 핵심 5줄 추출
    3. "다음 액션" 항목을 (담당자/액션/기한) 표로

    ## 출력 형식
    - 5줄 불릿 + 3컬럼 표
    - 한국어 존댓말
    - 참석자 실명 대신 직책으로 표기

  4. 저장한다.

  5. 새 대화창에서 description의 트리거 표현 중 하나를 던져본다.

    이번 주 미팅 요약해줘. 회의록은 아래야...

    ✓ 체크포인트: Claude가 meeting-summarizer를 자동 로드했다는 표시 또는 그 절차에 따른 응답이 나온다.

결과 인증​

이 실습을 끝냈다면:

  • 자기 첫 스킬이 ~/.claude/skills/meeting-summarizer/SKILL.md에 있다
  • 트리거 표현으로 자동 호출이 동작한다
  • 같은 일을 다음 주에 또 시킬 때 4공식을 다시 안 적어도 된다

⚠️ 트러블슈팅​

문제 1: 트리거 표현을 던졌는데 Claude가 알아채지 못합니다. → description을 더 구체적으로. 키워드 2~3개 명시 (예: "회의록 정리", "미팅 요약", "월요일 회의").

문제 2: 스킬이 작동하지만 결과가 SKILL.md 절차와 다릅니다. → Claude가 절차를 흘려봤을 가능성. SKILL.md 본문에 "위 절차를 그대로 따라" 한 줄 추가.

문제 3: 같은 폴더에 여러 스킬이 있는데 다른 스킬이 호출됩니다. → description의 키워드가 겹치는 경우. 더 구체적인 표현으로 차별화.

5. 한 가지 더 — 훅(Hooks) 한 박스​

스킬은 트리거 표현이 메시지에 등장하면 호출되는 자동화. 그런데 어떤 자동화는 트리거 없이 사건이 일어날 때마다 작동해야 한다 — 파일을 저장할 때 자동 검사, 세션이 시작될 때 자동 메모 로드, 커밋 직전 자동 보안 점검 같은 일. 이때 쓰는 게 **훅(Hooks)**이다.

도구호출 시점
슬래시 커맨드사용자가 직접 /clear 같은 단어 입력
스킬메시지에 트리거 표현이 등장
훅파일 저장·세션 시작·커밋 직전 같은 사건이 일어남

훅은 ~/.claude/settings.json의 hooks 항목에 "PreToolUse / PostToolUse / SessionStart" 같은 시점을 적고, 그때 실행할 명령을 짝지어 둔다. 비개발자에게는 자주 안 쓰지만 한 번 알아두면 강력한 도구. 매주 같은 시점에 자동으로 도는 일이 늘어나면 훅을 떠올린다.

다음 장으로: Ch11에서는 스킬을 한 단계 더 발전시킨 도구 — 에이전트·서브에이전트를 다룬다. 스킬이 매뉴얼이라면 에이전트는 그 매뉴얼을 들고 일하는 일꾼이다.

© 2026 COMMME · Built with Claude Code