클로드 스킬(Skill)이 실제로 «먹히게» 만드는 것 — 앤트로픽 자체 가이드로 확인
앤트로픽의 스킬 작성 가이드는 «무엇을 넣을까»보다 «무엇을 뺄까»에 가깝다. 두 줄짜리 설명문, 짧은 SKILL.md, 한 단계 깊이를 넘지 않는 참조 파일.
한 줄 답
앤트로픽 문서에 따르면 클로드 스킬을 «실제로 작동하게» 만드는 건 무엇인가?
스킬의 생사는 필드 하나에 달렸다 — description. 3인칭으로, «무엇을 하는지»와 «언제 쓰는지»를 함께 적어야 한다. SKILL.md 는 500줄 아래로, 참조 파일은 한 단계 깊이로 유지하고, 쓸 모든 모델에서 테스트하고, 믿을 수 없는 출처의 스킬은 설치하지 않는다.
핵심 요약
- 클로드는 다른 걸 읽어보기도 전에 description 필드 하나만 보고 어느 스킬을 열지 고른다 — 설명이 모호하면 그 스킬은 조용히 한 번도 선택되지 않는다.
- 스킬은 3단계로 로딩된다. 늘 컨텍스트에 있는 건 1단계(약 100토큰짜리 메타데이터)뿐이고, 본문은 호출될 때, 첨부 파일은 실제로 읽힐 때만 들어온다.
- 참조 파일은 SKILL.md 에서 한 단계 이상 떨어뜨리지 않는다. 클로드가 깊이 중첩된 체인을 부분적으로만 읽고 나머지를 놓칠 수 있다.
- 부서지기 쉬운 작업엔 정확한 스크립트를, 판단이 필요한 작업엔 자유도 높은 지시문을 — 길이보다 «형식이 작업에 맞는가» 가 더 중요하다.
- claude.ai 에 올린 스킬은 API 나 클로드 코드에 안 나타난다. 세 표면(surface)마다 설치가 따로 논다.
스킬은 클로드가 작업 도중에 «열어볼 수 있는» 폴더다 — SKILL.md 파일 하나에, 선택적으로 스크립트와 참조 자료가 딸린다. 요점은 클로드가 «쓰는 만큼만» 비용을 낸다는 것이다. 스킬 대부분은 대화 중 실제로 필요해지기 전까지 컨텍스트 창 바깥에 머문다. 앤트로픽 자체 작성 가이드는 «무엇을 넣을지»보다 «무엇을 뺄지»에 더 많은 분량을 쓰는데, 그 조언의 모양 자체를 그대로 따라 할 값어치가 있다.
description 필드가 모든 걸 정한다
클로드가 스킬을 열어보기 전에 보는 건 하나뿐이다 — YAML 프런트매터의 description 필드, 최대 1,024자. 앤트로픽 지침은 구체적이다. 3인칭으로 쓸 것(«엑셀 파일을 처리한다…»지 «제가 도와드릴 수 있는 건…»이 아니다), 그리고 «무엇을 하는지»와 «언제 쓰는지»를 함께 적을 것. 한 번에 100개 넘는 스킬이 후보로 있을 수 있는 상황에서 이 한 문장은 «매칭 문제»다 — 클로드는 오직 이 설명문만 보고 후보 중에서 고른다. 모호하게 쓰면 그 스킬은 왜인지도 모른 채 조용히 한 번도 선택받지 못한다.
name 필드는 더 작지만 규칙은 따로 있다 — 최대 64자, 소문자·숫자·하이픈만, «claude»나 «anthropic»은 못 넣는다. 앤트로픽은 동명사형 이름(processing-pdfs, analyzing-spreadsheets)을 helper·utils 같은 모호한 이름보다 권한다.
3단계, 3개의 비용
스킬은 단계별로 로딩되고, 이 비용 모델이 형식 자체를 결정한다.
이 구조가 크기 제한이 존재하는 이유이기도 하다. 앤트로픽은 SKILL.md 본문을 5,000토큰·500줄 아래로 유지하라고 권한다. 그보다 길면 별도 파일로 빼고 링크만 건다 — 클로드가 그 파일을 열기 전까지는 비용이 0이다.
참조는 한 단계 깊이로
클로드가 «일부만» 읽은 파일은 아예 안 읽은 것보다 나쁠 수 있다. 앤트로픽 지침은 클로드가 깊이 중첩된 참조 체인을 (사실상 head -100 을 돌리듯) 훑고 지나갈 수 있다고 경고한다 — 그래서 SKILL.md 에서 한 단계보다 먼 파일은 불완전하게 읽힐 위험이 있다. 100줄이 넘는 참조 파일에는 맨 위에 목차를 넣어라. 그러면 부분적으로만 읽혀도 클로드가 «무엇이 있는지» 전체 범위는 보게 된다.
잘못될 수 있는 정도에 지시문 형식을 맞춘다
모든 스킬이 같은 종류의 지시문을 필요로 하지는 않는다. 앤트로픽은 이를 «자유도(degrees of freedom)»로 설명한다 — 판단이 필요한 작업(문서 요약, 메일 초안)은 유연하고 자유도 높은 문장으로 서술해도 되지만, 부서지기 쉽거나 일관성이 절대적으로 필요한 작업(DB 마이그레이션, 특정 API 호출 순서)은 자유도 낮은 정확한 스크립트로 못 박아야 한다. 후자에 느슨한 산문을 쓰는 것이 스킬이 «조용히» 실패하는 흔한 지점이다.
에세이를 쓰기 전에 기준선부터 잰다
건너뛰기 쉽고, 건너뛰면 반드시 후회하는 순서다 — 문서를 길게 쓰기 «전에» 실제 테스트 시나리오 최소 3개를 클로드에게 돌려서, 스킬 없이 클로드가 뭘 틀리는지부터 파악한다. 그러지 않으면 클로드에게 애초에 없던 문제를 몇 문단씩 들여 해결하게 된다. 앤트로픽은 완성된 스킬을 쓸 모든 모델에서 테스트하라고도 권한다 — 하이쿠·소네트·오퍼스는 똑같이 반응하지 않는다. 오퍼스에게 충분히 간결한 지시문이 하이쿠에게는 너무 성글 수 있다.
«소프트웨어 설치»처럼 다룬다
앤트로픽은 이걸 명확히 못 박는다 — 직접 만들었거나 앤트로픽이 직접 배포한 스킬만 써라. 스킬은 클로드에게 도구를 오용하거나 데이터를 유출하도록 지시할 수 있고, 신뢰할 수 없는 스킬을 기본값으로 안전하게 만들어 주는 샌드박스는 없다. 내가 쓰지 않은 마크다운·스크립트 폴더는 여전히 «곧 에이전트가 실행할 코드»다.
날짜를 확인하시라. 앤트로픽 자체 모범사례 문서도 «2025년 8월 이전에는 X를 써라» 같은 시점 종속적 문구를 스킬에 박아 넣지 말라고 경고한다 — 스킬 콘텐츠는 자동으로 갱신되지 않고, 이 글도 같은 주의가 적용된다. 위 표면별 가용성 설명이 그새 바뀌었을 수 있으니 링크된 원문을 직접 확인하시라.
자주 묻는 질문
- SKILL.md 는 실제로 얼마나 짧아야 하나?
- 앤트로픽 자체 권고는 본문 500줄 이하다. 그보다 길면 별도 파일로 빼서 링크만 걸어라 — 그 파일은 클로드가 실제로 열 때까지 비용이 0이다.
- description 은 나머지 부분과 다르게 써야 하나?
- 그렇다. 반드시 3인칭이어야 하고, «무엇을 하는지»와 «언제 쓰는지»를 함께 적어야 한다. 클로드가 이 스킬을 열지 말지 정하기 전에 보는 건 그 한 문장뿐이다.
- claude.ai 에 올린 스킬을 API 에서도 쓸 수 있나?
- 아니다. 스킬은 표면별로 따로 올린다 — claude.ai(사용자별), 클로드 API(/v1/skills 로 워크스페이스 전체), 클로드 코드(파일시스템의 폴더). 자동 동기화는 없다.
- 남이 만든 스킬을 설치해도 안전한가?
- 앤트로픽 문서는 스킬 설치를 «소프트웨어 설치»처럼 다루라고 명시한다. 스킬은 클로드에게 도구를 오용하거나 데이터를 유출하도록 지시할 수 있다 — 직접 만들었거나 앤트로픽이 배포한 것만 쓰라는 것이다.
출처
- Agent Skills — Anthropic
- Skill authoring best practices — Anthropic
- anthropics/skills — Anthropic