skill-stocktake — 스킬 품질 감사
설치된 스킬을 전체적으로, 하나의 컨텍스트에서 평가하고 각 스킬에 대해
Keep / Improve / Update / Retire / Merge 평결을 내립니다. 이 스킬은 개선 작업을 직접
수행하지 않으며, 평결이 내려지면 skill-creator(개선 엔진)에게 핸드오프합니다.
이것이 핵심 경계입니다: stocktake은 품질 게이트이고, skill-creator는 수정자입니다.
설계 참고: 이전 버전은 스캔 스크립트를 셸 명령으로 실행하고 평가를 ~20개 스킬씩 서브에이전트 배치로 나누었습니다. 1M 컨텍스트에서는 이것이 불필요할 뿐만 아니라 해롭습니다. 배칭은 각 서브에이전트가 다른 배치의 스킬을 보지 못하게 하여 스킬 간 중복을 놓칩니다. 이제 Glob으로 열거하고 모든 스킬을 하나의 컨텍스트로 읽습니다. 중복 감지는 이 단일 컨텍스트 보기에 의존합니다.
모드 ($ARGUMENTS)
| 인수 | 동작 |
|---|---|
없음 / full | 모든 스킬을 읽고 평가 (기본값) |
changed | SKILL.md의 수정 시간이 results.json의 evaluated_at보다 최신인 스킬만 재평가하고, 나머지는 ledger의 이전 평결을 유지 |
changed 모드는 인라인으로 변경 감지합니다 (스크립트 불필요):
find ~/.claude/skills -name SKILL.md -newermt "$(jq -r .evaluated_at ~/.claude/skills/skill-stocktake/results.json)"
1단계 — 인벤토리
Glob으로 스킬 정의 파일 열거 (스크립트 불필요):
~/.claude/skills/*/SKILL.md~/.claude/skills/learned/*.md- 현재 작업 디렉토리에
.claude/skills/가 있으면{cwd}/.claude/skills/*/SKILL.md(프로젝트 스킬)
Glob이
SKILL.md/learned/*.md만 대상으로 하므로,.venv나.pytest_cache아래의 의존성 마크다운은 구조적으로 제외됩니다 (정리 불필요). 이전find -name "*.md"가 가져왔던 노이즈는 발생할 수 없습니다.
사용 횟수: ~/.claude/metrics/skill-usage.jsonl을 인라인으로 읽고 (PostToolUse 훅
log-skill-usage.sh가 이 파일에 추가합니다 — 독립적인 측정 계층), 7/30/90일 동안
스킬별 이벤트를 계산합니다. 각 줄은 JSON {ts,event,skill,path,project}입니다;
invoke와 read 이벤트를 모두 계산합니다. 손으로 세는 대신 일회성 python3/jq
원라이너로 집계하세요 — 로그는 시간이 지남에 따라 커지며 손으로 세면 호출마다 한 번의
툴 턴이 낭비됩니다.
- 로그가 없거나 첫 번째 이벤트가 90일보다 최신이면 사용량을
—(측정되지 않음)으로 표시합니다. 절대 0으로 표시하지 마세요 — 측정되지 않음과 사용되지 않음은 다른 사실입니다.
검사 결과를 먼저 명시하세요: 스캔한 경로, 발견된 스킬 수, 사용량 측정 가능 여부.
2단계 — 평가 (완전 인라인, 전체적)
모든 대상 스킬의 본문을 읽고 전체 집합을 보면서 하나씩 평가합니다. 체크리스트:
- 다른 스킬과의 내용 중복 (문서화된 오케스트레이터/서브 스킬 분할은 중복이 아님 — 예: paper-ecosystem → 검토자들, citation-sync → release-doi/wikidata. 의도적 계층화와 진정한 중복을 구분하세요)
- MEMORY.md / CLAUDE.md / rules와의 중복
- 기술 참조의 최신성 (CLI 플래그 / API / 도구 이름이 낡아 보이면 WebSearch로 확인)
- 사용 빈도 (측정되지 않은 경우 신호로 무시)
평가는 숫자 기준표가 아닌 전체적 판단입니다. 안내 차원: 실행 가능성(실행할 수 있는 구체적인 예제/단계), 범위 적합성(이름, 트리거, 본문이 정렬됨 — 너무 넓거나 좁지 않음), 고유성(MEMORY/다른 스킬로 대체 불가능), 최신성(참조가 현재 환경에서 작동).
집계 비용 (스킬별이 아닌 집합 수준): 스킬을 보유하는 것은 개별 스킬이 괜찮더라도 공짜가 아닙니다. 스킬의 이점은 깨지기 쉽습니다 — 크고 정리되지 않은 라이브러리는 에이전트가 올바른 스킬을 선택하는 능력을 저하시키고 동작을 스킬 없는 기준선으로 되돌립니다. 따라서 Keep 기준은 라이브러리 크기에 따라 상승합니다: 집합이 클 때, 간신히 적당한 스킬(드문 사용, 낮은 고유성, 다른 스킬과의 높은 인접성)은 스킬 자체에 결함이 없더라도 집합 희석 근거만으로 Retire/Merge 후보가 됩니다. 이것은 판단 입력일 뿐이며 쿼터가 아닙니다; 숫자를 맞추기 위해 은퇴시키지 마세요.
| 평결 | 의미 |
|---|---|
| Keep | 유용하고, 최신이며, 고유한 가치 |
| Improve | 보존할 가치가 있지만 특정 개선 필요 |
| Update | 참조하는 기술이 구식 (WebSearch로 확인) |
| Retire | 낮은 품질, 노후화 또는 비용 비대칭 |
| Merge into [X] | 다른 스킬과 상당한 중복; 대상 스킬 이름 명시 |
사용량 제로 규칙: 사용 로그의 첫 번째 이벤트가 최소 90일 이전이고 스킬의
use_90d == 0이면 반드시 Retire 후보로 표시해야 합니다 (최종 결정은 사용자의 몫).
로그가 90일보다 젊은 동안 이 규칙은 적용되지 않으며, 평결은 전적으로 전체적 판단에
따릅니다.
평가는 출처에 관계없이 동일: ECC / 자체 작성 / 자동 추출 여부에 따라 분기하지 않습니다. 모든 스킬에 동일한 체크리스트가 적용됩니다.
3단계 — 요약
표로 렌더링: 스킬 | 7일 | 90일 | 평결 | 사유.
4단계 — 정리
- Retire / Merge: 파일별로 (1) 발견된 특정 결함, (2) 동일한 요구를 대체하는 것 (Retire: 기존 스킬/규칙; Merge: 대상과 통합할 내용), (3) 제거 영향 (의존 스킬, MEMORY 참조)을 제시합니다. 사용자가 확인한 후에만 실행합니다.
- Improve / Update: 핸드오프를 제안합니다 — "
<스킬>을(를) skill-creator에 넘겨 개선할까요?" — 승인 시skill-creator를 대상 스킬과 함께 호출합니다. Stocktake은 절대 개선 작업을 직접 수행하지 않습니다. - Ledger 업데이트:
results.json읽기 → 이번 실행의 평결 병합 → 다시 쓰기 (evaluated_at=date -u +%Y-%m-%dT%H:%M:%SZ의 실제 UTC).changed모드에서는 재평가하지 않은 스킬의 이전 평결을 유지합니다. - MEMORY.md가 100줄을 초과하면 압축을 제안합니다.
사유 품질 (필수)
모든 reason은 자체 완결적이어야 합니다 — 그 자체로 결정을 내릴 수 있어야 합니다.
"변경 없음"만 있는 경우는 금지됩니다; 항상 증거를 다시 명시하세요.
- Retire: 결함 + 대체물을 명시. 나쁨:
"대체됨"/ 좋음:"disable-model-invocation: true가 이미 설정됨; continuous-learning-v2가 동일한 패턴과 신뢰도 점수를 포함. 고유한 내용이 남아 있지 않음." - Merge: 대상 + 통합할 내용을 명시. 나쁨:
"X와 중복됨"/ 좋음:"42줄 얇은 내용; chatlog-to-article의 4단계가 이미 이 워크플로를 포함. 'article angle' 팁을 참고로 추가." - Improve: 어떤 섹션, 어떤 변경 (관련 시 대상 크기). 나쁨:
"너무 김"/ 좋음:"276줄; 'Framework Comparison'(L80–140)이 ai-era-architecture-principles와 중복. 삭제하여 ~150줄로 줄임." - Keep (
changed모드에서 수정 시간만 변경): 원래 근거를 다시 명시. 나쁨:"변경 없음"/ 좋음:"내용 변경 없음. rules/python/에서 명시적으로 가져온 고유 Python 참조; 중복 없음."
results.json (간결한 원장)
{
"evaluated_at": "2026-06-24T11:09:00Z",
"skills": {
"<skill-name>": {
"path": "~/.claude/skills/<name>/SKILL.md",
"verdict": "Keep",
"reason": "...",
"mtime": "2026-01-15T08:30:00Z"
}
}
}
평결 기록과 마지막 감사 타임스탬프만을 위한 원장입니다. 스크립트 없이 읽기/쓰기로 인라인 업데이트합니다. 전역 스킬만 포함합니다 (프로젝트 스킬은 cwd에서 새로 읽으며 여기에 캐시되지 않습니다).
관련 항목
skill-creator— 개선 엔진; Improve/Update 작업을 위임합니다.config-gc— 스킬 존재와 ~/.claude 전체 (훅/권한/MCP/캐시)에 대한 GC; stocktake은 스킬 품질을 판단합니다.harness-sync— 이 스킬을 공개 저장소와 동기화하는 데 사용합니다.- 사용량 측정:
~/.claude/hooks/log-skill-usage.sh→~/.claude/metrics/skill-usage.jsonl(stocktake과 독립적인 측정 계층).