/skill-doctor로 스킬의 건전성을 진단하는 방법 — 13개 스킬 107KB를 상시 로드하던 회사의 재고 조사 기록

당사(合同会社ジョインクラス)는 Claude Code를 'AI 경영팀'으로 운영하고 있습니다. 17개의 서브 에이전트와 13개의 커스텀 스킬이 .claude/ 아래에 존재하며, launchd를 통해 하루 40회 이상의 헤드리스 실행이 이루어집니다.

스킬은 매우 편리합니다. /write-qiita를 입력하면 기사가 작성되고, /publish-kindle을 입력하면 EPUB 검사부터 KDP 등록 프롬프트까지 한 번에 진행됩니다. 그래서 스킬이 계속 늘어납니다. 문제는 줄일지 판단할 근거가 어디에도 없었다는 것입니다.

필자는 CLAUDE.md에 '컨텍스트 사용률을 10~15%로 유지한다'는 Thin Orchestrator 원칙을 작성했습니다. 하지만 13개 스킬이 매 세션 컨텍스트를 얼마나 소모하는지 실제 측정할 수 있는 수단이 없었습니다. 원칙만 있고 계측기가 없는 상태였습니다.

Claude Code 2.1.261에 추가된 /skill-doctor는 바로 이 계측기입니다. 본 기사에서는 /skill-doctor의 사용법과, 그 결과를 바탕으로 당사에서 실제로 구동하고 있는 체크 스크립트, 그리고 재고 조사를 자동화한 절차를 소개합니다.

/skill-doctor는 대화 세션 내에서 실행하는 슬래시 커맨드입니다. 기능은 간단하며, 현재 로드된 모든 스킬에 대해 다음을 목록으로 보여줍니다:

• 최근 세션에서 호출되었는지 여부 (미사용 여부)
• 해당 스킬이 컨텍스트에 포함하는 대략적인 토큰 양
• frontmatter의 결함 (description 누락/너무 길거나, name과 디렉토리 이름 불일치)

핵심은 '미사용' 여부와 '비용(Cost)'을 같은 표에서 볼 수 있다는 점입니다. 사용하지 않는데도 무거운 스킬이 즉시 눈에 띕니다.

/skill-doctor는 2.1.261 이후 버전이 아니면 존재하지 않습니다. 당사에게 이것은 큰 함정이었습니다.

claude --version
# 2.1.261 미만인 경우 다음으로 업데이트
claude update

당사의 /upgrade-automation 스킬은 매주 Changelog을 읽고 신기능을 제안하지만, 어느 주에 제안된 5가지 기능이 모두 본체 업데이트를 전제로 했음에도 불구하고 '즉시 실행 가능'으로 판단했습니다. 설정 파일을 수정해도 아무 효과가 없는 상태로 2주 동안 방치되었습니다. 신규 기능을 시도하기 전에 먼저 자신의 버전이 요구 사항을 충족하는지 확인해야 합니다.

실행하면 대략 다음과 같은 표가 나옵니다 (당사 실행 결과 요약).

/skill-doctor는 대화 세션에서만 작동합니다. 당사처럼 launchd로 헤드리스 운영하는 환경에서는 '월 1회 Slack에 건전성 리포트가 전송되는' 형태로 만들고 싶습니다. 그래서 기존의 월간 품질 체크 auto-agent-health-check.sh에 스킬 진단을 통합했습니다.

먼저, 기존 스크립트의 해당 부분입니다.

AGENT_COUNT=$(ls "$AGENTS_DIR"/*.md 2>/dev/null | wc -l | tr -d '[:space:]')
SKILL_COUNT=$(ls "$SKILLS_DIR"/*.md 2>/dev/null | wc -l | tr -d '[:space:]')

에이전트는 .claude/agents/foo.md처럼 평면 구조이지만, 스킬은 .claude/skills/foo/SKILL.md와 같이 디렉토리 구조입니다. 이 glob 방식으로는 SKILL_COUNT가 항상 0이 됩니다. 월간 리포트에 '스킬: 0개'라고 계속 표시되었지만 아무도 알아차리지 못했습니다. 이는 Slack에 흘러가는 숫자를 사람이 읽지 않았다는 증거이기도 합니다.

/skill-doctor

가(が) 13개의 스킬을 나열해 준 덕분에, 자체 보고서의 '0' 값과의 차이에 처음으로 깨달았습니다. 공식 도구의 출력과 자체 측정값을 비교하는 것은 이러한 침묵 버그를 찾아내는 데 효과적입니다.

수정된 스크립트의 주요 부분입니다. common.sh

(로그, Slack 알림, .env)

읽기 공통 헬퍼)를 source 하는 당사의 표준 형식에 맞추었습니다.

#!/bin/bash
# .company/scripts/auto-skill-health.sh
# 월 1회: 스킬의 크기, frontmatter, 최종 사용일을 진단하여 Slack 알림
...

notify_slack와 log_info는 common.sh 측의 함수입니다. SLACK_WEBHOOK_URL이 설정되어 있지 않으면 알림을 건너뛰고 로그만 남기므로, 먼저 로컬에서 bash auto-skill-health.sh를 실행하여 표준 출력을 살펴보는 것부터 시작할 수 있습니다.

위 스크립트는 '최종 사용일'을 skill-usage.tsv에서 읽어옵니다. 이것은 Claude Code 측의 hook으로 작성합니다. .claude/settings.json에 다음을 추가해 주세요.

{
"hooks": {
"PostToolUse": [
...

Skill 도구가 호출될 때마다 'UNIX 초 스킬 이름'이 한 줄씩 추가됩니다. 이렇게 하면 /skill-doctor가 보여주는 '최종 사용' 정보를 헤드리스 실행을 포함한 모든 세션을 가로질러 유지할 수 있게 됩니다.

함정: hook은 settings.json을 편집한 후, 새로운 세션에서 유효해집니다. 기존 세션에서 /write-qiita를 실행해도 기록되지 않아 'hook이 작동하지 않는다'며 30분 동안 고민했습니다.

/skill-doctor와 자체 스크립트의 결과를 비교하여, 당사는 다음 3가지 분류로 처리했습니다.

6개 페이즈를 하나의 파일에 작성했기 때문에, SKILL.md 본체는 '언제 사용할지'와 '페이즈 목록'만 담은 약 2KB로 줄이고, 각 페이즈의 상세 내용은 references/phase-N.md로 분리했습니다. Claude Code의 스킬은 본체가 상시 로드되고 참조 파일은 필요할 때 읽히기 때문에, 이 것만으로도 상시 비용이 약 7,400 토큰에서 약 700 토큰으로 떨어집니다.

.claude/skills/validate-hypothesis/
├── SKILL.md # 2KB: 시작 조건 + 페이즈 목차
└── references/
...

31일 동안 사용하지 않았지만, Kindle 출판은 월 1회 있을까 말까한 빈도이고, 사용할 때는 3개가 연쇄적으로 작동합니다. 삭제하면 다음 출판 시 재작성 비용이 발생하므로 남겨두었습니다. 다만 description을 짧게 줄여 전체 약 5,800 토큰을 약 4,000 토큰으로 압축했습니다.

판단 기준: '사용 빈도가 낮은' 것만으로는 삭제하지 않습니다. '다음에 사용할 때의 재구축 비용'과 '매 세션 로드 비용 × 세션 수'를 비교합니다. 당사는 하루에 40세션을 돌리기 때문에, 1,000 토큰을 줄이는 것이 월 120만 토큰의 차이가 됩니다.

이번에는 '0'이었습니다. 13개 스킬 모두가 지난 90일 이내에 사용 기록이 있었고, 중복 기능도 없었습니다. '삭제할 것이 없다'는 결론 역시 계측기가 있어야 비로소 자신 있게 말할 수 있습니다.

변경 후 효과가 나타나는지 확인할 절차입니다.

# 1. 스킬 본체의 총 크기가 줄었는지
wc -c .claude/skills/*/SKILL.md | tail -1
# 변경 전: 107427 total → 변경 후: 약 72000 total을 목표
...

세 번째가 중요합니다. 자체 스크립트는 바이트 수로부터의 개산이므로, /skill-doctor와 /context의 실측값과 월 1회는 비교해 주세요. 차이가 크다면 개산 계수(위 스크립트에서는 bytes / 3)를 조정합니다.

월 1회, 월초 아침에 실행합니다. 당사는 이미 17개의 launchd job이 있어 신규 추가는 신중하지만, 이것은 기존의 auto-agent-health-check.sh에서 호출하는 형태로 작업 수를 늘리지 않고 통합했습니다.

# auto-agent-health-check.sh 끝에 1줄 추가
bash "$SCRIPT_DIR/auto-skill-health.sh" || true

|| true

을 붙이는 이유는, 스킬 진단이 실패하더라도 부모(parent) 월간 리포트를 중단시키지 않기 위함입니다. 진단 관련 기능은 '본체에 방해를 주지 않는 것'이 원칙입니다.

• /skill-doctor는 미사용 스킬과 그 컨텍스트 비용을 같은 표에서 보여주는 계측기입니다. 2.1.261 버전 이후부터 필요합니다 - 공식 출력과 자체 측정을 비교하면, '스킬 수 0'과 같은 침묵 버그를 발견할 수 있습니다.
• 결과는 '분할 / 남기기 / 삭제'의 3가지 분류로 처리합니다. 빈도뿐 아니라 재구축 비용과 로드 비용 × 세션 수로 판단합니다.
• 사용 로그는 PostToolUse hook에서 Skill 도구를 포착하면, 헤드리스 실행을 포함하여 얻을 수 있습니다.

스킬은 '만드는 것'보다 '육성하고 가지치기 하는 것(刈る)'이 더 어렵습니다. 원칙을 작성하는 것뿐 아니라, 그 원칙을 측정할 수 있는 수단을 갖는 것이 중요합니다. /skill-doctor는 그 첫걸음으로서 충분한 도구였습니다.

본 기사에서 다룬 스킬 설계(SKILL.md 본체와 references/의 분리, description 작성법, frontmatter 규약)는 당사의 『Claude Skills 완벽 가이드』에서 체계적으로 설명하고 있습니다. 스킬을 '일단 만들어 보는' 단계에서 '조직에서 운영하는' 단계로 나아가고 싶은 분들을 위해 작성했습니다.

hook이나 launchd를 이용한 무인 운영의 전체적인 모습은 『Claude Code 자동화 바이블』, 컨텍스트 예산 설계는 『CLAUDE.md 설계 패턴』에서 다루고 있습니다. 함께 확인해 주세요.