Skill Maker로 가족 캘린더 스킬 업그레이드 — 잘 돌아가는 스킬을 믿을 수 있는 스킬로

SKILL MAKER 레벨업 — 작은 매뉴얼이 큰 매뉴얼로 업그레이드되는 픽셀 일러스트

📝 한줄 요약

지난 글에서 만든 가족 캘린더 조회 스킬, 잘 돌아가고 있었어요. 그런데 "잘 돌아간다"와 "믿을 수 있다"는 다르더라고요. Skill Maker 방식으로 이 스킬을 뜯어고쳐서 — 기능은 하나도 안 늘리고 — 호출 조건, 입출력 약속, 오류 대응을 계약서처럼 명시하고 테스트를 3개에서 6개로 늘렸어요. 그 과정에서 실제 오류까지 하나 찾아서 스킬에 반영했고요.

바쁘시면 이것만 읽어도 돼요:

좋은 스킬은 기능 소개문이 아니라 AI의 행동을 예측 가능하게 만드는 운영 절차예요
"언제 써라"만큼 중요한 게 "언제 쓰지 마라" — 읽기 전용 스킬에는 수정 요청을 거절하는 조항이 필요해요
결과는 세 가지로 구분해요: 일정 있음 / 일정 없음 / 조회 실패. 실패를 "일정 없음"으로 바꾸는 순간 사고가 나요
단계마다 완료 조건을 붙이면 AI가 검증을 건너뛰고 다음 단계로 못 넘어가요
문서만 고치고 끝내지 마세요 — 실제로 한 번 돌려보니 문서에 없던 진짜 오류(-600)가 나왔고, 그 대응이 스킬의 일부가 됐어요

🎯 이런 분들께 도움돼요

스킬(또는 자주 쓰는 프롬프트)을 만들어봤는데, 어딘가 불안하게 돌아가는 것 같은 분
"스킬 구조를 잘 짜라"는 말은 들었는데 뭘 어떻게 고쳐야 할지 막막한 분
AI가 가끔 확인 없이 "됐어요!"라고 하는 게 찝찝했던 분
지난 글(가족 공용 AI 비서 만들기)을 읽고 다음 단계가 궁금한 분

😫 계기: 잘 돌아가는데 왜 고쳐? (Before)

지난 글에서 가족용 AI 비서 "토리"에 macOS 캘린더를 읽기 전용으로 조회하는 스킬을 만들었어요. 테스트 3개도 통과했고, 실제로 매일 잘 쓰고 있었어요.

그러던 중 "좋은 스킬의 구조를 분석하고, Skill Maker 방식으로 기존 스킬 하나를 개선하라"는 과제를 받았어요. 처음엔 이런 생각이 들었죠. 잘 돌아가는데 굳이?

그런데 기존 스킬 문서를 다시 읽어보니 구멍이 보이기 시작했어요. "이 스킬을 쓰면 안 되는 경우"가 안 적혀 있고, 결과 형식이 어렴풋이만 설명돼 있고, 캘린더 앱이 꺼져 있으면 어떻게 되는지는 아예 없고. 사람이 보면 "알아서 하겠지" 싶은 부분들인데, AI는 바로 그 "알아서" 구간에서 사고를 쳐요.

🛠️ 사용한 도구

도구명**: Hermes Agent (가족 프로필의 스킬), Skill Maker 방식(스킬 구조화 방법론)
특이사항**: 새 기능 추가 0개. 고친 건 전부 "약속을 글로 명시하는 일"이었어요

---

🔧 1. Skill Maker 방식이 뭐냐면요

거창한 도구가 아니에요. 스킬을 이렇게 구조화하는 방법이에요.

언제 부르는지(호출 조건), 언제 부르면 안 되는지(비적용 범위), 뭘 받고 뭘 돌려주는지(입출력 계약), 각 단계가 끝났다는 걸 어떻게 아는지(완료 조건), 뭘 하면 안 되는지(안전 경계), 잘못됐을 때 어떻게 하는지(오류 처리), 성공을 주장하기 전에 뭘 확인하는지(검증)

비유하면, 기존 스킬이 "일 잘하는 직원의 머릿속 노하우"였다면, Skill Maker를 거친 스킬은 누가 와도 같은 품질이 나오는 매장 운영 매뉴얼이에요. 프랜차이즈 매뉴얼에 "손님이 이렇게 물으면 이렇게 답한다, 이 경우엔 본사에 연락한다"까지 적혀 있는 것처럼요.

🔧 2. "언제 쓰지 마라"부터 썼어요

기존 스킬엔 "언제 쓰는지"만 있었어요. 개선판에서 제일 먼저 추가한 건 반대쪽 — When Not to Use 독립 섹션이에요.

일정을 만들거나·고치거나·지우는 요청 → 이 스킬 쓰지 마라 (읽기 전용이니까)
허용 목록에 없는 캘린더 요청 → 쓰지 마라
메모·참석자·위치가 필요한 요청 → 쓰지 마라 (일부러 안 가져오니까)
캘린더 앱 자체를 못 쓰는 상황 → 기억으로 때우지 말고 "전제조건이 안 됐다"고 보고해라

특히 마지막 줄이 중요해요. AI는 조회가 안 되면 예전에 본 일정으로 슬쩍 대답하고 싶어 하거든요. "그럴 땐 이 스킬을 쓰지 말고 실패를 보고하라"고 문서에 박아두는 거예요.

💡 스킬의 안전은 "할 수 있는 일 목록"이 아니라 "하면 안 되는 일 목록"이 지켜줘요.

🔧 3. 결과를 세 가지 상태로 갈랐어요

지난 글에서 "조회 실패를 '일정 없음'으로 보여주면 위험한 비서"라고 했었죠. 이번엔 그 교훈을 계약서 조항으로 만들었어요. 스킬의 모든 결과는 셋 중 하나예요.

성공 + 일정 있음** → 일정을 보여준다
성공 + 일정 없음** → "등록된 일정이 없어요" (이건 오류가 아니에요!)
조회 실패** → "지금 캘린더를 확인할 수 없어요" (절대 '일정 없음'으로 바꾸지 않는다)

그리고 각 작업 단계마다 완료 조건을 붙였어요. 예를 들어 "조회 결과 검증" 단계는 정상 종료·형식 일치·시간대 확인 등 8가지가 전부 통과해야 끝난 거고, 하나라도 실패하면 다음 단계(사용자에게 보여주기)로 못 넘어가요. 완료 조건이 없으면 AI가 검증을 건너뛰고 "됐어요!"부터 말할 수 있거든요.

테스트도 3개에서 6개로 늘렸어요. 새로 추가한 3개가 재밌는데:

제목이 같아도 시간이 다르면 다른 일정으로 남기는가 — "회의"가 오전·오후 두 번 있으면 둘 다 보여야죠
빈 결과가 "정상"으로 처리되는가 — 일정 없는 날이 오류로 뜨면 안 되니까
끝나는 날짜가 시작 날짜보다 빠르면 거부하는가 — 이상한 입력은 문 앞에서 막기

🔧 4. 매뉴얼 본문과 부록을 분리했어요

고치다 보니 문서가 88줄에서 225줄로 늘었어요. 어, 너무 길어진 거 아닌가? 여기서 쓴 기법이 Progressive Disclosure(점진적 공개)예요. 말은 어렵지만 익숙한 개념이에요 — 본문과 부록의 분리요.

평소에 늘 필요한 절차 → SKILL.md 본문에
데이터 형식의 시시콜콜한 규격 → references/ 부록 문서로 분리, 필요할 때만 열어보기

AI가 매번 읽는 양(컨텍스트)이 곧 비용이라서, 늘 읽는 본문은 가볍게 유지하고 진단할 때만 부록을 여는 구조가 돼요. 참고로 허용 캘린더 목록의 "원본"은 문서가 아니라 실행 스크립트 한 곳에만 두었어요 — 같은 정보가 두 군데 있으면 언젠가 서로 달라지거든요.

🔧 5. 실제로 돌렸더니, 문서에 없던 오류가 나왔다

ERROR -600 오류 블록을 만난 로봇, 재시도 후 OK — 픽셀 일러스트

여기가 이번 작업에서 제일 중요한 순간이에요. 문서를 다 고치고 테스트 6개도 통과한 다음, 마지막으로 실제 조회를 한 번 돌려봤어요(이걸 smoke test라고 해요 — 연기 나는지만 확인하는 시동 테스트요). 그랬더니:

Calendar app is not running: AppleScript -600

캘린더 앱이 꺼져 있으면 조회가 실패하는 거예요. 테스트 6개는 전부 통과했는데도요 — 자동 테스트는 캘린더 앱 없이 돌아가게 만들어져 있어서, 이 오류는 실제로 돌려야만 만날 수 있었던 거죠.

대응을 정하고(캘린더를 백그라운드로 켜고, 같은 읽기 전용 조회를 딱 한 번 재시도) 스킬의 오류 처리표에 추가했어요. 재시도 후 결과는 정상:

exit: 0
ok: true
timezone: Asia/Seoul

💡 문서를 고쳤으면 실제로 한 번 돌려보세요. 진짜 오류는 문서 밖에서 나와요. 그리고 그 오류의 대응이 스킬의 일부가 돼요.

---

✅ 결과 (After)

Before vs After

스킬 문서**: 88줄, 8개 섹션 → 225줄, 13개 섹션 (부록 분리)
쓰지 말아야 할 때**: 본문에 섞여 있음 → 독립 섹션으로 명시
결과 해석**: 어렴풋이 → 일정 있음/없음/실패 3상태 계약
완료 조건**: 전체에 하나 → 5단계 각각에 정의
오류 대응**: 주의사항 위주 → 오류 9종별 인식·대응표
테스트**: 3개 통과 → 6개 통과 + 실제 조회 성공
실전 오류 환류**: 없음 → 캘린더 미실행(-600) 대응 추가

기능은 그대로인데, 이제 이 스킬이 어디까지 하고 어디서 멈추는지를 문서만 읽고 예측할 수 있어요. 아침 브리핑 스킬처럼 이 스킬의 결과를 가져다 쓰는 쪽도 "어떤 형식이 온다"를 믿고 만들 수 있고요.

💬 이 과정에서 배운 팁

효과적이었던 것

기능 추가보다 약속 명시가 먼저 — 이번에 늘린 기능은 0개예요. 그런데 스킬의 신뢰도는 확실히 올라갔어요.
"언제 쓰지 마라"를 독립 섹션으로 — AI의 사고는 대부분 스킬을 잘못 쓸 때가 아니라, 쓰면 안 될 때 쓰는 데서 나요.
단계마다 완료 조건 붙이기 — "다 됐어요"를 말하려면 뭘 통과해야 하는지 스킬에 적어두세요.
고쳤으면 실제로 한 번 돌리기 — 자동 테스트가 다 통과해도, 진짜 환경의 오류는 따로 있어요.

이렇게 하면 안 돼요

문서 길어진다고 다 본문에 넣기 — 늘 읽는 본문과 필요할 때 여는 부록을 나누세요. AI가 매번 읽는 양이 곧 비용이에요.
같은 정보를 두 문서에 복사하기 — 원본은 한 곳에만. 두 군데 적으면 언젠가 서로 달라져요.
실패를 "없음"으로 포장하기 — "조회 못 했어요"가 "일정 없어요"보다 백 배 안전한 답이에요.

🌍 다른 데 적용한다면?

캘린더 스킬이라서가 아니라, 반복 작업을 AI에게 맡기는 모든 곳에 같은 구조가 통해요. 보고서 자동 생성이든, 메일 초안이든, 데이터 정리든 — "언제 쓰지 마라 / 결과는 몇 가지 상태인가 / 각 단계의 완료 조건은 / 실패하면 뭐라고 말하나" 네 가지만 적어도 스킬의 격이 달라져요.

🚀 앞으로의 계획

이 스킬의 결과를 받아 쓰는 아침 브리핑 스킬에도 같은 방식을 적용할 거예요. 특히 "캘린더 조회가 실패하면 브리핑은 어떻게 말해야 하는가"를 두 스킬 사이의 계약으로 명시하는 게 다음 과제예요.

📋 재사용 가능한 스킬 구조 템플릿

스킬(또는 자주 쓰는 프롬프트)을 운영 매뉴얼로 업그레이드할 때 이 순서로 섹션을 채워보세요.

1. Overview — 이 스킬이 뭘 하는지 한 문단
2. When to Use — 어떤 요청에서 부르는지
3. When Not to Use — 어떤 요청은 거절하거나 다른 길로 보내는지
4. Preconditions — 시작 전에 확인할 전제조건
5. Input Contract — 받는 입력의 형식과 잘못된 입력의 처리
6. Output Contract — 결과의 상태 구분 (성공/빈 결과/실패)
7. Workflow — 단계별 절차, 각 단계에 완료 조건
8. Safety Boundaries — 절대 하면 안 되는 것
9. Error Handling — 오류별 인식 방법과 대응
10. Verification Checklist — 성공을 주장하기 전 확인 목록
11. Regression Test — 고칠 때마다 돌리는 자동 테스트
그리고 마지막으로: 실제로 한 번 돌려서, 거기서 나온 오류를 다시 이 문서에 반영하세요.

🔥<24기 AI 스터디> 얼리버드 신청하기 🔥