skill-metrics

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

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

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

실행 절차

Step 1: 측정 스크립트 실행

스킬 디렉토리의 scripts/measure.py를 실행한다. 인자($ARGUMENTS)로 기간을 받는다.

# 기본: 최근 14일, stdout 출력
python3 "$SKILL_DIR/scripts/measure.py" --days 14

# 특정 시작일부터
python3 "$SKILL_DIR/scripts/measure.py" --since 2026-06-05 --until 2026-06-19

# 프로젝트 필터 + 파일 저장
python3 "$SKILL_DIR/scripts/measure.py" --days 14 --project voltera --out /tmp/skill-metrics.md

주요 옵션:

$ARGUMENTS가 숫자면 --days로, YYYY-MM-DD 형식이면 --since로 넘긴다.

Step 2: 결과 해석

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

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

주간 회고(retrospective) 맥락이면, 이 지표를 자동화 우선순위의 정량 근거로 인용한다. 결과를 보존하려면 회사 볼트 synergyai-obsidian/<프로젝트>/reports/ 또는 retrospective/에 저장을 제안한다 (사용자 확인 후).

지표 정의

① AutoScore — 자동화 우선순위

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

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

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

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

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

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

③ 상시 지표 (Reach)

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

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

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

한계 (정직하게)

• 마찰율은 세션 단위 귀속이라, 긴 작업 세션에 잠깐 등장한 스킬도 그 세션의

마찰을 함께 떠안아 과대평가될 수 있다. 마찰율은 보조 신호로만 본다 (주 변별은 빈도·체인).

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

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

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

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

• 20줄 이하의 즉시 종료 세션은 제외한다(빈 세션 노이즈).

확장 여지

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

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