---
name: skill-metrics
description: >
  Claude Code 세션 로그를 집계해 "어떤 스킬·워크플로우를 얼마나 자주 쓰는지"와
  "무엇을 먼저 자동화하면 좋은지"를 정량 지표로 보여주는 스킬.
  다음 표현이 나오면 반드시 이 스킬을 사용할 것:
  "스킬 사용 지표", "스킬 사용 현황", "어떤 스킬 자주 쓰는지", "스킬 메트릭",
  "skill-metrics", "자동화 우선순위", "자동화할 거 찾아줘", "워크플로우 지표",
  "스킬 도달률", "반복 워크플로우 분석".
  주간 회고에서 자동화 후보를 정량 근거로 뽑을 때, 또는 새 스킬이 실제로 채택됐는지
  추적할 때 사용한다.
allowed-tools: Bash, Write
argument-hint: (선택) 기간 — "14"(최근 N일) 또는 "2026-06-05"(시작일). 생략 시 최근 14일
---

# skill-metrics

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

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

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

---

## 실행 절차

### Step 1: 측정 스크립트 실행

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

```bash
# 기본: 최근 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 myproject --out /tmp/skill-metrics.md
```

주요 옵션:

| 옵션 | 의미 | 기본 |
|---|---|---|
| `--days N` | 오늘 기준 최근 N일 | 14 |
| `--since YYYY-MM-DD` | 시작일 (지정 시 `--days` 무시) | — |
| `--until YYYY-MM-DD` | 종료일 | 오늘 |
| `--project <부분문자열>` | 프로젝트 경로 필터 (예: `myproject`) | 전체 |
| `--top N` | 랭킹 표 상위 N개 | 15 |
| `--out <경로>` | 마크다운 저장 (미지정 시 stdout) | — |

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

### Step 2: 결과 해석

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

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

주간 회고(`retrospective`) 맥락이면, 이 지표를 자동화 우선순위의 정량 근거로 인용한다.
결과를 보존하려면 회사 문서의 `<프로젝트>/reports/`(예: `~/workspace/<프로젝트>/docs/engineering/reports/`) 또는
`~/workspace/<회사문서>/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`)에 붙이면 주간 자동 집계.
- 향후 작업별 미활용률(②)을 다시 넣고 싶으면, 스킬↔수동 매핑을 코드 밖
  선언 파일로 빼는 방식을 검토한다(수동 유지보수 최소화).