Claude Code 스킬 여덟 개를 하루 동안 정비했다

오늘은 새 걸 만들지 않았다. 이미 만들어 둔 Claude Code 스킬 여덟 개를 하나씩 열어 문서와 실제가 어긋난 곳을 잡았다. 결론부터 말하면, 버그보다 무서운 건 "설명서가 현실과 다른 것"이었다.

왜 스킬을 정비하나

스킬은 AI 에이전트가 읽는 설명서다. 사람은 설명서가 좀 틀려도 눈치로 메우지만, 에이전트는 문서를 곧이곧대로 믿는다. 문서가 "A 폴더에 저장하라"는데 코드는 B 폴더를 쓰면, 에이전트는 엉뚱한 곳을 뒤진다. 자율로 도는 스킬일수록 이 어긋남이 조용히 사고를 만든다.

스킬이 두세 개일 땐 안 보이던 문제가, 십수 개로 늘자 드러났다. 그래서 오늘은 신규 개발 대신 감사(audit)를 했다.

정비한 스킬 여덟 개

글쓰기·출판

• novel-writer(소설 집필): 퇴고 단계에 'AI 티 점검' 체크리스트를 새로 넣었다. 반전 클리셰 남발, 매 장면을 교훈으로 끝맺기, 균일한 문장 리듬처럼 AI 특유의 버릇을 잡는 항목이다. 그 외 폴더 구조와 도구명을 정리했다.
• sellable-book(수익형 전자책): 끝까지 자율로 도는 스킬이라 모순이 치명적이다. "합격 판정을 사람이 하나 기계가 하나"가 문서마다 달라서 한쪽으로 통일했고, 수요 점수 척도(35점 만점)와 자동 합격선을 못 박았다. 빠져 있던 퇴고 단계도 끼워 넣었다.

영상 제작

• oldbook(명작 비주얼 오디오북): 폴더 표준이 문서마다 달랐다. 실제로는 쓰지 않는 유령 폴더를 참조하던 곳을 전부 실제 구조에 맞췄다.
• ai-contest-video(공모전 영상): 영상 템플릿이 이미 스킬 안에 들어 있는데, 문서는 "외부에서 복사해 와라"라고 안내하고 있었다. 로컬에 있다고 바로잡고, 의존성 점검 코드의 누락도 메웠다.
• youtube-comfyui-video(AI 클립 영상): 지난 테스트에서 찾은 함정 세 가지 — 세로 영상이 강제로 가로가 되는 버그, 자막 경로 버그, 나레이션 분할 한도 — 가 내 메모에만 있고 정작 스킬엔 없었다. 별도 함정 문서로 박아 넣었다.
• youtube-hyperframes-generator(이미지 기반 영상): 내 PC 사용자명이 코드에 박혀 있어 다른 기계에선 안 돌던 부분을 환경변수로 바꿨다.
• youtube-yuna(유나 운세 쇼츠): 열어 봤지만 멀쩡했다. 손댈 곳이 없어서 그대로 뒀다. 이것도 점검의 결과다.

사이트 관리

• home(바로 이 블로그를 관리하는 도구): 한글이 깨지던 문제를 구조적으로 막았고(한글은 인자가 아니라 파일로 전달한다), 무엇보다 이 스킬을 icenovel.com 자기 자신이 배포하게 만들었다. 새 노트북에서 한 줄로 받아 설치하고, 명령 한 줄로 최신본을 당겨 온다. 지금 이 글도 그 home으로 쓰고 있다.

오늘 배운 것

스킬도 코드처럼 썩는다. 그리고 가장 흔한 사인(死因)은 거창한 버그가 아니라 문서와 현실의 사소한 어긋남이다. 만들 때 맞았던 문서가, 코드가 한 발씩 움직이는 동안 조용히 틀려진다.

앞으로는 스킬을 고칠 때마다 문서도 같은 호흡으로 손보기로 했다. 그리고 home처럼 도구가 자기 자신을 배포하고 갱신하는 구조를 더 늘릴 생각이다. 가장 좋은 설명서는, 늘 최신인 설명서니까.