Claude API 스킬

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

• Messages API: 단일 요청, 스트리밍 채팅, 도구 사용, 배치 처리, 프롬프트 캐싱, 구조화된 출력 및 커스텀 에이전트 루프를 위한 기본 서피스입니다.
• Claude Managed Agents(베타): Anthropic이 호스팅하는 도구 실행, 영구 에이전트 구성 및 세션별 샌드박스를 갖춘 서버 관리형 상태 유지 에이전트를 위한 Anthropic 호스팅 서피스입니다.

이 스킬은 Messages API와 Managed Agents 모두에 대해 Python, TypeScript, C#, Go, Java, PHP, Ruby, cURL 등 8개 프로그래밍 언어를 지원합니다.

이 스킬은 Claude Code에 번들로 제공되며, Agent Skills를 지원하는 모든 환경에 설치할 수 있는 오픈 소스 Anthropic 스킬 리포지토리에서도 사용할 수 있습니다.

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



스킬이 제공하는 내용

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

Messages API의 경우:

• 언어별 SDK 문서: 프로젝트 언어에 대한 설치, 빠른 시작, 일반적인 패턴 및 오류 처리
• 도구 사용 가이드: 함수 호출에 대한 언어별 예제 및 개념적 기초(사용 가능한 경우 베타 도구 러너 포함)
• 스트리밍 패턴: 채팅 UI 구축 및 점진적 표시 처리를 위한 구현 세부 정보
• 배치 처리: 50% 비용으로 오프라인 배치 처리
• 프롬프트 캐싱: 접두사 안정성 설계, 중단점 배치 및 무음 무효화 감사
• 모델 마이그레이션: 최신 Claude 모델로 마이그레이션하기 위한 단계별 가이드(Claude Opus 4.8의 주요 변경 사항 및 동작 변화 포함)
• 최신 모델 정보: 모델 ID, 컨텍스트 윈도우 크기 및 가격
• 일반적인 함정: API 통합 시 자주 발생하는 실수를 피하기 위한 상세 가이드

Managed Agents(베타)의 경우:

• 온보딩 플로우: /claude-api managed-agents-onboard 하위 명령을 통해 사용할 수 있는, 새 Managed Agent를 처음부터 설정하기 위한 인터뷰 기반 안내
• 언어별 Managed Agents 문서: Python, TypeScript, C#, Go, Java, PHP, Ruby, cURL에 대한 영구 에이전트 생성, 세션 시작, 이벤트 스트리밍 및 도구 확인 처리
• 클라이언트 패턴: 무손실 스트림 재연결, processed_at 대기/처리 게이트, 인터럽트 처리, 파일 마운트 주의 사항 및 자격 증명 처리
• 배포 제약 사항: Managed Agents는 Claude API 및 AWS의 Claude Platform에서만 사용할 수 있습니다(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-4-8

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

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

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

스킬은 다음을 처리합니다.

• 모델 ID 교체: 지원되는 모든 언어에서 타입이 지정된 SDK 상수(Model.CLAUDE_OPUS_4_7 → Model.CLAUDE_OPUS_4_8)를 포함하며, 편집하기 전에 각 파일을 호출자, 모델 정의자 또는 불투명 문자열 참조로 분류합니다
• 클라우드 플랫폼 감지: 플랫폼별 모델 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"}로 변환하는 등의 작업
• 프리필 대체: 해당되는 경우 어시스턴트 메시지 프리필 패턴을 구조화된 출력으로 변환합니다
• 베타 헤더 정리: 대상 모델에서 GA(정식 출시)된 헤더(예: 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 4.8 및 Claude Opus 4.7의 코딩 및 에이전트 사용 사례에 대해 xhigh)
• 프롬프트 동작 조정: 대상 모델에서 다르게 동작할 수 있는 길이 제어, 도구 트리거링, 서브에이전트 및 지시 사항 준수 프롬프트를 표시합니다
• 무음 기본값 처리: Claude Opus 4.8 및 Claude Opus 4.7에서 추론이 사용자에게 표시될 때 사고 요약(thinking.display: "summarized")을 다시 활성화합니다
• 거부 폴백 구성: 대상이 Claude Fable 5인 경우 응답 콘텐츠를 읽기 전에 stop_reason: "refusal" 처리를 추가하고 폴백 재시도 경로(서버 측 fallbacks 매개변수, SDK 거부 폴백 미들웨어 또는 폴백 크레딧 재시도)를 설정하며, 이전 프리뷰 형태에 대해 작성된 폴백 코드를 업데이트합니다

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

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



Managed Agent 설정

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

/claude-api managed-agents-onboard

스킬은 Managed Agents 멘탈 모델(Agent 구성 대 Sessions)을 안내하고, 에이전트 구성을 템플릿화하고, 환경 및 도구를 구성하고, 세션 루프를 설정하고, 사용 언어에 대한 실행 가능한 코드를 생성하는 인터뷰를 실행합니다. 스킬은 또한 필수적인 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-4-8 and re-tune effort

새 Managed Agent 온보딩:

/claude-api managed-agents-onboard

각 경우에 스킬은 관련 언어별 문서를 로드하고 최신 API 패턴 및 모범 사례를 사용하여 Claude가 구현을 진행하도록 안내합니다.



다음 단계