클로드 스킬 예시, 원칙당 2~3개면 충분합니다 — 지식이 아니라 «취향»을 가르치는 자리라서

클로드 스킬 예시, 원칙당 2~3개면 충분합니다 — 지식이 아니라 «취향»을 가르치는 자리라서

한 줄 요약클로드 스킬의 예시는 원칙당 2~3개면 충분합니다.
같은 스킬을 예시 2개와 8개로 만들어 42번 돌려 보니, 원칙에 적어 둔 규칙은 예시 2개로도 모두 지켰습니다.
차이는 원칙에 안 적은 «취향»에서 났어요.
예시에만 들어 있던 말머리는 낯선 입력에서 예시 2개면 8번 중 3번만 붙었습니다.
그래서 예시를 늘리기 전에 그 취향을 원칙 한 줄로 적는 게 먼저입니다.
예시에 틀린 사실이 섞이면 그것도 따라 배웁니다.

스킬을 만들다가 «예시» 칸 앞에서 멈춘 적 있으시죠.
두 개면 너무 적은 것 같고, 열 개를 넣자니 파일이 길어집니다.

찾아보면 «예시를 넣으면 좋다»는 말은 많습니다.
그런데 몇 개면 되는지, 늘리면 뭐가 달라지는지는 잘 안 나와요.

저도 스킬마다 예시 개수가 제각각이었습니다.
그래서 같은 스킬을 예시 2개짜리와 8개짜리로 만들어 직접 돌려 봤어요.

결론은 이렇습니다. 원칙에 적어 둔 건 예시 2개로 충분했습니다.
흔들린 건 원칙에 안 적은 «취향»이었어요.

이 글에서 확인하실 수 있는 것

하나. 예시 2개와 8개가 실제로 얼마나 다른 결과를 냈는지 출력 그대로 보실 수 있습니다.

둘. 예시가 가르치는 게 지식이 아니라 취향이라는 게 무슨 뜻인지 확인하실 수 있습니다.

셋. 예시 칸을 채우기 전에 먼저 할 일 세 가지를 가져가실 수 있습니다.

---

한 줄 결론 — 예시는 원칙에 없는 것만 가르칩니다

스킬은 클로드에게 특정 일을 하는 방법을 적어 둔 설명서입니다.
파일 이름은 SKILL.md예요.
스킬이 무엇인지는 스킬 75개를 열어 본 글에 정리했습니다.

스킬 본문에는 보통 원칙과 예시가 함께 들어갑니다.
원칙은 «날짜를 맨 앞에 쓴다»처럼 말로 적은 규칙이에요.
예시는 «이런 입력이면 이렇게 낸다»를 보여 주는 입력과 출력 한 쌍입니다.

실험해 보니 둘이 맡는 일이 달랐습니다.

원칙에 적은 규칙은 예시 2개로도 전부 지켰고, 예시에만 있던 말머리 취향은 낯선 입력에서 예시 2개면 3/8만 붙었다

원칙에 적은 것과 예시에만 있는 것 — 예시 개수가 영향을 준 건 뒤쪽뿐이었습니다

원칙에 적은 규칙은 예시가 2개든 8개든 똑같이 지켰습니다.
예시를 더 넣어도 나아질 게 없었어요.

예시에만 들어 있는 취향은 달랐습니다.
입력이 예시와 비슷하면 2개로도 따라왔어요.
입력이 낯설어지자 2개로는 흔들렸습니다.

그래서 순서가 정해집니다. 취향이 흔들리면 예시를 늘리기 전에, 그 취향을 원칙 한 줄로 적습니다. 예시는 원칙마다 2~3개면 됩니다.

이렇게 실험했습니다

2026-09-16에 맥에서 스킬 두 개를 만들었습니다.
원칙과 출력 형식은 똑같이 두고 예시 개수만 2개와 8개로 바꿨어요.

	실험 1 · 파일이름 스킬	실험 2 · 메일제목 스킬
원칙	날짜를 맨 앞에 · 띄어쓰기 대신 하이픈 · «최종» 금지	할 일이 보이게 · 날짜가 있으면 넣기 · 30자 이내
예시 2개	회의 메모 · 영수증 모음	둘 다 [요청] 말머리
예시 8개	위 2개 + 사내 문서 6개	위 2개 + [공유]·[확인] 말머리 6개
일부러 준 입력	예시에 없는 개인 사진 폴더	예시에 없는 사과 메일 · 홍보 메일
돌린 횟수	조건마다 6번	조건마다 8번 (홍보 메일 8개 조건은 6번)

실험 설계 — 스킬 파일과 원본 출력은 그대로 보관했습니다

말머리는 제목 맨 앞에 붙이는 [요청] 같은 분류 표시입니다.
메일제목 스킬의 원칙에는 말머리 얘기가 한 줄도 없어요. 예시에만 들어 있습니다. 이게 이번 실험의 «취향»입니다.

모델은 하이쿠(Haiku)로 골랐습니다.
클로드 모델 중 가장 작고 빠른 모델이에요.
공식 문서도 하이쿠에서는 «스킬이 충분히 안내하는지»를 보라고 권합니다.
작은 모델에서 되면 큰 모델에서도 된다고 봤어요.

claude -p "파일이름 스킬을 써서: 아이 돌잔치에서 찍은 사진 300장을 넣어 둘 폴더 이름. 돌잔치는 9월 6일이었어." --model haiku

-p는 대화창을 열지 않고 답만 받는 옵션입니다.
이 명령을 조건마다 여러 번 돌려 출력을 모았어요.

주의

claude -p를 반복문으로 여러 번 돌리면 실행이 끝날 때마다 맥 알림이 뜰 수 있습니다.
저는 이 실험 중에 알림이 열 번 넘게 쌓였어요.
반복 실행 전에는 횟수를 먼저 정해 두세요.

•••

실험 1 — 원칙에 적은 건 예시 2개로 충분했습니다

파일이름 스킬에 «돌잔치 사진 폴더 이름»을 물었습니다.
예시는 전부 회사 문서였으니 예시와 전혀 다른 입력이에요.

파일이름 스킬 — 예시 2개와 8개 모두 6번 중 6번 2026-09-06으로 시작하고 하이픈을 썼다

실험 1 출력 12개를 그대로 옮겼습니다 — «아이»를 넣었는지만 달랐습니다

	예시 2개	예시 8개
날짜 2026-09-06을 맨 앞에	6/6	6/6
띄어쓰기 대신 하이픈	6/6	6/6
확장자를 안 붙임(폴더라서)	6/6	6/6
가장 많이 나온 이름	2026-09-06-돌잔치-사진 5번	같은 이름 3번 · 아이-돌잔치-사진 3번

파일이름 스킬, 2026-09-16 · 하이쿠 · 조건마다 6번

차이가 없었습니다.
원칙 두 줄(날짜 맨 앞, 하이픈)을 12번 모두 지켰어요.

눈여겨볼 곳은 확장자입니다.
예시에는 전부 .md, .pdf 같은 확장자가 붙어 있었어요.
그런데 폴더 이름을 물으니 한 번도 확장자를 안 붙였습니다. 예시를 베낀 게 아니라 «날짜-내용» 모양을 배워 간 겁니다.

예시 8개가 준 건 이름이 조금 더 길어진 것뿐이었습니다. 아이-를 넣은 이름이 3번 나왔어요.
좋아진 건지는 취향 문제입니다.

실험 2 — 원칙에 없는 취향은 낯선 입력에서 흔들렸습니다

메일제목 스킬에는 두 가지를 물었습니다.

첫째는 납품이 늦어져 사과하는 메일입니다.
업무 메일이라 예시와 가까운 편이에요.

둘째는 가을 신제품 할인을 알리는 홍보 메일입니다.
사내 업무 메일만 있던 예시와 거리가 멀어요.

![메일제목 스킬 — 사과 메일은 예시 2개와 8개 모두 [사과] 말머리를 8/8 붙였고, 홍보 메일은 예시 2개면 3/8, 8개면 6/6](03-mail.webp)

실험 2 — 말머리가 붙은 횟수.
원본 출력은 아래 표에 그대로 옮겼습니다

사과 메일에서는 차이가 없었습니다. 예시에 없던 [사과] 말머리를 두 조건 모두 8번 중 8번 스스로 만들어 붙였어요.
예시 2개로도 «대괄호 말머리를 단다»는 취향이 넘어간 겁니다.

홍보 메일에서 갈렸습니다. 예시 2개 조건의 실제 출력이 이랬어요.

#	예시 2개 — 홍보 메일 제목
1	[안내] 신제품 가을 컬렉션 9/25 할인 시작
2	[신제품] 가을 신상 9/25 할인 시작
3	[공지] 가을 신제품 9/25 할인 시작
4	신상 가을 제품 9/25 할인 시작
5	`가을 신제품 \	9/25 할인 시작`
6	가을 신제품 9/25 할인 시작
7	🍂 가을 신제품 9/25 할인 시작
8	가을 신제품 홍보 9/25(수) 할인 시작

예시 2개 조건 출력 8개 — 말머리는 3번, 나머지는 세로줄·이모지·없음

말머리가 붙은 건 3번뿐입니다.
나머지 5번은 말머리가 없거나 세로줄, 이모지로 바뀌었어요.
붙은 3번도 이름이 [안내]·[신제품]·[공지]로 제각각이었습니다.

예시 8개 조건은 6번 모두 말머리를 붙였습니다. [안내] 3번, [공유] 3번이었어요.

그런데 8개 쪽에도 흠이 있었습니다. [공유]는 예시에서 사내 공지에 쓰던 말머리예요.
그걸 고객에게 보내는 홍보 메일에 3번 붙였습니다.
형식은 지켰지만 예시의 단어를 빌려 온 것입니다.

정보

홍보 메일의 예시 8개 조건은 6번만 돌렸습니다.
7번째 실행 전에 실험을 멈췄어요.
그래서 비율은 «8번 중»이 아니라 «6번 중»으로 적었습니다.

•••

예시에 섞인 틀린 사실도 따라 배웁니다

결과를 정리하다가 제 실수를 하나 발견했습니다.

메일 예시에 요일을 적었는데, 전부 2025년 달력 기준이었어요.
예를 들어 9/19(금)은 2026년에는 토요일입니다.
예시 8개 중 요일을 적은 7개가 모두 그랬습니다.

그 결과가 출력에 그대로 나왔습니다.

출력에 나온 날짜	2026년 실제 요일	예시 2개	예시 8개
사과 메일 9/22	화요일	(월) 5번 · (화) 3번	(월) 4번 · (화) 4번
홍보 메일 9/25	금요일	(수) 1번	(목) 3번 · (수) 1번

요일을 적은 출력만 셌습니다 — 2025년 달력이면 9/22는 월요일, 9/25는 목요일입니다

사과 메일에서는 16번 중 9번이 틀린 요일(월)을 붙였습니다.
2025년 달력으로 9/22는 월요일이에요.
예시의 달력을 따라간 셈입니다.

홍보 메일에서 요일을 붙인 5번은 모두 틀렸습니다. 예시가 8개면 요일을 더 자주 붙였고, 틀린 요일도 더 자주 나왔어요.

예시는 형식만 가르치지 않습니다.
예시 안의 사실도 함께 가르칩니다. 날짜·금액·이름 같은 값은 예시에서 빼거나, 넣었다면 한 번 더 확인하세요.
예시를 늘릴수록 틀린 값이 섞일 자리도 늘어납니다.

공식 문서는 «예시가 스타일을 전한다»고만 적었습니다

앤트로픽의 스킬 작성 가이드에도 예시 이야기가 있습니다.

Claude 공식 문서 Skill authoring best practices의 Examples pattern — 입력·출력 쌍 3개와 «Examples convey the desired style and level of detail» 문장

Claude 공식 문서 「Skill authoring best practices」 중 Examples pattern.
2026-09-17 조회

문서는 출력 품질이 예시에 달린 스킬이라면 입력·출력 쌍을 넣으라고 합니다.
그리고 예시가 원하는 스타일과 자세함의 정도를 설명보다 더 분명하게 전한다고 적었어요.

몇 개를 넣으라는 숫자는 없습니다. 문서 속 예시는 3개였어요.

재밌는 건 그 예시 3개 바로 아래에 스타일을 한 줄로 다시 적어 둔 것입니다. «이 스타일을 따르라: 타입(범위): 짧은 설명».
예시가 보여 준 취향을 원칙 한 줄로 못박은 셈이에요.
제 실험 결과와 같은 방향입니다.

책에서도 비슷한 숫자를 봤습니다.
제가 읽은 하네스 엔지니어링 책의 권장은 이렇습니다.
나쁜 예·좋은 예를 한 세트로, 원칙마다 2~3개, 많아도 5개 이하예요.

예시 칸, 이렇게 채우세요

실험과 문서를 합쳐 순서를 정리했습니다.

예시 칸 쓰기 전 3단계 — 1 취향을 원칙으로 적는다 2 원칙마다 예시 2~3개, 서로 다르게 3 낯선 입력으로 돌려 본다

예시 칸 채우는 순서 — 개수보다 순서가 먼저입니다

Step 1. 예시에만 들어 있는 취향을 찾아 원칙으로 올립니다.

예시를 훑으며 «원칙에는 없는데 예시마다 똑같은 것»을 찾으세요.
말머리, 괄호, 이모지를 안 쓰는 것, 문장 끝 모양 같은 것들이에요.
찾았으면 원칙에 한 줄로 적습니다.

## 원칙
1. 제목 맨 앞에 대괄호 말머리를 붙인다. [요청] [공유] [확인] 중에서 고른다.

말머리 목록까지 적어 두면 [사과]처럼 새로 만들지, 목록 안에서만 고를지도 정할 수 있어요.
이 한 줄을 넣고 다시 돌려 보지는 않았습니다.
그래서 효과는 단정하지 않겠습니다.

Step 2. 원칙마다 예시는 2~3개, 서로 다르게 고릅니다.

비슷한 예시 8개보다 서로 다른 예시 3개가 낫습니다.
실험 2의 예시 2개는 둘 다 [요청] 메일이었어요.
종류가 한 가지뿐이라 홍보 메일에서 흔들린 겁니다.

Step 3. 예시에 없는 입력으로 여러 번 돌려 봅니다.

한 번 돌려서 잘 나오면 안심하기 쉽습니다.
이번 실험의 흔들림은 8번을 돌려야 보였어요.
예시와 먼 입력 하나를 골라 5번 이상 돌려 보세요.

성공

출력이 여러 번 모두 같은 모양으로 나오면 예시 칸은 충분합니다.
이때 예시를 더 넣지 마세요.
파일만 길어지고, 실험 1처럼 달라지는 게 없습니다.

막히면 — 증상별로

① 출력마다 형식이 조금씩 다르다

예시를 늘리기 전에 원칙을 보세요.
흔들리는 부분이 원칙에 적혀 있는지 확인합니다.
안 적혀 있으면 한 줄로 적으세요.
실험 2의 말머리가 딱 이 경우였습니다.

② 예시의 단어를 그대로 가져다 쓴다

실험 2에서 홍보 메일에 사내용 [공유]가 붙은 경우입니다.
예시를 서로 더 다르게 고르거나, «어떤 경우에 어떤 말머리를 쓰는지» 원칙에 적으세요.

③ 날짜나 요일이 이상하게 나온다

예시 안의 날짜부터 확인하세요.
저처럼 작년 달력으로 요일을 적었을 수 있습니다.
예시의 날짜를 오늘 기준으로 고치거나, 요일을 아예 빼세요.

④ 작은 모델에서만 형식이 무너진다

공식 문서는 스킬을 쓸 모델마다 따로 시험해 보라고 권합니다.
작은 모델일수록 안내가 더 필요할 수 있어요.
이때도 순서는 같습니다.
원칙 한 줄이 먼저, 예시 추가가 나중입니다.

자주 묻는 것

Q. 예시를 아예 안 넣으면 안 되나요?

형식이 정해진 일이라면 넣는 게 좋습니다.
공식 문서도 예시가 설명보다 스타일을 더 분명하게 전한다고 적었어요.
이번 실험에서도 사과 메일의 말머리는 예시만 보고 붙였습니다.
예시 0개로는 돌려 보지 않았습니다.

Q. 예시가 많으면 클로드가 느려지나요?

스킬 본문은 그 스킬을 쓸 때 읽힙니다.
평소에는 목록 한 줄만 읽혀요.
다만 한 번 읽힌 본문은 그 대화 동안 남습니다.
예시가 길면 그만큼 대화 공간을 씁니다.
자세한 숫자는 스킬 75개 실측 글에 있어요.

Q. 나쁜 예시도 넣어야 하나요?

책은 나쁜 예·좋은 예를 한 세트로 넣으라고 권합니다.
이번 실험에는 좋은 예시만 넣었어요.
그래서 나쁜 예시의 효과는 직접 확인하지 못했습니다.

Q. 예시는 SKILL.md에 넣나요, 따로 빼나요?

짧으면 SKILL.md 안에 두면 됩니다.
공식 문서는 예시가 많아지면 examples.md 같은 파일로 빼서 필요할 때만 읽게 하라고 안내합니다.
원칙마다 2~3개라면 대부분 본문에 들어갑니다.

다음 단계

• 클로드 스킬은 그냥 마크다운 파일입니다 — 제 맥의 스킬 75개를 열어 봤습니다 — 스킬이 언제 읽히는지
• 클로드에게 «다음엔 잘해줘»라고 쓰지 마세요 — 하네스 엔지니어링 — 규칙을 어디에 적어야 지켜지는지
• 클로드가 지어내는 걸 막는 세 줄, 프롬프트 말고 CLAUDE.md에 박으세요 — 틀린 사실이 섞이는 걸 막는 다른 자리

---

기준일 2026-09-16. 클로드 코드에서 claude -p --model haiku로 돌린 값입니다.
파일이름 스킬은 조건마다 6번, 메일제목 스킬은 조건마다 8번(홍보 메일 8개 조건은 6번) 돌렸습니다.
모델이 바뀌면 결과가 달라질 수 있어요.

출처 — Claude 공식 문서 「Skill authoring best practices」의 Examples pattern입니다.
2026-09-17에 열어 확인했어요.
주소는 platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices 입니다. «원칙마다 2~3개, 5개 이하»는 제가 정리해 둔 하네스 엔지니어링 책 노트에서 옮겼습니다.