클로드 기초 및 활용 30회: 스킬 직접 만들기 — 설명문 한 줄이 성패를 가릅니다

잘 만들었는데 아무도 안 부르는 스킬

29회에서 스킬의 정체를 알아봤습니다. 오늘은 실제로 만듭니다.

그런데 시작 전에 짚어 둘 것이 있습니다. 스킬을 만들 때 가장 많이 실패하는 지점은 절차가 아닙니다. 절차는 잘 적어 놓고, 설명문을 대충 적어서 영영 안 불려오는 스킬이 됩니다.

그래서 오늘은 설명문 쓰는 법에 절반을 씁니다.

오늘의 목표

오늘이 끝나면 할 수 있게 되는 것: 스킬 파일의 구조를 알고, 자동으로 불려오는 설명문을 쓸 수 있고, 첫 스킬을 만들어 실제로 동작시킬 수 있게 됩니다.

스킬 파일의 구조

29회에서 본 뼈대를 다시 봅니다. 순서대로 적으면 됩니다.

• ① 이름 — 짧고 기억나는 것
• ② 설명(언제 쓰는가) — 자동 호출의 근거. 가장 중요
• ③ 절차 — 어떻게 하는가
• ④ 하지 말 것 — 겪었던 실패
• ⑤ 결과 형식 — 어떤 모양으로

①③⑤는 쉽습니다. ②와 ④가 스킬의 품질을 결정합니다.

🔴 설명문 — 오늘의 핵심

클로드는 설명문을 읽고 "지금 이 스킬이 필요한가"를 판단합니다. 그러니 설명문은 클로드가 판단할 수 있는 형태여야 합니다.

나쁜 설명문과 좋은 설명문을 나란히 보겠습니다.

❌ 나쁜 예: "회의록을 정리한다."

✅ 좋은 예: "회의 메모나 녹취를 회의록 형식으로 정리할 때 사용한다. 사용자가 '회의록', '회의 정리', '미팅 노트'라는 말을 쓰거나, 회의 내용으로 보이는 메모를 붙여 넣었을 때 적용한다."

차이가 보이시나요? 좋은 예에는 구체적인 상황과 신호가 들어 있습니다.

설명문 쓰는 세 가지 요령

① 상황을 적으세요. "무엇을 한다"가 아니라 "언제 한다"입니다.

② 사용자가 쓸 법한 말을 넣으세요. "회의록", "미팅 정리", "회의 내용" — 여러 표현을 적어 두면 어느 것으로 말해도 걸립니다.

③ 쓰지 않을 상황도 적으세요. "단순 메모 정리에는 쓰지 않는다"처럼요. 이게 엉뚱한 호출을 막습니다.

"하지 말 것"을 적는 이유

초보자가 가장 자주 빠뜨리는 항목입니다. 그런데 실무에서 가장 값진 부분입니다.

왜냐하면 이건 여러분이 시행착오로 배운 것이기 때문입니다. 12회에서 "주의 줄이 가장 값지다"고 한 것과 같습니다.

예를 들면 이런 것들입니다.

• "원문에 없는 수치를 만들어 내지 않는다"
• "담당자가 불명확하면 '미정'이라고 적고 추측하지 않는다"
• "파일을 수정하지 않는다. 결과만 보고한다"

마지막 항목은 안전과 직결됩니다. 29회 끝에서 말한 대로, 스킬 안에 위험한 지시를 적지 않는 것도 중요하지만 명시적으로 금지해 두면 더 안전합니다.

결과 형식을 정하는 이유

이게 있으면 매번 같은 모양으로 나옵니다. 없으면 그때그때 다릅니다.

구체적으로 적으세요. "보기 좋게"가 아니라 "항목마다 한 줄, 전체 열 줄 이내, 목록 형태"입니다.

13회에서 디자인을 다룰 때 배운 "감상이 아니라 측정 가능한 말로"가 여기서도 그대로 적용됩니다.

만드는 법 — 클로드에게 시키기

24회에서 배운 방식입니다. 다만 오늘은 설명문을 신경 써서 요청합니다.

"스킬을 하나 만들어 줘.
이름: 회의록
언제 쓰나: 회의 메모를 회의록으로 정리할 때. '회의록', '회의 정리', '미팅 노트' 같은 말을 쓰거나 회의 내용으로 보이는 메모를 붙여 넣었을 때.
절차: 결정 사항 / 담당자 / 마감일 세 항목으로 나눠 정리.
하지 말 것: 원문에 없는 내용 추가 금지. 불명확하면 '미정'으로 표시.
결과 형식: 항목마다 한 줄, 전체 열두 줄 이내."

이렇게 다섯 항목을 다 주면 제대로 된 스킬이 만들어집니다.

만들고 나서 반드시 할 일 — 시험

만들었다고 끝이 아닙니다. 두 가지 시험을 하세요.

시험 1 — 불러서 되나: /회의록으로 직접 불러 봅니다.

시험 2 — 안 불러도 되나: 이름을 말하지 않고 "이 메모 회의록으로 정리해 줘"라고만 합니다.

둘 다 되면 설명문이 잘 적힌 것입니다. 시험 2가 안 되면 설명문을 고쳐야 합니다.

따라 하기 ① 후보 고르기

29회에서 찾은 후보 중 하나를 고르세요.

처음이라면 파일을 고치지 않는 작업을 고르시길 권합니다. 정리·요약·검토 같은 것요. 안전하고, 결과를 바로 확인할 수 있습니다.

따라 하기 ② 다섯 항목 적어 보기

파일을 만들기 전에 종이나 메모장에 다섯 항목을 적어 보세요.

이 단계를 건너뛰고 바로 만들면, 대개 설명문이 부실해집니다. 손으로 한 번 적으면 무엇이 빠졌는지 보입니다.

따라 하기 ③ 만들기

적어 둔 다섯 항목을 그대로 클로드에게 주고 만들게 하세요.

만들어진 뒤 어디에 저장됐는지 경로를 확인하세요. 개인용인지 프로젝트용인지도요(24회).

따라 하기 ④ 두 가지 시험

클로드 코드를 재시작한 뒤(/exit → claude), 앞의 두 시험을 하세요.

시험 2가 안 된다면 이렇게 고칩니다.

"'회의록' 스킬의 설명 부분을 고쳐 줘. 사용자가 '회의', '미팅', '논의' 같은 말과 함께 정리를 요청할 때 이 스킬이 쓰이도록 상황을 더 구체적으로 적어 줘."

따라 하기 ⑤ 세 번 써 보고 다듬기

실제 작업에서 세 번 써 보세요. 그때마다 아쉬운 점이 나옵니다.

아쉬운 점은 "하지 말 것"에 추가하세요. 12회에서 배운 다듬기 과정이 여기서도 그대로입니다.

세 번 다듬고 나면 여러분의 업무에 맞는 스킬이 됩니다.

자주 겪는 오류 ① "자동으로 안 불려와요"

거의 항상 설명문 문제입니다. 세 가지를 확인하세요.

① 상황이 적혀 있나 — "무엇을 한다"만 있고 "언제"가 없으면 판단할 수 없습니다.
② 표현이 다양한가 — 내가 실제로 쓰는 말이 들어 있나요.
③ 너무 좁게 적었나 — "월간 회의록에만"이라고 적으면 주간 회의에는 안 걸립니다.

클로드에게 진단시킬 수도 있습니다. "이 스킬의 설명문을 읽고, 어떤 상황에서 불려올 것 같은지 알려 줘."

오류 ② "엉뚱할 때 불려와요"

반대 문제입니다. 설명문이 너무 넓게 적혀 있습니다.

해결책은 "쓰지 않을 상황"을 추가하는 것입니다.

"단순 메모 정리나 일반 문서 요약에는 이 스킬을 쓰지 않는다. 회의 내용일 때만 쓴다."

오류 ③ "결과가 매번 달라요"

결과 형식이 모호한 경우입니다. 숫자로 못 박으세요.

"짧게" → "열 줄 이내"
"항목별로" → "항목마다 한 줄씩, 번호 매김"
"정리해서" → "결정 / 담당 / 마감 세 덩어리로"

오류 ④ "스킬이 규칙을 어겨요"

스킬의 지시와 지침 파일(CLAUDE.md)의 규칙이 충돌하는 경우입니다.

예를 들어 지침에는 "답은 다섯 줄 이내"인데 스킬에는 "열두 줄 이내"라고 되어 있으면, 어느 쪽을 따를지 애매해집니다.

정리 원칙: 스킬에는 그 작업에만 해당하는 것만 적고, 공통 규칙은 지침 파일에 맡기세요. 29회에서 배운 구분이 그대로 적용됩니다.

실전 사례 ① 검토 스킬

가장 만들 가치가 큰 종류입니다. 검토는 매번 같은 항목을 봐야 하기 때문입니다.

이름: /검토
언제: 문서·글·계획을 봐 달라거나 검토해 달라고 할 때
절차: ① 빠진 항목이 있는지 ② 앞뒤가 맞지 않는 부분이 있는지 ③ 숫자·날짜가 일관된지 ④ 읽는 사람이 오해할 만한 표현이 있는지
하지 말 것: 문체나 취향에 대한 지적은 하지 않는다. 사실 관계와 논리만 본다. 확실하지 않은 지적에는 '확인 필요'라고 표시한다.
결과 형식: 지적마다 한 줄, 심각한 것부터, 최대 일곱 개

"하지 말 것"이 특히 중요한 예입니다. 이게 없으면 문체 지적까지 잔뜩 나와서 정작 중요한 게 묻힙니다.

실전 사례 ② 정리 스킬 (파일 다루기)

클로드 코드에서 쓰는 스킬입니다. 안전 조항이 들어가야 합니다.

이름: /파일점검
언제: 폴더의 파일 상태나 이름 규칙을 점검해 달라고 할 때
절차: ① 파일 목록과 개수 ② 이름 규칙에서 벗어난 것 ③ 중복으로 보이는 것 ④ 오래되어 정리 후보인 것
하지 말 것: 파일을 절대 수정·이동·삭제하지 않는다. 보고만 한다. 정리는 사용자가 확인한 뒤 별도로 요청한다.
결과 형식: 항목마다 파일 이름과 이유를 한 줄로

굵게 표시한 부분이 안전장치입니다. 20회의 원칙을 스킬 안에 넣은 것입니다.

실전 사례 ③ 저시력 사용자를 위한 스킬 설계

29회 끝에서 예고한 /읽기좋게 스킬을 완성해 보겠습니다. 다섯 항목을 다 채우면 이렇게 됩니다.

이름: /읽기좋게

언제: 긴 문서, 많은 파일, 복잡한 표를 다뤄 달라고 할 때. 사용자가 '요약', '정리', '알려 줘'라고 하면서 분량이 큰 대상을 지정했을 때. 결과가 열 줄을 넘길 것으로 예상될 때도 이 절차를 적용한다.

절차: ① 전체를 훑고 구조부터 세 줄로 알려 준다 ② 어느 부분을 볼지 사용자가 고르게 한다 ③ 고른 부분만 다섯 줄 이내로 정리한다 ④ 더 필요하면 사용자가 요청하게 한다

하지 말 것: 전체 내용을 한 번에 출력하지 않는다. 표를 단독으로 쓰지 않는다 — 쓸 경우 같은 내용을 문장으로 반드시 병기한다. 목록은 다섯 항목을 넘기지 않는다.

결과 형식: 구조 요약은 세 줄, 부분 정리는 다섯 줄 이내, 문장 위주(목록 최소화)

이 스킬의 진짜 가치는 절차 ①②에 있습니다. 긴 내용을 한꺼번에 받지 않고 골라서 받는 구조요. 확대 환경에서는 이 한 가지가 사용 경험을 크게 바꿉니다.

그리고 자동 호출이 되면 — 긴 문서를 만날 때마다 여러분이 요청하지 않아도 이 절차가 적용됩니다. 매번 "짧게 해 주세요"라고 말할 필요가 없어지는 것이 이 스킬의 목적입니다.

핵심 정리 3줄

• 설명문이 성패를 가릅니다. "무엇을"이 아니라 "언제"를, 사용자가 쓸 법한 표현과 함께.
• "하지 말 것"을 반드시 적으세요. 시행착오로 배운 것이 여기 들어갑니다.
• 만들고 두 가지 시험을 하세요. 불러서 되나, 안 불러도 되나.

용어 정리

• 설명문 — 스킬을 언제 쓰는지 적은 부분. 자동 호출의 판단 근거입니다.
• 쓰지 않을 상황 — 엉뚱한 호출을 막기 위해 명시하는 제외 조건.
• 하지 말 것 — 겪었던 실패를 규칙으로 굳힌 부분.
• 결과 형식 — 출력의 모양을 숫자로 못 박은 부분. 매번 같은 품질을 만듭니다.

다음 회차 예고와 실습 과제

31회 「스킬 관리와 문제 해결」에서는 만든 뒤의 이야기를 다룹니다. 수정·삭제·정리, 스킬이 안 불릴 때의 점검 순서, 너무 자주 불릴 때의 대처, 그리고 팀과 공유하는 법입니다. 제6부의 마지막 회차입니다.

실습 과제 두 가지

• ① 다섯 항목을 먼저 손으로 적은 뒤 스킬을 하나 만들고, 두 가지 시험을 해 보세요.
• ② 시험 2(자동 호출)가 안 됐다면 설명문을 고쳐 다시 시험해 보세요. 몇 번 만에 되는지가 설명문 감각을 길러 줍니다.

만드신 스킬의 설명문을 댓글로 공유해 주시면, 어떻게 고치면 좋을지 함께 볼 수 있습니다.

본 회차는 2026년 8월 2일 기준입니다. 스킬의 파일 형식과 자동 호출 사양은 버전에 따라 바뀔 수 있습니다. 화면과 이 글이 다르면 화면이 맞습니다.

협업문의 : kuroicode@gmail.com
블로그 : https://ghost-production-0ec2.up.railway.app/
홈페이지 : https://kuroicode-beep.github.io/svil-homepage/