에이전트가 볼 수 없었던 스킬들

저는 스킬 84개를 설치해 두고 84개가 모두 동작한다고 믿었습니다. 그중 다섯 개는 동작하지 않았습니다. swiftui, testing-philosophy, typeset, web-performance, update-shortcuts-guide는 디스크의 파일에 아무 문제 없는 description을 담고 있었는데도, description이 빠진 이름만으로 모델에 도달하고 있었습니다. description 자체가 라우팅 신호이므로, description이 없는 스킬로는 라우팅할 수 없습니다. 이 다섯 개는 애초에 자동으로 활성화될 수 없었고, 그 사실을 알려 주는 것은 어디에도 없었습니다. 오류도, 경고도, 로그 한 줄도 없었습니다. 저는 우연히 이것을 발견했고, 원인을 증명할 수 있었던 유일한 이유는 수정하자마자 눈앞에서 증상이 뒤집혔기 때문입니다. {.answer-block}

TL;DR

• 스킬 description은 매 턴의 컨텍스트에 로드되며 고정된 문자 예산을 함께 씁니다. 이를 넘기면 description은 조용히 버려집니다.¹²
• 설치된 스킬은 84개였고 그중 82개가 description을 갖고 있었으며, 합계는 21,848자였습니다. 다섯 개는 이름만 도착하고 description은 사라진 상태였습니다. 디스크상에서 이 다섯 개는 각각 206자에서 336자였습니다.
• 어떤 다섯 개가 버려졌는지 설명해 주는 파일 속성은 없었습니다. description 길이, 파일 크기, YAML 형식, name과 디렉터리 이름의 불일치, 수정 시각 모두 버려진 쪽과 남은 쪽에서 겹쳤습니다.
• 저는 description 74개를 다시 써서 합계를 9,885자로 줄였습니다. 다섯 개 모두가 세션 도중에, 같은 대화 안에서 description이 온전한 채로 다시 나타났습니다. 가설, 개입, 확인입니다.
• 정확한 예산은 문서화되어 있지 않고 현재도 논쟁 중입니다. Anthropic에는 이 비율이 고정된 200K 기준선에 대해 계산되며 1M 컨텍스트 확장을 무시한다는 보고가 열린 이슈로 올라와 있습니다.³⁴
• 예산에 맞게 만들어 준 재작성 규칙은 이것입니다. description의 유일한 임무는 언제 호출해야 하는가에 답하는 것입니다. 절차와 철학과 파일 경로는 본문에 속하며, 본문은 호출될 때만 로드됩니다.

오류 메시지가 없는 장애

대부분의 하네스 버그는 스스로 존재를 알립니다. 훅이 0이 아닌 값으로 종료하고, MCP 서버가 시작을 거부하고, 도구 호출이 스택 트레이스를 돌려줍니다. description 예산은 그중 어느 것도 하지 않습니다. 디스크에 있는 것보다 짧은 목록을 모델에 조용히 내밀 뿐이고, 그 아래로 이어지는 증상은 전부 배관 문제가 아니라 모델 문제처럼 보입니다.

제가 알아차린 계기는 파일 시스템이 아니라 제 컨텍스트 윈도를 읽은 것이었습니다. 스킬 목록을 훑어보니 다섯 항목만 이름이 있고 그 뒤에 아무것도 없었습니다. 나머지 항목은 모두 이름과 한 문장을 갖고 있었습니다. 그래서 파일을 열어 확인했습니다.

swiftui                    HAS  322 chars on disk -> DROPPED in context
testing-philosophy         HAS  291 chars on disk -> DROPPED in context
typeset                    HAS  248 chars on disk -> DROPPED in context
web-performance            HAS  206 chars on disk -> DROPPED in context
update-shortcuts-guide     HAS  336 chars on disk -> DROPPED in context

그 결과는 스킬이 느리거나 틀린 것보다 나쁩니다. 에이전트는 description을 읽고 스킬을 호출할지 결정합니다. description을 걷어내면 라우팅이 나빠지는 것이 아니라 라우팅이 사라집니다. 스킬은 설치되어 있고 유효하지만 도달할 수 없습니다. swiftui는 제 iOS 26 패턴 스킬이므로, 제가 돌린 모든 Swift 세션은 그것 없이 날고 있었던 셈입니다.

Anthropic에는 같은 장애를 기술한 열린 이슈들이 있으며, 그중 하나의 제목은 “Skill description budget silently truncates routing information, causing skill routing failures”입니다.² 즉 이 동작은 로컬 설정 실수가 아니라 알려진 버그입니다. 그 사실을 알게 된 것은 유용했지만, 제 스킬 중 어느 것이 영향을 받았는지 찾는 데는 도움이 되지 않았습니다.

쉬운 답부터 배제하기

솔깃했던 선택지는 메커니즘을 추측하고 곧바로 고치는 것이었습니다. 저는 먼저 그 추측들을 반증하려고 했습니다. “스킬 다섯 개가 망가졌다”와 “이런 이유로 스킬 다섯 개가 망가졌다”는 전혀 다른 주장이기 때문입니다.

파일 수준의 어떤 속성이 스킬을 삭제 대상으로 표시한다면, 버려진 집단은 측정 가능한 어딘가에서 남은 집단과 달라야 합니다. 그래서 둘을 비교했습니다.

둘을 갈라놓는 것은 아무것도 없었습니다. 버려진 description이 가장 길지도 않았고, 파일이 유난히 크지도 않았으며, YAML 스타일은 양쪽 집단에 섞여 있었고, 수정 날짜도 같은 범위에 걸쳐 있었습니다. 알파벳 순서라는 설명도 빗나갔습니다. swiftui 뒤에 정렬되는 스킬들은 description을 그대로 유지했기 때문입니다.

그 시점에서 정직한 입장은 재현되는 증상은 있지만 메커니즘은 없다는 것이었습니다. 그래서 그렇게 적어 두고, 이론이 아니라 테스트를 찾아 나섰습니다.

테스트

중요한 것이 전체 예산이라면, 어떤 파일을 줄이든 상관없이 총량을 줄이면 버려진 description이 되돌아와야 합니다. 이 예측은 반증 가능하고 비용도 적습니다.

저는 description 74개를 다시 써서 총량을 21,848자에서 9,885자로 낮췄습니다. 그때까지 보이지 않던 다섯 개의 스킬이 같은 세션 안에서, 재시작도 없이 description을 달고 돌아왔습니다.

실험은 이것이 전부입니다. 예측 하나, 개입 하나, 확인 하나. 삭제는 개별 파일의 어떤 속성이 아니라 총합 크기의 함수이며, 그렇기 때문에 파일 단위의 어떤 속성으로도 두 집단을 구별할 수 없었던 것입니다.

흔적을 남기지 않는 버그도 반사실은 남깁니다. 장애를 들여다봐서 원인을 찾을 수 없다면, 변수 하나를 바꾸고 장애가 그것을 따라가는지 보십시오.

제가 무엇을 입증하지 못했는지도 정확히 밝히고 싶습니다. 저는 정확한 예산을 알지 못하고, 출처를 댈 수 없는 숫자를 공개할 생각도 없습니다. 공식 문서는 이 한계를 언급하지 않습니다.⁵ 커뮤니티 측정은 실용적인 상한을 스킬 메타데이터 총량 기준 15,500자에서 16,000자 부근으로 잡고, XML 태그와 스킬 이름과 location 필드에서 오는 항목당 약 109자의 오버헤드를 지적합니다. 순수한 description 문자 수로는 그중 어느 것도 잡히지 않습니다.⁶ 스킬이 84개라면 이 오버헤드만으로 약 9,156자가 됩니다. 한편 Anthropic 기여자들은 예산 비율이 고정된 200K 기준선에 대해 계산되고 1M 컨텍스트 확장을 무시한다고 보고합니다. 같은 머신의 두 세션이 서로 다른 예산을 받을 수 있다는 뜻입니다.³⁴

이 발견을 처음 정리했을 때 저는 제 환경이 “예산을 119% 초과했다”고 썼습니다. 검증하지 않은 가정(1M 윈도의 1%)에 실제 측정값을 곱해서, 아래에 아무것도 받치지 않은 자신만만한 숫자를 만들어 냈던 것입니다. 관측된 사실은 살아남습니다. 21,848자에서는 description 다섯 개가 떨어졌고 9,885자에서는 하나도 떨어지지 않았습니다. 백분율은 살아남지 못했고, 애초에 쓰이지 말았어야 했습니다.

description의 유일한 임무는 라우팅이다

12,000자를 잘라낸다고 하면 파괴적으로 들립니다. 그렇지 않았습니다. 그 description들에 들어 있던 내용의 대부분은 애초에 라우팅 일을 하고 있지 않았기 때문입니다.

제 jiro 스킬이 내걸고 있던 것은 686자짜리 다음 문장입니다.

코드 품질과 직업적 자부심을 위한 쇼쿠닌 장인 정신 철학. 기능 구현, 코드 리팩터링, 테스트 작성, 작업 리뷰, 또는 FastAPI/Python, Swift/SwiftUI, HTMX 프런트엔드, 인프라 코드 전반에서 사소하지 않은 변경을 다룰 때 활성화됩니다. 세 가지 핵심 철학을 담고 있습니다. 쇼쿠닌(보이지 않는 세부에서의 탁월함), 오모테나시(기예를 통한 봉사), Rick Rubin(창조성의 매개와 증류). 중심 판단 관문은 Evidence Gate(품질에 대한 느낌이 아니라 품질의 증거를 내놓을 것). 사용 시점: 기능 구축, 리팩터링, 테스트, 코드 리뷰, 버그 수정, 또는 완료를 보고하기 전에 품질 증거가 필요한 모든 작업.

그중 대략 500자는 이 스킬에 무엇이 들어 있는지를 설명합니다. 어느 것도 이 스킬을 열어야 할지 판단하는 데 도움이 되지 않습니다. 이를 대체한 문장은 126자입니다.

코드 품질을 위한 장인 정신과 증거 기준. 구현, 리팩터링, 테스트, 리뷰, 버그 수정 시 사용.

같은 트리거 단어, 같은 라우팅 동작, 5분의 1의 비용입니다. 철학이 사라진 것은 아닙니다. 그것은 본문에 살고 있고, 본문은 스킬이 실제로 실행될 때만 로드됩니다. 매 턴 그 값을 치러도 얻는 것은 없었습니다.

같은 패턴이 전체 집합에서 되풀이됐습니다. update-*-guide 스킬 아홉 개는 소스를 스캔하고 사본을 동기화하고 번역을 돌린다는 거의 똑같은 상용구를 3,024자나 안고 있었습니다. 각각 약 115자로 접어도 여전히 올바르게 라우팅됩니다. 이들을 구별하는 것은 함께 쓰는 파이프라인이 아니라 어떤 가이드를 갱신하는가이기 때문입니다.

일을 해낸 규칙은 세 가지입니다.

1. 트리거는 남기고 설명은 잘라낸다. 이름, 슬래시 명령, 사용자가 실제로 입력할 단어는 남깁니다. 내부 절차에 대한 설명은 내보냅니다.
2. 파일 경로는 본문에 속한다. 경로는 무언가를 언제 호출할지 모델이 판단하는 데 도움이 되지 않습니다.
3. 공유 상용구는 순수한 오버헤드다. 아홉 개의 스킬이 같은 문장을 말한다면, 그 문장은 어느 것도 구별해 주지 않습니다.

두 번째 세금: 호출되지 않고도 작용하는 description

다듬는 과정에서 더 미묘한 비용이 드러났습니다. 제 description 가운데 열한 개, 합계 3,808자가 명령형 언어를 담고 있었습니다. ALWAYS, NEVER, MUST, PROACTIVELY, BEFORE. distribute는 NEVER라고 말했고, no-shortcuts는 ALWAYS라고 말했으며, git-custody는 BEFORE라고 말했습니다.

이 단어들은 해당 스킬이 실행되든 말든 매 턴 컨텍스트에 앉아 있습니다. 지시문으로 쓰였기 때문에 지시문으로 읽힙니다. 그리고 모델에게는 description을 비활성 카탈로그 문구로 다루면서 똑같이 표현된 시스템 지시는 구속력 있는 것으로 다루는 믿을 만한 방법이 없습니다.

최근 연구가 이 효과에 이름을 붙였습니다. 두 개의 사무 자동화 벤치마크와 세 개의 하네스 스택에서 약 6,000회 실행을 측정한 “The Regression Tax”는 skill description osmosis를 규정합니다. 한 번도 호출되지 않았는데도 컨텍스트에 존재한다는 사실만으로 스킬이 에이전트의 행동을 바꾸는 현상입니다.¹ 핵심 발견은 가장 좋은 스킬이 더 많이 얻어서가 아니라 덜 퇴행해서 이긴다는 것, 그리고 스킬들이 절차 안내에는 과잉 투자하면서 그라운딩과 검증에는 과소 투자한다는 것입니다.

실전 증거는 이론보다 먼저 도착했습니다. Anthropic은 v2.1.215에서 번들된 /verify와 /code-review 스킬의 자동 활성화를 철회하고 명시적 호출만 가능하게 바꿨습니다.⁷ 두 릴리스 뒤에는 /deep-research도 스스로 호출하기를 멈췄습니다.⁸ 둘 다 무거운 스킬이고, 요청받지 않은 실행이 벌어들이는 것보다 더 큰 비용을 치렀습니다. 벤더가 현장에서 관측한 osmosis이며, description을 다시 쓰는 대신 활성화를 제거하는 방식으로 바로잡은 사례입니다.

그러므로 과도하게 큰 description은 비용을 두 번 물립니다. 다른 스킬이 라우팅에 필요로 하는 예산을 잡아먹고, 아무도 요청하지 않은 행동상의 압력을 가합니다. 두 비용 모두 그 스킬이 아무것도 기여하지 않는 턴에 떨어집니다.

불편한 대목: 본문 역시 통제하지 못할 수 있다

“본문으로 옮겨라”는 제가 방금 드린 조언이고, 여기에는 소리 내어 말해 둘 만한 전제가 하나 딸려 있습니다. 호출 시점에 에이전트가 로드하는 절차가 실제로 에이전트의 행동을 통제한다는 전제입니다. 새로운 벤치마크 연구는 그 전제가 들리는 것만큼 강하지 않다고 시사합니다.

HANDBOOK.md가 바로 그것을 시험했습니다. 65개 과제, 20쪽에서 124쪽에 이르는 정책 문서, 모의 기업 안에서 이메일과 채팅과 캘린더와 커머스를 넘나들며 일하는 에이전트, 그리고 824개의 프로그램적 채점 기준. 모델 구성 서른 개 가운데 최고가 시행의 36.2%를 통과했고, 대부분의 프런티어 구성은 25%에 못 미쳤습니다.⁹

여기서 중요한 것은 이름 붙은 실패 양상들입니다. 에이전트는 그럴듯한 환경 내 요청이 기존 정책을 덮어쓰도록 내버려 둡니다. 요구된 확인을 수행하고 나서 그 결과에 반하는 행동을 합니다. 긴 호흡 속에서 규칙의 세부를 잃어버립니다. 이들 중 어느 것도 검색 실패가 아닙니다. 문서는 내내 사용할 수 있었습니다.

그래서 제 규칙의 정직한 버전은 “description은 라우팅하고 본문은 설명한다”보다 좁습니다. 절차를 description 밖으로 옮기는 일은 여전히 옳습니다. 다른 스킬이 라우팅에 필요로 하는 예산을 되찾아 주고, 호출되지 않은 텍스트가 행동을 조종하는 것을 막아 주기 때문입니다. 둘 다 실질적인 이득이고, 둘 다 본문이 잘 통제한다는 전제에 기대지 않습니다. 그것이 사 주지 않는 것은 옮겨 간 절차가 지켜지리라는 확신입니다. 124쪽짜리 핸드북과 3,000단어짜리 SKILL.md 본문은 같은 곡선 위에 놓여 있습니다.

실무적으로 읽으면 이렇습니다. 본문 길이를 비용으로 다루고, 무료 주차장으로 여기지 마십시오. 어떤 규칙이 정말로 지켜져야 한다면, description은 그것을 둘 자리로 틀렸고 긴 본문은 아주 조금 나을 뿐입니다. 강제는 결정론적인 곳(훅, 권한 규칙, 테스트)에 속하지, 다른 일을 하는 와중에 모델이 기억해 주기를 바라는 산문 속에 있지 않습니다.

내 환경을 직접 감사하기

세션 안에서 시작하십시오. /context를 실행하면 제외된 스킬이 있는지 보고해 줍니다.⁵ 제외가 표시된다면 문제가 확정된 것이고 진단은 거기서 끝납니다.

제가 거기서 시작하지 않은 이유는 시사하는 바가 있습니다. 제 다섯 개 스킬은 제외된 것이 아니라, 이름은 온전한 채 description만 벗겨진 상태로 도착했습니다. 항목이 통째로 빠지는 것보다 조용한 장애이고, 같은 방식으로 드러나지 않을 수도 있습니다. 그러니 어느 쪽이든 파일 시스템과 대조해 검증하십시오. 확인에는 셸 말고 다른 도구가 필요하지 않습니다.

python3 - <<'PY'
import os, re, glob
rows = []
for f in glob.glob(os.path.expanduser('~/.claude/skills/*/SKILL.md')):
    name = os.path.basename(os.path.dirname(f))
    fm = re.match(r'^---\s*\n(.*?)\n---\s*\n', open(f, encoding='utf-8', errors='replace').read(), re.S)
    if not fm:
        continue
    d = re.search(r'^description:\s*(.*?)(?=\n[a-zA-Z_-]+:|\Z)', fm.group(1), re.S | re.M)
    if not d:
        continue
    desc = ' '.join(d.group(1).split()).strip('"\'').lstrip('|').strip()
    rows.append((len(desc), name))
rows.sort(reverse=True)
print(f'{len(rows)} skills, {sum(r[0] for r in rows)} description chars')
for length, name in rows[:15]:
    print(f'  {length:4d}  {name}')
PY

그런 다음 그 출력을 모델이 실제로 받은 내용과 비교하십시오. 이 둘 사이의 간극이 이 글의 발견 전부입니다. 컨텍스트에 스킬이 이름만 있고 그 뒤에 문장이 없다면, 그 스킬은 설치되어 있으면서 도달할 수 없는 상태입니다.

감사에서 세 가지 습관이 따라옵니다.

긴 것뿐 아니라 새로 추가하는 모든 스킬을 예산에 넣으십시오. 항목당 오버헤드는 description 길이와 무관하게 따라붙으므로, 열 번째로 추가한 90자짜리 스킬은 90자보다 비쌉니다.

스킬을 추가한 뒤에는 다시 세십시오. 안전 여유치는 알려 드릴 수 없습니다. 상한이 문서화되어 있지 않고, 비율이 계산되는 방식에 따라 달라진다고 보고되기 때문입니다.³⁴ 가정 위에 얹힌 계산상의 여유보다 경험적 확인이 낫습니다. 바로 그 실수를 제가 저질렀습니다.

잘라내기 전에 스냅숏을 남기십시오. 제 스킬 디렉터리의 대부분은 git이 추적하지 않았고, 일곱 개는 아예 저장소가 아닌 디렉터리로 향하는 심볼릭 링크였기 때문에 git add가 “beyond a symbolic link”라며 거부했습니다. 저는 원본 description을 전부 먼저 JSON 파일에 적어 두었습니다. 검증해 보지 않은 버전 관리는 백업이 아닙니다.

핵심 정리

• description이 없는 스킬은 성능이 떨어진 것이 아니라 도달할 수 없는 것입니다. description이 라우팅 판단 전체를 짊어집니다.
• 이 장애는 구조상 조용합니다. 오류도, 경고도, 로그도 없습니다. 먼저 /context로 제외 경고를 확인한 다음, 컨텍스트 목록을 파일 시스템과 대조하십시오. 벗겨진 description은 사라진 항목보다 더 조용하기 때문입니다.
• 삭제를 좌우하는 것은 총합 크기이지 파일별 속성이 아닙니다. 어떤 스킬이 description을 잃을지 개별 파일의 어떤 속성도 예측하지 못했습니다.
• 관찰이 실패하면 개입하십시오. 장애를 들여다보는 것만으로는 메커니즘을 찾을 수 없었습니다. 총량을 바꾸고 장애가 뒤집히는 것을 지켜보는 한 걸음이 그것을 증명했습니다.
• description은 라우팅하고 본문은 설명합니다. description에서 언제 호출할지 판단에 도움이 되지 않는 것은 매 턴 값을 치르면서 아무것도 벌지 못합니다.
• description 속 명령형은 호출되지 않은 채로 당신에게 작용합니다. ALWAYS와 NEVER는 카탈로그에서 행동을 조종하며, 이것이 측정된 osmosis 효과입니다.¹
• 출처를 댈 수 없는 백분율은 공개하지 마십시오. 제 첫 정리는 실제 측정값에 추측한 예산을 곱해 자신만만하고 틀린 숫자를 만들어 냈습니다.

자주 묻는 질문

Claude Code 스킬이 활성화되지 않는 이유는 무엇입니까

모델이 그 description을 실제로 볼 수 있는지 확인하십시오. 스킬 description은 매 턴의 컨텍스트에 로드되고 고정된 문자 예산을 함께 쓰며, 이를 넘기면 description이 오류도 경고도 로그 한 줄도 없이 조용히 버려집니다. 제 스킬 84개 중 다섯 개는 디스크의 파일에 아무 문제 없는 description이 있었는데도 이름만으로 모델에 도달했습니다. description이 없는 스킬로는 라우팅할 수 없습니다.¹²

Claude Code의 스킬 description 예산은 얼마입니까

정확한 예산은 문서화되어 있지 않고 현재도 논쟁 중이며, 저는 출처를 댈 수 없는 숫자를 공개하지 않겠습니다. 제가 측정한 것은 이렇습니다. description 21,848자에서는 다섯 개가 떨어졌고, 9,885자에서는 하나도 떨어지지 않았습니다. 커뮤니티 측정은 실용적 상한을 15,500자에서 16,000자 부근으로 보고 항목당 약 109자의 오버헤드를 함께 계산하며, Anthropic 기여자들은 예산 비율이 고정된 200K 기준선에 대해 계산된다고 보고합니다.³⁴⁶

어떤 스킬이 description을 잃었는지 어떻게 감사합니까

세션 안에서 /context로 시작하십시오. 제외된 스킬이 있는지 보고해 줍니다. 그런 다음에도 파일 시스템과 대조해 검증하십시오. 제 다섯 개는 제외된 것이 아니라 이름은 온전하고 description만 벗겨진 채로 도착했고, 이는 항목이 빠지는 것보다 조용한 장애이기 때문입니다. SKILL.md 프런트매터의 description 문자 수를 모두 더한 뒤, 그 목록을 컨텍스트 목록이 실제로 보여 주는 것과 비교하십시오.⁵

스킬 description과 본문에는 각각 무엇이 들어가야 합니까

description의 유일한 임무는 그 스킬을 언제 호출해야 하는지에 답하는 것입니다. 트리거 단어와 이름, 사용자가 실제로 입력할 슬래시 명령은 남기고, 절차와 철학과 파일 경로는 본문으로 옮기십시오. 본문은 호출될 때만 로드됩니다. 제 jiro description은 686자에서 126자가 되었지만 라우팅 동작은 같았습니다. 그중 약 500자는 스킬에 무엇이 들어 있는지를 설명하기만 했기 때문입니다.

스킬이 한 번도 실행되지 않아도 description이 행동에 영향을 줍니까

그렇습니다. 그것이 두 번째 세금입니다. 제 description 가운데 열한 개가 ALWAYS, NEVER, MUST, PROACTIVELY, BEFORE를 담고 있었습니다. 이 단어들은 매 턴 컨텍스트에 앉아 있고, 지시문으로 쓰였기 때문에 지시문으로 읽힙니다. “The Regression Tax”는 이 효과를 skill description osmosis라고 부릅니다. 한 번도 호출되지 않았는데도 컨텍스트에 존재한다는 사실만으로 스킬이 에이전트의 행동을 바꾸는 현상입니다.¹

참고 문헌