skill-metrics

Claude Code가 남긴 세션 JSONL(~/.claude/projects/**/*.jsonl)을 집계해 스킬/워크플로우 사용을 정량 지표로 환산한다. 목적은 두 가지다:

1. 자동화 우선순위 산정 — 무엇을 먼저 스킬·체인·훅으로 자동화하면 임팩트가 큰가.
2. 상시 측정 — 도달률·빈도 추이로 스킬 채택/이탈을 추적한다.

측정은 전부 번들된 scripts/measure.py가 수행한다. Claude가 JSONL을 직접 읽어 토큰을 태우지 않는다 — 스크립트를 호출하고 결과 마크다운만 해석한다.

지원 범위 확인 — 먼저 실행

이 스킬의 지표는 Claude Code 세션 로그가 스킬 호출을 `Skill` 도구 사용으로 기록한다는 사실에 의존한다. 현재 하네스가 이 관측량을 제공하는지 먼저 확인한다.

• Claude Code의 ~/.claude/projects/**/*.jsonl처럼 Skill 도구 호출이 구조화되어 있으면 아래 절차를 계속한다.
• 스킬이 프롬프트로 로드될 뿐 별도 도구 호출로 기록되지 않으면 호출 횟수·도달률·전환을 계산할 수 없다.

이 경우 다른 세션 로그를 억지로 비슷하게 파싱하지 말고, "현재 하네스는 스킬 호출을 독립 이벤트로 기록하지 않아 skill-metrics를 지원할 수 없습니다"라고 알린 뒤 종료한다.

파일 위치 차이가 아니라 지표 정의에 필요한 사건이 없다는 문제이므로, 추정값을 만들지 않는다.

실행 절차

Step 1: 측정 스크립트 실행

현재 SKILL.md가 들어 있는 디렉터리의 scripts/measure.py를 실행한다. 호출과 함께 전달된 자연어 인자로 기간을 받는다.

# 기본: 최근 14일, stdout 출력
python3 "<스킬 디렉터리>/scripts/measure.py" --days 14

# 특정 시작일부터
python3 "<스킬 디렉터리>/scripts/measure.py" --since 2026-06-05 --until 2026-06-19

# 프로젝트 필터 + 파일 저장
python3 "<스킬 디렉터리>/scripts/measure.py" --days 14 --project myproject --out /tmp/skill-metrics.md

주요 옵션:

전달된 인자가 숫자면 --days로, YYYY-MM-DD 형식이면 --since로 넘긴다.

Step 2: 결과 해석

스크립트 출력을 그대로 사용자에게 보여주되, 상위 3개 자동화 후보와 묶음 후보(transition) 를 짚어 "다음에 무엇을 자동화하면 좋은지" 한두 줄로 요약한다.

Step 3 (선택): 회고에 연결

주간 회고(retrospective) 맥락이면, 이 지표를 자동화 우선순위의 정량 근거로 인용한다. 결과를 보존하려면 프로젝트 문서 폴더의 보고서·회고 하위 폴더에 저장을 제안한다 (사용자 확인 후).

지표 정의

① AutoScore — 자동화 우선순위

AutoScore = 주간호출수 × (평균후속체인길이 + 1) × (1 + 마찰율)

• 주간호출수: 기간 내 그 스킬 호출수를 주 단위로 환산. (자주 쓸수록 자동화 가치↑)
• 평균후속체인길이: 그 스킬 호출 직후 같은 세션의 윈도우(30 tool_use) 안에

따라오는 다른 스킬의 평균 개수. 높으면 다른 스킬과 엮여 돌아 — 단일 체인으로 묶을 가치가 큼. (체인이 0이어도 빈도가 반영되도록 +1)

• 마찰율: 그 스킬이 등장한 세션 중 사용자 발화에 재작업/교정/실패 표현

("다시 해", "그게 아니", "안 돼", "재시도" 등)이 있던 세션의 비율. 마찰이 잦은 워크플로우일수록 자동화로 덜어낼 여지가 큼.

①-b 묶음 후보 (transition): A → B는 A 호출 직후 윈도우 안에 처음 등장한 다른 스킬 B의 쌍별 빈도. 같은 쌍이 반복되면 단일 체인 커맨드로 묶을 1순위 신호다. (예: 프로젝트 커밋 스킬 → PR 스킬 연결이 잦으면 둘을 한 워크플로로 묶는다.)

③ 상시 지표 (Reach)

• 스킬 도달률(Reach): 스킬을 한 번이라도 쓴 세션 / 전체 세션.

나머지(미사용 세션)가 거시적 "미활용" 신호 — 스킬 없이 손으로 돌린 세션 비중이다. (작업별 미활용을 정밀 추적하려면 스킬↔수동 매핑이 필요한데, 그건 수동 유지보수 부담이 커서 1차 범위에서 제외했다. 거시 신호로 Reach를 본다.)

• 서브에이전트 도달률: Agent 도구를 쓴 세션 비율.
• 스킬 호출 빈도 / 일별 세션 분포 / 슬래시 커맨드 빈도: 추이·습관 파악용.

한계 (정직하게)

• 마찰율은 세션 단위 귀속이라 긴 세션이 많으면 대부분 스킬에서 100%로 포화한다.

순위 근거로 쓰지 않는다(주 변별은 빈도·체인).

• 마찰 표현 사전은 휴리스틱이다. 한국어/영어 교정·재시도 표현 위주로 보수적으로

잡으며, 놓치거나 오탐할 수 있다. (scripts/measure.py의 FRICTION_PATTERNS에서 조정)

• 버전이 다른 동명 스킬(create-pr vs development:create-pr)은 별개로 집계된다 —

합산 해석이 필요하면 사람이 묶어 읽는다.

• 20줄 이하의 즉시 종료 세션은 제외한다(빈 세션 노이즈).
• 스크립트를 직접 부르는 스킬(search-sessions 등)은 Skill 호출이 0으로 잡힌다. 미사용으로

판정하기 전에 그 스킬 scripts/ 경로를 부른 Bash 실행 수를 같이 센다.

확장 여지

• --out으로 저장한 리포트를 일일 업무 기록이나 스케줄(/schedule)에 붙이면 주간 자동 집계.
• 향후 작업별 미활용률(②)을 다시 넣고 싶으면, 스킬↔수동 매핑을 코드 밖

선언 파일로 빼는 방식을 검토한다(수동 유지보수 최소화).