Claude API 스킬
Claude API 스킬 (Claude API skill)
claude-api 스킬은 클로드가 두 Anthropic 표면에서 애플리케이션을 구축할 때 필요한 상세하고 최신의 참조 자료를 제공하는 오픈소스 에이전트 스킬이에요. 이 스킬은 프로젝트의 언어, 표면(Messages API 또는 Managed Agents), 그리고 손에 든 특정 작업과 관련된 문서만 로드해 컨텍스트를 효율적으로 유지해요.
출처: 문서
본문
claude-api 스킬은 두 Anthropic 표면에서 애플리케이션을 구축하기 위한 상세하고 최신의 참조 자료를 클로드에 제공하는 오픈소스 에이전트 스킬이에요:
- Messages API: 단일 요청, 스트리밍 채팅, 도구 사용, 배치 처리, 프롬프트 캐싱, 구조화 출력, 커스텀 에이전트 루프를 위한 주 표면이에요.
- Claude Managed Agents (베타): Anthropic 호스팅 도구 실행, 영구 에이전트 구성, 세션별 샌드박스를 갖춘 서버 관리 상태 에이전트를 위한 Anthropic 호스팅 표면이에요.
Messages API와 Managed Agents 모두에 대해 Python, TypeScript, C#, Go, Java, PHP, Ruby, cURL의 8개 프로그래밍 언어를 다뤄요.
이 스킬은 Claude Code에 번들되어 있으며, 에이전트 스킬을 지원하는 모든 환경에 설치할 수 있는 오픈소스 Anthropic skills 리포지토리에서도 사용할 수 있어요.
스킬은 점진적 공개를 사용해 컨텍스트를 효율적으로 유지해요. 클로드는 모든 것을 한 번에 로드하는 대신, 프로젝트의 언어, 표면(Messages API 또는 Managed Agents), 그리고 손에 든 특정 작업(도구 사용, 스트리밍, 배치 등)과 관련된 문서만 로드해요.
스킬이 제공하는 것 (What the skill provides)
발동되면 스킬은 클로드에 다음을 갖춰줘요:
Messages API의 경우:
- 언어별 SDK 문서: 프로젝트 언어의 설치, 퀵 스타트, 흔한 패턴, 오류 처리
- 도구 사용 안내: 함수 호출을 위한 언어별 예시와 개념적 기반. 사용 가능하면 베타 도구 러너 포함
- 스트리밍 패턴: 채팅 UI 구축과 점진적 표시 처리를 위한 구현 세부 사항
- 배치 처리: 50% 비용의 오프라인 배치 처리
- 프롬프트 캐싱: 프리픽스 안정성 설계, 브레이크포인트 배치, 조용한 무효화자 감사
- 모델 마이그레이션: 최신 클로드 모델로 마이그레이션하는 단계별 안내(Claude Opus 5.5와 Claude Fable 5.1의 breaking changes와 동작 변화 포함)
- 현재 모델 정보: 모델 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와 Claude Platform on AWS에서만 사용할 수 있어요(Amazon Bedrock, Google Cloud, Microsoft Foundry에서는 사용 불가). 스킬은 다른 배포를 대신 Messages API와 도구 사용으로 라우팅해요.
스킬이 활성화되는 시점 (When the skill activates)
스킬은 두 가지 방식으로 활성화돼요:
자동 활성화는 다음 경우에 발생해요:
- 코드가 Anthropic SDK를 가져옴(
anthropicfor Python,@anthropic-ai/sdkfor TypeScript/JavaScript) - Claude API, Anthropic SDK, 또는 Managed Agents로 무언가를 구축·디버깅·최적화하는 데 도움을 요청함
- 파일에서 클로드 기능(프롬프트 캐싱, 적응형 사고, 컴팩션, 도구 사용, 배치, 파일, 인용, 메모리)이나 모델 참조를 추가·수정·조정함
수동 호출은 스킬이 설치된 환경에서 /claude-api를 입력(선택적 하위 명령이나 산문 포함)해 발생해요.
스킬은 일반 프로그래밍 작업, ML/데이터 과학 작업, 또는 다른 AI SDK(OpenAI 같은)를 가져오는 코드에는 활성화되지 않아요.
지원 언어 (Supported languages)
스킬은 프로젝트 파일(Python은 requirements.txt, TypeScript는 tsconfig.json, Go는 go.mod 등)을 검사해 프로젝트 언어를 자동으로 감지하고 적절한 문서를 로드해요.
| 언어 | Messages API SDK | 도구 러너 | Managed Agents |
|---|---|---|---|
| Python | 예 | 예 (베타) | 예 (베타) |
| TypeScript | 예 | 예 (베타) | 예 (베타) |
| C# | 예 | 예 (베타) | 예 (베타) |
| Go | 예 | 예 (베타) | 예 (베타) |
| Java | 예 | 예 (베타) | 예 (베타) |
| PHP | 예 | 예 (베타) | 예 (베타) |
| Ruby | 예 | 예 (베타) | 예 (베타) |
| cURL | 예 | N/A | 예 (베타) |
프로젝트가 여러 언어를 사용하면 클로드가 어느 언어가 적용되는지 물어봐요. 지원되지 않는 언어(Rust, Swift, C++)의 경우 스킬이 cURL/원시 HTTP 예시를 제공해요.
스킬 사용 방법 (How to use the skill)
Claude Code에서 (번들)
스킬은 Claude Code와 함께 제공되며 설치가 필요 없어요. 클로드에게 Claude API로 무언가를 구축하도록 도움을 요청하거나, 프로젝트가 이미 Anthropic SDK를 가져오면 스킬이 자동으로 활성화돼요.
직접 호출할 수도 있어요:
/claude-api
Claude Code에서 번들 스킬이 작동하는 방식에 대한 자세한 내용은 Claude Code 스킬 문서를 참고하세요.
스킬 리포지토리에서 (From the skills repository)
스킬 소스는 Anthropic skills 리포지토리에서 사용할 수 있어요. 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
더 새로운 클로드 모델로 마이그레이션 (Migrating to a newer Claude model)
Claude API 스킬은 코드 베이스 전반에 걸쳐 클로드 모델 마이그레이션을 수행할 수 있어요. /claude-api migrate로 직접 호출하세요:
/claude-api migrate this project to claude-opus-5-5
범위 확인 질문을 건너뛰도록 범위를 미리 전달할 수도 있어요:
/claude-api migrate everything under src/ to claude-opus-5-5
/claude-api migrate apps/api.py and apps/worker.py to claude-opus-5-5
범위가 모호하면(예: 단순히 /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.접두사)을 보존하고 파트너 운영 플랫폼에서 사용할 수 없는 기능은 변경을 건너뜀 - Breaking 파라미터 변경, 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")으로 다시 선택 - 거부 폴백 구성, 응답 콘텐츠를 읽기 전에
stop_reason: "refusal"처리 추가, 대상이 Claude Fable 5.1, Claude Fable 5, Claude Opus 5.5, Claude Opus 5일 때 폴백 재시도 경로 설정(서버 측fallbacks파라미터, 보통"default"모드, SDK 거부 폴백 미들웨어, 또는 폴백 크레딧 재시도), 그리고 이전 프리뷰 모양에 대해 작성된 폴백 코드 업데이트
편집하면서 스킬은 각 변경과 그 동기를 인라인으로 설명해요. 완료 시 통합 테스트, 길이 제어 프롬프트 튜닝, 비용/요율 한도 재기준 같은 수동 검증이 필요한 항목의 체크리스트를 만들어요.
스킬이 적용하는 모델별 변경 전체 목록은 Claude Opus 5에서 Claude Opus 5.5로 마이그레이션, Claude Opus 4.8에서 Claude Opus 5.5로 마이그레이션, Claude Fable 5.1로 마이그레이션을 참고하세요.
Managed Agent 설정하기 (Setting up a Managed Agent)
새 Managed Agent를 처음부터 스캐폴딩하려면 managed-agents-onboard 하위 명령을 호출하세요:
/claude-api managed-agents-onboard
스킬은 Managed Agents의 개념 모델(에이전트 구성 대 세션), 에이전트 구성 템플릿, 환경과 도구 구성, 세션 루프 설정을 안내하는 인터뷰를 실행하고 언어에 맞는 실행 가능한 코드를 만들어요. 스킬은 또한 필수 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.* 호출에 자동으로 설정해요.
예시 사용법 (Example usage)
스킬이 클로드가 처리하도록 돕는 작업의 예시는 다음과 같아요:
채팅 애플리케이션 구축:
Build a streaming chat UI with the Claude API in TypeScript
기존 프로젝트 마이그레이션:
/claude-api migrate this codebase to claude-opus-5-5 and re-tune effort
새 Managed Agent 온보딩:
/claude-api managed-agents-onboard
각 경우에서 스킬은 관련 언어 특화 문서를 로드하고 현재 API 패턴과 모범 사례를 사용해 구현을 클로드가 안내하도록 해요.