# Skill Checkup

> 설치한 스킬이 실제로 돌고 있는지 재고, 안 돌면 트리거를 고친다. 사용자가 "스킬 점검", "스킬들 잘 돌고 있어?", "스킬 발동률 좀 봐줘", "설치한 스킬 상태 점검", "원장 정리 필요한지 봐줘", "프로필 업데이트 필요해?"라고 하거나, 스킬을 새로 만들거나 고친 뒤 한 달쯤 지나 효과를 확인하려 할 때 발동한다. 세션 로그에서 스킬별 발동 횟수를 세고, 기회 대비 발동률과 원장 기록률을 대조해 트리거 문제인지 절차 이탈인지 가른다. 원장·프로필의 상태도 함께 보고, 프로필 기재가 지금도 맞는지 새 문제를 내서 확인한다. 개별 스킬 하나가 자기 성공 기준을 충족했는지 보는 것("이 스킬 의도대로 작동해?")은 그 스킬 자신이 하고, 이 스킬은 함대 전체가 애초에 돌기는 했는지를 본다. 로그에서 새 자동화 후보를 발굴하는 것은 session-audit이다. 또한 "이 스킬 의도대로 작동해?"처럼 이 스킬 자체의 효과를 점검해 달라는 요청에도 발동하며, 그때는 같은 폴더의 `RATIONALE.md`를 읽고 지난 회차 관측과 대조한다.

- Skill: `iceberggymnast/skill-checkup` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add iceberggymnast/skill-checkup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/iceberggymnast/skill-checkup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: iceberggymnast (https://skillmd.com/u/iceberggymnast)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/iceberggymnast/skill-checkup

---


# Skill Checkup — 스킬이 돌기는 하는지 잰다

스킬의 1차 실패 모드는 **절차가 틀리는 것이 아니라 조용히 안 쓰이게 되는 것**이다. 안 도는 스킬은 아무 신호도 안 보낸다 — 원장이 안 자라고, 지표가 0으로 예쁘고, 아무도 불평하지 않는다. 이 스킬은 그 침묵을 숫자로 바꾼다.

## 이 스킬이 다루는 것

| 상황 | 담당 |
|---|---|
| **함대 전체가 돌기는 하는지 · 트리거 수리** | **이 스킬** |
| **원장·프로필의 상태 점검과 정리** | **이 스킬** |
| 스킬 하나가 자기 성공 기준을 충족했는지 | 그 스킬 자신 ("이 스킬 의도대로 작동해?") |
| 로그에서 **새** 자동화 후보를 발굴 | `session-audit` |
| `CLAUDE.md`·설정 파일 점검 | `claude-md-management` 플러그인 |

**개별 점검과 겹치지 않는다.** 개별 스킬 점검은 "내 기준을 충족했나"를 묻고 그 스킬의 `RATIONALE.md` 관측 표에 남는다. 이 스킬은 "애초에 돌기는 했나"를 묻는다. 재는 대상이 달라서 한쪽이 다른 쪽을 대체하지 않는다.

**`session-audit`과 방향이 반대다.** 그쪽은 없는 것을 만들 근거를 찾고, 이쪽은 있는 것이 죽었는지 본다. 로그를 읽는다는 점만 같다.

## 측정 대상

**판정은 `RATIONALE.md`를 가진 스킬에만 한다.** 그 파일이 있다는 것은 성공 기준을 선언했다는 뜻이고, 선언이 없으면 발동률이 낮은 것이 문제인지 정상인지 판정할 근거가 없다.

**단, 발동 수치는 전부 보고한다.** `RATIONALE.md`가 없어도 계기는 스킬 이름을 가리지 않고 세므로 숫자는 나온다. 그 숫자를 빼면 "함대가 돌기는 했는지"라는 이 스킬의 목적 자체가 사라진다. 없는 스킬은 수치 옆에 **"판정 보류 — 기준 없음"**으로 적고 임의 기준을 지어내지 않는다.

**`RATIONALE.md`를 찾는 순서**: 스킬 폴더 안 → 없으면 `<기준 폴더>/rationale/<스킬명>.md`. 플러그인으로 설치한 경우 스킬 폴더가 캐시 디렉터리라 관측 기록이 `/plugin update`에 지워지므로, 그쪽 규약은 후자에 두게 되어 있다(BOOTSTRAP 2-7). **앞만 보고 "기준 없음"으로 처리하면 규약을 지킨 사람이 전부 측정 불가를 받는다.**

**전 스킬이 "기준 없음"으로 나오면 갓 설치한 상태다.** 고장이 아니다. 그 사실을 그대로 알리고, 만드는 형식은 각 스킬 `SKILL.md` 끝의 "성공 기준 · 존재 의의" 절과 BOOTSTRAP 2-7에 있다고 안내한 뒤 **발동 수치만 내고 끝낸다.** 판정 없는 결과를 "고장"처럼 내면 첫 사용자가 이 스킬을 다시 안 부른다.

## 분모에서 빼야 하는 것

수치를 내기 전에 먼저 거른다. 안 거르면 정상인 것을 실패로 적는다.

**스킬이 없던 기간.** 스킬 폴더의 생성일이나 그 스킬의 첫 커밋보다 앞선 세션은 분모에서 뺀다. 없던 스킬의 발동이 0인 것은 당연하고, 그걸 발동률에 넣으면 최근에 만든 스킬일수록 나쁘게 나온다.

**재실행이 드문 것이 정상인 스킬.** 아래 둘은 발동률로 재지 않는다.

| 유형 | 왜 |
|---|---|
| **일회성 작업을 절차로 굳힌 스킬** | 한 번 돌린 결과가 이미 산출물이고, 절차는 다음에 같은 일이 생길 때를 위해 남긴 것이다. 안 도는 게 아니라 돌 일이 아직 없는 것이다 |
| **도입·설정용 스킬** | 한 번 쓰고 끝나는 것이 정상이다 |

이런 스킬은 **"필요한 순간에 찾아지는가"**로 본다. 로그에서 그 스킬을 썼어야 할 상황이 있었는데 다른 방식으로 처리한 흔적이 있는지 보고, 그런 상황이 아예 없었으면 **판정하지 않는다.**

**어느 유형인지는 그 스킬의 `RATIONALE.md`가 정한다.** 판단이 안 서면 사용자에게 한 줄로 묻는다 — 발동률이 낮은 것이 문제인지 아닌지는 만든 사람이 안다.

## 무엇을 재나 — 세 층

```
기회  (조건이 성립한 횟수)
  ↓  ← 여기서 새면 트리거 문제
발동  (스킬이 실제로 로드되거나 훅이 울린 횟수)
  ↓  ← 여기서 새면 절차 이탈
기록  (원장에 남은 항목 수)
```

**누락이 어느 구간에서 났는지가 곧 진단이다.** 두 구간을 합쳐서 "잘 안 돌아간다"고 하면 처방이 갈린다 — 앞은 트리거를 고치는 일이고, 뒤는 절차를 지키게 하는 일이다.

### 1. 발동 — 스크립트로 센다

```
python scripts/skill-usage.py --days 45
```

세는 신호는 둘이다.

- **스킬 파일 로드** — 세션 jsonl의 `Base directory for this skill: <경로>`. 명시 호출과 자동 발동을 모두 잡는다
- **훅 주입** — 각 훅이 내보내는 마커 문구(`[이해 확인 대상]`, `[CS 복습]` 등 — **훅 파일에서 확인하고 넣는다**). 훅은 스킬 파일을 로드하지 않고도 절차를 시작시키므로, 로드만 세면 훅으로 도는 스킬을 크게 과소평가한다

출력의 `스킬별로드`는 총 횟수, `스킬별발동세션수`는 그 스킬이 한 번이라도 돈 세션 수다. **비율은 세션 수 기준으로 본다** — 한 세션에서 열 번 도는 것과 열 세션에서 한 번씩 도는 것은 다른 이야기다.

**분석 전에 데이터 창부터 확인한다.** `--days`로 준 값이 아니라 **출력의 `기간`이 실제 창이다.** `cleanupPeriodDays` 기본값이 30일이라 45일을 요청해도 30일치만 남아 있을 수 있고, 그러면 발동률이 조용히 3분의 1만큼 줄어든다. 분모를 실제 창에 맞춘다.

**출력의 `경고`·`거른것`·`쓴훅마커`를 읽는다.** `경고`가 있으면 그 회차 수치로 아무것도 고치지 않는다 — 계기가 하네스와 안 맞는 상태다. `쓴훅마커`는 어떤 문구로 셌는지 보여주므로 자기 훅과 대조할 수 있다.

**플러그인으로 설치했으면 캐시 안의 스크립트를 고치지 말고 기준 폴더에 복사해서 돌린다.** `HOOK_MARKERS`에 자기 훅 마커를 추가해도 `/plugin update`에 원복되고, 그러면 그 훅의 발동이 조용히 0으로 돌아간다.

### 2. 계기가 못 보는 것 — 결과와 함께 반드시 적는다

이 숫자를 그대로 "발동률"이라 부르면 안 된다. 아래가 분자에서 빠져 있다.

| 사각지대 | 왜 |
|---|---|
| 다른 하네스(codex 등)의 발동 | 스킬 폴더를 링크해 쓰면 그쪽 로그는 `~/.claude/projects`에 없다 |
| 서브에이전트 레인 내부 | 메인 세션 jsonl에 안 들어온다 (`--with-subagents`로 일부 포함) |
| 삭제된 기간 | `cleanupPeriodDays` 설정에 따라 오래된 로그가 이미 없다 |
| 마커 없는 훅 | 마커 문구를 안 내보내는 훅은 안 잡힌다 |
| **감지 문자열을 인용한 세션** | 반대로 **부풀린다.** 로그를 분석·디버깅하면서 감지 문자열을 화면에 찍은 세션은 자기가 분자에 섞인다. **점검을 돌린 세션 자신이 다음 회차를 오염시킨다** — 회차 기록에 그 사실을 적고, 오염된 항목은 표에서 뺀다 |

**"안 잡혔다"와 "안 돌았다"는 출력이 같고, "인용했다"와 "돌았다"도 출력이 같다.** 낮은 수치를 보고 트리거를 고치기 전에, 높은 수치를 보고 안심하기 전에 이 목록부터 확인한다. 계기를 못 믿으면 그 항목은 "측정 불가"로 두고 넘어간다.

**훅 마커는 추측하지 말고 훅 파일에서 확인한다.** 첫 실행에서 마커 한 개를 추측으로 넣었다가 커밋 케이스가 통째로 빠졌고, 그 수치로 잘못된 진단을 한 번 냈다. 훅 문구가 바뀌면 `HOOK_MARKERS`도 같이 고쳐야 한다.

### 3. 기회 — 레포에서 센다

스킬마다 조건이 다르므로 한 명령으로 안 나온다. 해당 스킬의 발동 조건을 보고 그 조건이 성립한 횟수를 센다.

- 커밋 직후 도는 스킬 → `git log --since='45 days ago' --oneline | wc -l`
- PR에 붙는 스킬 → `gh pr list --state all --json number,author` 로 내 PR과 팀원 PR을 나눠 센다
- 세션마다 걸릴 수 있는 스킬 → 세션 수 자체

**모든 레포를 다 세지 않는다.** 그 스킬이 실제로 쓰이는 레포만 센다. 안 쓰는 레포를 분모에 넣으면 발동률이 인위적으로 낮아진다.

### 4. 기록 — 원장에서 센다

각 스킬의 `RATIONALE.md`가 `## 원장 위치`에서 적재처를 가리킨다. 그 파일에서 같은 기간의 항목 수를 센다.

**적재처가 `없음`이거나 칸이 비었으면 기록 층을 건너뛰고 기회 → 발동 두 층으로만 진단한다.** 사람 관측치로만 재는 스킬(되묻는 횟수, 손으로 고친 빈도 같은 것)은 적재처가 원래 없다. 그런 스킬에 남의 원장을 대입하면 발동은 있는데 기록이 0으로 나와 **정상 작동이 절차 이탈로 뒤집힌다.**

## 진단

| 관측 | 진단 | 처방 방향 |
|---|---|---|
| 기회는 많은데 발동이 적다 | **트리거 문제** | 아래 "트리거 수리" |
| 발동은 하는데 기록이 적다 | **절차 이탈** — 발동해도 끝까지 안 간다 | 절차의 어느 단계에서 끊기는지 로그에서 확인하고, 그 단계를 가볍게 만들거나 훅이 그 단계를 상기시키게 한다 |
| 기록은 있는데 스킵이 누적 | **마찰 문제** | 한 번에 묻는 양을 줄이거나 발동 시점을 옮긴다. 3주 연속이면 그 스킬 자신의 재설계 조항을 따른다 |
| 셋 다 낮은데 기회 자체가 없다 | 문제 아님 | 그 스킬의 대상 작업을 안 한 것뿐이다. **"발동 0"을 실패로 적지 않는다** |
| 발동 0인데 스킬이 최근에 만들어졌다 | 측정 기간 부족 | 다음 회차까지 판정을 보류한다 |
| 발동 0인데 일회성·도입용 스킬이다 | 문제 아님 | 위 "분모에서 빼야 하는 것" 참조 |
| 발동은 있는데 기록이 0이고 적재처가 `없음` | **오진 주의** | 절차 이탈이 아니다. 기록 층을 빼고 두 층으로만 본다 |

## 트리거 수리 — 선택지와 판단 기준

**BOOTSTRAP에서 사용자가 거부한 항목부터 본다.** 도입 때 고른 발동 방식은 `mentee-profile.md`에 남아 있다(BOOTSTRAP 2-6). 그때 "명시 호출만"을 골랐으면 자동 발동 경로가 애초에 없는 것이고, 낮은 발동률은 고장이 아니라 그 선택의 결과다. **그 경우 먼저 물을 것은 트리거 수리가 아니라 "그때 결정을 지금도 유지할 것인가"다.**

**프로필 자체가 없으면 "거부 없음"이 아니라 "도입 안 함"이다.** 상태가 셋이다 — 도입하고 자동 발동을 켠 것 / 도입하고 거부한 것 / 도입을 안 한 것. 셋째를 첫째로 읽으면 훅을 건 적도 없는 사람의 스킬이 "트리거 문제"로 진단되고, 훅으로 도는 스킬에 무효인 수리(description 보강)부터 적용된다. **프로필이 없으면 도입 여부부터 확인한다.**

거부 항목이 아니라면 아래 순서로 본다. **위쪽이 비용이 싸다.**

| 수리 | 언제 | 비용 |
|---|---|---|
| **description 트리거 문구 보강** | 실제로 쓴 표현이 description에 없을 때. 로그에서 그 스킬을 불렀어야 할 발화를 찾아 문구를 그대로 넣는다 | 낮음 |
| **발동 시점을 옮긴다** | 지금 시점에 마찰이 커서 무시될 때. 작업 도중이 아니라 작업이 끝나는 자리로 옮긴다 | 중간 |
| **훅 추가·수정** | 사람이 말해야만 도는데 그 말이 구조적으로 안 나올 때. 자동 커밋 규약이 있으면 "커밋해줘"는 영영 안 나온다 | 중간 |
| **앞 세션을 읽고 묻는다** | 워크스페이스를 열었을 때 직전 세션에서 끝내지 못한 절차가 있으면 그것부터 확인한다 | 중간 |
| **스킬 병합·폐기** | 두 스킬이 같은 시점을 두고 경합해 둘 다 신뢰도가 떨어질 때, 또는 대상 작업 자체가 끝났을 때 | 높음 |

**훅을 늘리는 것은 마지막에 검토한다.** 부팅 시점 알림이 둘 이상이면 사용자가 전부 무시하게 되고, 그때 잃는 것은 새 훅 하나가 아니라 기존 훅까지다.

## 원장·프로필 상태 점검

**이 절은 원장·프로필을 실제로 쓰는 환경에서만 돈다.** 파일이 없으면 절 전체를 "해당 없음"으로 적고 건너뛴다 — **부재는 진단 근거가 아니다.** 도입 절차를 안 돌린 것과 도입했는데 안 도는 것은 완전히 다른 상태인데, 파일만 보면 둘 다 똑같이 비어 있다.

측정과 별개로 데이터 자체가 썩고 있는지 본다.

| 볼 것 | 신호 |
|---|---|
| 미복습 항목의 나이 | 4주를 넘긴 것이 쌓이면 복습 경로가 안 도는 것이다 |
| `판별점`이 빈 항목 | 나중 복습이 알던 층을 물어 통과 도장이 된다. 채우거나 항목을 접는다 |
| 닫히지 않는 항목 | 같은 항목이 세 번 이상 재대조에서 실패하면 출제 방식을 의심한다 |
| 스킵 기록의 빈도 | 그 스킬 자신의 재설계 조항에 걸리는지 |
| 원장 크기 | 커져서 매 리뷰 시작에 읽기 부담이면 닫힌 항목을 아카이브로 접는다 |
| 프로필 기재 | 아래 |

## 프로필 검증 — 새 문제를 내서 확인한다

**`mentee-profile.md`가 있을 때만 한다.** 없으면 이 절을 통째로 건너뛴다 — 프로필이 없다는 것은 그 사람이 멘토 계열 스킬을 도입한 적이 없다는 뜻이고, **"스킬 잘 돌아?"라고 물었을 뿐인 사람에게 스택 숙련도 시험을 내는 것은 이 스킬이 할 일이 아니다.**

`mentee-profile.md`의 주장(주력 스택, 영역별 숙련도 판정)이 지금도 맞는지 본다. **기재를 그냥 믿지 않는다** — 숙련도는 변하고, 원장의 판정은 그 스킬이 만난 코드에 한정돼 있다.

**출제 규칙**

- **기존 프로젝트 코드에서 꺼내지 않는다.** 프로젝트 코드로 물으면 그 프로젝트를 아는지 재게 되고, 프로필이 주장하는 것은 스택 숙련도다
- 프로필이 **명시적으로 주장하는 항목**만 겨냥한다. 주장이 없는 영역은 검증 대상이 아니다
- 질문 품질 규칙은 `senior-mentor`의 "질문은 답을 몰라도 읽혀야 한다"와 "겨냥" 절을 따른다. **여기 옮겨 적지 않는다**
- 한 번에 두세 문제. 그 이상은 시험이 되고, 시험은 다음 점검을 거부당하게 만든다

**결과 처리**

- 결과는 **`mentee-profile.md`의 숙련도 기재만** 갱신한다
- **`comprehension-debt.md`에 쓰지 않는다.** 그 표는 AI 코드 이해도를 재는 지표라 프로필 검증 결과를 섞으면 분포가 오염된다
- **`cs-progress.md`에도 쓰지 않는다.** 그쪽은 "커리큘럼을 배웠나"를 묻고 이쪽은 "프로필 기재가 맞나"를 묻는다
- 기재와 결과가 다르면 프로필을 고치되, **한 번의 결과로 등급을 바꾸지 않는다.** 그 판정은 원장의 관찰 구간 규칙(첫 3회)을 따른다

## 적용 — 승인을 받고 고친다

이 스킬이 손대는 대상은 다른 스킬의 description, 훅, `settings.json`, 프로필이다. **전부 승인 게이트 뒤에 둔다.**

1. 측정 결과와 진단을 먼저 낸다
2. 수리안을 **근거와 함께** 제시한다 — 어느 수치가 어느 처방을 부르는지
3. 사용자가 고를 것을 고른다
4. 고른 것만 적용하고, 무엇을 바꿨는지 파일 단위로 보고한다

**측정하고 조용히 고치지 않는다.** 함대 전체의 트리거를 자동으로 바꾸는 스킬은 그 자체가 가장 위험한 스킬이 된다.

**플러그인으로 설치한 스킬은 파일을 고쳐도 `/plugin update`에 원복된다.** description 보강이 가장 싼 수리인데 캐시 디렉터리에 하면 다음 업데이트에 사라지고, 그러면 **다음 회차가 이미 없어진 수리의 효과를 재게 된다.** 원본 레포에 고치고, 원본이 없으면 그 사실을 보고한 뒤 다른 수리를 고른다.

## 주기

**명시 호출로만 돈다. 훅을 걸지 않는다.**

로그 전수 스캔은 비싸고 함대는 천천히 변한다. 매 세션 도는 것은 낭비고, 부팅 알림을 하나 더 얹으면 기존 알림까지 무시된다.

점검이 끝나면 `RATIONALE.md`의 관측 표에 회차를 남기고 **다음 점검 시점을 한 줄로 제안한다**(기본 한 달 뒤). 그 표가 곧 주기 기록이다 — 별도 원장을 만들지 않는다.

## 하지 말 것

- **측정 결과로 다른 스킬 파일을 승인 없이 고치는 것**
- 계기의 사각지대를 안 적고 수치만 내는 것 — "안 잡혔다"와 "안 돌았다"는 구분되지 않는다
- 기회가 없어서 발동이 0인 것을 실패로 적는 것
- `RATIONALE.md`가 없는 스킬에 임의 기준을 지어내 평가하는 것 — **판정은 보류하되 발동 수치는 낸다**
- 원장·프로필이 없는 환경에서 그 부재를 진단 근거로 삼는 것
- 프로필이 없는 사람에게 검증 문제를 내는 것
- 프로필 검증 결과를 이해 부채 원장이나 CS 진도 원장에 적는 것
- 프로필 검증 문제를 진행 중인 프로젝트 코드에서 뽑는 것
- 한 번의 점검 결과로 숙련도 등급을 바꾸는 것
- 훅을 늘려 해결하려는 것 — 마지막 선택지다

## 성공 기준 · 존재 의의

`RATIONALE.md`를 만들어 아래를 시드로 옮기고, 점검 회차 기록도 그 파일의 관측 표에 쌓는다. **만든 뒤에는 이 절을 참조만 하고 두 벌로 두지 않는다.**

**없애려는 것** — 스킬은 절차가 틀려서 죽지 않고 안 쓰여서 죽는다. 그런데 안 쓰이는 스킬은 아무 신호도 안 보낸다. 원장이 안 자라고, 스킵 기록이 비어 지표가 깨끗해 보인다. 각 스킬의 성공 기준은 "발동했을 때 값을 냈는가"를 묻지 "발동하기는 했는가"를 묻지 않아서, 발동이 0이면 평가할 대상이 없어 조용히 통과한다.

**재는 것 (1차) — 진단이 처방으로 이어졌는가.** 산출물은 숫자가 아니라 고친 트리거다. 지난 회차 제안 중 적용된 것이 있는지, 적용한 수리가 다음 회차 수치를 움직였는지 본다. **수치를 냈다는 것만으로 성공으로 치지 않는다** — 읽고 아무것도 안 바꾸는 보고서는 노이즈 자산이다. 두 회차 연속으로 제안이 하나도 적용되지 않으면 제안이 실행 가능한 형태가 아니거나 점검 자체에 값이 없다.

**재는 것 (2차) — 계기의 정직성.** 수치와 함께 못 본 것을 적었는가. 사각지대를 안 적은 회차는 실패로 친다. 낮은 발동률을 근거로 트리거를 고쳤는데 실은 계기가 못 본 것이었다면 없는 문제를 고친 것이다.

사용자가 *"이 스킬 의도대로 작동해?"* 라고 물으면 `RATIONALE.md`를 읽고 지난 회차 관측과 대조한다.