Claude Code 플러그인 구조 — 백그라운드 감시까지 담기고, 의존성 자동 설치는 끌 수 없습니다

플러그인을 찾아서 까는 쪽은 앞서 정리했는데, 정작 그 안에 뭐가 들어갈 수 있는지는 안 봤습니다. 공식 레퍼런스를 열어 보니 담을 수 있는 게 일곱 가지였고, 그중 하나는 세션이 끝날 때까지 백그라운드에서 계속 도는 감시였습니다. 그리고 문서가 한 줄로 못 박은 게 있는데 — 의존성 자동 설치는 끄는 설정도 환경 변수도 없습니다. 만드는 쪽이 아니어도 알아둘 값어치가 있는 대목들이라 정리했습니다.

📌 30초 요약

• 담을 수 있는 건 일곱 가지 — 스킬·에이전트·훅·MCP 서버·언어 서버·감시·테마.
• 감시는 세션 내내 도는 백그라운드 프로세스입니다. 플러그인을 꺼도 이미 돌던 건 안 멈춥니다.
• 플러그인이 주는 에이전트에는 세 가지가 금지돼 있습니다 — 훅, MCP 서버, 그리고 권한 모드.
• 의존성 자동 설치는 끌 수 없습니다. 다만 락파일이 있어야만 돌고, Yarn·pnpm은 일부러 건너뜁니다.
• 이름을 안 적은 스킬은 호출 이름이 업데이트마다 바뀔 수 있습니다.
• 옛 버전은 14일 뒤 지워지는데, 플러그인을 전부 지우면 그 청소가 멈춥니다.

담을 수 있는 일곱 가지

제가 예전에 스킬과 MCP가 무엇이 다른지를 갈라 설명한 적이 있는데, 플러그인 관점에서 보면 그 둘이 나란히 놓인 구성요소입니다. 하나의 플러그인이 여럿을 동시에 담을 수 있고요.

구성요소	하는 일	짚어둘 점
스킬 · 커맨드	빗금 단축 명령을 만듦	설치하면 자동으로 발견됨
에이전트	특정 작업 전담 서브에이전트	금지 항목 셋 있음
훅	특정 시점에 내 스크립트 실행	샌드박스 없이 실행
MCP 서버	외부 도구·서비스 연결	켜고 끌 때 캐시 비용 발생
언어 서버	편집 직후 타입 오류·정의 이동	바이너리는 사용자가 직접 설치
감시	세션 내내 도는 백그라운드 프로세스	실험 단계 · 꺼도 안 멈춤
테마	색 배색을 추가	읽기 전용 · 고치면 복사됨

세션 내내 도는 감시

가장 낯선 항목입니다. 플러그인이 백그라운드 감시를 선언해두면 활성화될 때 자동으로 시작되고, 각 감시는 셸 명령을 세션 수명 동안 계속 실행합니다. 그리고 그 명령이 뱉는 출력 한 줄 한 줄이 Claude에게 알림으로 전달됩니다. 문서가 든 예가 배포 상태를 주기적으로 확인하는 스크립트와 오류 로그를 따라 읽는 명령입니다. 즉 내가 "이거 지켜봐 줘"라고 시키지 않아도 Claude가 로그 변화에 반응할 수 있게 됩니다.

시작 시점은 두 갈래입니다. 기본은 세션 시작과 플러그인 재로드 때이고, 특정 스킬이 처음 호출될 때만 시작하도록 걸 수도 있습니다. 제약도 분명한데 — 대화형 세션에서만 돌고, 훅과 같은 신뢰 수준에서 샌드박스 없이 실행되며, 이 기능을 못 쓰는 환경에서는 그냥 건너뜁니다.

⏹️ 껐는데도 안 멈춥니다

문서가 한 줄로 적어둔 게 있습니다 — 세션 도중에 플러그인을 비활성화해도 이미 돌고 있는 감시는 멈추지 않습니다. 세션이 끝나야 같이 끝나죠. "플러그인 껐으니 관련된 건 다 멈췄겠지"가 여기서는 틀립니다. 로그를 따라 읽는 명령이라면 끈 뒤에도 계속 읽고 있고, 출력이 나오면 계속 알림으로 올라옵니다.

설정값을 다루는 방식도 재밌습니다. 감시 명령은 사용자 설정값을 참조할 수 없습니다. 그런데 그냥 무시하는 게 아니라 참조가 들어 있으면 아예 오류로 거부합니다. 이유가 명확한데 — 그 명령이 셸을 거쳐 실행되기 때문입니다. 사용자가 넣은 값이 셸 명령 문자열에 그대로 끼어드는 경로를 치환을 막는 대신 아예 거부로 끊은 것이죠. 감시 프로세스는 관련 환경 변수도 못 받아서, 값이 필요하면 스크립트가 자기 설정 파일을 직접 읽어야 합니다.

에이전트에 금지된 셋, 스킬 이름의 함정

플러그인이 배포하는 에이전트는 모델·추론 강도·최대 턴 수·쓸 수 있는 도구·격리 방식까지 지정할 수 있습니다. 그런데 보안상의 이유로 세 가지는 지원하지 않는다고 문서가 명시합니다 — 훅, MCP 서버, 그리고 권한 모드입니다. 셋의 공통점을 뜯어보면 "에이전트가 자기 실행 환경의 규칙을 스스로 들고 오는 것"입니다. 남이 만든 에이전트가 자기한테 유리한 권한 모드를 챙겨 오는 경로를 아예 없앤 셈이죠.

📛 이름을 안 적으면 호출 이름이 버전 문자열이 됩니다

스킬 파일 하나만 플러그인 루트에 두면 그게 단일 스킬로 로드됩니다. 편한데 함정이 있습니다 — 머리말에 이름을 적지 않으면 설치 디렉터리 이름으로 대신 씁니다. 그런데 마켓플레이스로 설치한 플러그인의 그 디렉터리 이름은 버전 문자열이라, 업데이트할 때마다 호출 이름이 바뀝니다. 어제 되던 명령이 오늘 안 되는 상황이 여기서 나옵니다. 해결은 간단합니다 — 머리말에 이름을 명시하면 되고, 스킬이 둘 이상이면 전용 폴더 구조를 쓰라는 게 문서 권고입니다. 참고로 참·거짓 항목은 특정 버전부터 yes·no·on·off·1·0까지 대소문자 상관없이 받습니다.

의존성 자동 설치는 끌 수 없습니다

플러그인을 캐시에 복사할 때 패키지 의존성도 같이 설치합니다. 훅과 MCP 서버가 그걸 불러 쓸 수 있게요. 문서가 딱 잘라 적습니다 — 이 자동 설치는 끌 수 없고, 그런 설정이나 환경 변수도 없습니다. 대신 돌아가는 조건과 제한이 촘촘히 걸려 있습니다.

락파일	처리
번 계열 락파일	설치함 (고정 해석 · 스크립트 금지)
npm 계열 락파일	설치함 (고정 해석 · 스크립트 금지)
Yarn · pnpm 락파일	일부러 건너뜀
락파일 없음	건너뛰고 로그도 안 남김

Yarn과 pnpm을 건너뛰는 이유가 명확하게 적혀 있습니다 — 그 둘은 해석 시점에 끼어드는 설정 훅을 지원해서, 스크립트를 막는 옵션을 우회할 수 있기 때문입니다. 안 하는 데도 이유가 있는 셈이죠. 나머지 제한은 락파일이 고정한 것만 정확히 설치하고 어긋나면 실패, 설치 전후 스크립트 실행 금지, 60초 제한 셋입니다. 시간을 넘기면 실패로 처리하는데, 부분적으로 받아진 의존성 트리가 남을 수 있다고 문서가 인정합니다. 실패해도 플러그인 자체를 막지는 않고 진단 출력에 경고로만 남습니다.

그런데 한 문장이 이 그림을 흔듭니다. 패키지 저장소를 통해 배포된 플러그인은 그 플러그인 자체를 가져오는 단계에서 설치 스크립트를 켠 채로 받아옵니다. 그 다음에야 위의 제한된 설치가 돌고요. 즉 스크립트를 막아둔 건 의존성 설치 단계이고, 그 앞 단계는 막혀 있지 않습니다. 제한을 읽을 때 어느 구간에 걸린 제한인지를 같이 봐야 하는 자리입니다.

옛 버전은 14일 뒤에 지워집니다

마켓플레이스 플러그인은 제자리에서 쓰지 않고 캐시로 복사되고, 설치된 버전마다 별도 폴더가 됩니다. 업데이트하거나 지우면 이전 버전 폴더를 고아로 표시하고 약 14일 뒤 백그라운드 청소로 제거합니다. 유예를 두는 이유가 좋습니다 — 이미 옛 버전을 물고 돌아가는 다른 세션이 오류 없이 계속 돌게 하려는 것입니다.

여기에 함정이 하나 붙습니다. 이 청소는 플러그인이 최소 하나 설치돼 있을 때만 돕니다. 그래서 마지막 플러그인을 지우고 나면 고아 폴더들이 디스크에 그대로 남고, 다시 뭔가를 설치할 때까지 청소가 안 됩니다. "다 지웠으니 깨끗해졌겠지"가 정확히 반대인 셈이죠. 개발용으로 작업 폴더를 캐시에 링크로 걸어둔 경우는 아예 다릅니다 — 그 링크는 고아로 표시되지도, 제거되지도 않습니다. 검색 쪽은 배려가 돼 있어서, 파일 검색 도구는 고아 폴더를 건너뜁니다. 옛 코드가 검색 결과에 섞이지 않도록요.

🔗 링크는 어디를 가리키느냐에 따라 셋으로 갈립니다

플러그인 안에 심볼릭 링크를 두면 캐시로 복사될 때 가리키는 곳에 따라 처리가 달라집니다. 자기 폴더 안을 가리키면 상대 링크 그대로 보존되고, 같은 마켓플레이스 안의 다른 곳이면 링크를 풀어 내용을 복사합니다 — 한 마켓플레이스 안에서 스킬을 공유하라고 열어둔 길이죠. 그런데 마켓플레이스 바깥을 가리키면 보안상 건너뜁니다. 이유도 적혀 있습니다 — 플러그인이 시스템 경로 같은 임의의 호스트 파일을 캐시로 끌어오는 걸 막으려고요. 같은 이유로 플러그인 폴더 밖을 참조하는 상대 경로는 설치 후 동작하지 않습니다. 복사본에는 그 파일이 없으니까요.

🙋 정직하게 밝혀둘 것

• 제가 플러그인을 만들어 배포해 보지 않았습니다. 감시가 실제로 얼마나 자주 알림을 올리는지, 알림이 컨텍스트를 얼마나 먹는지는 제가 잰 값이 없습니다.
• 103KB짜리 레퍼런스에서 절반쯤만 옮겼습니다. 매니페스트 스키마 전체, 사용자 설정 항목, 채널, 경로 규칙, 명령 목록은 빼뒀습니다. 실제로 만들 때는 원문을 여셔야 합니다.
• "제한이 촘촘하니 안전하다"는 뜻이 아닙니다. 훅과 감시는 샌드박스 없이 내 권한으로 돌고, 의존성 설치의 스크립트 차단도 그 앞 단계에는 안 걸려 있습니다.
• 반대로 "위험하니 쓰지 말라"도 아닙니다. 감시·테마는 실험 단계로 표시돼 있고 나머지는 이미 널리 쓰입니다. 믿는 출처에서 받는다는 전제만 지키면 됩니다.

🗺️ AI 지출 전체 지도

구성요소가 늘수록 매 세션 컨텍스트에 올라가는 고정 비용도 같이 늡니다. 감시가 올리는 알림도 결국 대화에 쌓이고요. 구독과 종량제 선택부터 캐시, 모델 조합, 상한 걸기까지 지금까지 확인한 것들을 일곱 단계 지도 한 장으로 묶어뒀습니다.

자주 묻는 것

Q. 파이썬 의존성이 필요한 플러그인은 어떻게 하나요?

자동 설치가 다루는 건 패키지 저장소 계열 의존성뿐입니다. 파이썬 의존성, 설치 스크립트가 돌아야 빌드되는 패키지, Yarn·pnpm으로 잠근 것은 대상이 아닙니다. 이럴 때 쓰라고 플러그인마다 따로 주어지는 데이터 폴더가 있는데, 버전이 바뀌어도 살아남는 자리라 한 번 깔아두고 재사용할 수 있습니다. 다만 문서가 함정을 짚습니다 — 폴더가 있는지만 확인해서는 업데이트로 의존성 목록이 바뀐 걸 알아챌 수 없습니다. 권장 방식은 딸려온 목록 파일과 데이터 폴더에 넣어둔 사본을 비교해서 다르면 다시 설치하는 것입니다.

Q. 감시를 쓰면 뭐가 좋아지나요?

"물어봐야 아는 것"이 "알아서 올라오는 것"으로 바뀝니다. 배포가 실패했는지, 로그에 오류가 찍혔는지를 내가 확인해서 알려주는 대신 Claude가 알림으로 받습니다. 대신 대가가 둘입니다 — 출력 한 줄마다 알림이 되니 시끄러운 로그를 붙이면 대화가 그걸로 찹니다. 그리고 세션 중간에 꺼도 안 멈춥니다. 그래서 특정 스킬을 부를 때만 시작하도록 거는 선택지가 같이 있는 것으로 보입니다 — 항상 켜두는 것보다 필요한 순간에만이 안전한 기본값이겠죠.

Q. 만들어 보려면 어디부터 시작하나요?

레퍼런스에 초기 골격을 만들어 주는 명령과 설치·제거·정리·켜기·끄기·업데이트 명령이 정리돼 있습니다. 그리고 스킬 폴더만 있는 플러그인도 가능해서, 절차서 몇 개만 묶어 배포하는 가벼운 형태부터 시작할 수 있습니다. 남이 만든 걸 먼저 써보고 싶다면 공식 마켓플레이스에서 찾아 까는 이야기가 앞단이고, 자기 마켓플레이스를 열어 배포하는 쪽은 따로 정리해 둔 글이 있습니다.

✨ 오늘 확인한 것 정리

플러그인에는 스킬·에이전트·훅·MCP 서버·언어 서버·감시·테마 일곱 가지가 담깁니다. 그중 감시는 세션 내내 도는 백그라운드 프로세스이고 중간에 플러그인을 꺼도 멈추지 않습니다. 에이전트에는 훅·MCP 서버·권한 모드가 금지돼 있는데, 셋 다 자기 실행 규칙을 스스로 들고 오는 통로입니다. 의존성 자동 설치는 끌 수 없고, 락파일이 있어야만 돌며 Yarn·pnpm은 스크립트 차단을 우회할 수 있어 일부러 제외됩니다. 마지막으로 옛 버전은 14일 뒤 지워지지만, 플러그인을 전부 지우면 그 청소가 멈춥니다.

※ 확인 경로(2026년 8월 17일 기준): code.claude.com/docs/en/plugins-reference. 구성요소와 설정 항목 이름은 제가 우리말로 옮긴 것입니다.

※ 감시와 테마는 실험 단계로 표시돼 있어 형식이 바뀔 수 있습니다. 만들기 전에 원문의 해당 절에서 현재 규격을 확인하시길 권합니다.