하네스 엔지니어링 - 클로드(CLAUDE) 기초 2. 스킬

Skills 시스템과 CLAUDE.md의 관계

1. 전체 구조: 두 개의 컨텍스트 레이어

Skills 시스템과 CLAUDE.md는 Claude에게 "맥락"을 주입하는 두 개의 독립적이지만 상호보완적인 레이어입니다.

📁 프로젝트 루트
├── CLAUDE.md          ← 프로젝트 전체에 적용되는 지시사항
└── my-skill/
    ├── SKILL.md       ← 특정 스킬에만 적용되는 지시사항
    ├── scripts/
    ├── references/
    └── assets/

 

 

 

	CLAUDE.md	SKILL.md
적용 범위	프로젝트 전체 (항상 활성)	특정 스킬 (트리거될 때만 활성)
로드 시점	Claude Code 세션 시작 시 자동 로드	available_skills 목록에서 선택될 때
주요 역할	환경 설정, 팀 규칙, 도구 설정	스킬별 행동 지침, 워크플로우

---

 

Claude 스킬 만들기: 처음부터 끝까지

이 문서는 Claude Code와 스킬(Skill) 시스템을 처음 접하는 분을 위한 교육용 가이드입니다.
"회의록 정리" 스킬 하나를 처음부터 만들고, 테스트하고, 실제로 사용하는 과정을 단계별로 설명합니다.

---

준비사항

• Claude Code가 설치되어 있어야 합니다 (npm install -g @anthropic-ai/claude-code)
• 터미널(Terminal) 사용법을 기본적으로 알고 있어야 합니다

---

1. 전체 구조 이해하기

스킬 시스템은 두 개의 파일이 함께 작동합니다.

내 프로젝트/
├── CLAUDE.md              ← Claude에게 "이 프로젝트에서 지켜야 할 규칙"을 알려주는 파일
└── skills/
    └── meeting-notes/     ← 스킬 폴더
        └── SKILL.md       ← Claude에게 "이 스킬을 어떻게 쓰는지" 알려주는 파일

CLAUDE.md : Claude Code를 열 때 자동으로 읽힙니다. "이 프로젝트에 어떤 스킬이 있고, 언제 써야 한다"는 지도 역할을 합니다.

SKILL.md : 사용자의 요청이 이 스킬과 관련이 있을 때만 읽힙니다. 스킬의 실제 작동 방법이 담겨 있습니다.

---

2. 예제 시나리오

팀에서 회의 후 누군가가 메모한 내용을 붙여넣으면,
Claude가 자동으로 참석자, 결정사항, 액션아이템이 정리된 회의록을 만들어주는 스킬을 만들겠습니다.

---

3. 폴더 만들기

터미널에서 아래 명령어를 실행합니다.

mkdir -p my-project/skills/meeting-notes
cd my-project

실행 후 폴더 구조:

my-project/
└── skills/
    └── meeting-notes/    ← 아직 비어 있음

---

4. CLAUDE.md 작성하기

my-project/ 폴더 바로 아래에 CLAUDE.md 파일을 만듭니다.

# my-project/ 폴더 안에서 실행
touch CLAUDE.md

파일 내용:

# CLAUDE.md

## 스킬 사용 원칙

이 프로젝트에는 `skills/` 폴더에 스킬이 있습니다.
작업을 시작하기 전에 관련 스킬이 있는지 확인하세요.

## meeting-notes 스킬

회의 내용, 회의록, 미팅 메모와 관련된 요청이 오면
반드시 `meeting-notes` 스킬을 사용하세요.

왜 CLAUDE.md가 필요한가?
SKILL.md는 Claude가 스스로 판단해서 꺼내 씁니다. CLAUDE.md에 "이런 요청이 오면 이 스킬을 써라"고 명시해두면 Claude가 더 정확하게 스킬을 활용합니다.

---

5. SKILL.md 작성하기

skills/meeting-notes/ 폴더 안에 SKILL.md를 만듭니다.

touch skills/meeting-notes/SKILL.md

파일 내용:

---
name: meeting-notes
description: |
  회의 내용이나 메모를 받아 참석자, 결정사항, 액션아이템이 포함된
  정형화된 회의록을 만들어주는 스킬.
  "회의록", "미팅 정리", "회의 메모", "회의 내용 정리" 등의
  요청이 오거나 회의와 관련된 날것의 텍스트가 제공되면 이 스킬을 사용한다.
---

# meeting-notes 스킬

## 작업 순서

1. 입력된 텍스트에서 다음 항목을 추출한다
   - 회의 날짜 (명시된 경우)
   - 참석자
   - 논의된 주요 안건
   - 결정된 사항
   - 각자 해야 할 일 (액션아이템)

2. 아래 양식에 맞춰 회의록을 작성한다

## 출력 양식

반드시 이 형식을 사용한다:

---
# 회의록

**날짜**: YYYY-MM-DD  
**참석자**: 이름1, 이름2, ...

## 논의 안건
- 안건 내용

## 결정사항
- 결정된 내용

## 액션아이템
| 담당자 | 내용 | 기한 |
|--------|------|------|
| 이름   | 내용 | 날짜 |

---
## 출력 규칙
- 회의록은 항상 한국어로 작성한다
- 날짜 형식은 YYYY-MM-DD를 사용한다
- 기한이 없는 액션아이템은 "미정"으로 표시한다

---
## 주의사항
- 입력 텍스트에 명시되지 않은 내용은 추측해서 채우지 않는다
- 기한이 언급되지 않은 액션아이템은 기한을 "미정"으로 표시한다
- 참석자가 불명확하면 텍스트에 등장하는 이름을 기준으로 한다

---

6. 지금까지 만든 파일 확인

# 현재 폴더 구조 확인
find . -type f

출력 결과:

./CLAUDE.md
./skills/meeting-notes/SKILL.md

이걸로 스킬 구성은 완료입니다.

---

7. Claude Code에서 직접 사용해보기

터미널에서 Claude Code를 실행합니다.

# my-project/ 폴더 안에서 실행
claude

Claude Code가 열리면, 아래 텍스트를 그대로 붙여넣어 보세요.

아래 회의 메모 정리해줘:

오늘 마케팅팀 미팅. 참석: 지수, 민준, 서연.
4분기 캠페인 주제로 SNS 집중하기로 했음.
지수가 인스타그램 콘텐츠 캘린더 만들기로, 다음주 금요일까지.
민준은 광고 예산안 작성. 이번달 말.
서연은 경쟁사 분석 리포트. 기한 미정.
다음 미팅은 2주 후.

예상 결과:

# 회의록

**날짜**: 미정  
**참석자**: 지수, 민준, 서연

## 논의 안건
- 4분기 마케팅 캠페인 방향 논의

## 결정사항
- SNS(인스타그램) 중심으로 캠페인 집중

## 액션아이템
| 담당자 | 내용                        | 기한           |
|--------|-----------------------------|----------------|
| 지수   | 인스타그램 콘텐츠 캘린더 작성 | 다음주 금요일  |
| 민준   | 광고 예산안 작성             | 이번달 말      |
| 서연   | 경쟁사 분석 리포트 작성      | 미정           |

스킬이 제대로 사용됐는지 어떻게 알 수 있나요?
Claude Code 화면에서 Claude가 skills/meeting-notes/SKILL.md를 읽었다는 표시가 나타납니다. 이것이 "스킬이 트리거됐다"는 의미입니다.

---

8. 트리거 테스트 이해하기

스킬을 직접 써보는 것 외에, "어떤 문장에서 스킬이 켜지는지"를 자동으로 검증하는 방법이 있습니다.

트리거 테스트가 필요한 이유

스킬이 다음처럼 작동하면 곤란합니다.

• "회의록 정리해줘"라고 했는데 스킬이 안 켜짐 (놓침)
• "오늘 날씨 어때?"라고 했는데 스킬이 켜짐 (오작동)

트리거 테스트는 이 두 가지 상황을 자동으로 잡아냅니다.

테스트가 검증하는 것 vs 검증하지 않는 것

검증함 검증 안 함

이 문장에서 스킬이 켜지는가?	스킬이 회의록을 잘 작성하는가?
관계없는 문장에서 스킬이 안 켜지는가?	출력 결과의 품질

즉, 회의 내용 같은 실제 파일이 없어도 됩니다.

---

9. 트리거 테스트 실행하기

Step 1. skill-creator 스크립트 준비

트리거 테스트는 skill-creator의 스크립트를 사용합니다. 아래 명령어로 복사해옵니다.

# my-project/ 폴더 안에서 실행
cp -r /mnt/skills/examples/skill-creator/scripts ./scripts

/mnt/skills/examples/skill-creator/scripts는 Claude Code 환경 안에 미리 설치된 스킬 도구 모음입니다.

Claude Code를 설치하면 내부적으로 /mnt/skills/ 라는 폴더가 마운트되는데, 거기에 Anthropic이 미리 만들어둔 예제 스킬들이 들어 있습니다. 그 중 skill-creator가 스킬을 만들고 테스트하는 도구 모음입니다.

/mnt/skills/                       ← Claude Code가 마운트하는 폴더
└── examples/
    └── skill-creator/
        └── scripts/               ← 트리거 테스트 도구들이 여기 있음
            ├── run_loop.py        ← 반복 테스트 + 자동 개선
            ├── run_eval.py        ← 단일 테스트 실행
            ├── improve_description.py  ← description 개선 제안
            └── package_skill.py   ← .skill 파일로 패키징

 

Step 2. 테스트 케이스 파일 작성

evals/ 폴더를 만들고 테스트 케이스를 작성합니다.

mkdir evals
touch evals/trigger-eval.json

evals/trigger-eval.json 내용:

[
  {
    "query": "어제 팀 회의 내용 정리해줘",
    "should_trigger": true
  },
  {
    "query": "오늘 미팅 메모 좀 깔끔하게 만들어줘",
    "should_trigger": true
  },
  {
    "query": "회의록 양식으로 정리해줘: 참석자 지수 민준, 내용은...",
    "should_trigger": true
  },
  {
    "query": "오늘 날씨 어때?",
    "should_trigger": false
  },
  {
    "query": "파이썬 코드 리뷰해줘",
    "should_trigger": false
  },
  {
    "query": "이메일 초안 작성해줘",
    "should_trigger": false
  }
]

should_trigger: true = 이 문장에서는 스킬이 켜져야 정상
should_trigger: false = 이 문장에서는 스킬이 켜지면 안 됨

Step 3. 테스트 실행

python -m scripts.run_loop \
  --eval-set evals/trigger-eval.json \
  --skill-path ./skills/meeting-notes \
  --model claude-sonnet-4-20250514 \
  --max-iterations 5 \
  --verbose

각 옵션 설명:

옵션	설명
-m scripts.run_loop	scripts/ 폴더 안의 run_loop.py를 실행
--eval-set	방금 만든 테스트 케이스 파일
--skill-path	테스트할 스킬의 폴더 경로 (SKILL.md가 들어있는 곳)
--model	테스트에 사용할 Claude 모델
--max-iterations	최대 몇 번 반복해서 개선할지
--verbose	진행 상황을 터미널에 출력

Step 4. 테스트 내부에서 일어나는 일

① SKILL.md에서 description(설명문) 추출

② 각 쿼리마다 다음을 반복 (3번씩):
   - claude -p "어제 팀 회의 내용 정리해줘" 실행
   - Claude가 meeting-notes 스킬 파일을 읽으려 했는가? 감시
   - Yes면 triggered=True, No면 triggered=False

③ 3번 중 2번 이상 트리거되면 → PASS
   should_trigger: true인데 PASS → 정상
   should_trigger: false인데 PASS → 오작동 (FAIL)

④ 실패한 케이스가 있으면:
   - Claude가 실패 원인을 분석
   - description을 개선한 버전 제안
   - 새 description으로 다시 테스트

⑤ 최대 5번 반복 후, 테스트 점수가 가장 높은 description 선택

Step 5. 출력 결과 읽기

Iteration 1/5
Description: 회의 내용이나 메모를 받아...
Train: 5/6 correct, precision=100% recall=83% accuracy=83% (12.3s)
  [PASS] rate=3/3 expected=True:  어제 팀 회의 내용 정리해줘
  [FAIL] rate=0/3 expected=True:  오늘 미팅 메모 좀 깔끔하게 만들어줘   ← 실패
  [PASS] rate=3/3 expected=True:  회의록 양식으로 정리해줘: 참석자...
  [PASS] rate=0/3 expected=False: 오늘 날씨 어때?
  [PASS] rate=0/3 expected=False: 파이썬 코드 리뷰해줘
  [PASS] rate=0/3 expected=False: 이메일 초안 작성해줘

Improving description...
Proposed: 회의 내용, 미팅 메모, 팀 미팅 정리 요청 시 사용...

Iteration 2/5
...
Train: 6/6 correct, precision=100% recall=100% accuracy=100%

All train queries passed on iteration 2!

"미팅 메모"라는 표현이 기존 description에 없어서 실패했고, iteration 2에서 description에 추가되어 통과된 예시입니다.

Step 6. 개선된 description을 SKILL.md에 반영

테스트가 끝나면 터미널에 best_description이 출력됩니다. 이걸 SKILL.md의 description 필드에 붙여넣으면 됩니다.

{
  "best_description": "회의 내용, 미팅 메모, 팀 미팅 정리, 회의록 작성 요청 시 사용...",
  "best_score": "6/6",
  ...
}

 

[AS-IS]

---
name: meeting-notes
description: |
  회의 내용이나 메모를 받아 참석자, 결정사항, 액션아이템이 포함된
  정형화된 회의록을 만들어주는 스킬.
  "회의록", "미팅 정리", "회의 메모", "회의 내용 정리" 등의
  요청이 오거나 회의와 관련된 날것의 텍스트가 제공되면 이 스킬을 사용한다.
---

# meeting-notes 스킬
... 생략

 

[TO-BE]

---
name: meeting-notes
description: |
  회의 내용이나 메모를 받아 참석자, 결정사항, 액션아이템이 포함된 정형화된 회의록을 만들어주는 스킬.
  회의 내용, 미팅 메모, 팀 미팅 정리, 회의록 작성 요청 시 사용.
  "회의록", "미팅 정리", "회의 메모", "회의 내용 정리", "팀 미팅 정리" 등의 
 요청이 오거나 회의와 관련된 날것의 텍스트가 제공되면 이 스킬을 사용한다.
---

# meeting-notes 스킬

## 작업 순서

1. 입력된 텍스트에서 다음 항목을 추출한다
   - 회의 날짜 (명시된 경우)
   - 참석자
   - 논의된 주요 안건
   - 결정된 사항
   - 각자 해야 할 일 (액션아이템)

2. 아래 양식에 맞춰 회의록을 작성한다

## 출력 양식

반드시 이 형식을 사용한다:

---
# 회의록

**날짜**: YYYY-MM-DD  
**참석자**: 이름1, 이름2, ...

## 논의 안건
- 안건 내용

## 결정사항
- 결정된 내용

## 액션아이템
| 담당자 | 내용 | 기한 |
|--------|------|------|
| 이름   | 내용 | 날짜 |
---

## 출력 규칙

- 회의록은 항상 한국어로 작성한다
- 날짜 형식은 YYYY-MM-DD를 사용한다

## 주의사항

- 입력 텍스트에 명시되지 않은 내용은 추측해서 채우지 않는다
- 기한이 언급되지 않은 액션아이템은 기한을 "미정"으로 표시한다
- 참석자가 불명확하면 텍스트에 등장하는 이름을 기준으로 한다

 

---

10. 완성된 파일 구조

my-project/
├── CLAUDE.md                     ← Claude에게 스킬 존재와 사용 규칙 알림
├── evals/
│   └── trigger-eval.json         ← 트리거 테스트 케이스
├── scripts/                      ← skill-creator에서 복사해온 테스트 도구
│   ├── run_loop.py
│   ├── run_eval.py
│   ├── improve_description.py
│   └── ...
└── skills/
    └── meeting-notes/
        └── SKILL.md              ← 스킬 본체

---

11. 전체 흐름 정리

사용자: "회의 메모 정리해줘"
         ↓
CLAUDE.md 참조 → "회의 관련이면 meeting-notes 스킬 써"
         ↓
SKILL.md description 확인 → "회의 메모" 키워드 매칭
         ↓
SKILL.md 본문 로드 → 작업 순서, 출력 양식 지침 확인
         ↓
회의록 작성 후 출력

트리거 테스트:
"어제 팀 회의 내용 정리해줘" → should_trigger: true  → 스킬이 켜지면 PASS
"오늘 날씨 어때?"            → should_trigger: false → 스킬이 안 켜지면 PASS
         ↓
실패 케이스 발견 → description 자동 개선 → 재테스트
         ↓
최적 description을 SKILL.md에 반영

---

12. 자주 하는 실수

스킬이 아예 안 켜질 때
→ SKILL.md의 description에 사용자가 실제로 쓸 법한 표현이 충분히 들어있는지 확인하세요. "회의록"만 있고 "미팅", "메모"가 없으면 해당 단어로 요청할 때 트리거가 안 됩니다.

관계없는 요청에도 스킬이 켜질 때
→ description이 너무 넓게 작성된 경우입니다. "텍스트 정리"처럼 범용적인 표현 대신 "회의, 미팅, 팀 미팅"처럼 구체적인 표현을 사용하세요.

SKILL.md를 읽었는데 지시를 안 따를 때
→ SKILL.md 본문의 지시가 모호한 경우입니다. "반드시 이 형식을 사용한다"처럼 명확한 지시어를 쓰고, 예시를 함께 넣어주세요.

트리거 테스트 실행 오류: No SKILL.md found
→ --skill-path에 지정한 경로가 SKILL.md 파일이 있는 폴더를 가리키는지 확인하세요.
올바름: --skill-path ./skills/meeting-notes
잘못됨: --skill-path ./skills/meeting-notes/SKILL.md