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% 비용의 오프라인 배치 처리
• 프롬프트 캐싱: 접두사 안정성 설계, 브레이크포인트 배치, 조용한 무효화 요인(silent-invalidator) 감사
• 모델 마이그레이션: 최신 Claude 모델로 마이그레이션하기 위한 단계별 가이드(Claude Opus 5의 호환성이 깨지는 변경 사항 및 동작 변화 포함)
• 현재 모델 정보: 모델 ID, "context window"(컨텍스트 윈도우) 크기, 가격
• 일반적인 함정: 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-api

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

스킬 저장소에서

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

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

또는 Claude Code 플러그인으로 설치할 수 있습니다:

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

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

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

/claude-api migrate this project to claude-opus-5

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

/claude-api migrate everything under src/ to claude-opus-5
/claude-api migrate apps/api.py and apps/worker.py to claude-opus-5

범위가 모호한 경우(예: 단순히 /claude-api migrate to claude-opus-5만 입력한 경우), 이 스킬은 파일을 편집하기 전에 전체 작업 디렉터리, 특정 하위 디렉터리 또는 명시적 파일 목록 중에서 선택하도록 요청합니다. 이는 Messages API와 Managed Agents 호출자 모두에 적용됩니다.

이 스킬은 다음을 처리합니다:

• 모델 ID 교체: 지원되는 모든 언어에서 타입이 지정된 SDK 상수(Model.CLAUDE_OPUS_4_8 → Model.CLAUDE_OPUS_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"}로 변환합니다
• 프리필 대체: 해당되는 경우 어시스턴트 메시지 프리필 패턴을 구조화된 출력으로 변환합니다
• 베타 헤더 정리: 대상 모델에 필요하지 않은 베타 헤더(예: 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 또는 Claude Opus 5인 경우 응답 콘텐츠를 읽기 전에 stop_reason: "refusal" 처리를 추가하고 폴백 재시도 경로를 설정하며(일반적으로 "default" 모드의 서버 측 fallbacks 파라미터, SDK 거부 폴백 미들웨어 또는 폴백 크레딧 재시도), 이전 프리뷰 형태에 맞춰 작성된 폴백 코드를 업데이트합니다

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

이 스킬이 적용하는 모델별 변경 사항의 전체 목록은 Claude Opus 4.8에서 Claude Opus 5로 마이그레이션을 참조하세요.

Managed Agent 설정

새로운 Managed Agent를 처음부터 스캐폴딩하려면 managed-agents-onboard 하위 명령을 호출하세요:

/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가 처리하도록 돕는 작업의 예시입니다:

채팅 애플리케이션 구축:

Build a streaming chat UI with the Claude API in TypeScript

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

/claude-api migrate this codebase to claude-opus-5 and re-tune effort

새로운 Managed Agent 온보딩:

/claude-api managed-agents-onboard

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

다음 단계