Claude Code 플러그인 설치, 확인, 삭제

플러그인은 여러 프로젝트에서 지시나 도구를 재사용할 때 유용합니다. 설치 과정만 확인하려면 알 수 없는 hooks가 든 외부 패키지가 필요하지 않습니다. 명시적으로 호출하는 skill 하나로 정해진 문자열을 반환하는 자체 플러그인부터 만들어 보세요.

예시는 Claude Code를 설치하고 설정한 macOS/Linux 환경을 전제로 합니다. Windows에서는 같은 JSON과 Markdown을 편집기로 만들 수 있지만 셸 명령은 Bash 또는 Zsh용입니다. 모델 응답에는 정상적인 연결이 필요하며 구조 검증은 별도로 진행합니다.

파일 세 개 만들기

새 빈 디렉터리에서 실행하세요.

mkdir -p plugin-lab/.claude-plugin
mkdir -p plugin-lab/plugins/load-check/.claude-plugin
mkdir -p plugin-lab/plugins/load-check/skills/ping

plugin-lab/plugins/load-check/.claude-plugin/plugin.json에 저장합니다.

{
  "name": "load-check",
  "version": "1.0.0",
  "description": "Local plugin loading exercise"
}

plugin-lab/plugins/load-check/skills/ping/SKILL.md에는 다음을 저장합니다.

---
description: Return a marker to verify this local plugin is loaded.
disable-model-invocation: true
---

Return exactly PLUGIN_READY. Do not use tools or change files.

plugin-lab/.claude-plugin/marketplace.json에는 다음을 저장합니다.

{
  "name": "local-load-lab",
  "owner": {"name": "Local developer"},
  "plugins": [
    {"name": "load-check", "source": "./plugins/load-check"}
  ]
}

marketplace는 패키지 위치를 가리킵니다. 패키지 안에서 .claude-plugin에는 manifest가 들어가고 skills는 그 옆에 놓입니다. skills를 .claude-plugin 안에 넣으면 공식 구조에 맞지 않습니다.

구조 검증과 설치

처음 디렉터리에서 실행합니다.

claude --version
claude plugin validate ./plugin-lab/plugins/load-check
claude plugin validate ./plugin-lab
claude

검증 오류가 있으면 지적된 파일부터 수정하세요. 구조가 올바르다는 결과가 지시의 품질이나 임의의 플러그인 안전성까지 증명하지는 않습니다.

Claude Code 세션에서 실행합니다.

/plugin marketplace add ./plugin-lab
/plugin install load-check@local-load-lab

설치 패널에서 Local을 선택해 현재 프로젝트로 시험 범위를 제한하세요. 확인 전에 설정이 저장될 위치를 읽으세요. 요약 화면에서 다시 불러오라고 하면 /reload-plugins를 실행합니다. 순서는 공식 marketplace 안내에 나와 있습니다.

올바른 skill이 로드됐는지 확인

/plugin list
/load-check:ping

첫 명령은 설치된 패키지를 보여 주고 두 번째는 PLUGIN_READY를 반환해야 합니다. 전체 이름 /load-check:ping에는 플러그인 이름이 포함되어 다른 패키지의 동명 skill과 구분됩니다.

작업 디렉터리도 확인하세요. 시험용 skill은 파일을 바꾸지 않아야 합니다. 도구를 사용하지 말라는 문장은 모델 지시이며 별도의 시스템 권한 경계를 만들지는 않습니다. 접근은 Claude Code permissions로 관리합니다.

명령이 없으면 manifest 이름, skills/ping/SKILL.md 위치, 설치 범위, enabled 상태, 다시 불러오기 필요 여부를 차례로 확인하세요. marketplace 로딩과 --plugin-dir 실행은 따로 시험합니다.

비활성화, 업데이트, 삭제

claude plugin disable load-check@local-load-lab --scope local
claude plugin enable load-check@local-load-lab --scope local
claude plugin update load-check@local-load-lab --scope local
claude plugin uninstall load-check@local-load-lab --scope local

같은 프로젝트에서 하나씩 실행하고 결과를 확인하세요. --scope local은 선택한 설치 범위에 해당합니다. 없으면 update와 uninstall의 기본 대상은 user입니다. 업데이트 후 CLI가 요청하면 세션을 다시 시작하세요. 비활성화나 삭제 후에는 새 세션에서 skill이 사라졌는지 확인하고, 활성화 후에는 짧은 시험을 반복합니다.

내용 변경을 시험하려면 원본 skill의 마커를 바꾸고 패키지 버전을 올린 다음 관리 안내에 따라 marketplace와 설치된 플러그인을 업데이트하세요. 원본 파일을 고쳐도 캐시된 설치본은 바뀌지 않을 수 있습니다.

외부 플러그인 도입 전

패키지 구성을 먼저 읽으세요. 텍스트 skill, 셸 명령 hook, MCP 서버는 프로젝트에 미치는 영향이 다릅니다. 명령, 외부 서비스 주소, 비밀 정보를 요구하는 지시를 점검하세요. 설치 오류를 없애려고 추가 권한부터 주지 마세요.

실제 프로젝트에서도 범위 확인, 구성 요소 표시, 예상 동작, 파일 확인, 명확한 비활성화 방법이라는 짧은 절차를 반복하세요. 전체 형식과 validator 기능은 플러그인 참조 문서에 있습니다.