---
title: Claude API 스킬
url: https://platform.claude.com/docs/ko/agents-and-tools/agent-skills/claude-api-skill
description: Claude API 및 Claude Managed Agents로 애플리케이션을 구축하기 위한 최신 API 참조 자료, SDK 문서, 모범 사례를 Claude에 제공하는 오픈소스 Agent Skill입니다.
---
`claude-api` 스킬은 두 가지 Anthropic 서피스에서 애플리케이션을 구축하기 위한 상세하고 최신의 참조 자료를 Claude에 제공하는 오픈소스 [Agent Skill](https://platform.claude.com/docs/ko/agents-and-tools/agent-skills/overview)입니다:
* **Messages API:** 단일 요청, 스트리밍 채팅, "tool use"(도구 사용), 배치 처리, "prompt caching"(프롬프트 캐싱), 구조화된 출력, 커스텀 에이전트 루프를 위한 기본 서피스입니다.
* **Claude Managed Agents (베타):** Anthropic이 호스팅하는 도구 실행, 영구적인 에이전트 구성, 세션별 샌드박스를 갖춘 서버 관리형 상태 유지 에이전트를 위한 Anthropic 호스팅 서피스입니다.
Messages API와 Managed Agents 모두에 대해 Python, TypeScript, C#, Go, Java, PHP, Ruby, cURL의 8개 프로그래밍 언어를 지원합니다.
이 스킬은 [Claude Code](https://code.claude.com/docs/en/overview)에 번들로 포함되어 있으며, 오픈소스 [Anthropic 스킬 저장소](https://github.com/anthropics/skills)에서도 제공되므로 Agent Skills를 지원하는 모든 환경에 설치할 수 있습니다.
이 스킬은 컨텍스트를 효율적으로 유지하기 위해 [점진적 공개(progressive disclosure)](https://platform.claude.com/docs/ko/agents-and-tools/agent-skills/overview#how-skills-work)를 사용합니다. Claude는 모든 것을 한 번에 로드하는 대신, 프로젝트의 언어, 서피스(Messages API 또는 Managed Agents), 그리고 당면한 특정 작업(도구 사용, 스트리밍, 배치 등)과 관련된 문서만 로드합니다.
## 스킬이 제공하는 것
트리거되면 이 스킬은 Claude에 다음을 제공합니다:
**Messages API의 경우:**
* **언어별 SDK 문서:** 프로젝트 언어에 맞는 설치, 빠른 시작, 일반적인 패턴, 오류 처리
* **도구 사용 가이드:** 함수 호출에 대한 언어별 예제와 [개념적 기초](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/overview)(지원되는 경우 베타 tool runner 포함)
* **스트리밍 패턴:** 채팅 UI 구축 및 점진적 표시 처리를 위한 구현 세부 사항
* **배치 처리:** 50% 비용으로 수행하는 오프라인 배치 처리
* **프롬프트 캐싱:** 접두사 안정성 설계, 중단점 배치, 캐시를 조용히 무효화하는 요소 점검
* **모델 마이그레이션:** 최신 Claude 모델로 마이그레이션하기 위한 단계별 가이드([Claude Opus 5.5](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#migrating-from-claude-opus-5), [Claude Sonnet 5.5](https://platform.claude.com/docs/ko/models/sonnet-5-5/migration-guide#migrating-from-claude-sonnet-5), [Claude Haiku 5.5](https://platform.claude.com/docs/ko/models/haiku-5-5/migration-guide) 및 [Claude Fable 5.1](https://platform.claude.com/docs/ko/models/fable-5-1/migration-guide)의 호환성을 깨는 변경 사항 및 동작 변화 포함)
* **보존된 사고 마이그레이션:** `thinking` 블록을 무효화하는 기록 편집을 찾고, 측정하고, 수정하는 기능으로, `/claude-api preserved-thinking-migration` 하위 명령을 통해 사용할 수 있습니다
* **최신 모델 정보:** 모델 ID, 컨텍스트 윈도우 크기, 가격
* **일반적인 함정:** API 통합 시 자주 발생하는 실수를 피하기 위한 상세 가이드
**Managed Agents(베타)의 경우:**
* **온보딩 흐름:** 새로운 Managed Agent를 처음부터 설정하기 위한 인터뷰 기반 안내로, `/claude-api managed-agents-onboard` 하위 명령을 통해 사용할 수 있습니다
* **언어별 Managed Agents 문서:** Python, TypeScript, C#, Go, Java, PHP, Ruby, cURL에 대한 영구 에이전트 생성, 세션 시작, 이벤트 스트리밍, 도구 확인 처리
* **클라이언트 패턴:** 무손실 스트림 재연결, `processed_at` 대기/처리 게이트, 인터럽트 처리, 파일 마운트 주의 사항, 자격 증명 처리
* **배포 제약 사항:** Managed Agents는 Claude API와 [Claude Platform on AWS](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws)에서만 사용할 수 있습니다(Amazon Bedrock, Google Cloud, Microsoft Foundry에서는 사용 불가). 이 스킬은 다른 배포 환경의 경우 Messages API와 도구 사용으로 안내합니다.
## 스킬이 활성화되는 시점
이 스킬은 두 가지 방식으로 활성화됩니다:
**자동 활성화**는 다음과 같은 경우에 발생합니다:
* 코드가 Anthropic SDK를 임포트하는 경우(Python의 경우 `anthropic`, TypeScript/JavaScript의 경우 `@anthropic-ai/sdk`)
* Claude API, Anthropic SDK 또는 Managed Agents로 무언가를 구축, 디버그 또는 최적화하는 데 도움을 Claude에 요청하는 경우
* 파일에서 Claude 기능(프롬프트 캐싱, 적응형 사고, 압축, 도구 사용, 배치, 파일, 인용, 메모리) 또는 모델 참조를 추가, 수정 또는 조정하는 경우
**수동 호출**은 스킬이 설치된 모든 환경에서 `/claude-api`(선택적으로 하위 명령 또는 설명 문구와 함께)를 입력하여 수행합니다.
이 스킬은 일반 프로그래밍 작업, ML/데이터 과학 작업, 또는 다른 AI SDK(예: OpenAI)를 임포트하는 코드에 대해서는 활성화되지 않습니다.
## 지원 언어
이 스킬은 프로젝트 파일(예: Python의 경우 `requirements.txt`, TypeScript의 경우 `tsconfig.json`, Go의 경우 `go.mod`)을 검사하여 프로젝트의 언어를 자동으로 감지하고 적절한 문서를 로드합니다.
| 언어 | Messages API SDK | 도구 러너 | Managed Agents |
| ---------- | ---------------- | ------ | -------------- |
| Python | 예 | 예 (베타) | 예 (베타) |
| TypeScript | 예 | 예 (베타) | 예 (베타) |
| C# | 예 | 예 (베타) | 예 (베타) |
| Go | 예 | 예 (베타) | 예 (베타) |
| Java | 예 | 예 (베타) | 예 (베타) |
| PHP | 예 | 예 (베타) | 예 (베타) |
| Ruby | 예 | 예 (베타) | 예 (베타) |
| cURL | 예 | 해당 없음 | 예 (베타) |
프로젝트에서 여러 언어를 사용하는 경우 Claude는 어떤 언어가 적용되는지 묻습니다. 지원되지 않는 언어(Rust, Swift, C++)의 경우 이 스킬은 cURL/원시 HTTP 예제를 제공합니다.
## 스킬 사용 방법
### Claude Code에서 (번들 포함)
이 스킬은 [Claude Code](https://code.claude.com/docs/en/overview)와 함께 제공되며 설치가 필요하지 않습니다. Claude API로 무언가를 구축하는 데 도움을 Claude에 요청하거나, 프로젝트가 이미 Anthropic SDK를 임포트하고 있는 경우 스킬이 자동으로 활성화됩니다.
직접 호출할 수도 있습니다:
Claude Code에서 이 스킬을 사용하세요
```text
/claude-api
```
Claude Code에서 번들 스킬이 작동하는 방식에 대한 자세한 내용은 [Claude Code 스킬 문서](https://code.claude.com/docs/en/skills#bundled-skills)를 참조하세요.
### 스킬 저장소에서
스킬 소스는 [Anthropic 스킬 저장소](https://github.com/anthropics/skills)에서 제공됩니다. `npx` 명령을 사용하여 설치할 수 있습니다:
```bash
npx skills add https://github.com/anthropics/skills --skill claude-api
```
또는 Claude Code에 [Claude Code 플러그인](https://code.claude.com/docs/en/plugins)으로 설치하도록 요청할 수 있습니다:
Claude Code가 대신 설치하도록 하세요
```text
anthropics/skills 플러그인 마켓플레이스에서 claude-api 플러그인을 설치해 줘
```
```text wrap
/plugin marketplace add anthropics/skills
/plugin install claude-api@anthropic-agent-skills
```
## 최신 Claude 모델로 마이그레이션
Claude API 스킬은 코드베이스 전체에 걸쳐 Claude 모델 마이그레이션을 수행할 수 있습니다. `/claude-api migrate`로 직접 호출하세요:
Claude Code가 코드를 대신 마이그레이션하도록 하세요
```text
/claude-api migrate 이 프로젝트를 최신 Claude Opus 모델로 마이그레이션해 줘
```
범위 확인 질문을 건너뛰기 위해 특정 범위를 미리 전달할 수도 있습니다:
Claude Code가 코드를 대신 마이그레이션하도록 하세요
```text
/claude-api migrate src/ 아래의 모든 항목을 최신 Claude Opus 모델로 마이그레이션해 줘
```
Claude Code가 코드를 대신 마이그레이션하도록 하세요
```text
/claude-api migrate apps/api.py와 apps/worker.py를 최신 Claude Opus 모델로 마이그레이션해 줘
```
범위가 모호한 경우(예: 단순히 `/claude-api migrate to claude-opus-5-5`만 입력한 경우), 스킬은 파일을 편집하기 전에 전체 작업 디렉터리, 특정 하위 디렉터리 또는 명시적인 파일 목록 중에서 선택하도록 요청합니다. 이는 Messages API 호출자와 Managed Agents 호출자 모두에 적용됩니다.
이 스킬은 다음을 처리합니다:
* **모델 ID 교체:** 지원되는 모든 언어에서 타입이 지정된 SDK 상수(`Model.CLAUDE_OPUS_4_8` → `Model.CLAUDE_OPUS_5_5`)를 포함하여 교체합니다. 편집 전에 각 파일을 호출자, 모델 정의자, 불투명 문자열 참조 중 하나로 분류합니다
* **클라우드 플랫폼 감지:** 플랫폼별 모델 ID 형식(예: Amazon Bedrock의 `anthropic.` 접두사)을 유지하고, 파트너가 운영하는 플랫폼에서 사용할 수 없는 기능에 대한 변경은 건너뜁니다
* **호환성을 깨는 매개변수 변경:** Claude Opus 4.8 및 Claude Opus 4.7에서 `temperature`, `top_p`, `top_k`를 제거하고, `thinking: {type: "enabled", budget_tokens: N}`을 `thinking: {type: "adaptive"}`로 변환하는 등의 작업을 수행합니다
* **Prefill 대체:** 해당하는 경우 어시스턴트 메시지 prefill 패턴을 [구조화된 출력](https://platform.claude.com/docs/ko/build-with-claude/structured-outputs)으로 변환합니다
* **베타 헤더 정리:** 대상 모델에 필요하지 않은 베타 헤더(예: `effort-2025-11-24`, `fine-grained-tool-streaming-2025-05-14`, `interleaved-thinking-2025-05-14`)를 제거하고, `client.beta.messages.create()` (go: `client.Beta.Messages.New()`; java: `client.beta().messages().create()`; csharp: `client.Beta.Messages.Create()`; php: `$client->beta->messages->create()`)에서 `client.messages.create()` (go: `client.Messages.New()`; java: `client.messages().create()`; csharp: `client.Messages.Create()`; php: `$client->messages->create()`)로 다시 전환합니다
* **Effort 보정:** 대상 모델에 맞는 `output_config.effort` 시작점을 권장합니다(예: Claude Opus 5에서는 기본값 `high`, Claude Opus 4.8 및 Claude Opus 4.7의 코딩 및 에이전트 사용 사례에서는 `xhigh`)
* **프롬프트 동작 조정:** 대상 모델에서 다르게 동작할 수 있는 길이 제어, 도구 트리거, 서브에이전트, 지시 따르기 관련 프롬프트를 표시합니다
* **암묵적 기본값 처리:** Claude Opus 4.8 및 Claude Opus 4.7에서 추론 내용이 사용자에게 표시되는 경우 사고 요약(`thinking.display: "summarized"`)을 다시 활성화합니다
* **거부 폴백 구성:** 대상이 Claude Fable 5.1, Claude Fable 5, Claude Opus 5.5, Claude Opus 5 또는 Claude Sonnet 5.5인 경우 응답 콘텐츠를 읽기 전에 `stop_reason: "refusal"` 처리를 추가하고 [폴백 재시도 경로](https://platform.claude.com/docs/ko/build-with-claude/refusals-and-fallback)(서버 측 `fallbacks` 매개변수(일반적으로 `"default"` 모드), SDK 거부 폴백 미들웨어 또는 폴백 크레딧 재시도)를 설정하며, 이전 프리뷰 형태를 기준으로 작성된 폴백 코드를 업데이트합니다
편집하는 동안 이 스킬은 각 변경 사항과 그 동기를 인라인으로 설명합니다. 완료되면 수동 검증이 필요한 항목(일반적으로 통합 테스트, 길이 제어 프롬프트 조정, 비용/속도 제한 기준 재설정)의 체크리스트를 생성합니다.
스킬이 적용하는 모델별 변경 사항의 전체 목록은 [Claude Opus 5에서 Claude Opus 5.5로 마이그레이션](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#migrating-from-claude-opus-5), [Claude Opus 4.8에서 Claude Opus 5.5로 마이그레이션](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#migrating-from-claude-opus-4-8), [Claude Sonnet 5에서 Claude Sonnet 5.5로 마이그레이션](https://platform.claude.com/docs/ko/models/sonnet-5-5/migration-guide#migrating-from-claude-sonnet-5), [Claude Haiku 5.5 마이그레이션 가이드](https://platform.claude.com/docs/ko/models/haiku-5-5/migration-guide) 및 [Claude Fable 5.1 및 Claude Mythos 5.1 마이그레이션 가이드](https://platform.claude.com/docs/ko/models/fable-5-1/migration-guide)를 참조하세요.
## 보존된 사고에 대한 통합 확인
"[Preserved thinking](https://platform.claude.com/docs/ko/build-with-claude/preserved-thinking)"(보존된 사고)은 `system` 프롬프트, `tools` 및 그 앞의 메시지가 변경되지 않은 동안에만 `thinking` 블록을 유효하게 유지합니다. 코드가 해당 기록을 편집하는 위치를 찾아 수정하려면 요청을 구성하는 저장소를 열고 `preserved-thinking-migration` 하위 명령을 호출하세요:
Claude Code가 코드를 대신 확인하도록 하세요
```text
/claude-api preserved-thinking-migration
```
스킬은 다섯 단계로 작업합니다:
1. **범위 지정:** 통합이 영향을 받는지 확인한 다음, API가 의도적인 편집을 보고하는지 확인하기 위해 세 개의 테스트 요청을 보냅니다.
2. **찾기:** 사용자 자신의 멀티턴 세션 몇 개를 캡처하고, 연속된 요청을 비교하여 코드가 접두사를 편집하는 각 위치를 나열합니다.
3. **측정:** `"drop_block"`으로 세션을 재생하고 어떤 대화가 어느 턴에서 왜 `thinking` 블록을 잃는지 보고합니다.
4. **수정:** 한 번에 하나의 편집을 [접두사를 편집하지 않고 변경하기](https://platform.claude.com/docs/ko/build-with-claude/preserved-thinking#replace-prefix-edits)의 해당 패턴으로 대체하고, 각 변경 후 다시 측정합니다.
5. **보고:** 각 원인, 이에 대해 수행한 변경 사항, 그리고 변경 전후의 수치를 요약합니다.
프로젝트에 평가(eval)가 있는 경우, 스킬은 `thinking` 블록이 삭제된 경우와 삭제되지 않은 경우의 점수와 토큰 사용량도 비교합니다.
테스트 요청과 재생은 실제 Messages API 요청이며 모델의 일반 요금으로 청구됩니다. 각 재생은 소수의 출력 토큰만 요청하고 `tool_choice`를 `none`으로 설정하므로 도구가 실행되지 않습니다. 스킬은 요청을 보내기 전에 비용을 알리고 승인을 요청합니다.
## Managed Agent 설정
새로운 Managed Agent를 처음부터 스캐폴딩하려면 `managed-agents-onboard` 하위 명령을 호출하세요:
Claude Code가 에이전트를 대신 설정하도록 하세요
```text
/claude-api managed-agents-onboard
```
이 스킬은 Managed Agents의 멘탈 모델(Agent 구성 대 Session)을 안내하고, 에이전트 구성을 템플릿화하고, 환경과 도구를 구성하고, 세션 루프를 설정하고, 사용 언어에 맞는 실행 가능한 코드를 생성하는 인터뷰를 진행합니다. 또한 이 스킬은 필수적인 **Agent(한 번) → Session(매 실행)** 흐름도 다룹니다. `model`, `system`, `tools`는 세션이 아닌 에이전트에 위치하며, 에이전트는 한 번 생성하고 ID로 참조해야 합니다.
Managed Agents에는 `managed-agents-2026-04-01` 베타 헤더가 필요하며, SDK는 모든 `client.beta.agents.*`, `client.beta.environments.*`, `client.beta.sessions.*`, `client.beta.vaults.*` 호출에 대해 이를 자동으로 설정합니다.
## 사용 예시
다음은 이 스킬이 Claude가 처리하도록 돕는 작업의 예시입니다:
**채팅 애플리케이션 구축:**
Claude Code가 대신 구축하도록 하세요
```text
TypeScript로 Claude API를 사용하는 스트리밍 채팅 UI를 구축해 줘
```
**기존 프로젝트 마이그레이션:**
Claude Code가 코드를 대신 마이그레이션하도록 하세요
```text
/claude-api migrate 이 코드베이스를 최신 Claude Opus 모델로 마이그레이션하고 effort를 다시 조정해 줘
```
**새로운 Managed Agent 온보딩:**
Claude Code가 에이전트를 대신 설정하도록 하세요
```text
/claude-api managed-agents-onboard
```
각 경우에 이 스킬은 관련 언어별 문서를 로드하고 현재 API 패턴과 모범 사례를 사용하여 Claude의 구현을 안내합니다.
## 다음 단계
Agent Skills의 작동 방식과 점진적 공개 모델에 대해 알아보세요
지원되는 모든 언어에 대한 공식 Anthropic SDK를 살펴보세요
GitHub의 공개 Anthropic 스킬 저장소를 탐색하세요