Claude 스킬 API, latest 쓰면 남이 바꿉니다

어제 공식 문서 색인이 크게 늘었는데, 그 안에 스킬을 API로 관리하는 기능이 통째로 들어와 있었습니다. 만들고, 목록 뽑고, 버전 올리고, 지우는 창구가 전부 생긴 겁니다. 지금까지 스킬은 폴더에 파일을 두는 물건이었는데 이제 업로드하고 버전을 붙이는 배포물이 됐습니다. 그런데 문서를 읽다 보니 조용히 사고 나기 좋은 대목이 둘 있었습니다 — 버전은 델타가 아니라 완전 스냅샷이라는 것과, 버전을 안 적으면 남이 올린 게 내 요청에 들어온다는 것입니다.

📌 30초 요약

• 스킬을 API로 올리고 버전을 붙일 수 있게 됐습니다. 워크스페이스 안에서만 보이는 비공개 자산입니다.
• 새 버전은 델타가 아니라 완전 스냅샷입니다. 빠뜨린 파일은 안 이어지고 그냥 사라집니다.
• 버전을 안 적으면 최신을 씁니다. 즉 워크스페이스의 다른 사람이 올린 버전이 내 요청에 들어옵니다.
• 혼자서는 못 돕니다 — 코드 실행 도구가 켜져 있어야 스킬이 작동합니다.
• 인터넷이 안 됩니다. 외부 호출도, 패키지 설치도 못 합니다.
• 이름에 못 쓰는 단어가 있습니다 — "anthropic"과 "claude"는 예약어입니다.

스킬이 파일에서 배포물이 됐습니다

전에 스킬과 MCP가 뭐가 다른지를 정리하면서 "MCP는 도구, 스킬은 플레이북"이라고 썼는데, 그때 스킬은 내 컴퓨터 폴더에 두는 파일 묶음이었습니다. 이번에 달라진 건 그 묶음을 서버에 올려 번호를 붙이고 관리한다는 점입니다.

문서가 스킬을 두 종류로 나눕니다. 만든 주체가 다를 뿐 붙이는 방식은 똑같다고 명시합니다.

항목	미리 만들어둔 것	내가 올린 것
이름	짧은 이름 — 파워포인트·엑셀·워드·PDF	발급되는 긴 식별자
버전	날짜 형식(예: 20251013)	올릴 때마다 자동 발급되는 번호
관리 주체	만든 회사가 유지보수	내가 올리고 내가 관리
공개 범위	모두 사용 가능	내 워크스페이스 안에서만

함정 ① 버전은 덮어쓰기입니다

버전 관리라고 하면 깃처럼 바뀐 부분만 쌓인다고 생각하기 쉽습니다. 여기는 다릅니다.

📦 새 버전은 완전한 스냅샷입니다

문서 표현을 옮기면 새 버전은 델타가 아니라 완전한 스냅샷이고, 매번 스킬의 전체 파일 묶음을 올려야 합니다. 그리고 결정적인 한 줄이 붙습니다 — "빠뜨린 파일은 이어지지 않습니다." 즉 설명 파일 하나만 고쳤다고 그것만 올리면, 나머지 파일이 통째로 사라진 버전이 만들어집니다. 오류도 안 납니다. 조건이 하나 더 있는데 — 새 버전의 설명 파일 안에 적힌 이름이 기존 스킬 이름과 같아야 합니다.

실무로 옮기면 "업로드 스크립트를 만들어두라"는 뜻입니다. 손으로 파일을 골라 올리는 순간 빠뜨릴 위험이 생기니까요.

# 새 버전을 올릴 때 — 폴더 전체를 매번 다시
curl -X POST ".../v1/skills/<스킬ID>/versions" \
  -H "x-api-key: <YOUR_API_KEY>" \
  -F "files[]=@my_skill/SKILL.md" \
  -F "files[]=@my_skill/analyze.py"
      ↑ 여기서 하나라도 빠지면 그 파일은 새 버전에 없습니다

# 운영에서는 버전을 못 박아 두는 쪽
"container": {
  "skills": [{
    "type": "custom",
    "skill_id": "skill_...",
    "version": "skver_..."  // latest가 아니라 특정 번호
  }]
}

함정 ② latest는 남이 바꿉니다

이게 더 조용합니다. 버전을 안 적거나 최신으로 두면 요청이 항상 가장 최근 버전을 씁니다. 편해 보이는데, 문서가 그 뒤에 조건을 붙여놨습니다.

내가 안 바꿨는데 동작이 바뀝니다

최신으로 두면 워크스페이스의 누군가가 올린 버전이 그대로 내 요청에 들어옵니다. 내 코드는 한 글자도 안 바뀌었는데 돌아가는 내용이 달라지는 겁니다.

그래서 문서 권고가 단호합니다 — 운영에서는 특정 버전을 못 박아, 스킬이 갱신돼도 배포된 동작이 절대 바뀌지 않게 하라.

혼자 쓰는 계정이면 크게 걸릴 일이 아닙니다. 문제는 팀으로 쓰는 워크스페이스입니다. 누군가 스킬을 개선하려고 올린 새 버전이 다른 사람의 운영 서비스에 즉시 반영되는 구조니까요. 팀 단위로 AI 설정을 공유할 때 어디까지 서로에게 영향을 주는지는 서버에서 내려주면 못 덮습니다에서도 다룬 적이 있는데, 이번 건은 방향이 반대입니다 — 관리자가 강제하는 게 아니라 동료가 무심코 바꾸는 쪽이죠.

혼자서는 못 돕니다

써보기 전에 알아야 할 전제 조건입니다. 스킬은 코드 실행 도구를 통해서만 작동합니다. 요청에 그 도구를 켜두지 않으면 스킬을 지정해도 소용이 없고, 그 도구가 지원하는 모델이어야 합니다.

그리고 스킬이 돌아가는 상자에는 제약이 세 개 걸려 있습니다.

제약	뜻
인터넷 없음	외부 API를 호출할 수 없습니다. 스킬 안에서 데이터를 가져오는 설계는 안 됩니다.
패키지 설치 없음	돌릴 때 새로 깔 수 없습니다. 미리 들어 있는 것만 씁니다.
매번 새 상자	기존 상자 번호를 지정하지 않으면 깨끗한 상자가 새로 만들어집니다. 앞선 작업물이 남지 않습니다.

숫자 제한도 있습니다 — 한 요청에 스킬 최대 20개, 올릴 수 있는 크기는 압축 안 한 상태로 30MB까지입니다. 이름 규칙도 은근히 빡빡한데, 영소문자·숫자·하이픈만 64자 이내이고 "anthropic"과 "claude"는 예약어라 못 씁니다.

어떻게 불려 나가나

동작 순서가 문서에 네 단계로 적혀 있는데, 토큰을 아끼는 구조가 여기 들어 있습니다.

먼저 이름과 설명만 시스템 프롬프트에 실립니다. 파일들은 상자 안 스킬 이름으로 된 폴더에 복사되고요. 그리고 Claude가 필요하다고 판단할 때만 전체 지시문을 불러옵니다. 어제 다룬 브라우저 도구가 선언만으로 6,600토큰을 먹는 것과 비교하면 설계 방향이 정반대입니다 — 그쪽은 전부 미리 싣고, 이쪽은 목차만 보여주고 필요할 때 펼칩니다.

다만 공짜는 아닙니다. 문서가 안 쓸 스킬을 끼워 넣으면 성능에 영향이 간다고 명시합니다. 목차라도 20개어치가 실리면 그만큼 자리를 차지하니까요.

자주 묻는 질문

Q. 제가 쓰는 코딩 도구의 스킬과 같은 건가요?

개념은 같은 계열이지만 사는 곳이 다릅니다. 개발 도구 쪽 스킬은 내 컴퓨터 폴더에 있고, 오늘 다룬 건 API 서버에 올려서 워크스페이스가 공유하는 쪽입니다. 폴더에 두고 쓰는 방식은 스킬 완전정복 글에 정리해뒀습니다.

Q. 인터넷이 안 되면 쓸모가 좁지 않나요?

용도가 다릅니다. 문서가 드는 예를 보면 문서 양식 맞추기, 회사 표준으로 보고서 구조 잡기, 사내 분석 절차 돌리기 같은 것들입니다. 밖에서 데이터를 가져오는 게 아니라 이미 있는 것을 규칙대로 처리하는 쪽이죠. 데이터를 가져와야 하면 그건 다른 도구의 몫입니다.

Q. 개인이 쓸 일이 있을까요?

API로 뭔가 만들고 계시다면요. 문서는 개인 용도로 나만의 문서 양식, 전용 데이터 처리 절차, 코드 생성 규칙을 듭니다. 다만 코드 실행 도구를 켜야 하고 그 자체로 비용이 붙으니, 반복해서 쓸 절차가 있을 때 값을 합니다. 한 번 쓰고 말 일이면 그냥 프롬프트에 적는 게 쌉니다.

🧭 정직하게 덧붙이면

①공식 문서를 읽은 것이고, 제가 스킬을 실제로 올려보지 않았습니다. 업로드 절차가 문서대로 매끄러운지는 확인 못 했습니다. ②색인에는 정식과 베타 두 갈래가 같이 올라와 있습니다 — 이 글은 정식 쪽 안내 문서를 기준으로 했고, 베타 창구는 항목이 더 있을 수 있습니다. ③제한 수치(20개·30MB·64자)는 문서 표기이고 바뀔 수 있습니다. ④"latest면 남이 바꾼다"는 문서 문장을 옮긴 것이지 제가 재현한 사고가 아닙니다. ⑤코드 실행 도구 자체의 요금과 사용 가능 모델은 따로 확인하셔야 합니다.

✨ 버전을 안 적는 순간, 내 서비스의 동작이 남의 손에 갑니다

AI 도구와 비용을 항목별로 뜯어본 글들은 AI 지출 정리 허브에 모아두고 있습니다. 오늘 건은 "기본값이 편한 쪽으로 잡혀 있어서 생기는 사고" 항목에 한 줄을 더한 셈입니다.

출처: Anthropic 공식 개발자 문서 「Skills in the API」(2026-08-19 직접 열람, 144,057바이트) 및 Skills API 엔드포인트 색인. 인용 항목 = 스킬 두 종류 비교표, 버전 스냅샷 규칙, 버전 고정 권고, 로딩 4단계, 요청·환경 제한. 수치와 규칙은 문서 표기이며 필자가 직접 업로드해 검증한 것이 아닙니다.