안녕하세요, 멘토 김부장입니다. 앞서 스킬(Skills)이 뭐길래 편에서 "스킬은 AI에게 붙이는 업무 매뉴얼"이라는 큰 그림을 잡았지요. 오늘은 거기서 한 걸음 더 들어가 보겠습니다. 매뉴얼이라는 건 알겠는데, 그럼 어떻게 써야 AI가 실제로 잘 따라 하는 매뉴얼이 될까요? 신입사원에게 인수인계 문서를 써 준 경험이 있으시다면 감이 오실 겁니다. 똑같은 일이라도 어떻게 적어 주느냐에 따라 결과가 하늘과 땅 차이니까요.
스킬은 보통 SKILL.md라는 이름의 문서 파일 하나로 시작합니다. AI가 필요할 때 이 문서를 펼쳐 읽고, 적힌 대로 일을 처리하지요. 그러니 이 문서를 잘 쓰는 것이 곧 스킬 설계의 전부라 해도 과언이 아닙니다.
좋은 스킬은 '무엇을 하라'만 적지 않습니다. '언제 이 문서를 펼쳐야 하는지'부터 '어떤 순서로, 어떤 모습으로 끝내야 하는지'까지 알려줍니다.
좋은 스킬이 갖춰야 할 네 가지
수많은 스킬을 만들고 고쳐 보며 제가 정리한 조건은 네 가지입니다. 하나씩 뜯어보겠습니다.
| 조건 | 하는 일 | 없으면 생기는 문제 |
|---|---|---|
| 명확한 이름·설명 | '언제 이 스킬을 쓸지' 알려주는 방아쇠 | 필요할 때 스킬이 안 불려 나옴 |
| 단계적 지침 | 일을 순서대로 쪼개 안내 | 중간을 건너뛰거나 제멋대로 함 |
| 구체적 예시 | '이런 모습이 정답'을 보여줌 | 형식이 매번 들쭉날쭉 |
| 점진적 공개 | 필요한 만큼만 펼쳐 읽게 함 | 문서가 비대해져 헷갈림 |
첫째, 이름과 설명이 '방아쇠'다
초보자가 가장 많이 놓치는 부분이 바로 이것입니다. 아무리 훌륭한 매뉴얼을 써 놔도, AI가 "지금이 이 매뉴얼을 펼칠 때"라는 걸 모르면 무용지물이거든요. 그래서 스킬의 이름과 설명은 내용 요약이 아니라 '언제 나를 불러라'는 신호여야 합니다. 이걸 흔히 방아쇠(트리거)라고 부릅니다.
나쁜 설명: "송장 처리 도구." — 너무 짧아 언제 쓰는지 알 수 없습니다.
좋은 설명: "PDF 송장에서 금액·날짜·거래처를 뽑아 정산표로 정리할 때 사용. 사용자가 '송장', '인보이스', '정산'을 언급하면 발동." — 상황과 신호 단어가 또렷하지요.
보시다시피 좋은 설명에는 '어떤 상황에서', '어떤 말이 나오면' 쓰는지가 구체적으로 적혀 있습니다. 마치 도서관 책등에 붙은 라벨처럼, AI가 수십 개의 스킬 중에서 지금 필요한 하나를 정확히 집어 들도록 돕는 것이지요.
둘째, 지침은 '단계'로 쪼갠다
매뉴얼 본문은 줄글로 주욱 늘어놓기보다, 순서가 있는 단계로 나누는 편이 훨씬 잘 작동합니다. 사람도 "알아서 잘 처리해 주세요"보다 "1번 먼저, 그다음 2번" 하고 짚어 주면 실수가 줄지요. AI도 똑같습니다.
입력 확인
필요한 재료(파일·값)가 다 있는지 먼저 점검하도록 적습니다. 없으면 물어보게 합니다.
핵심 작업
실제 처리 규칙을 순서대로 적습니다. 판단이 갈리는 지점엔 '이럴 땐 이렇게'를 명시합니다.
결과 형식
끝난 결과가 어떤 모습이어야 하는지 못 박습니다. 표인지, 요약인지, 파일인지.
이렇게 단계로 쪼개 두면 AI가 중간을 건너뛰거나 순서를 뒤집는 일이 크게 줄어듭니다. 특히 판단이 필요한 갈림길마다 "이런 경우엔 이렇게 하라"를 미리 적어 두는 것이 핵심입니다. 그 갈림길을 비워 두면 AI가 그때그때 다르게 처리해, 결과가 오락가락하게 되거든요.
셋째, 예시 하나가 백 마디 설명을 이긴다
말로 아무리 "정중하게 요약하라"고 해도 사람마다 정중함의 기준이 다릅니다. AI도 마찬가지예요. 그래서 완성된 결과물의 예시를 한두 개 넣어 주면, 설명 열 줄보다 강력하게 작동합니다. "아, 이런 모양으로 끝내면 되는구나" 하고 곧장 감을 잡거든요.
예시는 형식뿐 아니라 톤과 분량까지 전해 줍니다. 짧고 담백한 예시를 넣으면 짧게, 표가 들어간 예시를 넣으면 표로 정리합니다. 그러니 원하는 결과물이 있다면 그 모범 답안을 스킬 안에 박아 두세요. 이것이 결과의 일관성을 지키는 가장 확실한 방법입니다.
넷째, 점진적 공개 — 다 펼치지 마라
마지막 조건이 조금 낯설 텐데, 알고 보면 아주 상식적입니다. 두꺼운 매뉴얼을 처음부터 끝까지 다 읽고 일하는 사람은 없지요. 목차를 보고 필요한 장만 펼쳐 봅니다. 스킬도 이렇게 설계하는 것이 점진적 공개(progressive disclosure)입니다.
먼저 읽기
세부 문서 펼침
깊게 읽기
핵심 안내는 짧게 두고, 세세한 규칙이나 참고 자료는 별도 파일로 빼 둔 뒤 "필요할 때 이 파일을 열어 보라"고 안내하는 방식입니다. 이렇게 하면 AI가 매번 방대한 문서를 다 읽느라 헷갈리지 않고, 지금 필요한 만큼만 집중해서 봅니다. 문서가 가벼워지니 오히려 정확해지지요.
스킬 설계의 목표는 '많이 적기'가 아니라 '필요한 것만, 필요한 순간에 보이게 하기'입니다.
정리하며 — 다음 편 예고
오늘 이야기를 한 문장으로 압축하면 이렇습니다. 좋은 SKILL.md는 언제 쓸지(이름·설명), 어떻게 할지(단계), 어떤 모습으로 끝낼지(예시)를 또렷이 담고, 필요한 만큼만 펼쳐 보이게(점진적 공개) 설계된 문서입니다. 신입에게 잘 쓴 인수인계서를 건네는 마음, 딱 그것이면 됩니다.
그런데 아무리 좋은 스킬을 붙여도, 그 스킬을 '언제, 몇 번, 어떤 순서로' 돌릴지 관리하는 바깥 구조가 없으면 반쪽입니다. 다음 6편(하네스 설계)에서는 바로 그 '작업대'를 다룹니다. 스킬이라는 도구를 손에 쥔 AI가, 그 도구를 안전하게 반복해 쓰도록 감싸 주는 틀 이야기로 이어가겠습니다.
← 기술 블로그 목록으로