헤드라인은 잘못된 이야기입니다

Anthropic은 이번 주에 _Claude Code를 구축하며 얻은 교훈: 우리가 스킬(skills)을 사용하는 방법_이라는 제목의 포스트를 게시했습니다. 여러분은 아마 이 글이 Hacker News에 올라온 지 한 시간 만에 읽었을 것입니다. 아마도 시도해 볼 만한 패턴 목록을 얻었거나, 자신의 리포지토리(repo)를 위해 몇 가지 스킬을 작성하겠다는 막연한 의도를 갖게 되었을 것이며

또한 이 포스트는 에이전트 도구화 (agent-tooling) 분야의 사람들이 이미 의심해 왔던 사실을 지나가는 말로 확인해 주었습니다. Anthropic은 긴 시스템 프롬프트 (system prompts)가 확장 가능하다는 것을 믿지 않습니다. 그들의 베팅은 관련이 있을 때만 로드되는, 잘 설명된 수많은 작은 스킬 (skills)에 걸려 있습니다. 컨텍스트 윈도우 (context windows)는 크지만, 어텐션 (attention)은 그렇지 않습니다. 토큰 효율성 (token efficiency)은 더 이상 제약 사항이 아닙니다. 관련성 (relevance)이 제약 사항입니다.

지난 12개월 동안 수천 줄에 달하는 CLAUDE.md 파일을 작성해 왔다면, 이 포스트는 그 방식이 저물어가고 있다고 — 완곡하게 — 말하고 있습니다. 그 대체제는 더 긴 문서가 아닙니다. 모델이 선택할 수 있는 50개의 짧은 문서들입니다. 이것이 2024년에는 중요하지 않았으나 지금 중요해진 이유는, 모델이 마침내 선택 과정을 신뢰할 수 있을 만큼 디스패치 (dispatch) 능력이 충분히 좋아졌기 때문입니다. 이 기능은 지난 두 번의 모델 세대에서 조용히 출시되었습니다. 대부분의 팀은 이에 발맞추기 위해 자신들의 프롬프팅 관행을 리팩터링 (refactor)하지 않았습니다. Anthropic은 방금 당신에게 마감 기한을 알려준 것입니다.

추출해 볼 가치가 있는 숨겨진 문장이 하나 더 있습니다. 이 포스트는 팀 간 지식 전달의 단위로 문서도, Slack 스레드도, 온보딩 자료도 아닌 '스킬 (skills)'을 취급한다고 거의 지나가는 듯이 언급합니다. Anthropic의 한 팀이 워크플로 (workflow)를 찾아내면, 그들은 스킬을 작성하고 회사의 나머지 인원들은 자신들의 에이전트를 통해 이를 사용할 수 있습니다. Slack은 일주일이면 사라지는 스레드입니다. 위키 (wiki) 페이지는 한 번 읽히고 끝납니다. 하지만 스킬은 복리로 쌓입니다.

만약 당신이 Claude Code로 코드를 배포한다면, 당신은 이 중 하나에 해당할 것입니다

여기까지 읽으셨다면, 아마도 다음 중 하나에 해당할 것입니다:

• 10~80명 규모 회사의 테크 리드 (Tech Lead)입니다. 두 분기 전에 Claude Code 라이선스를 구매했습니다. 도입 수준은 불균형합니다. 시니어 엔지니어들은 이를 매우 좋아하지만, 주니어들은 자동 완성 (Autocomplete) 용도로만 사용합니다. 출력 품질 (Output quality)에 대한 측정 지표도 없습니다.
• 창업자 (Founder)입니다. 본인 코드의 60%를 Claude Code로 배포합니다. "그냥 나 혼자 쓰는 거니까"라는 이유로 프롬프트 (Prompt)를 공식화하지 않았습니다. 다음 채용은 30일 이내에 예정되어 있습니다.
• 엔지니어링 매니저 (Engineering Manager)입니다. 팀원들은 한 번 실행되고 잊혀지는 일회성 에이전트 스크립트 (Agent scripts)를 작성합니다. 아무도 관리하지 않기 때문에 공유된 skills/ 디렉토리가 없습니다.
• 스태프/프린시펄 엔지니어 (Staff/Principal Engineer)입니다. 자신만의 스킬 (Skills)을 로컬에 작성해 두었습니다. 성능은 훌륭합니다. 하지만 아무도 그곳에 저장하라고 요청하지 않았기에 레포지토리 (Repo)에는 포함되어 있지 않습니다.

이 네 부류의 사람들은 모두 곧 동일한 사실을 발견하게 될 것입니다: Claude Code를 통한 레버리지 (Leverage)가 팀 내에 고르게 분산되어 있지 않으며, 누가 그 레버리지를 생성하고 있는지 측정할 도구가 없다는 사실입니다. Anthropic의 포스트는 우연히 그 격차를 가시화했습니다.

만약 지난 14일 동안 팀의 skills/ 디렉토리를 열어보지 않았다면, 이 글을 다 읽기 전에 먼저 확인해 보십시오.

메커니즘 — 왜 설명 (Description)이 실제 표면적(Surface area)인가

Claude Code의 스킬 (Skills)은 탐지 (Detection)와 실행 (Execution)이라는 두 단계로 작동합니다. 거의 모든 사람이 실수하는 지점은 바로 탐지 단계입니다.

사용자가 프롬프트 (Prompt)를 보내면, 하네스 (Harness)는 사용 가능한 스킬들을 스캔하고 description 필드가 프롬프트의 의도와 일치하는 스킬을 선택합니다. 이는 단순한 패턴 매칭 (Pattern matching)이 아닙니다. 모델이 설명 문구 (Description prose)를 바탕으로 판단을 내리는 과정입니다. 즉, 설명은 단순한 메타데이터 (Metadata)가 아닙니다. 설명이 곧 API (API)입니다.

잘못 작성된 스킬 설명은 다음과 같습니다:

---
name: pr-review
description: "Reviews pull requests."
...

해당 스킬은 "이 PR을 리뷰해줘"라는 문구에만 트리거되며, 그 외에는 거의 작동하지 않을 것입니다. "diff를 봐줄 수 있어?", "이 브랜치 준비됐어?", "리뷰 피드백 확인해줘" 또는 실제 엔지니어들이 사용하는 그 어떤 자연스러운 표현에도 트리거되지 않을 것입니다. 스킬은 존재하지만, 하네스 (harness)가 이를 포착하지 못하는 것입니다. 레버리지 (leverage)의 낭비입니다.

하중을 견딜 수 있는 (load-bearing) 스킬 설명은 다음과 같은 모습이어야 합니다:

---
name: pr-review
description: GitHub PR 또는 로컬 브랜치 diff의 정확성, 누락된 테스트 커버리지, API 파괴적 변경 사항, 그리고 리뷰어 코멘트 권장 사항을 리뷰합니다. 사용자가 PR, 브랜치, diff, 커밋 또는 변경 세트 (change set)를 리뷰, 감사 (audit), 확인 (check), 평가 (evaluate) 또는 건전성 검사 (sanity-check)해달라고 요청할 때 사용합니다. 변경 요청, 병합 (merge) 또는 보류 (hold) 여부를 포함합니다.
...

두 번째 설명은 "누군가 코드가 배포되기 전에 검토하기를 원한다"라는 전체 영역에 걸쳐 트리거됩니다. 또한 열거 (enumeration)를 통해 하네스에게 해당 스킬이 하지 않는 일이 무엇인지도 알려줍니다. 열거를 통한 커버리지가 바로 핵심 열쇠 (unlock)입니다. Anthropic 팀은 이에 대해 완곡한 표현으로 글을 썼지만, 게시물을 두 번 읽어본다면 그들이 이 주제로 계속 되돌아오고 있다는 것을 알 수 있을 것입니다.

명확하지 않은 함의는 다음과 같습니다: 스킬을 잘 작성하는 것은 코딩 기술이 아니라 작문 기술 (writing skill)이라는 점입니다. 여러분 팀에서 가장 뛰어난 스킬 작성자는 가장 깔끔한 산문 (prose)을 쓸 수 있는 사람입니다. 그리고 그 사람은 종종 가장 시니어 엔지니어가 아닙니다. 여러분의 skills/ 디렉토리의 디스패치 (dispatch) 품질은 영어를 가장 잘 구사하는 사람(또는 일본어 하네스 사용 사례의 경우 일본어)에 의해 병목 현상 (bottleneck)이 발생합니다. 단, 이 글을 쓰는 시점 기준으로 영어 모델이 설명 매칭 (description matching) 능력 면에서 실질적으로 더 뛰어납니다.)

아무도 이야기하지 않는 두 번째 메커니즘은 다음과 같습니다: 스킬의 본문(skill bodies)은 디스패치(dispatch) 이후에만 로드됩니다. 본문이 3,000단어에 달하더라도 탐지 지연 시간(detection latency) 측면에서 비용이 전혀 들지 않습니다. 매 턴마다 컨텍스트(context)를 소모하는 것은 바로 설명(description)입니다. 따라서 스킬 본문의 올바른 형태는 다음과 같습니다: 심도 있고, 실행 예시(worked examples)를 포함하며, 직접 겪어본 시행착오를 통해서만 알 수 있는 예외 케이스(corner cases)를 담고 있어야 합니다. 설명의 올바른 형태는 다음과 같습니다: 간결하고, 열거되어 있으며, 디스패치에 최적화되어 있어야 합니다. 사람들이 작성하는 대부분의 스킬은 이 과정을 정반대로 수행합니다. 즉, 본문은 빈약하고 설명은 모호합니다. 두 부분 모두 서로 반대 방향으로 잘못 작성되어 있습니다.

실행 예시를 들어보겠습니다. "이 디자인 명세(design spec)를 Linear 티켓으로 변환하라"를 처리하는 스킬을 가정해 봅시다. 잘못된 형태는 워크플로를 요약한 400단어의 설명과, "그 일을 수행하라"라고만 적힌 50단어의 본문이 결합된 형태입니다. 올바른 형태는 트리거 문구("turn this into a ticket", "file this in Linear", "open an issue for this", "track this work", "add to backlog")를 열거한 90단어의 설명과, 필드 매핑(field mapping), 수락 기준(acceptance-criteria) 템플릿, 우선순위 휴리스틱(priority heuristic), 팀 라우팅 로직, 그리고 올바르게 파싱되는 디자인 예시 3개와 지속적으로 실패하는 유형 1개를 비교하여 보여주는 2,000단어의 본문이 결합된 형태입니다. 첫 번째 형태는 매 턴마다 비용을 발생시키며 제대로 작동하는 경우도 드뭅니다. 두 번째 형태는 실행되기 전까지는 비용이 전혀 들지 않으며, 실행되는 순간 그 로드(load)의 가치를 증명합니다.

반대 의견: "이것은 오버헤드일 뿐이다, 그냥 좋은 프롬프트를 작성하라"

반대 의견은 실재하며, 이를 철저히 검토(steelmanning)할 가치가 있습니다. 그 논거는 다음과 같습니다: 스킬은 간접 계층(layer of indirection)입니다. 스킬은 단발적인 "이 PR을 리뷰해줘"라는 요청을 반복적인 작성 부담으로 바꿉니다. 팀은 이를 유지 관리해야 합니다. 스킬은 노후화됩니다. 서로 충돌하기도 합니다. 필요할 때 그냥 더 긴 프롬프트를 작성하면 됩니다. Cursor의 탭 완성(tab completion) 기능은 스킬 없이도 훌륭한 코드를 배포합니다.

그 'steelman(상대방의 논리를 가장 강력한 형태로 재구성한 것)'은 절반만 맞습니다. 만약 당신이 사이드 프로젝트를 출시하는 1인 창업자라면, 스킬 (skills)은 오버헤드 (overhead)입니다. 손익분기점은 한 달 동안 에이전트 (agent)에게 동일한 다단계 지침을 두 번째로 내리는 시점쯤에 형성됩니다. 그 미만이라면 더 긴 프롬프트 (prompt)를 작성하세요. 그 이상이라면 스킬 (skill)을 작성하세요.

이 논리가 무너지는 지점은 레버리지 (leverage)가 감쇠한다고 가정한다는 것입니다. 그렇지 않습니다. 일단 스킬이 훌륭해지면 — 즉, 그 설명이 자연스러운 문구들을 통해 트리거 (trigger)되고, 그 본문이 정교하게 조정되면 — 스킬은 이자를 창출합니다. 당신의 팀원은 그것이 존재하는지 모른 채 사용합니다. 다음 채용 인원은 입사 3일 차에 그것을 사용합니다. CI 러너 (CI runner) 상의 에이전트는 업무 시간 외에 그것을 사용합니다. 동일한 200줄의 산문이 단일 프롬프트가 할 수 있는 것보다 훨씬 더 넓은 영역에서 가치를 창출합니다.

Cursor에 대한 반론 또한 들리는 것보다 약합니다. 탭 완성 (tab completion)은 다른 제품입니다. 그것은 로컬 편집 (local edit)에 최적화되어 있습니다. 스킬 (skills)은 코드 리뷰 (code review), 릴리스 준비 (release prep), 사후 분석 작성 (postmortem authoring), 고객 지원 라우팅 (customer support routing)과 같이 조율된 다단계 작업 (orchestrated, multi-step task)에 최적화되어 있습니다. 이 둘은 대체재가 아닙니다. Claude Code 스킬을 실행하는 팀과 탭 완성을 실행하는 팀은 서로 다른 업무를 수행하고 있는 것입니다.

플레이북: 이번 주에 실행할 네 가지 단계

1. skills/ 디렉토리를 감사하고 한 줄짜리 장부를 작성하세요

저장소의 skills/ 디렉토리(개인용의 경우 ~/.claude/skills/)로 이동하세요. 모든 스킬에 대해 다음 한 줄을 작성합니다:

이름 | 마지막 수정일 | 지난 30일간 트리거 횟수 | 작성자

만약 "트리거 횟수"를 채울 수 없다면, 당신은 측정 수단이 없는 것입니다. 그것부터 먼저 해결하세요 — 모든 호출(dispatch) 시 스킬 이름을 로그로 남기십시오. 계측 (instrumentation)은 15줄의 Python 코드나 settings.json의 단일 훅 (hook)으로 가능합니다:

{
  "hooks": {
    "SkillStart": [
...

2주 동안 실행해 보세요. 하위 25%(bottom quartile)에 속하는 스킬은 불필요한 짐입니다. 삭제하세요. 상위 25%(top quartile)는 레버리지입니다 — 해당 스킬 작성자들이 당신의 성과 검토를 담당하는 사람들에게 눈에 띄도록 만드세요.

2. 호출 우선 스타일(dispatch-first style)로 설명을 다시 작성하세요

가장 자주 사용하는 세 가지 스킬로 이동하세요. 위에서 언급한 두 번째 예시처럼 설명을 다시 작성하세요: 동작 동사(action verbs), 열거형 문구(enumerated phrasings), 그리고 해당 스킬이 하지 않는 일이 무엇인지 포함해야 합니다. 분량은 60~120단어를 목표로 하세요. 이 설명은 인간을 위한 문서(documentation)가 아닙니다. 이는 하네스(harness)가 어떤 스킬을 트리거할지 결정할 때 모델에게 보여주는 프롬프트(prompt)입니다.

간단한 테스트 방법: 설명을 소리 내어 읽으며 스스로에게 물어보세요. "만약 내가 금요일 오후 6시에 짜증 난 엔지니어처럼 이 말을 한다면, 모델이 이것을 선택할까?" 만약 대답이 '아니오'라면, 당신의 설명은 지나치게 깔끔한 상태입니다.

3. 모든 스킬에 SKILL_OWNER를 추가하세요

공유 저장소(shared repo)에 있는 각 스킬에 대해 한 명의 소유자(owner)를 지정하세요. 소유자의 이름을 프론트매터(frontmatter)에 기입하세요:

---
name: release-prep
description: ...
...

소유자는 기반이 되는 워크플로우가 변경될 때(릴리스 프로세스 이동, 지원 라우팅 규칙 변경, PR 템플릿에 새로운 섹션 추가 등) 스킬이 정확하게 유지되도록 관리할 책임이 있습니다. 소유자가 없다면 스킬은 미묘하게 틀린 방향으로 표류(drift)하게 되는데, 이는 스킬이 아예 없는 것보다 더 나쁩니다. 잘못된 스킬은 없는 스킬보다 더 해롭습니다. 하네스가 어쨌든 이를 실행할 것이기 때문입니다.

소유권을 분기별로 검토하세요. 아무도 소유하지 않는 스킬은 삭제해야 할 스킬입니다.

4. 채용 시 skills/ 디렉토리를 포트폴리오 결과물로 활용하세요

이것은 아직 아무도 시도하지 않는 전략입니다. 엔지니어를 인터뷰할 때 이렇게 물어보세요: "당신이 매일 사용하는 에이전트(agent)를 위해 직접 작성한 스킬을 보여주세요. 그 설명을 저에게 설명해 주시겠어요?"

당신이 테스트하고 있는 것:

• 개인의 차원을 넘어 팀 규모의 레버리지(leverage)를 생각할 수 있는가?
• 모델이 실행(dispatch)할 수 있는 문장(prose)을 작성할 수 있는가?
• 소유권(ownership), 표류(drift), 그리고 실패 모드(failure modes)에 대해 고민해 보았는가?

사려 깊은 스킬 디렉토리를 보유한 후보자는 지난 6~18개월 동안 복리(compounding) 효과를 쌓아온 사람입니다. 디렉토리가 없는 후보자는 일회성 결과물(one-off output)만을 만들어온 사람입니다. 둘 다 기능을 출시할 수는 있습니다. 하지만 팀을 떠난 후에도 자신의 작업에 대한 이자(interest)를 얻는 사람은 오직 첫 번째 유형뿐입니다.

이것은 정보 차단(gatekeeping)을 하려는 것이 아닙니다. 수많은 뛰어난 엔지니어들이 Claude Code를 사용해 보지 않았을 수도 있습니다. 하지만 특히 AI-native 트랙 — 즉, 에이전트 함대(agent fleet)를 생산적으로 만들기 위해 채용하는 사람들 — 의 경우, skills 디렉토리는 2015년경 GitHub가 인터뷰의 표준이 된 이후 존재했던 가장 깔끔한 포트폴리오 신호(portfolio signal)입니다.

5. 코드 리뷰(code review)를 하는 것과 동일한 방식으로 매달 "skills 리뷰"를 실시하세요

skills를 통해 레버리지(leverage)를 얻는 팀과 쓰레기(junk)를 축적하는 팀을 가르는 단 하나의 움직임은 바로 정기적인 리뷰 미팅을 갖는 것입니다.