플러그인을 고르고 안전하게 설치하는 방법

스킬 하나로 페이지가 눈에 띄게 좋아지면, 그다음 단계는 저절로 떠오릅니다. 하나가 아니라 열 개를 한꺼번에 설치하자는 것입니다. 마침 동료가 링크를 보내옵니다. "이거 설치해 봐, 쓸 만해." 이 모든 게 명령 하나로 설치되는데, 바로 여기에 함정이 있습니다. 플러그인은 능력 목록처럼 보이지만, 실제로는 여러분 컴퓨터에서 여러분의 권한으로 실행되고 에이전트와의 모든 대화에서 자리를 차지하는 코드입니다.

플러그인이 스킬과 어떻게 다른지, 그 안에 무엇이 들어 있을 수 있는지, 카탈로그는 어디서 오는지, 믿을 만한 출처와 그렇지 않은 출처를 어떻게 구분하는지, 설치 전에 Claude Code가 무엇을 보여 주고 그것을 어떻게 읽는지 살펴봅니다. 그런 다음 전체 과정을 따라가 봅니다. 설치하고, 자신의 작업으로 확인하고, 끄고, 제거하는 순서입니다. 마지막으로 매번 설치 전에 무엇을 해야 하는지, 그리고 에이전트가 인터넷에서 가져온 스킬에도 똑같이 해야 하는 이유를 다룹니다.

1. 스킬과 플러그인

목수에게는 적어 둔 절차가 있습니다. 작업대를 준비하는 법, 날을 가는 법, 틀에 맞춰 한 묶음을 뽑아내는 법. 혼자 일하는 동안은 이 절차가 공책 속에 있습니다. 그러다 옆 작업대 동료가 하나 부탁하고, 견습생이 또 하나 부탁하고, 한 달 뒤에는 길 건너 공방에서 전화가 옵니다. 사람마다 종이 한 장씩 보내는 것도 슬슬 귀찮아집니다. 그래서 그는 절차 몇 개를 상자에 담고, 옆면에 공방 이름표를 붙이고, 안에는 이게 무엇이고 어떻게 쓰는지 적은 쪽지를 넣습니다. 이런 상자는 통째로 건네줄 수 있고, 업데이트할 수 있고, 버전 번호를 매길 수 있습니다.

이것이 바로 플러그인입니다. 또 하나의 능력이 아니라, 여러 능력을 감싸는 포장입니다.

플러그인 자체는 독립된 능력이 아니라 여러 능력을 나눠 주는 방법입니다. 플러그인이 할 수 있는 일은 모두 그 안에 든 것을 통해 이루어집니다. 능력, 도우미, 자동 반응, 연결이 그것입니다. 그래서 "이 플러그인이 뭘 할 수 있나"라는 질문은 항상 다른 질문으로 돌아갑니다. 안에 뭐가 들어 있는가.

자신만의 플러그인은 여러분의 스킬을 다른 사람들도 원하기 시작할 때 만들게 됩니다. 무엇이 필요한지 확신이 서지 않는다면 - 스킬인지, 독립된 역할을 가진 도우미인지, 플러그인인지 - 에이전트에게 물어보되, 바로 만들지 말고 먼저 질문을 던지게 하세요. 에이전트는 초안을 만들고, 안에 무엇이 들어가는지는 여러분이 확인합니다. 기준은 단순합니다. 같은 요청을 반복한다면 스킬, 부수적인 작업이 대화를 어지럽힌다면 도우미, 같은 세트가 다른 프로젝트에서도 필요하다면 플러그인입니다. 플러그인을 단계별로 만드는 방법은 별도의 이야기입니다. 이 글은 상자를 받는 쪽을 위한 것입니다.

2. 플러그인 안에 들어 있는 것

보통 상자 안 칸은 다섯 개이고, 이들이 똑같이 무해한 건 아닙니다.

• skills - 에이전트가 설명을 보고 스스로 적용하거나 여러분의 명령으로 적용하는 절차;
• agents - 독립된 역할을 가진 도우미로, 에이전트가 작업 일부를 맡깁니다;
• hooks - 이벤트에 대한 자동 반응입니다. 무언가 일어났을 때 여러분이 요청하지 않아도 명령을 실행합니다;
• MCP servers - 외부 서비스로의 연결로, 에이전트는 이를 통해 여러분 컴퓨터 밖의 무언가를 읽고 바꿉니다;
• LSP servers - 특정 언어를 위한 코드 힌트로, 별도로 설치된 프로그램이 필요합니다.

이 상자를 구석에 던져 두지 않고 제대로 살펴서 받아야 하는 이유가 바로 아래 두 칸입니다.hooks와 MCP가 있는 플러그인은 "능력 모음"에서 기대하지 않는 일을 할 수 있습니다. 명령을 실행하고 외부 서비스로 나가는 일입니다. 안에 들어 있는 건 벽에 걸린 포스터가 아니라 전원이 켜진 살아 있는 도구입니다. hooks, MCP, agents가 각각 무엇인지는 별도의 이야기이고, 여기서는 구성 요소로서 무엇을 의미하는지만 알면 됩니다. 이 다섯 가지 말고 다른 칸도 있을 수 있습니다. 기본 설정이나 에이전트의 응답 스타일 같은 것인데, 큰 그림을 바꾸지는 않습니다.

카드가 손에 없다면 에이전트에게 플러그인의 저장소를 열어 폴더 안에 무엇이 있는지 알려 달라고 요청하세요.

3. 이름에 붙는 접두사

플러그인에서 나온 스킬은 접두사를 달고 이름이 붙습니다. /플러그인-이름:스킬-이름, 예를 들면 /commit-commands:commit입니다. 옆 플러그인에도 "정리하기"라는 스킬이 있을 수 있지만, 이름표가 붙어 있는 한 헷갈릴 일은 없습니다.

대가는 긴 이름입니다. 공용 세트를 쓰는 만큼 명령을 더 길게 입력해야 합니다. 프로젝트 폴더 안 자신의 스킬에는 접두사가 없습니다.

이점도 있습니다. / 메뉴에서 접두사만 보면 명령이 어디서 왔고 어느 상자 소속인지 늘 알 수 있습니다.

4. 카탈로그와 두 단계

상자는 창고에서 가져옵니다. 플러그인 카탈로그, 영어로 marketplace는 누군가 관리하는 다른 사람들의 플러그인 목록입니다. 다루는 방법은 두 단계입니다. 카탈로그를 연결하고, 그다음 그 안의 플러그인을 하나씩 설치합니다. 카탈로그를 연결하는 것만으로는 아무것도 설치되지 않습니다. 목록만 받을 뿐입니다.

대부분에게는 첫 단계가 이미 되어 있습니다. /plugin 명령은 탭 네 개짜리 패널을 엽니다. Discover - 연결된 모든 카탈로그에서 플러그인 검색; Installed - 설치된 것; Marketplaces - 카탈로그 목록; Errors - 로딩 오류. Anthropic 공식 카탈로그는 첫 실행부터 연결되어 있고, Discover 탭에서 바로 그 플러그인들이 보입니다. 고르고, 열고, 설치하면 됩니다. Claude Code 없이 보고 싶다면 같은 목록이 claude.com/plugins 사이트에도 있습니다.

필요한 플러그인이 공식 카탈로그에 없을 때 두 번째 카탈로그가 등장합니다. 커뮤니티 카탈로그이거나 카탈로그 파일이 들어 있는 다른 사람의 저장소입니다. 명령 하나로 연결하고, 그 안의 플러그인도 명령 하나로 설치합니다.

/plugin marketplace add anthropics/claude-plugins-community   # 커뮤니티 카탈로그 연결
/plugin install 플러그인-이름@claude-community                  # 그 안에서 플러그인 하나 설치
/plugin list                                                  # 플러그인이 목록에 있는지 확인

다른 사람의 카탈로그도 같은 첫 번째 명령으로 연결하되, 그 주소만 다릅니다.

사람들이 가장 자주 걸려 넘어지는 미묘한 부분이 하나 있습니다(저도 예외는 아니었습니다). 설치할 때 쓰는 카탈로그 이름은 저장소 이름이 아니라 카탈로그 자체의 설명에서 나옵니다. 저장소 이름은 anthropics/claude-plugins-community이지만, 설치는 claude-community에서 합니다. 카탈로그 이름이 무엇인지는 Marketplaces 탭에서 보입니다.

공식 카탈로그에는 여러 종류의 플러그인이 있습니다. GitHub 통합은 MCP, 즉 외부 서비스로의 연결입니다. 특정 언어를 위한 코드 힌트, 예를 들어 typescript-lsp는 LSP입니다. security-guidance는 에이전트가 만드는 변경마다 흔한 취약점을 검사합니다.

5. 출처를 신뢰하는 세 단계

플러그인은 폴더에 있다고 저절로 작동하지 않습니다. 명시적으로 설치해야 하고, 이건 형식적인 절차가 아닙니다. 안에는 여러분의 권한으로 실행될 코드가 있습니다. 즉 이 컴퓨터에서 여러분이 할 수 있는 모든 것을 할 수 있다는 뜻입니다. 그래서 어떤 플러그인이든 첫 질문은 "무엇을 할 줄 아는가"가 아니라 "어디서 왔는가"입니다.

공식 카탈로그. Anthropic이 관리하지만, 그 안의 플러그인 대부분은 Anthropic이 아니라 파트너와 다른 작성자가 만든 것입니다. 낯선 저장소만큼 주의할 필요는 없어도, 설명과 구성은 읽어 볼 만합니다.

커뮤니티 카탈로그. Anthropic의 자동 검토를 통과한 서드파티 플러그인이며, 거의 모든 플러그인이 카탈로그 안에서 특정 버전으로 고정되어 있습니다. 이건 필터이지 보증이 아닙니다. 플러그인이 약속한 그대로 동작하는지는 아무도 확인하지 않았습니다.

임의의 저장소나 폴더. 아무 검토도 없습니다. 작성자가 누구인지, 명확한 설명이 있는지, 폴더 안에 무엇이 있는지는 여러분이 직접 확인합니다.

한 작업 세션 안에서 세 단계가 모두 나타날 수 있습니다. 커뮤니티 카탈로그의 디자인 플러그인 하나, Anthropic 카탈로그의 또 다른 하나, 플러그인 하나만 들어 있는 남의 저장소에서 온 세 번째. 지금 자신이 어느 단계에 서 있는지 알고 있다면 문제없습니다.

주의 정도는 플러그인마다 다르게 잡으세요. 할 수 있는 일이 많을수록, 즉 hooks와 MCP가 많을수록, 그리고 출처가 공식에서 멀수록 더 꼼꼼히 살펴봐야 합니다.

6. 설치 전에 Claude Code가 보여 주는 것

출처가 얼마나 꼼꼼히 봐야 할지를 정합니다. 세부 사항은 Claude Code가 직접 보여 줍니다. /plugin 패널의 Marketplaces 탭에서 플러그인을 열거나 /plugin install 이름@카탈로그 명령을 실행하면 카드가 나타납니다. Discover 목록에서 여는 카드는 더 짧고, 비용 추정이 없습니다.

카드에는 이 모든 이야기의 핵심인 세 줄이 있습니다. 마지막 두 줄은 공식 카탈로그 플러그인에만 있습니다.

• Will install - 구성: skills, agents, hooks, MCP, LSP가 각각 몇 개 딸려 오는지;
• Context cost - 플러그인이 에이전트의 컨텍스트 창에 얼마나 더해지는지: Every turn은 여러분의 요청마다, When invoked는 에이전트가 플러그인의 skills와 agents를 불러올 때;
• Last updated - 플러그인이 마지막으로 업데이트된 시점.

Will install:  skills: 8   agents: 1   hooks: 2   MCP servers: 1
Context cost:  Every turn: ~400 tokens   When invoked: ~1.5k tokens
Last updated:  2 weeks ago

숫자와 줄 모양은 예시일 뿐, 플러그인과 Claude Code 버전마다 다릅니다. 구성을 읽는 건 간단하지만 어디까지나 첫인상입니다. skills만 있다면 그 플러그인은 대체로 읽고 제안하는 쪽입니다. hooks나 MCP가 있다면 명령을 실행하거나 외부로 나간다는 뜻이고, 정확히 무엇을 하는지 설명을 열어 확인할 이유가 됩니다. 카드가 전부를 보여 주지는 않습니다. 플러그인은 카드에 없는 실행 파일이나 기본 설정을 함께 가져올 수도 있습니다. 낯선 출처라면 저장소도 들여다보세요.

그리고 카드가 묻지 않는 세 번째 질문이 있습니다. 이 플러그인이 여러분에게 맞는가. 좋은 플러그인이라도 설치하지 않을 수 있습니다. 여러분의 스킬과 겹치거나, 다른 운영체제용 스크립트를 끌고 오거나, 여러분에게 없는 문제를 해결하는 것일 수 있습니다.

7. 플러그인은 누구에게 가는가

상자가 누구에게 갈지는 설치할 때 미리 정합니다. 선택지는 세 가지입니다.

• user - 여러분에게, 모든 프로젝트에서;
• project - 이 저장소로 작업하는 모두에게. 기록은 .claude/settings.json에 들어가 프로젝트와 함께 이동합니다;
• local - 여러분에게, 그리고 이 프로젝트에서만. 동료에게는 보이지 않습니다.

managed도 있습니다. 관리자가 설치하며, 여러분이 바꿀 수는 없습니다. 대부분은 마주칠 일이 없습니다.

규칙은 하나입니다. 적합한 scope 중 가장 좁은 것을 고르세요. 플러그인이 켜진 곳이 적을수록 실제로 작동하는 상황도 적어지고, 나중에 정리할 것도 줄어듭니다. 의심스러운 플러그인은 좁은 scope로도 무해해지지 않습니다. 켜져 있는 곳에서는 똑같은 일을 다 할 수 있습니다. project scope는 따로 짚을 만합니다. 여러분은 자신뿐 아니라 다른 사람을 위해서도 결정하는 셈입니다. 동료가 저장소를 열면 그 플러그인은 켜져 있지만 설치되어 있지는 않은 상태가 됩니다. /plugin 패널의 Errors 탭에 경고가 나타나고, 플러그인은 동료가 직접 설치해야 합니다.

패널에서 설치할 때는 scope를 물어봅니다. /plugin install도 선택할 수 있는 카드를 엽니다.

8. 설치하고 확인하기

설치가 매끄럽게 끝나면 두 문구 중 하나로 마무리됩니다. 플러그인이 이미 활성 상태이거나, /reload-plugins를 실행하라는 요청이 뜹니다. 후자라면 실행하세요. 이 명령이 대화를 처음부터 다시 읽게 된다고 경고하면 --force를 붙여 다시 시도하세요. Claude Code를 재시작할 필요는 없습니다.

플러그인이 자리 잡았는지는 /plugin list로 확인합니다. 목록에 있고, 그 스킬들이 / 메뉴에 접두사를 달고 나타납니다.

열린 상자는 작업대를 차지합니다. 활성화된 플러그인은 첫 순간부터 에이전트의 창에 자기 스킬들의 선언, 즉 이름과 설명을 더합니다. 전체 내용은 스킬이 실제로 쓰일 때만 불러오지만, 이 선언은 늘 떠 있습니다. 외부 서비스로의 연결은 도구 이름이 곧바로 들어오고 설명은 필요할 때 들어옵니다. 자동 반응은 창을 거의 차지하지 않습니다. 창이 꽉 찰수록 답변마다 비용도 커지고 속도도 느려집니다.

진짜 비용은 비교해야 보입니다. /context가 창이 무엇으로 채워져 있는지 보여 줍니다. 설치 전과 후에 각각 실행해 보세요.

1) 플러그인 없이: 자신의 작업을 하고 결과를 기억해 둔다
2) 플러그인을 설치하고, 필요하면 /reload-plugins
3) 같은 작업을 다시 한다
4) 비교하고 결정한다: 유지, 끄기, 제거

비교 결과는 일부러 여기 적지 않았습니다. 사람마다 다르니까요. 기준은 단순합니다. 이 플러그인이 무엇을 하는지 두 문장으로 말할 수 있고, 설명이 아니라 자신의 실행 결과에서 나온 이유로 유지하거나 없앨 근거를 하나 댈 수 있으면 됩니다.

9. 끄기, 제거하기, 카탈로그 없애기

세 가지 동작이고, 서로 다릅니다. /plugin disable은 끄기만 할 뿐 제거하지는 않습니다. 플러그인이 창을 차지하지 않게 되고, /plugin enable로 되돌릴 수 있습니다. /plugin uninstall은 완전히 제거합니다. /plugin marketplace remove는 카탈로그를 없애고, 그 안에서 설치했던 플러그인도 전부 함께 사라집니다. 이건 잊기 쉬운 부분입니다.

/plugin disable 플러그인-이름@카탈로그      # 끄지만 잃지는 않는다
/plugin uninstall 플러그인-이름@카탈로그    # 완전히 제거한다
/plugin marketplace remove 카탈로그        # 카탈로그와 거기서 설치한 모든 것을 없앤다

이 명령들은 같은 패널을 열고 그대로 열어 둡니다. 닫으려면 Esc를 누르세요. Installed 탭에서는 명령 없이도 같은 일을 할 수 있습니다. 문제가 있는 플러그인은 위에, 꺼진 플러그인은 아래에 접혀 표시됩니다. 프로젝트 전체에 켜진 플러그인을 제거하면 Claude Code가 묻습니다. 여러분에게서만 지울지, 모두에게서 지울지.

정리. 여러분이 직접 설치했지만 열 세션에 걸쳐 2주간 쓰지 않은 플러그인은 Claude Code가 Installed 탭의 "Not used recently" 항목 아래로 모아 두고, 카드에는 마지막으로 작동한 시점이 나타납니다. 별도로 /doctor는 쓰지 않는 플러그인을 컨텍스트 비용과 함께 알려 줍니다. 도구 모음은 그 안에 무엇이 있고 왜 있는지 기억하는 동안만 도구 모음으로 남습니다.

업데이트. 공식 카탈로그는 스스로 업데이트하며 /reload-plugins 실행을 요청합니다. 서드파티는 기본적으로 그렇지 않습니다. 업데이트는 거의 새로 설치하는 것과 같습니다. 구성이 바뀔 수 있으니 카드를 다시 열어 볼 만합니다.

설치 자체를 포함해 무언가 잘못됐다면 Errors 탭이 원인을 보여 줍니다. 그다음은 끄기, 재설치, 최후의 수단으로 플러그인 캐시를 지우고 다시 설치하는 순서입니다. Marketplaces 탭에서 공식 카탈로그가 사라졌다면 /plugin marketplace add anthropics/claude-plugins-official로 되돌릴 수 있습니다.

10. 플러그인만의 문제가 아닙니다

여러분의 요청으로 에이전트가 남의 저장소에서 내려받아 프로젝트 폴더에 넣은 스킬도 같은 경우입니다. 다만 카탈로그, 카드, scope가 없을 뿐입니다. 그것을 확인해 줄 사람은 여러분 말고 없습니다.

질문은 똑같습니다. 어디서 왔는가. 안에 무엇이 있는가. SKILL.md는 1분이면 읽지만, 폴더 전체를 확인해야 합니다. 그것이 가리키는 스크립트와 파일도 마찬가지입니다. 어떤 도구를 미리 스스로에게 허용하는가는 allowed-tools 필드가 보여 줍니다. 이 필드는 별도 확인 없이 미리 승인된 것을 보여 줄 뿐, 일어날 수 있는 일의 전체 목록이 아닙니다. 서드파티 서비스 저장소에서 온 스킬이라면 스스로에게 명령 실행을 허용해 두는 일이 얼마든지 있을 수 있고, 무언가를 밖으로 보내는 스킬이라면 그건 자연스러운 일입니다. 하지만 이건 첫 실행 뒤가 아니라 전에 봐야 할 것입니다.

플러그인과 다른 점은 하나입니다. 스킬에는 카드가 없지만, 그 대신 모든 내용이 평범한 텍스트로 바로 옆에 놓여 있고, 첫 실행 전에 읽어 볼 수 있습니다.

11. 설치할 때마다 해야 할 일

여섯 단계이고, 글에 나온 순서 그대로입니다.

1. 출처. 공식 카탈로그, 커뮤니티 카탈로그, 아니면 남의 저장소인지가 이후 얼마나 꼼꼼히 볼지를 정합니다.
2. 구성. 카드의 "Will install"; hooks와 MCP는 명령 실행과 외부로 나가는 걸 뜻하니 그런 항목은 설명을 열어 보세요.
3. 비용. 카드의 "Context cost"(공식 카탈로그의 경우)와 설치 전후의 /context. 플러그인 비용은 여러분의 모든 요청에서 빠져나갑니다.
4. Scope. 맞는 것 중 가장 좁은 scope. project scope는 동료를 위한 결정이기도 합니다.
5. 시험 실행. 전후로 작업 하나씩, 설명이 아니라 자신의 테스트에서 나온 결론.
6. 결정. 유지, 끄기, 제거. 2주쯤 지나면 Installed 탭이 쓰지 않은 것을 다시 알려 줄 겁니다.

이름표 붙은 상자는 절차를 통째로, 종이 한 장씩 보내지 않고 건네주려고 만들어졌고, 이건 양쪽 모두에게 적용됩니다. 상자를 받는 사람은 이름표를 보고, 뚜껑을 열고, 오늘 필요한 것만 작업대에 올려놓습니다.

플러그인 패널과 그 메시지 문구는 버전마다 바뀝니다. 화면이 여기 설명과 다르다면 정확한 모양이 아니라 문구의 의미를 기준으로 삼으세요.