45단계설명 한 문장이 스킬을 불러낸다

걸리는 시간 · 읽기 약 5분 · 따라 하기 약 20분 · 난이도 ★★☆ 실무 · 화면 확인 2026.09.27

이 단계를 마치면

• 설명(description)이 왜 스킬의 스위치 구실을 하는지 설명할 수 있다.
• "무엇을 한다"와 "언제 쓴다"가 모두 담긴 설명을 쓴다.
• 비슷한 스킬끼리 부딪히지 않도록 경계를 긋는다.

공들여 만든 스킬이 한 달 내내 한 번도 불리지 않았다면, 문제는 어디에 있을까? 대부분은 본문에서 원인을 찾는다. 그런데 범인은 맨 위에 적힌 짧은 설명인 경우가 훨씬 많다.

Claude는 평소 모든 스킬의 본문을 읽고 있지 않다. 이름과 설명만 알고 있다가, 지금 하는 일이 설명과 맞을 때 비로소 본문을 연다. 그러니 본문을 아무리 잘 써도 설명이 어긋나면 소용이 없다. 스킬을 만드는 사람이 가장 많이 막히는 곳이 바로 여기다. 본문은 공들여 쓰고 설명은 마지막에 대충 붙이는 일이 흔하기 때문이다.

스킬이 여러 개가 되면 설명은 더 중요해진다. 주간 보고 스킬, 회의록 스킬, 요약 스킬이 함께 있으면 Claude는 설명만 보고 이 가운데 무엇을 꺼낼지 고른다. 설명이 흐릿하면 엉뚱한 스킬이 불리거나, 아무것도 불리지 않는다.

좋은 설명의 세 부분

좋은 설명은 먼저 두 가지를 담는다. 무엇을 하는지, 그리고 언제 쓰는지. "주간 보고 스킬"이라고만 적으면 Claude는 언제 꺼내야 할지 모른다. "고객 미팅 메모를 영업 본부 주간 보고 양식으로 정리한다. 사용자가 미팅 메모, 통화 기록을 올리고 보고서나 정리를 요청할 때 쓴다"라고 적어야 꺼낼 때가 분명해진다.

"언제 쓰는지"에는 두 가지 단서를 넣는다. 사용자가 실제로 쓸 말과, 사용자가 올릴 입력물이다. 사람들은 "주간 보고"라고 말하는 대신 "이번 주 거 정리해 줘"라고 말하기도 한다. 영업팀이 "콜 리포트"라고 부른다면 그 말도 넣는다. 말이 달라도 입력물이 미팅 메모라면 알아볼 수 있도록 "미팅 메모, 통화 기록, 방문 메모를 올리고"처럼 적어 둔다.

필요하면 셋째 부분인 "쓰지 않을 때"를 붙인다. 설명을 너무 넓게 쓰면 엉뚱한 때 불린다. "문서를 정리할 때 쓴다"라고 적으면 계약서 요약을 부탁해도 주간 보고 양식이 튀어나온다. 여기에 "계약서나 내부 회의록에는 쓰지 않는다"를 한 문장 더하면 경계가 선다.

고치기 전과 후

설명은 길다고 좋은 것도 아니다. 본문의 내용을 설명에 옮겨 적지 말자. 설명은 꺼낼지 말지를 정하는 한두 문장이면 되고, 어떻게 할지는 본문이 맡는다.

여러 스킬 사이의 경계

스킬이 둘 이상이면 설명끼리 겹치지 않게 한다. 요약 스킬과 주간 보고 스킬에 모두 "정리할 때 쓴다"고 적혀 있으면 Claude는 둘 중 하나를 고르다 갈팡질팡한다. 입력물로 나누면 쉽다. 주간 보고는 고객 미팅 메모를, 요약은 그 밖의 긴 글을 맡는다. 그리고 각 설명의 "쓰지 않을 때"에 상대 스킬의 일을 적어 둔다.

설명을 쓰는 순서

설명은 본문보다 먼저 쓴다. 순서는 이렇다. 우선 입력물과 결과물을 넣어 "무엇을 한다"를 한 문장으로 쓴다. 다음으로 동료 두세 사람에게 "이 일을 Claude에 부탁한다면 뭐라고 말하겠느냐"고 물어, 그 말을 모아 "언제 쓴다"를 쓴다. 마지막으로 가장 헷갈릴 만한 이웃 일을 하나 떠올려 "쓰지 않을 때"를 쓴다. 이렇게 먼저 쓴 설명을 기준으로 본문을 채우면, 본문이 설명보다 넓어지거나 좁아지는 일도 막을 수 있다.

설명에 넣을 말은 부서마다 다르다. 영업에는 "콜 리포트", "상담 일지" 같은 사내 말이 많고, 재무에는 "법카", "증빙" 같은 줄임말이 많다. 고객지원에서는 "CS 답변", "문의 회신"처럼 영어와 한국어가 섞인다. 요령은 간단하다. 내 부서가 실제로 쓰는 말을 그대로 옮겨 적으면 된다.

이 요령을 몰라 한 달을 허비한 사람이 있다.

현장 장면

재무팀 정 차장은 "비용 보고서 검토"라는 설명을 달아 스킬을 만들었다. 본문에는 공을 많이 들였다. 증빙이 없는 항목, 한도를 넘는 항목, 같은 날 같은 가맹점에서 두 번 결제된 항목을 가려내는 순서가 꼼꼼하게 적혀 있었다.

그런데 팀원들은 "경비 정산 봐 줘", "영수증 확인해 줘", "이번 달 법카 내역 체크해 줘"라고 말했다. 스킬은 한 번도 불리지 않았고, 팀원들은 스킬 없는 평범한 검토 결과를 받았다. 정 차장은 한 달이 지나도록 스킬이 왜 효과가 없는지 알지 못했다.

실마리는 우연히 풀렸다. 팀원 한 사람이 Claude와 대화하는 모습을 옆에서 지켜보다가, 정 차장은 문득 깨달았다. 자기가 적은 "비용 보고서"라는 말을 팀에서 쓰는 사람이 아무도 없었다.

그는 설명을 이렇게 고쳤다. "법인카드 사용 내역과 경비 정산 자료를 사내 기준으로 1차 검토한다. 경비 정산, 영수증 확인, 법카 내역 체크를 요청하거나 카드 사용 내역 파일을 올릴 때 쓴다. 세금 신고 판단에는 쓰지 않는다." 그 뒤로 같은 말에 스킬이 꼬박꼬박 불려 나왔다. 본문은 한 글자도 고치지 않았다.

따라 하기

1. 44단계에서 고른 일의 설명을 "무엇을 한다" 한 문장으로 써 본다. 성공 기준: 입력물과 결과물이 모두 들어 있다.
2. 그 일을 부탁할 때 나와 동료가 실제로 쓰는 말을 다섯 가지 적는다. 줄임말과 사내 용어도 포함한다. 가능하면 동료 한 명에게 직접 물어본다. 성공 기준: 내가 쓰지 않는 말이 하나 이상 들어 있다.
3. 적은 말과 입력물 종류를 "언제 쓴다" 문장에 넣는다. 성공 기준: 설명이 두 문장이고, 둘째 문장에 실제 말이 셋 이상 있다.
4. 이 스킬이 불리면 안 되는 비슷한 부탁을 하나 적고, "이럴 때는 쓰지 않는다"를 붙인다. 성공 기준: 쓰지 않을 때가 입력물이나 목적으로 분명히 구분된다.
5. 아래 프롬프트로 설명을 점검받는다. 성공 기준: 안 불릴 부탁과 잘못 불릴 부탁이 각각 셋씩 나오고, 그에 맞춰 설명을 한 번 고친다.

복사해 쓰는 프롬프트

아래는 내가 만들 스킬의 설명 초안이다. Claude가 이 설명만 보고 스킬을 꺼낼지 정한다는 점을 생각해서 검토해 줘.
- 이 설명으로 불려야 하는데 안 불릴 것 같은 부탁 세 가지
- 불리면 안 되는데 불릴 것 같은 부탁 세 가지
- 위 두 가지를 고친 설명 (무엇을 하는지 + 언제 쓰는지 + 필요하면 쓰지 않을 때)
설명에 본문 내용을 옮겨 적지는 마.

스킬이 하는 일: [한 문장]
우리 팀이 이 일을 부탁할 때 쓰는 말: [말 목록]
함께 있는 다른 스킬의 설명: [있으면 붙여 넣기]
설명 초안: [초안]

막히면 이렇게

실습 파일

공개 저장소에 올려 둔 가공 자료와 양식이다. 회사 자료 대신 먼저 이것으로 해 본다.

• 채워 쓰는 양식 SKILL.md · 스킬 파일

스스로 점검

• ☐ 내 설명에 "무엇을 한다"와 "언제 쓴다"가 모두 있는가
• ☐ 동료가 실제로 쓰는 말이 설명에 셋 이상 들어 있는가
• ☐ 설명에 본문 내용을 옮겨 적지 않았는가

기억할 것

• 설명에는 무엇을 하는지와 언제 쓰는지를 함께 적는다.
• 언제 쓰는지에는 동료들이 실제로 쓰는 말과 올릴 입력물을 넣는다.
• 스킬이 둘 이상이면 설명끼리 경계를 긋는다.