한 번의 명령으로 필요한 모든 것을 설치하기: Claude Code 플러그인 설정

요약 (TL;DR): Claude Code 스킬(skill)은 Claude가 읽고 실행하는 SKILL.md 파일입니다. 여러 마켓플레이스에 걸쳐 전체 플러그인 라인업을 올바른 순서로 설치하고, 사용자의 의견이 반영된 CLAUDE.md를 글로벌 설정에 추가할 것을 제안하는 스킬을 작성할 수 있습니다. 프론트매터(frontmatter) 한 줄을 통해 자동으로 실행되는 것을 방지할 수 있으므로, 이름을 직접 호출할 때만 실행됩니다. 이 글에서는 새로운 기기를 단 한 번의 명령으로 제로 상태에서 완전한 설정 상태로 만드는 스킬 구축 과정을 살펴봅니다.

새로운 기기에 Claude Code를 설정하는 것은 망각의 작은 의식과 같습니다. 플러그인을 재설치하다가, 마켓플레이스를 추가하기 전에 먼저 설치하려고 시도했다는 사실을 깨닫게 됩니다. 결국 작동은 하지만, CLAUDE.md를 복사해오지 않았기 때문에 글로벌 기본 설정(global defaults)은 하나도 남아있지 않습니다. 한 시간 뒤에 설정은 완료되지만, 당신은 다음번을 위한 플러그인과 스킬의 절반을 이미 잊어버린 상태가 됩니다.

그래서 저는 이 모든 의식을 하나의 스킬로 옮겼습니다. 이는 첫 번째 글에서 다룬 마켓플레이스(marketplace) 개념을 직접적으로 확장한 것입니다. 아직 스캐폴딩(scaffolded)을 하지 않았다면 거기서부터 시작하세요. 이 글의 URL을 Claude Code에 직접 전달하여 따라 할 수도 있습니다.

스킬은 단순한 마크다운(Markdown) 파일입니다

이 부분은 사람들을 놀라게 합니다. Claude Code 스킬은 플러그인의 skills/ 디렉토리 하위 폴더에 있는 단순한 SKILL.md 파일일 뿐이며, 특별한 DSL(Domain Specific Language)이나 스크립트 형식이 필요하지 않습니다. Claude는 이를 지침으로 읽고 수행합니다.

plugins/your-plugin/
└── skills/
    └── plugin-setup/
...

폴더 이름이 당신이 호출할 이름이 됩니다. 파일 안의 모든 내용은 프롬프트(prompt)입니다. 단계를 평이한 영어로 작성하면, 당신이 /your-plugin:plugin-setup을 호출할 때 Claude가 이를 실행합니다.

얼마 전 Claude Code 명령어를 작성해 본 적이 있다면, 그것들이 바로 이곳으로 이동했습니다. Anthropic은 슬래시 명령어(slash commands)를 스킬로 통합했으므로, 예전에 작성했을 수도 있는 commands/plugin-setup.md는 이제 skills/plugin-setup/SKILL.md가 되었으며, 호출 방식은 정확히 동일합니다 (문서에 설명되어 있습니다). 이제 스킬이 유일한 기본 단위(primitive)입니다.

이러한 병합(merge)은 특히 설정(setup) 과정에서 중요합니다. 왜냐하면 스킬(skill)은 두 가지 방식으로 실행될 수 있기 때문입니다: 이름을 직접 호출하거나, 요청 내용이 관련이 있다고 판단될 때 Claude가 스스로 로드하는 방식입니다. 설치 프로그램(installer) 입장에서는 두 번째 방식이 가장 피하고 싶은 상황입니다. 관련 없는 문장에서

얼마나 설치할지 묻습니다. '전체 설치' 또는 '선택 설치'라는 깔끔한 두 가지 옵션을 제공하며, 이를 위해 스킬은 구조화된 다중 선택 프롬프트인 AskUserQuestion을 사용합니다.
사용자가 요청한 경우 선택하게 합니다. 이 단계에서는 의도적으로 AskUserQuestion을 건너뜁니다. 마켓플레이스(marketplace)가 여러 개이고 플러그인(plugin)이 수십 개라면 위젯 방식은 번거로워지기 때문입니다. 따라서 스킬은 마켓플레이스 그룹별로 플러그인 번호 목록을 출력하고, 다음 단계로 넘어가기 전 한 번에 한 그룹씩 일반 텍스트 응답을 받습니다. 스무 개의 체크박스를 일일이 클릭할 필요가 없습니다.
올바른 순서로 설치합니다. 수동으로 할 때 가장 골치 아픈 단계입니다. 플러그인은 해당 마켓플레이스가 먼저 등록되지 않으면 설치할 수 없습니다. 따라서 스킬은 마켓플레이스를 먼저 추가한 다음 플러그인을 추가하며, 해당 마켓플레이스의 플러그인이 최소 하나 이상 선택된 경우에만 마켓플레이스를 추가합니다. 마켓플레이스에서 아무것도 선택하지 않으면 해당 마켓플레이스는 등록되지 않습니다.
글로벌 CLAUDE.md를 제안합니다. 마지막 마무리 단계이자 대부분의 설정 과정에서 생략되는 부분입니다. 왜 이것이 별도의 선택 사항(opt-in)인지에 대해서는 아래에서 자세히 설명합니다.

플러그인이 설치된 후, 스킬은 사용자에게 Claude Code를 재시작하라고 안내합니다. 플러그인은 재시작 시 활성화되기 때문입니다.

CLAUDE.md 단계가 명시적인 제안인 이유

첫 번째 문서에서 이 점을 강조했습니다. 플러그인 폴더 내부에 있는 CLAUDE.md는 그 자체로는 아무런 역할을 하지 않습니다. Claude Code의 플러그인 시스템은 이를 무시합니다. 따라서 글로벌 기본 설정(global defaults)을 플러그인 파일로 배포하더라도 어디에도 적용되지 않습니다.

설정 스킬은 마지막 단계에서 수동으로 이 간극을 메웁니다. 즉, 플러그인의 CLAUDE.md를 사용자의 글로벌 ~/.claude/CLAUDE.md로 복사할 것을 제안합니다. 핵심은 '제안'이라는 점입니다. 사용자의 글로벌 CLAUDE.md는 개인적인 것이며, 설정 실행 중에 이를 조용히 덮어쓰는 것은 공격적인 동작이 될 수 있습니다. 따라서 스킬은 먼저 확인 과정을 거칩니다. 기존 파일이 있는 경우 사용자에게 보여준 다음, 내용을 추가(append)할지, 교체(replace)할지, 아니면 건너뛸지(skip) 결정하게 합니다. 사용자는 매번 직접 선택(opt in)합니다.

큐레이션된 목록에 들어가는 내용

플러그인 목록은 스킬의 본체입니다. 마켓플레이스별로 그룹화하고, 각 플러그인 위에 주석(comment)으로 한 줄 설명을 작성하세요. 스킬은 선택 메뉴를 출력할 때 해당 주석들을 읽어줍니다.

이를 당신이 편집할 시작점으로 간주하세요. 마켓플레이스(Marketplaces)를 하나의 블록으로 구성하고, 플러그인들은 그것들이 속한 마켓플레이스 아래에 그룹화합니다. 실제로 자주 사용하는 것들로 교체하세요.

전체 구조는 아래와 같습니다. 더 많은 예시가 필요하다면 참조 리포지토리(reference repo)에 제가 실제로 사용하는 더 긴 목록이 있습니다: github.com/Nagell/claude-marketplace.

전체 스킬 (The complete skill)

다음은 skills/plugin-setup/SKILL.md에 바로 넣을 수 있도록 준비된 전체 내용입니다. 이는 위에서 언급한 모든 요소들, 즉 에이전트 모드(agent-mode) 스위치, Windows 경로, 4단계 과정, CLAUDE.md 제안, 그리고 두 개의 마켓플레이스가 포함된 스타터 플러그인 목록을 하나로 연결합니다.

---
name: plugin-setup
description: Install all recommended plugins and marketplaces
...
```bash
/plugin marketplace add claude-plugins-official
/plugin marketplace add some-author/their-marketplace
```

### Plugins

...
```bash
# 탐색 및 리뷰 에이전트(exploration and review agents)를 활용한 기능 개발 워크플로우 (Feature development workflow)
/plugin install feature-dev@claude-plugins-official
# 브레인스토밍, 계획, 디버깅 및 TDD를 위한 조합 가능한 워크플로우 스킬 (Composable workflow skills)
/plugin install superpowers@claude-plugins-official
# 코멘트, 테스트 및 에러 핸들링을 위한 PR 리뷰 에이전트 (PR review agents)
/plugin install pr-review-toolkit@claude-plugins-official
```

#### their-marketplace

```bash
# 모든 프로젝트에서 사용하고 싶은 스킬
/plugin install some-skill@their-marketplace
```

저장한 뒤, 당신의 플러그인으로 설치하고 다음을 실행하세요:

/your-plugin:plugin-setup

다음 기사에서는 이를 더 발전시켜 보겠습니다. 도구 설치가 한 번의 명령으로 완료되면, 그다음 질문은 해당 도구가 세션당 어느 정도의 비용을 발생시키는지, 그리고 전체 토큰(token) 사용량을 어떻게 줄일 수 있는지에 대한 것이 됩니다.

시작하기

모든 것이 미리 연결된 깨끗한 상태로 시작하려면 스타터 템플릿(starter template)을 사용하세요: github.com/Nagell/claude-marketplace-template.

이 템플릿은 하나의 빈 플러그인, 합리적인 기본값이 설정된 CLAUDE.md, 그리고 버전 관리(versioning)와 릴리스(releases)를 자동으로 처리하는 GitHub Actions 워크플로(workflow)를 제공합니다. GitHub에서 "Use this template"을 클릭하면 첫 번째 플러그인을 추가할 준비가 완료됩니다.

여러 개의 플러그인과 실제 훅 스크립트(hook scripts)가 포함된 더 완전한 작동 예시를 보고 싶다면, 이 시리즈 전반에서 참조 리포지토리(reference repo)로 사용되는 github.com/Nagell/claude-marketplace를 확인하세요.