스킬 16개를 만들었더니 명령어 모음이 판단 문서가 됐다

첫 스킬은 16줄짜리 셸 래퍼였다

Claude Code 의 스킬(skill)은 특정 상황에서만 읽히는 지침 문서다. 규칙 파일과 달리 매 대화에
실리지 않고, 필요할 때만 로드된다. 계층과 로드 비용 이야기는
1편에 썼다.

지금 24개가 있고 그중 16개를 직접 만들었다. 가장 오래된 것 하나를 그대로 옮기면 이렇다.

---
name: dump
description: MySQL 데이터 마이그레이션 실행.
             "dump", "마이그레이션", "db 이전" 등의 요청 시 사용
argument-hint: "[스키마명...]"
---

(스크립트 경로) 를 실행한다.

16줄이고, 사실상 “이 스크립트 돌려라” 한 줄이다. 가장 최근에 만든 것은 198줄이고 절반이
직접 렌더해본 실측 기록이다.

이 글은 그 사이에 무슨 일이 있었는지에 대한 것이다.

1세대 — 명령어를 적어둔 것 (2026-06-10)

처음 만든 스킬들은 성격이 같다.

spring-start / spring-test / spring-deploy — 서버 실행·테스트·배포
fe-start / fe-deploy — 프론트 개발서버·배포
querydsl-regen — 엔티티 바꾼 뒤 Q클래스 재생성
db-migrate / docker-infra / dump

만든 이유는 단순했다. 프로젝트마다 명령이 달라서 매번 설명하기 싫었다. 어떤 레포는
./gradlew bootRun 이고 어떤 건 프로파일 인자가 붙는다. 배포는 SSH 로 rsync 하는 곳도 있고
CodeDeploy 를 쓰는 곳도 있다.

이 세대의 공통점이 둘 있다.

argument-hint 가 붙어 있다. 슬래시 명령처럼 인자를 받게 설계했다.

argument-hint: "[local|dev|stg|prod]"
argument-hint: "[ClassName] [--coverage] [--sonar]"

“왜”가 한 줄도 없다. 9개 전부 본문이 명령 나열이다. 지금 다시 열어보면 무슨 문제를
풀려고 만들었는지 알 수 없다.

2세대 — 틀리는 지점을 적어둔 것

성격이 바뀐 계기는 브랜치 작업이었다.

“작업 올려줘” 한마디로 커밋 → 푸시 → PR → 병합까지 가게 하려고 스킬을 만들었는데, 이게
자꾸 틀렸다. 그래서 틀리는 지점을 목록으로 적기 시작했다.

작업 시작 스킬에는 이런 절이 있다. 사내 브랜치명이라 가명으로 바꿨다.

## 이 skill이 막는 것 (skill 없이 하면 틀리는 지점)

- ❌ dev에서 새 브랜치를 딴다 → 개인 브랜치에서 따야 한다
- ❌ merge로 dev를 합친다 → rebase여야 한다
- ❌ 원격을 먼저 당기는 단계를 건너뛴다 → 당기고 그 위에 rebase
- ❌ 보호 브랜치를 직접 체크아웃·merge한다 → 체크아웃은 한 번뿐
- ❌ 부른 그 프롬프트로 성급히 이름 짓는다
     → 다음 "무슨 작업" 프롬프트를 기다린다

여섯 항목이 전부 ❌ 이렇게 틀린다 → 이렇게 해야 한다 형식이다. 명령을 적은 게 아니라
실패를 적었다.

마지막 항목이 특히 그렇다. “작업 시작하자”라고만 말한 시점에는 무슨 작업인지 아직 모른다.
그런데 그 프롬프트로 브랜치 이름을 지어버리는 일이 반복됐다. 그래서 “다음 프롬프트를
기다려라”를 규칙으로 박았다.

하나가 둘로 쪼개진 날

2026년 6월 25일 하루에 커밋 세 개가 났다.

순서	커밋
1	work-up 분기에 dev 동기화(rebase) 단계 추가
2	work-start 추가, work-up 의 앞부분을 위임
3	work-up → work-finish 개명 + 올리기 직전 재최신화 추가

원래 work-up 하나가 브랜치 따기부터 병합까지 전부 했다. 그런데 앞부분(브랜치 준비)과
뒷부분(올리기)은 부르는 시점이 다르다. 앞은 코드 쓰기 전, 뒤는 다 쓰고 난 뒤다.

쪼개고 나서 이름이 안 맞아졌다. work-up 이 이제 “올리기”만 하니까 work-finish 로
바꿨다.

두 스킬은 브랜치 이름으로 통신한다. 시작 스킬이 티켓 키를 브랜치명에 넣고, 마무리
스킬이 브랜치명만 보고 어느 티켓인지 찾아낸다. 스킬 본문에 그 이유가 적혀 있다.

넣었다가 뺀 것

work-finish 에 봇 리뷰 대기 기능을 넣은 적이 있다. PR 을 올리면 자동 리뷰 봇이 코멘트를
다는데, 그걸 기다렸다가 읽고 조치하는 단계였다.

처음엔 최대 5분 대기
2026-08-07 — 3분으로 줄임
2026-08-13 — 삭제

삭제 커밋의 첫 문단이다.

PR 생성 후 봇 리뷰가 달릴 때까지 10초 간격으로 최대 3분 폴링하고,
봇 코멘트를 읽어 판단·조치하던 5·6단계를 삭제했다.
PR 생성 다음은 바로 병합이다.

기능을 뺄 때 딸려 나오는 게 있다. 대기가 없어지니 그 뒤 단계 번호가 밀리고, 안전장치의
“3분 타임아웃 시 중단” 조항이 무의미해지고, 병합 전 재확인의 근거 문구가 성립하지 않게 됐다.
커밋에 그것들을 함께 정리했다고 적혀 있다.

특히 마지막 것이 그렇다. 재확인 자체는 남겼는데, 이유를 바꿔서 남겼다.

병합 전 mergeable 재확인의 근거를 "대기 중" → "재최신화 이후"로 교체
(대기가 없어져 기존 문구가 성립하지 않음. 재최신화와 병합 사이에도
다른 사람이 움직일 수 있으므로 재확인 자체는 유지)

자리를 네 번 옮긴 스킬

batch-pr-merge 는 여러 PR 을 하나로 묶어 배포를 한 번만 돌게 하는 스킬이다. 이게 가장
파란만장하다.

날짜	사건
2026-06-10	최초 7개 중 하나로 탄생
2026-06-23	삭제
2026-07-30	부활 — 한 머신에만 있던 걸 저장소로
2026-07-31	회사 프로파일 전용으로 이동

마지막 이동의 이유가 한 문장이다.

공통 스킬이라 mac-mini·mac-air 에도 PR 병합 컨텍스트가 깔렸다.

개인 맥북에 회사용 스킬이 뜨는 게 싫었던 것이다. 1편에서 계층을 왜 나눴는지 썼는데,
그 필요를 실제로 느낀 지점이 여기다. 규칙만이 아니라 스킬도 머신별로 갈려야 했다.

안 쓰는 스킬은 고치지 않고 지웠다

2026년 7월 말에 정리를 한 번 했다. 그중 하나의 삭제 커밋이 기준을 잘 보여준다.

스킬 호출 이력 0건이고, 패키징 단계가 2026-07-06 에 제거한
playwright MCP 의 명령을 호출하도록 남아 있어 실행해도 그 단계에서 멈춘다.
안 쓰는 스킬을 검증 없이 고치는 대신 제거한다.

다시 필요하면 chrome-devtools MCP 기준으로 재작성한다.

고칠 수도 있었다. 호출하는 도구만 바꾸면 된다. 그런데 한 번도 안 쓴 스킬을 고쳐봐야
그게 동작하는지 확인할 방법이 없다. 지우고, 필요해지면 그때 다시 쓰기로 했다.

다른 삭제 커밋은 사라지는 명령 8개를 표로 남겨뒀다. “필요해지면 이 커밋에서 복원”이라는
주석과 함께.

두 가지 예외

만들다 보니 일반적인 스킬과 다르게 다뤄야 하는 것이 나왔다.

출력 스타일 스킬은 모델이 못 부르게 막았다. 답변 형식을 바꾸는 스킬인데, 이건 지식이
아니라 스위치다. 한 번 켜면 세션 내내 적용된다. 그래서 설정에 한 줄을 넣었다.

disable-model-invocation: true

모델이 알아서 켜면 안 되고, 사람이 / 로 켜고 말로 꺼야 한다.

도구 제한은 스킬에 걸지 않았다. 스킬 설정에 allowed-tools 라는 항목이 있어서 쓸 수
있는 도구를 좁힐 수 있다. 그런데 24개 중 이걸 쓰는 게 하나도 없다.

이유는 1편에 쓴 실측 때문이다. 비슷한 성격의 옵션이 실제로는 강제되지 않았다. 도구를 진짜
막으려면 훅을 써야 한다. 스킬 설정으로 막았다고 믿으면 안 막힌 채로 안심하게 된다.

남는 것

숫자로 적으면 이렇다.

직접 만든 스킬 16개 (공통 7 · 회사 전용 9)
외부에서 가져와 편입한 것 3개, 순수 외부 5개
가장 짧은 것 16줄, 가장 긴 것 240줄
argument-hint 를 쓰는 것은 전부 1세대 8개, 2세대는 0개

그런데 개수보다 방향이 더 눈에 띈다. 1세대는 명령을 적었고, 2세대는 틀리는 지점을
적었다. 명령은 검색하면 나오지만 “여기서 이렇게 틀린다”는 겪어야만 안다.

스킬이 실제로 값을 하는 지점도 거기다. 명령어를 대신 쳐주는 게 아니라, 같은 실수를 두 번
하지 않게 막아준다. 그래서 요즘은 스킬을 만들 때 명령부터 적지 않고 “이거 없으면 뭘
틀리지” 부터 적는다.