클로드 API로 작은 자동화를 만들면 몇 달 뒤 “모델을 찾을 수 없다”는 오류를 만나기 쉽습니다. 모델이 바뀔 때마다 이름뿐 아니라 쓸 수 있는 설정도 바뀌기 때문입니다. claude-api는 클로드 API 코드를 짤 때 최신 모델 이름, 요금, 바뀐 설정을 읽어 오게 하는 Anthropic 공식 스킬입니다. 클로드 코드에는 처음부터 들어 있어서 따로 깔 것이 없고, 스킬은 무료지만 쓸 때마다 클로드 사용량이 듭니다. 가상의 반찬가게 리뷰로 같은 요청을 스킬을 막고·켜고 모두 8번 보낸 기록입니다.
- 새 스크립트를 만들 때는 스킬이 없어도 4번 모두 가장 싼 하이쿠 5.5와 배치 API(50% 할인)를 골랐고, 검사 서버에서 12건이 모두 저장됐습니다.
- 옛 코드를 고칠 때 갈렸습니다. 검사 서버에서 스킬 없이 고친 2번은 응답의 첫 블록을 그대로 읽어, 응답이 생각(thinking) 블록으로 시작하면 멈췄습니다. 스킬을 켠 2번은 글 블록을 골라 읽고 구조화 출력으로 바꿔 12건을 저장했습니다.
- 스킬을 켜면 만드는 비용이 늘었습니다(API 단가로 한 번에 0.04달러 → 0.26~0.28달러). 클로드 코드에서는 끄지만 않으면 알아서 불렸습니다(4번 중 4번).
결과부터 보기: 같은 요청 8번
요청은 두 가지입니다. 하나는 새 분류 스크립트 만들기, 다른 하나는 2025년식 옛 스크립트를 최신 하이쿠로 고치기입니다. 요청마다 스킬을 막고 2번, 켜고 2번 보냈고, 결과물은 실제 API 대신 요청을 검사하는 서버로 돌려 봤습니다. 영상은 요청 두 가지, 새로 만들기 결과, 옛 코드 고치기에서 달라진 줄, 검사 서버 실행 화면, 결과 표 순서입니다.
직접 눌러 보기: 클로드 API 옛 코드 점검기. 파이썬 코드를 붙여 넣으면 하이쿠 5.5로 바꿀 때 오류가 나는 줄을 찾아 줍니다. 이번 실험의 옛 코드, 스킬 없이 고친 코드, 스킬로 고친 코드를 예시 버튼으로 넣어 볼 수 있습니다.
직접 실행 확인한 날짜 2026-10-21
- 실행 환경
- macOS 26.1 · Claude Code 2.1.299 · Sonnet 5.5 · 생각 깊이 중간 (8번 모두 같은 설정) · anthropic 파이썬 SDK 1.17.0
- 설치 난이도
- 클로드 코드에는 기본 포함. 다른 곳은 플러그인 설치 두 줄(공식 문서 기준)
- 비용
- 스킬은 무료. 이번 요청은 스킬을 켜면 한 번에 API 단가로 0.26~0.43달러어치(막으면 0.04~0.19달러어치)
- 확인 방법
- 실제 API 키 없이, 공식 하이쿠 5.5 이전 안내의 400 오류 규칙을 넣은 요청 검사 서버로 실행. 분류가 맞았는지는 보지 않음
- 라이선스
- Apache-2.0 · anthropics/skills 저장소(별 18만 2천여 개, 2026-10-21 기준)
claude-api 스킬에 들어 있는 것
스킬 하나에 파일이 96개(약 2.2MB) 들어 있습니다. 처음에는 SKILL.md(616줄)만 읽고, 프로젝트 언어와 할 일에 맞는 문서만 골라 더 읽습니다. 이번 실행에서도 파이썬 문서 한두 개만 열었습니다. 공식 문서에 따르면 anthropic SDK를 불러오는 코드가 있거나, 클로드 API로 무언가 만들어 달라고 하면 저절로 켜집니다. OpenAI 같은 다른 회사 SDK 코드에는 켜지지 않습니다.
| 들어 있는 것 | 하는 일 |
|---|---|
| 모델 목록(shared/models.md) | 지금 쓸 수 있는 모델 이름, 은퇴한 모델, 요금, 컨텍스트 길이. “이름을 추측하지 말 것”이 첫 줄 |
| 언어별 SDK 문서 | 파이썬·타입스크립트·자바·고·루비·PHP·C#·cURL 8가지. 설치, 도구 호출, 스트리밍, 배치, 파일 API |
| 바뀐 API 표 | 예전 방식과 지금 방식을 나란히 둠. 예: 생각 예산(budget_tokens)은 최신 모델에서 400 오류, adaptive로 |
| 비용 줄이기 문서 | 배치 API(50% 할인), 프롬프트 캐싱, 모델·effort 고르기 |
| 매니지드 에이전트 문서 | Anthropic 서버에서 도는 에이전트(베타) 만들기·보안 점검 |
스킬 이름 뒤에 하위 명령을 붙여 특정 일만 시킬 수도 있습니다. 명령 이름은 그대로 씁니다(SKILL.md·공식 문서 기준, 이번 실험에서는 하위 명령을 쓰지 않고 말로 요청함).
| 하위 명령 | 하는 일 |
|---|---|
/claude-api migrate | 옛 모델 코드를 새 모델로 옮김. 고칠 범위(폴더·파일)를 먼저 묻고, 바꾼 이유를 줄마다 설명 |
/claude-api prompt-audit | 프롬프트·CLAUDE.md에 남은 옛 모델용 문장을 찾아 보고서와 고칠 안을 냄 |
/claude-api cost-optimize | 이미 있는 코드의 실행 비용을 줄임 |
따라 해 보기: 요청문과 실습 재료
이번에 쓴 두 요청입니다. 리뷰 파일(reviews.csv)과 옛 스크립트(classify_old.py)가 든 폴더에서 클로드 코드에 보냅니다.
동네 반찬가게를 하고 있습니다. 배달앱 리뷰가 매일 수백 개씩 쌓여서 손으로 못 읽겠어요.
reviews.csv(id,review)를 읽어서, 클로드 API로 리뷰마다 감정(긍정/부정/중립)과 불만 유형(맛/양/배달/포장/가격/서비스/없음)을 붙여 results.csv(id,review,감정,불만유형)로 저장하는 파이썬 스크립트 classify.py를 만들어 주세요.
매일 밤 한 번 돌리고 결과는 다음 날 아침에 보면 됩니다. 비용은 최대한 아끼고 싶어요.
API 키는 ANTHROPIC_API_KEY 환경 변수에 있고, anthropic 파이썬 패키지는 설치돼 있습니다.
지금은 키가 없으니 스크립트는 실행하지 말고 만들기만 해 주세요.작년에 만든 리뷰 분류 스크립트 classify_old.py가 이제 안 돌아요. 모델을 찾을 수 없다는 오류가 나요.
최신 하이쿠 모델로 돌아가게 이 파일 하나만 고쳐 주세요. 결과 파일 모양(results.csv)은 그대로 두고 싶어요.
지금은 API 키가 없으니 실행하지 말고 고치기만 해 주세요.좋은 답이라면 모델 이름만 바꾸지 않고, temperature·미리 채운 답(프리필)을 지우고, 응답에서 글 블록을 골라 읽도록 고칩니다. 실습 재료(zip)에는 요청문 두 개, 리뷰 12건, 옛 스크립트, 채점 기준, 요청 검사 서버를 넣었습니다.
1단계. 스킬이 들어 있는지 확인 (약 1분)
이 단계에서는 클로드 코드에 claude-api 스킬이 있는지 봅니다. 클로드 코드 대화창에서 /를 치고 claude-api를 찾습니다.
/claude-api이렇게 나오면 성공 공식 문서에 따르면 명령 목록에 /claude-api가 보입니다. 이번에는 대화창 대신 화면 없는 실행(2.1.299)의 시작 기록에서 기본 스킬 목록에 claude-api가 있는 것을 확인했습니다.
- 목록에 없으면: 클로드 코드가 오래된 버전일 수 있습니다. 클로드 코드 설치 방법대로 최신으로 올립니다.
- 클로드 앱(claude.ai)이나 다른 에이전트에서 쓰려면 아래 명령으로 anthropics/skills 마켓에서 설치합니다(공식 문서 기준).
/plugin marketplace add anthropics/skills
/plugin install claude-api@anthropic-agent-skills따로 설치한 것이 필요 없어지면 /plugin uninstall claude-api@anthropic-agent-skills로 지웁니다(클로드 코드 플러그인 문서 기준). 클로드 코드에 기본으로 든 스킬은 지울 필요가 없습니다.
2단계. 새 스크립트 만들기: 스킬 없이도 통과 (약 1분)
이 단계에서는 첫 번째 요청을 보냅니다. 채점 기준은 실행 전에 공식 문서(모델 개요, 하이쿠 5.5 안내, 배치 처리 문서)에서 뽑아 8가지로 고정했습니다. 공식 SDK, 쓸 수 있는 모델 이름, 분류에 맞는 가장 싼 모델, 배치 API, 400 오류 설정 없음, 형식 고정, 키를 코드에 안 씀, 검사 서버 실행입니다.
| 조건 | 스킬이 불렸나 | 고른 모델 | 형식 고정 | 검사 서버 | 비용 1·2(달러) |
|---|---|---|---|---|---|
| 스킬 막음 | – | claude-haiku-5-5 | enum 도구 강제 호출 | 2번 모두 12건 저장 | 0.19 · 0.19 |
| 스킬 켬 | 2번 | claude-haiku-5-5 | 구조화 출력 + effort low | 2번 모두 12건 저장 | 0.43 · 0.38 |
4번 모두 8가지를 채웠습니다. 클로드 코드는 스킬이 없어도 최신 모델 이름을 알고 있었고, “밤에 돌리고 아침에 본다”는 말에서 배치 API를 골랐습니다. 하이쿠 5.5는 분류·추출용으로 안내된 모델이고 요금은 100만 토큰당 입력 0.10달러, 출력 0.50달러부터입니다(10만 토큰 이하 요청 기준). 배치 API는 여기서 다시 절반입니다.
스킬을 켠 쪽은 스킬을 부른 뒤 파이썬 문서를 한두 개 더 읽고 썼습니다. 생각 깊이를 낮추는 effort: "low"와 “생각 토큰도 max_tokens에 들어간다”는 주석이 붙었습니다.
3단계. 옛 코드 고치기: 여기서 갈렸습니다 (약 1분)
이 단계에서는 2025년식 옛 스크립트를 고치게 합니다. 옛 스크립트는 은퇴한 모델 claude-3-5-haiku-20241022를 부르고, temperature=0을 쓰고, 답 앞에 {를 미리 채워 JSON을 받는 흔한 방식입니다.
4번 모두 모델 이름을 claude-haiku-5-5로 바꾸고, temperature와 미리 채운 답을 지웠습니다. 하이쿠 5.5 공식 이전 안내에서 둘 다 400 오류가 나는 설정입니다. 달라진 곳은 응답을 읽는 줄입니다.
model="claude-haiku-5-5",
max_tokens=200,
...
text = msg.content[0].text
data = json.loads(text[text.index("{"):text.rindex("}") + 1]) model="claude-haiku-5-5",
max_tokens=1024,
output_config={"effort": "low", "format": {"type": "json_schema", "schema": SCHEMA}},
...
text = next(b.text for b in msg.content if b.type == "text")
data = json.loads(text)하이쿠 5.5는 생각이 기본으로 켜져 있어서, 응답이 생각(thinking) 블록으로 시작할 수 있습니다. 공식 이전 안내는 “첫 번째 블록을 답으로 읽는 코드라면 종류로 골라 읽으라”고 적어 두었습니다. 스킬을 켠 쪽은 이 항목을 그대로 따랐고, 답에서도 “content[0]을 읽으면 thinking 블록을 잡을 수 있다”고 설명했습니다. max_tokens를 200에서 1024로 올린 것도 같은 이유입니다. 생각 토큰도 max_tokens 안에 들어가서 200이면 답 전에 끊길 수 있습니다. 형식은 구조화 출력(JSON 스키마)으로 고정해, 감정과 불만 유형이 정해진 값으로만 나오게 했습니다.
4단계. 검사 서버로 돌려 보기 (약 1분)
이 단계에서는 고친 스크립트를 실제로 돌립니다. API 키가 없어서, 공식 이전 안내의 400 오류 규칙(temperature, top_p, top_k, 생각 예산, 미리 채운 답)과 은퇴 모델 목록을 넣은 작은 검사 서버를 만들어 그쪽으로 요청을 보냈습니다. 서버는 문서대로 응답 맨 앞에 생각 블록을 붙여 돌려줍니다. 분류 값은 자리 채움 값이라 분류가 맞았는지는 보지 않았습니다.
스킬 없이 고친 2번은 첫 리뷰에서 AttributeError: 'ThinkingBlock' object has no attribute 'text'(생각 블록에는 글이 없다는 뜻)로 멈췄습니다. 공식 이전 안내에 따르면 실제 API에서는 쉬운 요청이면 생각을 건너뛸 수도 있어서 늘 멈추지는 않습니다. 그래서 더 곤란합니다. 어떤 날은 돌고 어떤 날은 멈춥니다. 스킬로 고친 2번은 12건을 모두 저장했습니다.
고치기 전 옛 스크립트는 서버에 닿기도 전에 멈췄습니다. 최신 파이썬 SDK(1.17.0)가 temperature 인자를 받지 않아 TypeError가 났습니다.
| 요청 | 조건 | 스킬 불림 | 검사 서버 | 비용 1·2(달러) |
|---|---|---|---|---|
| 새로 만들기 | 스킬 막음 | – | 2/2 통과 | 0.19 · 0.19 |
| 새로 만들기 | 스킬 켬 | 2/2 | 2/2 통과 | 0.43 · 0.38 |
| 옛 코드 고치기 | 스킬 막음 | – | 0/2 (생각 블록에서 멈춤) | 0.04 · 0.04 |
| 옛 코드 고치기 | 스킬 켬 | 2/2 | 2/2 통과 | 0.26 · 0.28 |
이런 사람에게 권합니다
- ✅ 클로드 API로 만든 자동화(리뷰 분류, 메일 요약, 챗봇)를 새 모델로 옮겨야 하는 사람. 이번에는 “이 파일을 최신 하이쿠로 고쳐 줘”라는 말만으로 스킬이 불려 모델 이름과 바뀐 설정까지 고쳤습니다. 여러 파일이면 공식 문서의
/claude-api migrate명령이 범위를 먼저 묻고 옮깁니다. - ✅ 클로드 코드로 API 코드를 짜는 사람. 이미 들어 있으니 끄지만 않으면 됩니다. 이번에도 4번 모두 저절로 불렸습니다.
- ✅ 클로드 앱이나 다른 코딩 에이전트에서 클로드 API 코드를 짜는 사람. anthropics/skills에서 설치해 같은 문서를 읽게 할 수 있습니다(공식 문서 기준).
- ❌ 오픈AI·제미나이 API로 만드는 사람. 다른 회사 SDK 코드에는 켜지지 않게 되어 있습니다.
한계와 주의할 점
- 실제 API 대신 검사 서버로 돌렸습니다. 요청 모양과 응답 읽는 코드만 확인했고, 분류가 맞는지·실제 비용이 얼마인지는 재지 않았습니다.
- 가상 리뷰 12건, 파이썬, Sonnet 5.5로 조건마다 두 번씩입니다. 다른 언어나 큰 코드베이스에서는 결과가 달라질 수 있습니다.
/claude-api migrate같은 하위 명령은 이번에 쓰지 않았습니다. 하위 명령 설명은 공식 문서와 SKILL.md 기준입니다.
대안
| 방법 | 다른 점 | 이럴 때 고르세요 |
|---|---|---|
| claude-api 스킬(이 글) | 최신 모델·설정 문서를 그때그때 읽고 코드에 반영 | 클로드 API 코드를 만들거나 옮길 때 |
| 공식 이전 안내 직접 읽기 | 하이쿠 5.5 이전 안내처럼 모델마다 체크리스트가 있음 | 고칠 곳이 몇 줄뿐이고 직접 확인하고 싶을 때 |
| 옛 코드 점검기(이 글의 데모) | 붙여 넣은 코드에서 하이쿠 5.5 오류 줄만 찾음 | 고치기 전에 어디가 문제인지만 보고 싶을 때 |
| agent-sdk-dev 플러그인 | 클로드 에이전트 SDK로 에이전트 앱을 만드는 쪽 | API 호출 한두 개가 아니라 에이전트를 만들 때 |
스킬이 무엇인지는 클로드 스킬 사용법, API 요금이 구독과 어떻게 다른지는 클로드 요금제 정리를 보세요.
자주 묻는 질문
클로드 API는 어디서 쓰고, 요금은 얼마인가요?
API 키는 클로드 개발자 콘솔(platform.claude.com)에서 만들고, 쓴 토큰만큼 냅니다. 이번 글의 하이쿠 5.5는 100만 토큰당 입력 0.10달러, 출력 0.50달러부터이고, 배치 API로 보내면 절반입니다(2026-10-21 공식 문서 기준). 키는 코드에 적지 말고 환경 변수에 넣습니다.
“model not found” 오류가 나요
은퇴한 모델 이름을 부르고 있을 가능성이 큽니다. 예를 들어 claude-3-5-haiku-20241022는 2026년 2월 19일에 은퇴했습니다(스킬의 모델 목록 기준). 모델 이름만 바꾸면 temperature나 미리 채운 답 때문에 400 오류가 이어질 수 있습니다. 클로드 코드에 “최신 모델로 고쳐 줘”라고 맡기거나(3단계), 공식 이전 안내를 함께 봅니다.
claude-api 스킬을 따로 설치해야 하나요?
클로드 코드에는 기본으로 들어 있습니다. 클로드 앱이나 다른 에이전트에서 쓸 때만 1단계의 명령으로 설치합니다.
스킬을 켜면 사용량이 늘어나나요?
이번에는 늘었습니다. 스킬 문서를 더 읽기 때문입니다. 새로 만들기는 2배쯤, 옛 코드 고치기는 6배쯤이었습니다. 그 대신 옛 코드 고치기에서는 스킬 없이 고친 코드가 멈추는 문제를 피했습니다.
출처
Claude API skill 공식 문서, anthropics/skills claude-api, 모델 개요, Claude Haiku 5.5 개요, Claude Haiku 5.5 이전 안내 (모두 2026-10-21 확인)