Claude Code plugin으로 Spotify Ads API에 자연어 인터페이스 구축

Spotify는 Spotify Ads API v3를 Claude Code plugin으로 감싸, macOS 환경의 Claude Code에 설치해 슬래시 명령과 대화형 요청을 모두 처리하는 흐름을 만들었다. 사용자가 Back to School Promo처럼 요청하면 agent가 campaign, ad set, ad 순서로 분해해 필요한 API 호출을 이어 붙인다. 플러그인은 GitHub과 Anthropic의 Claude Plugins marketplace에 공개됐다.

이 과정에서 agent는 geo-targeting search endpoint(/targets/geos)로 Connecticut 같은 요청을 ID로 바꾸고, 달러 예산을 micro-units로 변환하며, audience estimate로 targeting이 충분히 넓은지 검증한다. 필요한 입력이 빠지면 사용자에게 다시 묻고, auto_execute 설정에 따라 확인 후 실행하거나 바로 실행한다.

• Skills는 슬래시 명령을, Agents는 자연어 해석을 맡는다.
• Hooks는 PreToolUse에서 OAuth 토큰 갱신과 HTTP header 주입을 처리한다.
• Settings는 계정과 environment preference를 gitignored local file에 저장한다.
• runtime은 curl, jq, python3만으로 굴러가고, 실제 구현은 Markdown files, 하나의 bash script, 두 개의 Python helper로 구성된다.

MCP 대신 CLI-first + OpenAPI를 택한 이유는 API가 너무 크기 때문이다. 30개가 넘는 resource type과 중첩 타깃팅 구조를 static tool로 노출하면 context window 비용이 커지지만, curl 명령을 그대로 보여주면 사용자가 요청을 복사·수정·재실행할 수 있다. 원본 OpenAPI v3 spec인 external-v3.yaml은 약 8,600줄이며, 이것이 사실상 단일 진실 공급원이다.

특히 OpenAPI Links로 campaign → ad set → ad 흐름과 응답 간 id 전달 경로를 명시했다. 런타임 표현식 $response.body#/id, $request.path.ad_account_id, 그리고 operationId가 agent에게 다음 호출에 넣을 값을 알려준다. 큐레이션된 api-reference skill은 자주 쓰는 endpoint의 schema와 enum을 정리하고, 원본 spec은 덜 쓰는 endpoint와 error response까지 보완한다.

플러그인은 Apache 2.0으로 공개됐고, 결국 소스 오브 트루스는 OpenAPI spec, 비즈니스 로직은 prose라는 철학을 택했다. 앞으로는 사용자 흐름 관찰, idempotency keys 지원, Codex와 Gemini CLI 확대, 그리고 GPT5.5와 Images 2.0을 활용한 창작용 이미지 생성까지 검토한다.