hf CLI 스킬은 무엇을 줄이나: 도움말 탐색과 토큰 비용의 손익

에이전트가 같은 작업을 끝내는 데 10번 대신 6번만 움직였다면 더 효율적이 된 것일까? 사용법을 찾는 네 번의 과정이 사라졌다면 그럴 수 있다. 하지만 결과를 확인하는 네 번을 건너뛰었다면 실행이 짧아졌다고 해서 개선됐다고 볼 수 없다. 스킬을 평가하려면 턴 수보다 어떤 단계가 줄어들었는지 먼저 살펴봐야 한다.

hf CLI 스킬 사례를 바탕으로 탐색·실행·검증 단계를 구분하고, 짧아진 대화가 토큰 비용 절감으로도 이어지는 조건을 계산해 보자. 아래 작업 흐름과 토큰 수는 설명을 위한 가정이며, 실제 에이전트를 실행해 얻은 측정값은 아니다.

Hugging Face 공식 발표 (새 창)는 Inference Providers에서 두 모델로 Hub 과제 28개를 비교했다. 성공률은 스킬 유무와 관계없이 99~100%였지만, 과제당 턴 수는 DeepSeek-V4.1-Flash에서 10.1→6.5, Kimi-K3에서 8.9→5.6으로 줄었다.

상대 감소율을 계산하면 각각 약 35.6%, 37.1%다. 이는 평균 턴 수의 감소율일 뿐, 비용이나 완료 시간의 감소율이 아니다. 발표에 따르면 스킬이 없을 때도 모델은 hf --help로 사용법을 찾아냈고, 스킬을 제공하자 도움말 호출이 거의 사라졌다. 아래 막대는 이 탐색 절약을 읽는 출발점이다.

이미 거의 다 성공하는 과제에서는 성공률만으로 스킬의 추가 효과를 구분하기 어렵다. 이럴 때는 같은 결과에 도달하면서 불필요한 탐색을 얼마나 줄이는지도 함께 볼 수 있다. 다만 이 결과를 다른 도구·모델·업무에서도 같은 감소율이 나온다는 근거로 확대 해석하지는 않는다.

가상의 공개 파일 다운로드 작업을 생각해 보자. 에이전트는 먼저 명령 목록을 읽고, 다운로드 하위 명령의 옵션을 확인한 뒤, 저장소와 파일명을 지정해 실행한다. 마지막으로 지정한 경로에 원하는 파일이 생겼는지 확인한다. 스킬이 명령과 옵션을 정확히 알려 주면 앞선 탐색 단계는 줄일 수 있다.

하지만 “다운로드 명령이 종료됐다”와 “요청한 파일이 맞게 저장됐다”는 별개의 조건이다. 다른 리비전이나 다른 경로의 파일을 받았을 수도 있기 때문이다. 최종 상태를 확인하는 단계가 남아 있어야 같은 품질의 결과를 놓고 비교할 수 있다. 스킬 유무에 따라 성공의 정의가 달라지면 턴 수만 비교해도 결론이 왜곡된다.

실행 기록에서는 도움말 조회, 본 작업, 실패 후 재시도, 결과 확인을 나눠 본다. 예를 들어 여덟 단계 중 도움말을 찾는 세 단계가 줄어 다섯 단계가 된 경우와, 오류 뒤 재시도를 포기해 다섯 단계로 끝난 경우는 숫자는 같아도 내용이 다르다. 짧은 실행을 보상할 때 무엇을 끝냈는지 함께 검사해야 하는 이유다.

토큰만 떼어 본 단순 가정으로, 스킬 없이 도움말 결과를 세 번 읽고 매번 새로 1,000토큰이 추가된다고 해 보자. 스킬 분량이 1,800토큰이고 도움말 세 번을 모두 대신한다면, 새로 들어오는 안내문은 3,000토큰에서 1,800토큰으로 줄어든다. 차이는 1,200토큰이다.

반대로 300토큰짜리 도움말 한 번만 필요했던 작업에 같은 스킬을 읽히면 안내문은 오히려 1,500토큰 늘어난다. 두 예제 모두 실제 총 과금 토큰이 아니라 새로 추가되는 안내문 길이를 비교한 것이다. 대화 이력이 반복 입력되는 방식, 캐시 적용 여부, 모델 출력 길이와 추론 비용까지 포함하면 실제 비용은 달라진다.

완료 시간 역시 턴 수와 일대일로 비례하지 않는다. 탐색 한 번이 느린 외부 응답을 기다려야 했다면 이를 없앤 효과가 클 수 있지만, 본 작업의 파일 전송이 대부분의 시간을 차지한다면 탐색을 줄여도 총시간 변화는 작을 수 있다. 따라서 호출 수·토큰·경과 시간을 같은 지표처럼 섞어 쓰지 않는다.

공식 CLI 에이전트 안내 (새 창)에 따르면 스킬은 로컬에 설치된 CLI 버전을 기준으로 생성된다. hf skills add는 현재 프로젝트에, --global 옵션은 전역에 스킬을 설치한다. hf update는 설치된 전역 스킬을 함께 갱신하며, hf skills update -g로 스킬만 따로 갱신할 수도 있다. 따라서 프로젝트에 둔 스킬과 전역 스킬의 관리 범위를 구분해야 한다.

가상으로 CLI는 새 버전인데 스킬은 이미 없어진 옵션을 안내한다고 해 보자. 에이전트가 도움말을 따로 읽지 않게 된 만큼, 잘못된 설명을 그대로 바로 실행할 수 있다. 이 경우는 스킬의 분량을 늘릴 문제가 아니라 문서와 실행 도구 사이의 계약을 맞출 문제다. 현재 명령 버전과 실제로 읽힌 스킬 위치를 함께 기록하면 원인을 추적하기 쉽다.

반대로 권한이 없거나 원격 서비스가 실패하는 상황은 올바른 명령을 아는 것만으로는 해결되지 않는다. 문법 오류와 인증·환경 오류를 섞어서 집계하면 스킬이 해결할 수 있는 문제를 과대평가하거나 과소평가하게 된다. 실패 원인별로 어떤 안내가 필요한지 확인한다.

도입 시험에서는 같은 모델, 도구 버전, 시작 파일 상태, 과제를 고정해 두고 스킬 유무를 비교할 수 있다. 앞선 실행에서 파일을 이미 받아 둔 상태라면 다음 실행은 캐시 덕분에 빨라질 수 있으므로, 시작 상태도 결과 해석에 포함한다. 외부 작업의 결과를 재사용했다면 이를 스킬 효과로 계산하지 않는다.

가상 평가표에는 과제 ID, 최종 상태 검사, 도움말 횟수, 재시도, 입력·출력 토큰, 경과 시간을 함께 남긴다. 완료한 과제만 비교하면 실패한 실행에 든 비용이 누락될 수 있으므로 실패와 중단도 별도 결과로 기록한다. 이 절차는 글쓴이의 제안이며 실험으로 효과를 입증한 방법은 아니다.

스킬의 목적은 같은 사용법을 매번 다시 찾는 수고를 줄이는 데 있다. 실제로 줄어든 것이 탐색인지, 아니면 꼭 확인해야 할 결과 검증인지 먼저 구분하고 그 뒤에 비용을 따져 본다. 스킬은 현재 버전에 맞는 짧은 안내가 필요한 작업에서 의미를 가지며, 긴 문서가 있다는 사실만으로 에이전트가 더 잘 일한다고 판단하지 않는다.