JYP Garden

Claude API Skill

Properties1
tagssource, harness-engineering, agentic-architecture, knowledge

4 min read

Claude API Skill

Source: raw/articles/2026-04-20-claude-api-skill.md Type: article (official docs) By: Anthropic Valid as of: 2026-04-20

핵심 Takeaway

  • claude-api 스킬은 Messages API + Claude Managed Agents 두 surface를 모두 커버하는 오픈소스 Agent Skill. claude-code에 번들 포함, GitHub 별도 설치도 가능.
  • Progressive disclosure 설계: 프로젝트 언어·surface·태스크에 맞는 문서만 지연 로드 — 불필요한 컨텍스트 낭비 방지. (출처: 공식 문서)
  • /claude-api migrate 서브커맨드: 코드베이스 전체에 Claude 모델 마이그레이션 자동화 — model ID swap, breaking parameter 처리(temperature/top_p/top_k 제거), beta header cleanup, prefill → structured outputs 변환.
  • Claude Managed Agents (beta): 서버 관리 stateful 에이전트 — managed-agents-2026-04-01 beta header 필요, Agent (once) → Session (every run) 필수 플로우. Amazon Bedrock/GCP Vertex/Azure Foundry 미지원(first-party only).
  • 언어 자동 감지: requirements.txt(Python), tsconfig.json(TypeScript), go.mod(Go) 등 파일 검사 → 적절한 SDK 문서 자동 로드. 8개 언어 지원(Messages API), 7개(Managed Agents, C# 제외).

상세 요약

Agent Skill 시스템

claude-api 스킬은 harness-engineering에서 Skills가 하네스 레이어의 핵심 컴포넌트임을 잘 보여주는 사례다. Skill은 단순한 문서 모음이 아니라 진단 결정 트리처럼 작동한다 — 언어, surface, 태스크를 감지해 필요한 문서만 로드하고, 서브커맨드(/claude-api migrate, /claude-api managed-agents-onboard)로 특정 워크플로우를 가이드한다.

Messages API 커버 범위

  • 언어별 SDK 설치·빠른 시작·공통 패턴·에러 처리
  • Tool use, Streaming, Batch processing(50% 비용 절감), Prompt caching
  • Model migration 가이드 (Claude Opus 4.7 포함)
  • 현재 모델 ID, 컨텍스트 창, 가격 정보

Claude Managed Agents (beta)

Managed Agents는 Anthropic 서버가 직접 관리하는 stateful 에이전트 서비스다. 핵심 설계 원칙:

  • Agent (once) → Session (every run): model, system, tools는 agent config에만 정의 — session에는 포함 금지
  • first-party only: Bedrock, Vertex AI, Azure Foundry에서는 사용 불가. 스킬이 third-party 환경 감지 시 Messages API + tool use로 자동 라우팅
  • Stream reconnect, processed_at 큐/처리 게이트, interrupt handling 등 엔터프라이즈 패턴 포함

모델 마이그레이션 자동화

/claude-api migrate 는 코드베이스를 세 카테고리로 분류:

  1. Caller: SDK를 직접 호출하는 파일
  2. Model definer: 모델 ID를 정의하는 파일
  3. Opaque string reference: 문자열로만 참조하는 파일

각 카테고리별 최소 침습 편집 후, 수동 검증이 필요한 항목 체크리스트 생성 (통합 테스트, length-control 프롬프트 튜닝, 비용/rate-limit 재기준선).

연결되는 위키 페이지

  • claude-code — claude-api 스킬이 번들로 포함된 에이전트
  • anthropic — claude-api 스킬 개발사
  • harness-engineering — Skills 시스템이 하네스 구현의 핵심 컴포넌트

그래프 뷰