10시간짜리 스킬이 10분짜리 스킬을 항상 이깁니다

스킬을 작성한다는 것이 SKILL.md 파일을 폴더에 넣고 넘어가는 일이라고 생각했습니다. 10분이면 끝나는 작업이었습니다. 그 방식은 나름대로 잘 작동했습니다. 하지만 매번 호출할 때마다 똑같은 실수가 반복되는 것을 보고 나서야, 스킬이 실제로 의도한 대로 동작하고 있는지 확인할 방법이 전혀 없었다는 사실을 깨달았습니다.

그때 Anthropic에서 Claude Code를 개발하는 엔지니어 Thariq이 모든 것을 다시 생각하게 만드는 글을 올렸습니다. “스킬을 잘 사용하는 것 자체가 하나의 스킬 문제입니다.”

그 문장이 머릿속에 남은 이유는 제가 직접 경험하고 있던 상황과 정확히 맞아떨어졌기 때문입니다. 빠르게 작성한 마크다운 파일과 제대로 구조화된 스킬 폴더 사이의 차이는 이론이 아니라 실제 출력 품질에서 드러나고 있었습니다.

스킬은 파일이 아니라 폴더입니다

가장 흔한 오해는 스킬이 SKILL.md 파일 하나와 같다는 생각입니다. 실제로 스킬은 스크립트, 참조 코드, 설정 파일, 그리고 이 모든 것을 연결하는 마크다운 파일을 담고 있는 폴더입니다.

Anthropic의 내부 접근 방식은 그들이 점진적 공개(progressive disclosure)라고 부르는 방식을 사용합니다. 모든 것을 단일 프롬프트에 집어넣는 대신, Claude가 필요한 순간에 필요한 것만 읽을 수 있도록 파일을 배치합니다. references/api.md 파일에는 Claude가 필요할 때 가져다 쓸 수 있는 함수 시그니처가 담겨 있습니다. assets/ 디렉토리에는 출력 템플릿이 있어 프롬프트에서 포맷을 따로 설명할 필요가 없습니다. 검증 스크립트를 통해 Claude가 결과를 반환하기 전에 스스로 출력을 테스트할 수 있습니다.

skill-creator 저장소를 열어보면 이 원칙이 실제로 적용된 모습을 확인할 수 있습니다. agents/, references/, scripts/ 디렉토리가 SKILL.md 파일과 나란히 위치합니다. 스킬을 만드는 도구 자체가 스킬로 구성되어 있습니다.

본문보다 주의사항이 더 중요합니다

Thariq은 Gotchas 섹션을 스킬에서 “신호 밀도가 가장 높은 콘텐츠”라고 표현했습니다. 주요 지침도 아니고, 예시도 아닙니다. 바로 Gotchas입니다.

이 말은 제 경험과 일치합니다. Gotchas 섹션 없이 스킬을 만들었더니 같은 오류가 연달아 세 번 발생했습니다. 그 특정 실패 패턴을 문서화한 한 줄을 추가한 순간부터 해당 오류는 더 이상 발생하지 않았습니다.

이유는 간단합니다. Claude는 프롬프트 본문에 작성할 내용의 대부분을 이미 알고 있습니다. TypeScript 작성 방법이나 JSON 포맷 방식을 알려주는 것은 기본적으로 잘 처리하는 것들을 다시 설명하는 데 불과합니다. 그러나 특정 맥락에서 무엇을 하지 말아야 하는지를 알려주는 것은 진정으로 새로운 정보입니다.

Thariq의 게시물에서 신뢰할 만하다고 느낀 몇 가지 원칙이 있습니다. 명백한 내용은 적지 않습니다. 중복된 지침은 오히려 성능을 저하시킬 수 있기 때문입니다. 지나치게 구체적인 단계로 Claude를 몰아붙이지 않습니다. 그렇게 하면 상황에 맞게 적응하는 능력이 사라집니다. 그리고 description 필드는 사람을 위한 문서가 아니라, Claude가 스킬을 언제 실행할지 결정하는 데 사용하는 입력값임을 기억합니다.

Skill Creator는 “잘 되는 것 같다”를 “검증됨”으로 바꿔줍니다

2주 전 Skill Creator 업데이트는 스킬 품질에 대한 생각을 바꿔놓았습니다. 테스트 프롬프트를 정의하고, 기대 결과를 설정하면, 도구가 스킬이 실제로 올바른 결과를 만들어내는지 검증합니다. 프롬프트를 위한 단위 테스트입니다.

몇 주 동안 사용해 온 스킬에 평가(eval)를 추가했습니다. 당연히 통과할 것이라고 생각했던 두 가지 테스트 케이스가 즉시 실패했습니다. 수정 사항은 작았지만, 수정을 적용하자 출력 품질이 눈에 띄게 달라졌습니다.

스킬에는 두 가지 유형이 있다는 유용한 구분법이 있습니다. 역량 향상 스킬은 Claude가 혼자서는 잘 수행하지 못하는 것을 가르칩니다. 인코딩된 선호도 스킬은 팀의 특정 워크플로우나 기준을 강제합니다. 첫 번째 유형에는 자연스러운 만료 기간이 있습니다. 모델이 개선되면 결국 불필요해지기 때문입니다. 두 번째 유형은 워크플로우가 존재하는 한 가치를 유지합니다. 평가를 통해 역량 향상 스킬이 효용을 잃는 순간을 파악할 수 있습니다.

도구는 모델 업데이트에 걸쳐 통과율과 토큰 사용량을 추적하는 벤치마크 모드, 테스트 중 컨텍스트 오염을 방지하는 멀티 에이전트 병렬 실행, 그리고 스킬 적용 유무에 따른 출력을 맹검 A/B 비교하는 비교 에이전트를 지원합니다.

복리 수익

수백 개의 스킬을 살펴보고 수십 개를 직접 유지 관리하면서 한 가지 패턴이 일관되게 나타났습니다. 스킬의 가치는 초안이 아니라 반복 개선에서 나옵니다.

폴더 구조는 Claude의 컨텍스트 창을 형성하는 방식입니다. Gotchas는 실패 경험을 재사용 가능한 지식으로 전환합니다. 평가는 그 지식이 여전히 유효한지 측정합니다.

SKILL.md를 작성하는 데는 10분이 걸립니다. 실제 실패에서 얻은 Gotchas를 추가하고, 평가 케이스를 만들고, 검증 스크립트를 포함하는 데는 10시간에 가까운 시간이 걸립니다. 그 투자는 스킬이 실행될 때마다 돌아옵니다. 오늘 밤 하나를 만들어 두시기 바랍니다. 아침이 되면, 직접 하지 않아도 되는 작업을 이미 처리해 놓았을 것입니다.