Agent SDK에서 플러그인 로드

공식 기준: https://code.claude.com/docs/en/agent-sdk/plugins

기준일: 2026-07-26 · CLI 기준 2.1.220

개요

플러그인은 skills, agents, hooks, MCP 서버를 묶어 프로젝트 간 공유하는 확장 패키지입니다. SDK는 로컬 경로만 받습니다(type: "local"). 마켓/원격 플러그인은 먼저 내려받은 뒤 경로를 넘깁니다.

commands/는 레거시입니다. 신규는 skills/를 사용합니다(둘 다 호환 유지).

핵심 개념

• plugins 옵션: { type: "local", path: "..." }[]
• 경로는 플러그인 루트( skills//agents//hooks//.claude-plugin/ 부모)
• 성공 시 system init에 plugins·skills·slash_commands 목록

상세

로드

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Hello",
  options: {
    plugins: [
      { type: "local", path: "./my-plugin" },
      { type: "local", path: "/absolute/path/to/another-plugin" }
    ]
  }
})) {
  // plugin features available
}

from claude_agent_sdk import query, ClaudeAgentOptions
import asyncio

async def main():
    async for message in query(
        prompt="Hello",
        options=ClaudeAgentOptions(
            plugins=[
                {"type": "local", "path": "./my-plugin"},
                {"type": "local", "path": "/absolute/path/to/another-plugin"},
            ]
        ),
    ):
        pass

asyncio.run(main())

상대 경로는 cwd 기준, 절대 경로 가능. 여러 위치에서 동시 로드 가능.

설치 검증

message.type === "system" && message.subtype === "init"에서:

• plugins: 로드된 이름·경로
• skills: 예) my-plugin:greet (플러그인명 prefix)
• slash_commands: 동일 prefix 포함

플러그인 skills 사용

로드 후 Claude가 자율 호출하거나 /my-plugin:skill-name 형태로 호출합니다. Skill 도구 권한이 필요합니다.

구조 참고

전형적인 플러그인 루트:

• skills/<name>/SKILL.md
• agents/*.md
• hooks 설정
• MCP 서버 정의
• .claude-plugin/ 메타데이터

자세한 작성법은 CLI Plugins 문서를 따릅니다.

사용 사례

• 개발·테스트 중 로컬 플러그인 핫로드
• 프로젝트 전용 확장 묶음
• 여러 플러그인 소스 조합

문제 해결

증상	조치
미로드	path가 루트인지, type이 local인지
skills 안 보임	SKILL.md 위치·init skills 목록·권한
path 해석 오류	cwd·절대 경로 확인

체크리스트

• 플러그인을 로컬에 배치했다
• type: "local"과 루트 path를 지정했다
• init 메시지로 skills/commands prefix를 확인했다
• 마켓 플러그인은 다운로드 후 경로로 연결했다

다음 단계

• 플러그인
• 플러그인 마켓
• SDK Skills