Claude Code Skill 설계부터 자동 실행까지 실전 가이드

같은 지시를 세 번째 타이핑하고 있다면 Skill로 만들 때다. 이 글은 실제로 운영 중인 스킬 두 가지, 주제 하나로 교육 영상을 만들어 유튜브에 올리는 topic-video-youtube와 매일 두 번 블로그 초안을 써 주는 자동 정리 작업을 예로 들어 Skill을 설계하고, 검수를 붙이고, 사람이 없어도 돌게 만드는 과정을 정리한 것이다.

레시피 카드를 보며 만드는 로봇과 돋보기로 검수하는 로봇, 그 옆에서 잠든 사람

Skill은 무엇인가

Skill은 SKILL.md 파일 하나가 든 폴더다. 개인용은 ~/.claude/skills/<이름>/에, 프로젝트용은 저장소의 .claude/skills/<이름>/에 둔다.

~/.claude/skills/topic-video-youtube/
├── SKILL.md        # 진입점: 언제 쓰는지(description)와 작업 순서
├── references/     # 필요할 때만 읽는 상세 규칙
├── scripts/        # 매번 같은 결과가 나와야 하는 작업
├── assets/         # 템플릿, 공용 소재
└── CHANGELOG.md    # 실패에서 배운 것을 고친 기록

핵심은 로딩 방식이다. 평소에는 SKILL.md 맨 위의 name과 description만 컨텍스트에 올라가 있다. 요청이 description과 맞을 때 본문이 읽히고, references/의 문서는 본문이 "이럴 때 이 파일을 읽어라"라고 할 때만 읽힌다. 그래서 규칙이 길어져도 평소 대화의 토큰을 잡아먹지 않는다. CLAUDE.md에 모든 걸 몰아넣는 것과 가장 크게 다른 점이다.

1단계: 스킬로 만들 일인지 판단하기

다음 세 가지 중 둘 이상이면 스킬로 만든다.

같은 순서의 지시를 반복해서 보낸다.
한 번 실수한 것을 다음에도 기억해야 한다.
결과물의 품질 기준이 있다(길이, 형식, 검수 항목).

반대로 한 번 쓰고 말 작업, 매번 판단이 크게 달라지는 작업은 스킬로 만들어도 이득이 적다.

2단계: description이 트리거다

Claude는 description을 보고 스킬을 쓸지 정한다. 그래서 description은 기능 소개가 아니라 "어떤 말을 들으면 이 스킬을 쓸지"를 적는 곳이다. 실제 영상 스킬의 description은 이렇게 끝난다.

---
name: topic-video-youtube
description: 주제 제목 하나로 3~4분짜리 한국어 교육·설명 영상을 끝까지 만들고 유튜브에 올리는 파이프라인. (중략)
  "역사: 로마 수도교 영상 만들어서 올려줘", "TCP 3-way handshake 설명 영상 유튜브에",
  "복리 이야기로 경제 영상 하나" 처럼 주제를 주고 영상 제작이나 유튜브 업로드를 원할 때는,
  스킬 이름을 말하지 않아도 이 스킬을 쓴다.
---

잘 쓴 description의 조건은 세 가지다.

무엇을 하는지 한 문장으로 말한다.
사용자가 실제로 칠 법한 문장을 예시로 넣는다.
"스킬 이름을 말하지 않아도 쓴다"처럼 적극적으로 쓰라고 적는다. 그러지 않으면 애매한 요청에서 스킬을 건너뛴다.

3단계: 본문은 기본값 표와 절대 규칙부터

본문 첫 화면에는 사용자에게 다시 묻지 않아도 되도록 기본값을 표로 둔다.

| 항목 | 기본값 |
|---|---|
| 길이 | 3~4분, 12~14장면 |
| 화면 | 1920×1080, 30fps |
| 유튜브 | 채널 「아키의 공백」, 공개, 아동용 아님 |
| 프로젝트 위치 | `~/edu-videos/<영문-slug>/` |

그 아래에 절대 규칙을 둔다. 절대 규칙은 상상으로 쓰지 말고 실제 사고에서 나온 것만 쓴다. 영상 스킬에는 "렌더된 영상 파일은 읽지 않는다"는 규칙이 있다. 검수하려고 완성 영상을 디코드했다가 맥 메모리가 바닥나 멈출 뻔한 뒤에 생긴 규칙이고, 날짜와 이유를 함께 적어 두었다. 이유가 같이 있어야 모델이 비슷한 다른 상황(프레임 추출, ffprobe)까지 피한다.

작업 순서는 번호를 매긴 단계로 쓰고, 각 단계에 "끝났다고 판단하는 기준"을 붙인다. 기준이 없으면 모델은 그럴듯해 보이는 지점에서 멈춘다.

4단계: 계산은 scripts로 뺀다

모델에게 매번 시키면 결과가 흔들리는 일은 스크립트로 만든다. 영상 스킬의 scripts/에는 장면별 음량 확인, 자막과 음성 시간 맞춤 확인, 발음 검사, 렌더 같은 작업이 들어 있다. 본문에는 "이 단계에서 scripts/qa_check.py <프로젝트 경로>를 실행하고 FAIL이면 고친다"처럼 언제 무엇을 실행할지만 적는다.

나누는 기준은 단순하다.

모델이 할 일	스크립트가 할 일
대본 쓰기, 장면 구성, 무엇을 고칠지 판단	측정, 형식 검사, 변환, 렌더, 업로드 전 점검

스크립트는 결과를 PASS/FAIL과 짧은 이유로 출력하게 만든다. 긴 로그를 그대로 내보내면 컨텍스트만 채운다.

5단계: 만드는 쪽과 검수하는 쪽을 나눈다

스스로 만든 결과를 스스로 검수하면 거의 항상 통과시킨다. 그래서 영상 스킬은 서브에이전트 둘로 나눴다. 에이전트는 ~/.claude/agents/<이름>.md에 정의한다.

maker가 만들고 수정 권한 없는 checker가 검수해 통과하면 오케스트레이터가 업로드하고, 실패하면 지적 항목만 고쳐 다시 검수받는 흐름

---
name: video-checker
description: CHECKER for the topic-video-youtube skill. Independently inspects a video project
  BEFORE render (...) and returns PASS/FAIL with concrete, scene-numbered issues.
  Read-only; never edits files, never renders, never uploads, never reads video files.
tools: Bash, Read, Grep, Glob
---

설계 포인트는 다음과 같다.

checker에게서 수정 도구를 뺀다. tools에 Edit, Write가 없으니 고치고 싶어도 못 고친다. 검수자는 판정만 한다.
maker는 자기 결과를 인증하지 않는다. maker 정의에 "Never certifies its own output"을 명시했다.
checker는 만든 과정을 모른다고 가정한다. 폴더의 파일만 보고 판단하게 해서, maker의 설명에 끌려가지 않게 한다.
보고 형식을 고정한다. "장면 번호 + 문제 + 근거"로 받으면 maker가 정확히 그 부분만 고친다. 재검수 때는 지적한 항목과 바뀐 장면만 다시 본다.
되돌리기 어려운 일은 오케스트레이터만 한다. 업로드는 checker가 PASS를 준 뒤 메인 대화가 한다.

6단계: 실패를 스킬에 되먹인다

스킬은 처음 만든 날보다 열 번째 실행한 뒤에 훨씬 좋아진다. 실행이 끝나면 다음을 스킬 파일에 적는다.

직접 고쳐야 했던 것: 절대 규칙이나 단계 기준으로 옮긴다.
새로 알게 된 수치: 기본값 표를 고친다(예: 음량 기준, 장면 수).
바뀐 도구나 경로: 본문의 명령을 고친다.

고친 내용은 CHANGELOG.md에 날짜와 함께 남긴다. 나중에 규칙이 왜 생겼는지 추적할 수 있고, 지나치게 엄격해진 규칙을 걷어낼 때도 근거가 된다.

7단계: 사람 없이 돌리기

대화창에서 부르는 스킬을 정해진 시간에 혼자 돌게 하려면 claude -p(헤드리스 모드)와 운영체제 스케줄러를 쓴다. 이 블로그의 자동 정리 작업이 그 예다. macOS의 launchd가 매일 13시와 19시에 셸 스크립트를 실행하고, 스크립트는 지난 실행 이후의 작업 기록을 모아 Claude에게 글 두 편을 쓰게 한 뒤 블로그에 초안으로 저장한다.

launchd, run.sh, extract.py, claude -p, ego-browser를 거쳐 초안이 저장되고 사람이 검토해 발행하는 자동 정리 파이프라인

<!-- ~/Library/LaunchAgents/com.yongdev.blog-digest.plist (일부) -->
<key>ProgramArguments</key>
<array>
  <string>/bin/zsh</string>
  <string>/Users/yongyeonkim/my-blog/scripts/blog-digest/run.sh</string>
</array>
<key>StartCalendarInterval</key>
<array>
  <dict><key>Hour</key><integer>13</integer><key>Minute</key><integer>0</integer></dict>
  <dict><key>Hour</key><integer>19</integer><key>Minute</key><integer>0</integer></dict>
</array>

스크립트의 핵심 줄은 이것이다.

{ cat "$SCRIPT_DIR/instructions.md"; echo; echo "## 입력"; echo; cat "$OUT/digest.md"; } |
  claude -p --setting-sources project --tools "" --no-session-persistence >"$OUT/claude.txt" ||
  fail "글 작성(claude -p)"

옵션마다 이유가 있다.

--setting-sources project: 내 개인 설정과 훅(말투 플러그인 등)이 섞이지 않게 한다. 대화창에서 쓰던 설정이 자동 작업 결과를 바꾸면 원인을 찾기 어렵다.
--tools "": 글만 쓰면 되는 단계라 도구를 전부 막는다. 권한을 물어볼 사람이 없는 자동 실행에서는 필요한 도구만 열어 두는 게 안전하다.
--no-session-persistence: 자동 실행 기록이 내 세션 목록을 채우지 않게 한다.

자동 실행을 안정적으로 만든 장치는 다음과 같다.

상태 파일: 마지막 실행 시각을 last-run에 적고 다음 실행은 그 뒤부터 모은다. 성공했을 때만 갱신하니 실패한 구간은 다음 실행이 다시 처리한다.
할 일이 없으면 끝내기: 모을 기록이 없으면 Claude를 부르지 않고 종료한다. 모델이 "쓸 게 없다"고 판단하면 SKIP을 출력하게 해서 빈 글도 막는다.
실패하면 알리기: 단계마다 실패 시 macOS 알림과 로그 경로를 띄운다. 조용히 실패하는 자동화가 가장 위험하다.
사람이 마지막에 본다: 결과는 바로 발행하지 않고 초안으로만 저장한다. 공개 여부는 사람이 관리자 화면에서 읽고 정한다.
민감정보 가리기: 입력을 만들 때 키, 토큰 같은 값을 가리고, 지시문에도 비밀번호·API 키·내부 주소는 "(가림)"으로 바꾸라고 적었다.
결과 보관: 실행할 때마다 입력, 출력, 결과를 날짜 폴더에 복사해 둔다. 글이 이상하면 어떤 입력에서 나왔는지 바로 찾을 수 있다.

처음 만들 때 점검표

description에 사용자가 칠 법한 문장 예시가 있다
본문 첫머리에 기본값 표가 있어 되묻지 않는다
절대 규칙은 실제 사고에서 나왔고 이유가 적혀 있다
단계마다 끝났다고 판단하는 기준이 있다
측정·변환·검사는 scripts로 빼고 PASS/FAIL로 출력한다
검수 에이전트는 수정 도구가 없고, 만든 쪽은 자기 결과를 인증하지 않는다
되돌리기 어려운 동작(업로드, 발행, 삭제)은 검수 통과 뒤에만 한다
자동 실행은 필요한 도구만 열고, 상태 파일·실패 알림·결과 보관이 있다
실행할 때마다 배운 것을 SKILL.md와 CHANGELOG.md에 되먹인다

Skill을 잘 만드는 요령은 프롬프트를 길게 쓰는 데 있지 않다. 모델이 판단할 것과 스크립트가 계산할 것을 나누고, 만드는 쪽과 검수하는 쪽을 나누고, 실패할 때마다 그 이유를 파일에 남기는 것이다. 그렇게 쌓인 스킬은 사람이 자는 동안에도 같은 품질로 돈다.