스킬 53개를 만들고 3개만 쓰고 있었다

만든 스킬이 왜 안 뜨는지 몇 달 동안 궁금했다. 기록을 열어보니 원인은 스킬이 아니라 설정 한 줄이었다.

AI 에이전트에 “스킬”을 붙이는 건 이제 흔한 일이 됐다. 반복 절차를 마크다운 한 장에 적어두면 에이전트가 알아서 꺼내 쓴다. 나도 열심히 만들었다. 프로젝트용 8개, 개인용 45개.

그런데 어느 날 문득 이상했다. 분명 스킬을 만들어뒀는데, 매번 손으로 시키고 있었다.

감으로는 답이 안 나와서 세어보기로 했다.

TL;DR

• 7일간 내가 친 프롬프트 236건 중 스킬이 발동한 건 10건(4.2%). 가진 53개 중 3개만 떴다.
• 원인은 스킬 품질이 아니었다. 개인 스킬 45개 중 38개에 자동 발동을 끄는 설정이 붙어 있었다.
• 두 번째 원인은 트리거 문구. 내가 실제로 쓰는 말이 스킬에 안 적혀 있으면 안 뜬다.
• 재는 데는 아무 준비도 필요 없었다. 대화 기록이 이미 내 노트북에 쌓여 있었다.

1. 세어봤다

Claude Code는 대화 기록을 로컬에 남긴다.

~/.claude/projects/<프로젝트>/*.jsonl

한 줄에 JSON 하나씩, 내가 친 프롬프트도 에이전트가 부른 도구도 전부 들어 있다. 스킬을 부르면 Skill이라는 도구 호출로 남고, 어떤 스킬인지도 그대로 적힌다. 세는 건 어렵지 않았다.

7일치를 뽑았다.

53개를 만들어놓고 3개를 쓰고 있었다.

작업 유형별로 나눠서, 그때 스킬이 실제로 떴는지 대조해봤다.

읽는 법은 두 갈래다.

• 요청은 많은데 스킬이 없다 → 새로 만들 자리
• 스킬이 있는데 안 뜬다 → 다른 문제

내 경우는 전부 후자였다. 티켓 44건, PR 21건, 메신저 5건 — 전부 스킬을 가지고 있었다.

그리고 발동한 10건 중 7건이 배포 준비 한 곳에 몰려 있었다. 이 쏠림이 결정적이었다. 같은 사람이 만든 스킬인데 한쪽만 되고 나머지는 안 된다면, 스킬 품질 문제가 아니다.

2. 자연어로도 뜨긴 뜬다

혹시 슬래시 명령을 쳐야만 뜨는 건가 싶었다. 기록을 뒤져보니 아니었다.

내가 친 말: "자 그럼 PR 올리기전에 코드 다시 한번 자체 리뷰 해보자"
같은 시각:  Skill 호출 → code-review

슬래시는 없었다. 그냥 말했는데 떴다. 그러니까 잘 만들어두면 알아서 뜨는 게 맞다.

그럼 왜 내 것들은 안 떴을까.

3. 원인 ①: 설정 한 줄

스킬 파일 앞머리에 이런 옵션이 있다.

---
name: my-skill
description: ...
disable-model-invocation: true
---

이게 붙으면 에이전트가 자연어로 판단해서 부르는 경로가 완전히 차단된다. 슬래시 명령으로만 실행된다. (Agent Skills 문서에 정의된 필드다.)

세어봤다.

grep -l 'disable-model-invocation: *true' ~/.claude/skills/*/SKILL.md | wc -l

38개. PR 본문 채우기, 리뷰 요청 보내기, 작업 시작·마무리, 리뷰 계열 전부 — 내가 “왜 안 뜨지” 했던 것들이 하나도 빠짐없이 여기 있었다.

발동이 몰려 있던 그 배포 준비 스킬은? 프로젝트 스킬이었다. 프로젝트 쪽은 차단이 하나도 없었다.

허무했다. 몇 달간 매번 손으로 시키고 있었는데, 원인은 파일 앞머리 한 줄이었다.

이 옵션 자체가 나쁜 건 아니다. 위험하거나 비용이 큰 작업은 사람이 명시적으로 부르게 막는 게 맞다. 문제는 내가 그걸 의도했는지도 모른 채 대부분에 붙어 있었다는 것이다.

전에 에이전트 권한은 실행 환경의 일부라는 글을 쓴 적이 있다. 그때는 인증 이야기였는데, 이번 건도 결국 같은 종류다. 에이전트가 뭘 할 수 있느냐는 코드가 아니라 설정에 적혀 있다.

4. 원인 ②: 내가 쓰는 말이 아니었다

차단이 안 걸린 스킬 중에도 안 뜨는 게 있었다. 티켓 관리 스킬은 자동 발동이 켜져 있는데 44건 중 0건이었다.

설명을 열어봤다. 트리거 문구가 이렇게 적혀 있었다.

"티켓 만들어", "티켓 쪼개기", "작업 산정"

그런데 내가 7일간 실제로 친 말은 이랬다.

"2210 진행하자"
"2228 쪼개자"
"2224 처리해보자"

하나도 안 겹친다. 게다가 스킬에 적힌 프로젝트 약어가 예전에 쓰던 것이었고, 지금 다루는 티켓은 전부 다른 약어였다.

내가 쓸 것 같은 말과 실제로 쓰는 말은 다르다. 스킬을 만들 때 트리거를 상상해서 적으면 이렇게 된다.

고치는 법은 간단하다. 기록에 남은 내 프롬프트 원문에서 그대로 복사해 넣는다. 지어내지 않는다.

5. 재는 법

준비물은 없다. 이미 쌓여 있는 걸 읽기만 하면 된다.

~/.claude/projects/<프로젝트>/*.jsonl

• 사람이 친 프롬프트: type === 'user'이고 내용이 문자열이거나 텍스트 블록만 있는 것
• 스킬 발동: type === 'assistant'의 도구 호출 중 이름이 Skill인 것 → 어떤 스킬인지도 나온다
• 도구 프로필: 같은 도구 호출의 이름 분포. Bash가 압도적인데 Skill이 1% 미만이면 자동화 여지가 크다는 신호다

기간은 파일 수정 시각이 아니라 각 줄의 timestamp로 자른다. 한 파일에 여러 날이 섞여 있다.

그리고 하나, 이걸 안 하면 숫자가 통째로 틀어진다.

시스템이 주입한 메시지를 걸러내야 한다. <task-notification>, This session is being continued, Caveat: 같은 것들이 전부 type: user로 들어와 있다. 안 거르면 건수가 30% 넘게 부풀려진다.

팀 단위로 보고 싶다면 사용량을 외부로 내보내는 설정도 있다. 다만 내 것만 볼 거면 로컬 기록이 더 낫다 — 잘림이 없고, 직접 만든 스킬의 이름이 그대로 남는다.

6. 그런데 나는 한 번 틀렸다

첫 집계에서 “검증·CI 89건”이 최상위권으로 나왔다. 게다가 상위 항목 중 유일하게 스킬이 없는 자리였다. 그래서 바로 만들었다.

그런데 원자료를 열어보니 이런 게 잔뜩 섞여 있었다.

<task-notification> ... CI check completed ...
This session is being continued from a previous conversation...

시스템이 주입한 메시지를 내가 친 프롬프트로 세고 있었다. CI 완료 알림이 89건의 대부분이었다.

걸러내니 236건 중 7건이었다. 최상위가 아니라 하위권이었다.

집계만 보고 결론을 냈으면 엉뚱한 데 시간을 썼을 것이다. 실제로 그 자리에 이미 스킬을 하나 만든 뒤였다. (그 스킬 자체는 쓸모가 있어서 남겨뒀지만, 최우선이라는 판단은 틀렸다.)

교훈: 분류하고 세는 건 쉽다. 각 분류의 원문을 20건씩 눈으로 확인하는 것을 건너뛰면 안 된다.

7. 그래서 뭘 했나

결론이 처음 예상과 정반대로 나왔다. 새로 만들 자리는 거의 없었다.

우선순위는 이렇게 정리됐다.

1. 차단 해제 — 자주 쓰는 것부터 disable-model-invocation 한 줄 지우기. 제일 싸고 효과가 크다.
2. 트리거 문구 교체 — 기록에서 뽑은 내 실제 표현으로. 상상 금지.
3. 통폐합 — 리뷰 계열이 6개나 됐다. 이러면 에이전트도 뭘 불러야 할지 모른다.
4. 그러고 나서 새로 만들기.

그리고 이 점검 자체를 스킬로 만들었다. 한 달 뒤에 다시 돌려서 발동률이 올랐는지 볼 생각이다.

모니터링을 숫자와 신호로 나눠 본 글에서 비슷한 얘기를 했었다. 사람이 매번 챙길 수 없는 건 대시보드가 아니라 정기적으로 돌아가는 절차로 만들어야 한다.

마무리

스킬을 만드는 건 재밌다. 절차를 정리하고, 함정을 적어두고, 늘어나는 걸 보면 뿌듯하다.

그런데 만든 것과 쓰이는 것은 다른 문제다. 나는 그 간극을 몇 달 동안 몰랐다. 재보기 전까지는.

혹시 스킬을 여럿 만들어두셨다면, 오늘 한 번 세어보시길 권한다. 파일 앞머리 한 줄 때문일 수도 있다.

덧. 이 글을 쓰려고 블로그 초안 스킬을 부르려 했는데 안 떴다. 열어보니 거기에도 disable-model-invocation: true가 붙어 있었다. 결국 손으로 썼다.