클로드코드 플러그인 완전정복 · 7편

클로드코드 플러그인 완전정복 · 7편

흩어진 .claude/ 설정, 플러그인으로 이사시키기

복사 붙여넣기 4단계 — 근데 원본을 안 지우면 이상한 일이 생겨.

지금까지 클로드코드 쓰면서 .claude/ 폴더에 이것저것 쌓아뒀을 거야. 스킬 몇 개, 에이전트 몇 개, settings.json에 훅 하나둘. 다 잘 돌아가는데 딱 하나, 공유가 안 돼.

오늘은 그걸 플러그인으로 옮길 거야. 어렵지 않아. 대부분 cp 명령어야.

옮기면 뭐가 달라져?

	단독 설정 (.claude/)	플러그인
범위	이 프로젝트에서만	마켓플레이스로 어디든
스킬 위치	.claude/commands/	플러그인이름/commands/
훅 위치	settings.json 안	hooks/hooks.json
공유 방법	폴더 복사해서 전달	/plugin install 한 줄

1단계 — 플러그인 껍데기 만들기

기존 .claude/ 폴더 옆에 만들어야 해. 다음 단계의 상대경로가 그 기준으로 돌아가거든.

mkdir -p my-plugin/.claude-plugin

my-plugin/.claude-plugin/plugin.json

{
  "name": "my-plugin",
  "description": "단독 설정에서 옮겨온 플러그인",
  "version": "1.0.0"
}

2단계 — 파일 복사하기

있는 것만 골라서 복사하면 돼. 없는 폴더는 건너뛰고.

# 슬래시 명령어(레거시 형식)
cp -r .claude/commands my-plugin/

# 서브에이전트
cp -r .claude/agents my-plugin/

# 스킬
cp -r .claude/skills my-plugin/

💡 이왕 옮기는 김에 — commands/는 레거시 형식이야. 시간 여유 있으면 이 참에 skills/<이름>/SKILL.md 구조로 바꿔두면 좋아. 물론 commands/도 계속 동작하니까 급할 건 없어.

3단계 — 훅 옮기기 (여기가 유일하게 손이 가)

훅은 위치가 바뀌어서 복사만으로는 안 돼. 근데 형식은 그대로라 어렵진 않아.

mkdir my-plugin/hooks

.claude/settings.json이나 settings.local.json에서 hooks 객체를 통째로 들어다가 새 파일에 넣으면 돼. 6편에서 만든 그 형식 그대로야. 이번엔 스크립트를 부르는 형태로 예를 들어볼게.

.claude/settings.json (옮기기 전)

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/safety-check.sh"
          }
        ]
      }
    ]
  }
}

my-plugin/hooks/hooks.json (옮긴 후)

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/safety-check.sh"
          }
        ]
      }
    ]
  }
}

구조는 글자 하나 안 바뀌었지? 딱 하나, 경로만 달라졌어. 그리고 그게 이 단계에서 제일 중요한 부분이야.

⚠️ 훅 안의 경로를 반드시 점검하자
위 예제에서 ./scripts/safety-check.sh를 그대로 뒀다면 거의 확실히 깨져. 6편에서 얘기했듯 플러그인은 캐시로 복사되거든. 스크립트 파일도 my-plugin/scripts/ 안으로 같이 옮기고, 경로는 ${CLAUDE_PLUGIN_ROOT} 기준으로 바꿔줘.

4단계 — 테스트

claude --plugin-dir ./my-plugin

하나씩 확인해보자.

• 스킬 — /my-plugin:스킬이름으로 불러보기
• 에이전트 — /context의 Custom Agents에 뜨는지
• 훅 — 파일 하나 수정해보고 실제로 발동하는지
• 검증 — claude plugin validate ./my-plugin

여기서 사람들이 제일 많이 당황해

테스트해보면 뭔가 이상해. 스킬을 고쳤는데 옛날 버전이 나온다든가, 에이전트가 내가 만든 대로 안 움직인다든가. 원본을 안 지웠기 때문이야. 그런데 재밌는 건, 에이전트랑 스킬이 서로 다르게 동작한다는 거야.

에이전트 — 원본이 이겨

• 프로젝트/유저의 .claude/agents/에 같은 이름이 있으면
• 그쪽이 플러그인 버전을 덮어써
• 원본을 지워야 플러그인 버전이 살아나

스킬 — 둘 다 살아남아

• 플러그인 스킬은 /my-plugin:이름으로 네임스페이스가 붙으니까
• 원래 /이름이랑 이름이 안 겹쳐
• 결과적으로 중복돼서 둘 다 목록에 뜸

7편의 핵심

옮겼으면 원본을 지우자.
에이전트는 덮어써지고, 스킬은 중복돼. 둘 다 헷갈리는 상황이야.

그럼 다 옮겨야 하나?

아니. 오히려 안 옮기는 게 맞는 것들도 있어.

○ 옮기면 좋은 것

• 팀 코드 컨벤션 리뷰어
• 여러 프로젝트에서 쓰는 워크플로우
• MCP 연결이 딸린 파이프라인
• 남들도 쓸 만한 범용 도구

✕ 그냥 두는 게 나은 것

• 이 프로젝트에서만 의미 있는 설정
• 아직 실험 중인 것
• 내 개인 경로가 박혀 있는 것
• 짧은 이름으로 자주 부르는 것

마지막 항목이 은근 현실적이야. /deploy를 하루에 열 번 치는데 /my-plugin:deploy로 바뀌면 짜증나거든. 그런 건 그냥 .claude/에 두는 게 나아.

💡 실전 팁 — 처음부터 다 옮기려 하지 말고 제일 자주 쓰고 남들도 좋아할 것 하나만 골라서 옮겨봐. 한 바퀴 돌려보면 감이 잡히고, 그다음부턴 빨라져.

이사 후 체크리스트

• 원본 .claude/agents/, .claude/skills/에서 옮긴 것 삭제했나
• settings.json에 남은 훅 설정 정리했나
• 훅 안의 경로를 ${CLAUDE_PLUGIN_ROOT}로 바꿨나
• 플러그인 폴더 바깥을 참조하는 게 남아있진 않나
• claude plugin validate 통과하나
• README.md 써뒀나 (배포할 거면)

다음 편 예고 → 드디어 마지막이야. 8편에서는 만든 플러그인을 진짜로 배포할 거야. GitHub 저장소 하나로 내 마켓플레이스를 만들고, 팀 전용으로 돌리거나 커뮤니티에 제출하는 것까지. 사람들이 /plugin marketplace add 내아이디/내저장소 한 줄로 내 도구를 받아가게 되는 거지.