Claude API 스킬

claude-api 스킬은 두 가지 Anthropic 서피스에서 애플리케이션을 구축하기 위한 상세하고 최신의 참조 자료를 Claude에 제공하는 오픈소스 Agent Skill입니다:

• 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에 번들로 포함되어 있으며, 오픈소스 Anthropic 스킬 저장소에서도 제공되므로 Agent Skills를 지원하는 모든 환경에 설치할 수 있습니다.

이 스킬은 컨텍스트를 효율적으로 유지하기 위해 점진적 공개(progressive disclosure)를 사용합니다. Claude는 모든 것을 한 번에 로드하는 대신, 프로젝트의 언어, 서피스(Messages API 또는 Managed Agents), 그리고 당면한 특정 작업(도구 사용, 스트리밍, 배치 등)과 관련된 문서만 로드합니다.

스킬이 제공하는 것

트리거되면 이 스킬은 Claude에 다음을 제공합니다:

Messages API의 경우:

• 언어별 SDK 문서: 프로젝트 언어에 맞는 설치, 빠른 시작, 일반적인 패턴, 오류 처리
• 도구 사용 가이드: 함수 호출에 대한 언어별 예제와 개념적 기초(지원되는 경우 베타 tool runner 포함)
• 스트리밍 패턴: 채팅 UI 구축 및 점진적 표시 처리를 위한 구현 세부 사항
• 배치 처리: 50% 비용으로 수행하는 오프라인 배치 처리
• 프롬프트 캐싱: 접두사 안정성 설계, 중단점 배치, 캐시를 조용히 무효화하는 요소 점검
• 모델 마이그레이션: 최신 Claude 모델로 마이그레이션하기 위한 단계별 가이드(Claude Opus 5.5, Claude Sonnet 5.5, Claude Haiku 5.5 및 Claude Fable 5.1의 호환성을 깨는 변경 사항 및 동작 변화 포함)
• 보존된 사고 마이그레이션: 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에서만 사용할 수 있습니다(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)을 검사하여 프로젝트의 언어를 자동으로 감지하고 적절한 문서를 로드합니다.

프로젝트에서 여러 언어를 사용하는 경우 Claude는 어떤 언어가 적용되는지 묻습니다. 지원되지 않는 언어(Rust, Swift, C++)의 경우 이 스킬은 cURL/원시 HTTP 예제를 제공합니다.

스킬 사용 방법

Claude Code에서 (번들 포함)

이 스킬은 Claude Code와 함께 제공되며 설치가 필요하지 않습니다. Claude API로 무언가를 구축하는 데 도움을 Claude에 요청하거나, 프로젝트가 이미 Anthropic SDK를 임포트하고 있는 경우 스킬이 자동으로 활성화됩니다.

직접 호출할 수도 있습니다:

Claude Code에서 번들 스킬이 작동하는 방식에 대한 자세한 내용은 Claude Code 스킬 문서를 참조하세요.

스킬 저장소에서

스킬 소스는 Anthropic 스킬 저장소에서 제공됩니다. npx 명령을 사용하여 설치할 수 있습니다:

npx skills add https://github.com/anthropics/skills --skill claude-api

또는 Claude Code에 Claude Code 플러그인으로 설치하도록 요청할 수 있습니다:

/plugin marketplace add anthropics/skills
/plugin install claude-api@anthropic-agent-skills

최신 Claude 모델로 마이그레이션

Claude API 스킬은 코드베이스 전체에 걸쳐 Claude 모델 마이그레이션을 수행할 수 있습니다. /claude-api migrate로 직접 호출하세요:

범위 확인 질문을 건너뛰기 위해 특정 범위를 미리 전달할 수도 있습니다:

범위가 모호한 경우(예: 단순히 /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 패턴을 구조화된 출력으로 변환합니다
• 베타 헤더 정리: 대상 모델에 필요하지 않은 베타 헤더(예: effort-2025-11-24, fine-grained-tool-streaming-2025-05-14, interleaved-thinking-2025-05-14)를 제거하고, client.beta.messages.create()에서 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" 처리를 추가하고 폴백 재시도 경로(서버 측 fallbacks 매개변수(일반적으로 "default" 모드), SDK 거부 폴백 미들웨어 또는 폴백 크레딧 재시도)를 설정하며, 이전 프리뷰 형태를 기준으로 작성된 폴백 코드를 업데이트합니다

편집하는 동안 이 스킬은 각 변경 사항과 그 동기를 인라인으로 설명합니다. 완료되면 수동 검증이 필요한 항목(일반적으로 통합 테스트, 길이 제어 프롬프트 조정, 비용/속도 제한 기준 재설정)의 체크리스트를 생성합니다.

스킬이 적용하는 모델별 변경 사항의 전체 목록은 Claude Opus 5에서 Claude Opus 5.5로 마이그레이션, Claude Opus 4.8에서 Claude Opus 5.5로 마이그레이션, Claude Sonnet 5에서 Claude Sonnet 5.5로 마이그레이션, Claude Haiku 5.5 마이그레이션 가이드 및 Claude Fable 5.1 및 Claude Mythos 5.1 마이그레이션 가이드를 참조하세요.

보존된 사고에 대한 통합 확인

"Preserved thinking"(보존된 사고)은 system 프롬프트, tools 및 그 앞의 메시지가 변경되지 않은 동안에만 thinking 블록을 유효하게 유지합니다. 코드가 해당 기록을 편집하는 위치를 찾아 수정하려면 요청을 구성하는 저장소를 열고 preserved-thinking-migration 하위 명령을 호출하세요:

스킬은 다섯 단계로 작업합니다:

1. 범위 지정: 통합이 영향을 받는지 확인한 다음, API가 의도적인 편집을 보고하는지 확인하기 위해 세 개의 테스트 요청을 보냅니다.
2. 찾기: 사용자 자신의 멀티턴 세션 몇 개를 캡처하고, 연속된 요청을 비교하여 코드가 접두사를 편집하는 각 위치를 나열합니다.
3. 측정: "drop_block"으로 세션을 재생하고 어떤 대화가 어느 턴에서 왜 thinking 블록을 잃는지 보고합니다.
4. 수정: 한 번에 하나의 편집을 접두사를 편집하지 않고 변경하기의 해당 패턴으로 대체하고, 각 변경 후 다시 측정합니다.
5. 보고: 각 원인, 이에 대해 수행한 변경 사항, 그리고 변경 전후의 수치를 요약합니다.

프로젝트에 평가(eval)가 있는 경우, 스킬은 thinking 블록이 삭제된 경우와 삭제되지 않은 경우의 점수와 토큰 사용량도 비교합니다.

테스트 요청과 재생은 실제 Messages API 요청이며 모델의 일반 요금으로 청구됩니다. 각 재생은 소수의 출력 토큰만 요청하고 tool_choice를 none으로 설정하므로 도구가 실행되지 않습니다. 스킬은 요청을 보내기 전에 비용을 알리고 승인을 요청합니다.

Managed Agent 설정

새로운 Managed Agent를 처음부터 스캐폴딩하려면 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가 처리하도록 돕는 작업의 예시입니다:

채팅 애플리케이션 구축:

기존 프로젝트 마이그레이션:

새로운 Managed Agent 온보딩:

각 경우에 이 스킬은 관련 언어별 문서를 로드하고 현재 API 패턴과 모범 사례를 사용하여 Claude의 구현을 안내합니다.

다음 단계