본문으로 건너뛰기

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

시선180

2026.07.23

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. 결과를 세 가지 상태로 갈랐어요


테스트 3개가 6개로 늘어난 점검표 픽셀 일러스트


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


  • 성공 + 일정 있음** → 일정을 보여준다

  • 성공 + 일정 없음** → "등록된 일정이 없어요" (이건 오류가 아니에요!)

  • 조회 실패** → "지금 캘린더를 확인할 수 없어요" (절대 '일정 없음'으로 바꾸지 않는다)


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


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


  1. 제목이 같아도 시간이 다르면 다른 일정으로 남기는가 — "회의"가 오전·오후 두 번 있으면 둘 다 보여야죠

  2. 빈 결과가 "정상"으로 처리되는가 — 일정 없는 날이 오류로 뜨면 안 되니까

  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) 대응 추가


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


💬 이 과정에서 배운 팁


효과적이었던 것


  1. 기능 추가보다 약속 명시가 먼저 — 이번에 늘린 기능은 0개예요. 그런데 스킬의 신뢰도는 확실히 올라갔어요.

  2. "언제 쓰지 마라"를 독립 섹션으로 — AI의 사고는 대부분 스킬을 잘못 쓸 때가 아니라, 쓰면 안 될 때 쓰는 데서 나요.

  3. 단계마다 완료 조건 붙이기 — "다 됐어요"를 말하려면 뭘 통과해야 하는지 스킬에 적어두세요.

  4. 고쳤으면 실제로 한 번 돌리기 — 자동 테스트가 다 통과해도, 진짜 환경의 오류는 따로 있어요.


이렇게 하면 안 돼요


  1. 문서 길어진다고 다 본문에 넣기 — 늘 읽는 본문과 필요할 때 여는 부록을 나누세요. AI가 매번 읽는 양이 곧 비용이에요.

  2. 같은 정보를 두 문서에 복사하기 — 원본은 한 곳에만. 두 군데 적으면 언젠가 서로 달라져요.

  3. 실패를 "없음"으로 포장하기 — "조회 못 했어요"가 "일정 없어요"보다 백 배 안전한 답이에요.


🌍 다른 데 적용한다면?


캘린더 스킬이라서가 아니라, 반복 작업을 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 — 고칠 때마다 돌리는 자동 테스트

그리고 마지막으로: 실제로 한 번 돌려서, 거기서 나온 오류를 다시 이 문서에 반영하세요.


9

함께 이야기해요 9

로그인하고 댓글을 남겨 주세요

유피테르 프로필 이미지
유피테르2026.07.29

기능을 추가하지 않고도 본문과 부록을 나누고, 허용 캘린더 목록의 원본을 실행 스크립트 한 곳에만 둔 선택이 특히 인상적이었어요. 매번 읽는 정보는 가볍게 유지하면서도 문서 간 불일치까지 예방해, 실제 운영을 오래 이어갈 수 있는 구조로 다듬으신 과정이 잘 느껴졌습니다. 꼼꼼한 설계와 실행 경험을 이렇게 재사용 가능한 형태로 정리해주셔서 감사해요.

시선180 프로필 이미지
시선1802026.07.29

읽어주셔서 감사합니다! ☺️🙏

망원궁예 프로필 이미지
망원궁예2026.07.28

사례글이 한편의 아티클 같네요!! 브런치도 도전해보심이?!

시선180 프로필 이미지
시선1802026.07.28

앗 과찬이십니다! 🤭 컨텐츠는 궁예님께 배워볼께요! ㅋ

Giacomo 프로필 이미지
Giacomo2026.07.28

기능을 하나도 늘리지 않고도 스킬의 신뢰도를 높일 수 있다는 점을, 일정 있음·일정 없음·조회 실패의 세 상태와 단계별 완료 조건으로 아주 구체적으로 보여주셨어요. 특히 자동 테스트 6개를 통과한 뒤 실제 조회에서 Calendar -600 오류를 발견하고, 한 번만 재시도하는 대응까지 규칙에 되돌려 넣은 흐름이 좋았습니다. 문서 정리와 실환경 검증이 왜 둘 다 필요한지 한 사례로 선명하게 전달돼요.

다음에 아침 브리핑 스킬로 연결하실 때 계획하신 것처럼, 조회 실패가 뒷단에서 일정 없음으로 다시 뭉개지지 않도록 두 스킬 사이의 상태 계약까지 이어지면 이번 개선의 가치가 더 잘 드러날 것 같아요. 잘 돌아가는 기능을 더 만드는 대신 어디서 멈추고 무엇을 보고할지를 설계한 과정 자체가 재사용하기 좋은 사례입니다.

시선180 프로필 이미지
시선1802026.07.28

지아코모님 스킬 덕에 좋은 내용 배웠습니다. 꿀팁 감사합니다~! 🙂

Giacomo 프로필 이미지
Giacomo2026.07.29

시선180님이 답글에서 “스킬 덕에 좋은 내용을 배웠다”고 말씀해주시니 저도 반가워요 🙂 일정 있음·일정 없음·조회 실패를 섞지 않는 관점은 다른 Skill을 살펴볼 때도 유용한 기준이 될 거예요. 꼼꼼히 읽어주시고 댓글까지 남겨주셔서 감사합니다!

자연어회계처리 프로필 이미지

중간에 삽입된 레트로 사진들 어떻게 만드셧나요?

시선180 프로필 이미지
시선1802026.07.27

슈퍼마리오 스타일로 픽셀 버전으로 게시글에 맞게 이미지 3개 생성해서 넣어달라고 했습니다. 🙂

필요한 AI 정보만
메일함에 쏙쏙 넣어드려요.

지금 핫한 AI 소식부터 직접 해 본 사례까지, 월요일마다 무료로 받아보세요

이런 사례도 있어요

사례 전체 보기