[Claude Code] 에이전트 확장 생태계 구축: Claude Code 플러그인 제작 및 커스텀 마켓플레이스 배포

1. 들어가며: 개별 프로젝트 커스터마이징의 한계를 넘어서

지난 학습 노트에서 다루었던 Agent Skills나 CLAUDE.md를 활용한 컨텍스트 주입 방식은 단일 프로젝트나 개인 개발 컴퓨터 환경을 최적화하는 데 매우 훌륭한 도구다. 하지만 비즈니스 규모가 커지고 팀의 구성원이 늘어나면 새로운 국면에 직면하게 된다.

"우리가 만든 고성능 빌드/테스트 검증용 Hook과 사내 코딩 컨벤션 Skill을 수십 명의 개발자 팀원에게 어떻게 일괄 배포할 것인가?" "여러 개의 MSA(마이크로서비스 아키텍처) 저장소에서 동일한 커스텀 에이전트 설정을 어떻게 중복 코드 없이 동기화할 것인가?"

이 질문에 대한 앤트로픽(Anthropic)의 기술적 해답이 바로 플러그인(Plugins)과 마켓플레이스(Marketplaces)다. 플러그인을 활용하면 복잡한 도구 세트(LSP, MCP, Hooks, Monitors)를 하나의 단위로 패키징할 수 있고, 마켓플레이스 카탈로그를 빌드하여 팀이나 사내망 전체에 안전하고 일관되게 배포할 수 있다.

[Claude Code] Claude Agent Skills 설계 패턴과 실무 활용 정리

1. 들어가며: 에이전트에게 '절차적 지식'이 필요한 이유대형 언어 모델(LLM)의 발전으로 우리는 단순히 질문에 답하는 챗봇을 넘어, 직접 컴퓨터 환경과 상호작용하는 '일반 목적형 에이전트(Gener

myblog01150.tistory.com

2. 패러다임 비교: 독립 실행형 구성 vs 플러그인

플러그인을 본격적으로 설계하기 전, 내가 해결하고자 하는 문제에 어떤 접근 방식이 적합한지 기준을 세워야 한다.

비교 항목	독립 실행형 구성 (.claude/)	플러그인 (.claude-plugin/)
적용 범위	단일 프로젝트 저장소 내로 제한됨	여러 프로젝트 및 팀원 전체에 다중 전파 가능
식별자 체계	단축 명령어 이름 사용 (예: /hello, /deploy)	플러그인명이 접두사로 붙는 네임스페이스 구조 (예: /my-plugin:hello)
구성 요소의 한계	주로 개별 Skills, 간단한 Hooks 위주 구성	Skills, Agents, Hooks는 물론 MCP, LSP 서버, 백그라운드 모니터(Monitors)까지 융합 가능
버전 관리 및 배포	수동으로 복사하거나 프로젝트 Git과 연계	마켓플레이스 카탈로그 등록, 버전 태깅, 원클릭 업데이트 지원
추천 용도	개인 전역 워크플로우 설정, 단일 프로젝트용 임무	조직 공통 개발 표준 배포, 패키징된 도구 공유

💡 네임스페이스(Namespace)의 안전성

독립 실행형 명령어는 이름이 충돌하면 덮어써지거나 에러가 발생하지만, 플러그인 형태로 등록된 기술들은 /plugin-name:skill-name 형태로 명확히 격리된다. 이는 대규모 엔터프라이즈 환경에서 여러 팀이 만든 다양한 자동화 스크립트들이 상호 충돌 없이 공존할 수 있도록 보장해준다.

3. 플러그인의 아키텍처 및 내부 구조 (Anatomy)

플러그인은 독립적으로 기능할 수 있는 모든 구성 요소를 수용하는 '컨테이너 패키지'와 같다. 전형적인 완성형 플러그인의 폴더 배치는 다음과 같다.

my-first-plugin/              # 플러그인 루트 디렉토리
├── .claude-plugin/
│   └── plugin.json           # 필수: 플러그인 신원 정보를 담은 메타데이터 매니페스트
├── settings.json             # 선택: 플러그인 활성화 시 주 에이전트 등의 기본 설정 제어
├── skills/
│   └── hello/
│       └── SKILL.md          # 선택: 네임스페이스 기반의 커스텀 스킬 지침
├── agents/
│   └── security-reviewer.md  # 선택: 시스템 프롬프트가 이식된 특화 서브에이전트
├── hooks/
│   └── hooks.json            # 선택: 파일 작성/도구 사용 시점 가로채기 자동화 룰
├── monitors/
│   └── monitors.json         # 선택: 백그라운드에서 특정 로그나 리소스를 관측하는 데몬
└── bin/
    └── linter.sh             # 선택: Claude Code가 셸 내부 PATH로 즉시 참조할 실행 파일

⚠️ 흔히 하는 실수: .claude-plugin/ 내부의 오염 방지

개발 도중 가징 많이 저지르는 실수는 skills/나 agents/ 같은 핵심 구성 요소 폴더를 메타데이터 저장 공간인 .claude-plugin/ 안으로 집어넣는 것이다. 반드시 .claude-plugin/ 폴더 안에는 오직 plugin.json 파일 하나만 존재해야 하며, 다른 모든 실체 요소들은 플러그인의 루트 경로에 존재해야 에이전트의 파싱 엔진이 정상적으로 구조를 인식한다.

3.1 매니페스트 파일 (plugin.json) 명세

{
  "name": "my-first-plugin",
  "description": "사내 컨벤션 검증 및 릴리스 배포 지원 플러그인",
  "version": "1.1.0",
  "author": {
    "name": "인프라코어팀",
    "email": "infra-dev@acme.com"
  },
  "homepage": "[https://wiki.acme.com/dev/plugins](https://wiki.acme.com/dev/plugins)",
  "repository": "git@github.com:acme-corp/my-first-plugin.git",
  "license": "MIT"
}

name: 플러그인의 공식 아이디가 되며, 터미널 자동 완성 네임스페이스 접두사로 매핑된다.
version: 시멘틱 버저닝(SemVer)을 준수해야 하며, 마켓플레이스 자동 업데이트 모듈은 이 필드의 숫자 변경을 감지해 클라이언트로 업그레이드 배포를 진행한다.

4. [실습] 나만의 플러그인 구축과 로컬 테스트

직접 간단한 코드 품질을 자동 진단하는 quality-review 플러그인을 바닥부터 빌드하고 터미널에서 구동해 보자.

STEP 1: 디렉토리 및 매니페스트 구성

로컬 개발 공간에 폴더 구조를 형성하고 플러그인의 신원을 등록한다.

# 1. 플러그인 아웃라인 생성
mkdir -p qa-tools/.claude-plugin
mkdir -p qa-tools/skills/analyzer

# 2. 매니페스트 파일 생성
cat << 'EOF' > qa-tools/.claude-plugin/plugin.json
{
  "name": "qa-tools",
  "description": "코드 품질 정밀 검토 및 아키텍처 제언 도구",
  "version": "1.0.0"
}
EOF

STEP 2: 스킬 핵심 지침 및 동적 인수 설계

스킬 디렉토리 안에 SKILL.md를 채워 넣는다. 사용자가 검토를 요청하며 넘겨주는 다양한 코드 블록이나 컴포넌트 명을 인수로 처리하기 위해 $ARGUMENTS 예약어를 활용해 본다.

# qa-tools/skills/analyzer/SKILL.md 경로로 보관할 내용

---
description: 주어진 코드의 설계 컨벤션을 ACME 엔지니어링 표준 기준으로 검증합니다.
disable-model-invocation: true
---

# ACME Code Analyzer

당신은 조직의 수석 아키텍트입니다. 다음 컴포넌트나 코드 영역에 대해 보안, 가독성, 성능 측면에서 날카롭게 질의하고 문제점을 감지하세요.

### 검토 대상 (사용자 입력)
$ARGUMENTS

### 필수 검증 룰셋
1. **의존성 규격:** 상위 계층의 컴포넌트가 하위 계층(도메인 데이터)의 세부 사항에 밀접하게 결합되어 있지는 않은가?
2. **트랜잭션 바운더리:** 영속성 작업이 일어날 때 적절한 트랜잭션 경계 설정이 선언적으로 명시되어 있는가?
3. **가시성:** 데이터 은닉 원칙(Encapsulation)을 위배하는 public 필드나 불필요한 게터/세터가 남발되었는가?

검토 결과를 명확한 불릿 포인트와 기술적 왜(Why)를 담아 한글로 보고해 주세요.

STEP 3: --plugin-dir을 사용한 로컬 무설치 런타임 검증

배포용 압축 패키지나 원격 마켓플레이스 등록 절차 없이, 현재 로컬에 존재하고 있는 생성 단계의 디렉토리를 곧바로 Claude Code 세션에 장착해 테스트한다.

# 로컬 개발 경로를 지목하여 세션 구동
claude --plugin-dir ./qa-tools

Claude Code가 기동되면 터미널 상단에 새로운 플러그인 로드 메시지가 나타난다.
아래의 명령어로 네임스페이스 기반 호출을 시험해 보자:

> /qa-tools:analyzer "public class User { public String password; }"

Claude가 $ARGUMENTS 위치에 사용자가 전달한 패스워드 오염 코드를 안정적으로 이식하여, 규칙에 부합하는 정밀 분석 결과서를 출력해 주면 성공이다.

5. 사내 커스텀 마켓플레이스(Custom Marketplace) 배포

로컬 테스트를 마쳐 안정성이 입증된 플러그인 패키지들을 사내 전체 개발자나 협업 팀에 전파하기 위해서는 사설 마켓플레이스라는 단일 창구를 개설해야 한다.

마켓플레이스의 실체는 매우 심플하다. 하나 혹은 그 이상의 플러그인들을 모듈별로 정리하고, 이들이 호스팅되고 있는 소스 저장소 경로들을 매핑해 둔 하나의 정적인 marketplace.json 인덱스 파일 시스템에 불과하다.

5.1 marketplace.json 스키마 설계 및 strict 모드 적용

마켓플레이스 저장소의 루트 경로 하위에 .claude-plugin/marketplace.json 파일을 작성한다.

{
  "name": "acme-devtools-catalog",
  "owner": {
    "name": "플랫폼팀 인프라 조직",
    "email": "platform-engine@acme.com"
  },
  "plugins": [
    {
      "name": "qa-tools",
      "displayName": "ACME 코드 보안 탐지기",
      "description": "프로덕션 코드의 정적 컨벤션을 통제하는 플러그인",
      "source": "./plugins/qa-tools",
      "strict": true
    },
    {
      "name": "deploy-helper",
      "displayName": "릴리스 배포 자동화 지원기",
      "description": "클라우드 자원 배포용 가이드 및 툴 제공",
      "source": {
        "source": "github",
        "repo": "acme-corp/deploy-helper-plugin",
        "ref": "v2.3.0",
        "sha": "9b1deb4d3b7d1e8c9b2f3a4b5c6d7e8f9a0b1c2d"
    },
      "strict": false
    }
  ]
}

🧐 Strict 모드의 선택적 활용 (설계 의사결정의 키)

strict: true (기본값): 플러그인 저장소 자체에 내장된 .claude-plugin/plugin.json 매니페스트 파일이 최종 권한을 지닌다. 마켓플레이스는 단순히 플러그인의 위치(Source)만 안내하고, 실제 구동 스펙이나 설정값은 플러그인 개발팀이 관리한다.
strict: false: 마켓플레이스 운영자(Platform Team)가 완전한 통제 주도권을 쥔다. 플러그인 자체에 매니페스트가 없거나, 혹은 있더라도 마켓플레이스 파일 내부에서 재정의한 구성(Skills, Hooks, Commands 지정 등)이 플러그인의 실제 규칙들을 강제로 덮어쓰고 통제한다. 사내 보안 가이드라인 준수가 필수적인 기업 환경에 아주 적합하다.

5.2 사용자 배포 및 등록 프로세스

설계를 마친 마켓플레이스 저장소를 사내 Git 서버에 푸시한 뒤, 각 개발자 컴퓨터 터미널에서 이를 추가하고 플러그인을 내려받게 가이드한다.

# 1. 사설 마켓플레이스 채널 등록 (예: acme-corp의 중앙 카탈로그)
claude plugin marketplace add acme-corp/acme-devtools-catalog

# 2. 마켓플레이스 소속 플러그인 검색 및 타겟 설치
claude plugin install qa-tools@acme-devtools-catalog

6. 고급 운영 및 거버넌스 관리 (Enterprise Operations)

대규모 IT 조직에서 수백 명의 엔지니어가 사용하는 Claude Code 인프라를 안전하게 유지관리하고, 배포 속도를 최적화하기 위한 고급 운영 기법들이다.

6.1 프라이빗 저장소 인증과 백그라운드 자동 업데이트

사내 사설 마켓플레이스나 플러그인 코드가 비공개(Private) Git 저장소에 잠겨 있다면, Claude Code는 로컬 컴퓨터 터미널의 기존 자격 증명 도우미(Git Credential Helper)를 고스란히 차용해 가져간다. 즉, SSH 키(ssh-agent)가 등록되어 있거나, gh auth login을 통해 터미널이 사전 신뢰된 상태라면 무리 없이 인증 관문을 통과한다.

그러나 백그라운드 자동 업데이트는 비대화형(Non-interactive) 환경에서 작동하므로 프롬프트 입력을 통한 암호 제출이 원천 차단된다. 이를 완벽하게 우회하려면 환경 변수에 전용 액세스 토큰을 세팅해 두어야 한다.

# GitHub Enterprise 및 사설 GitHub 조직을 사용할 경우 (기밀 토큰 인젝션)
export GITHUB_TOKEN=ghp_yourEnterprisePersonalAccessTokenHere

6.2 도커(Docker) 컨테이너 및 CI 환경 최적화 (Seed Dir)

개발용 가상 환경 컨테이너나 원격 CI/CD 파이프라인에서 Claude Code가 매번 가동될 때마다 원격 깃허브에서 수십 메가바이트 크기의 플러그인을 복제해 오느라 네트워크 지연이 발생하고 빌드 시간이 늦어지는 문제점을 극복하는 특급 처방이다.

이미지 빌드 시점에 플러그인을 미리 로컬 특정 경로에 패키징하여 캐시로 구워두고, 런타임 기동 시에 읽기 전용 구조로 재이용하게 만드는 시드 디렉토리(Seed Directory) 패턴을 활용한다.

Dockerfile 실전 템플릿 예시

# 1단계: 빌드 타임 캐싱 레이어 구성
FROM node:20-slim AS builder

RUN npm install -g @anthropic-ai/claude-code

# 특정 빌드 대상 시드 디렉토리 정의 및 가상의 캐시 변수 설정
ENV CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed

# 빌드 시점에 사내 플러그인들을 안전하게 로컬 디스크로 선복제 진행
RUN claude plugin marketplace add acme-corp/acme-devtools-catalog && \
    claude plugin install qa-tools@acme-devtools-catalog

# 2단계: 최종 경량 프로덕션 이미지
FROM node:20-slim
COPY --from=builder /opt/claude-seed /opt/claude-seed

# 컨테이너 실행 환경 변수 주입 (완벽한 네트워크 차단 모드 동작 가능)
ENV CLAUDE_CODE_PLUGIN_SEED_DIR=/opt/claude-seed

ENTRYPOINT ["claude"]

6.3 엔터프라이즈 화이트리스트 제한 (strictKnownMarketplaces)

보안 통제실과 아키텍처 거버넌스 조직의 허락 없이, 사용자가 임의의 무작위 외부 플러그인을 마구잡이로 설치하여 사내 원스톱 코드나 설계 자산이 외부 악성 서버로 유출되거나, 부적절한 셸 스크립트 도구 오용으로 시스템이 망가지는 잠재적 보안 리스크를 통제하는 최후의 바리케이드다.

엔터프라이즈 전역 통제 설정 파일(managed-settings.json) 내부에서 strictKnownMarketplaces와 extraKnownMarketplaces 프로퍼티의 유기적 결합을 통해 완벽한 화이트리스트 망을 형성한다.

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "acme-corp/approved-plugins-catalog"
    },
    {
      "source": "hostPattern",
      "hostPattern": "^github\\.internal-domain\\.net$"
    }
  ],
  "extraKnownMarketplaces": {
    "acme-secure-market": {
      "source": {
        "source": "github",
        "repo": "acme-corp/approved-plugins-catalog"
      }
    }
  }
}

strictKnownMarketplaces: 사용자가 추가 등록하거나 플러그인을 내려받을 수 있는 마켓플레이스의 범위를 '정확히 명시된 목록'이나 '사내 프라이빗 도메인 정규식 패턴'으로 극단적으로 제한한다. 이 목록에 명시되지 않은 경로에 대한 모든 마켓플레이스 설치 및 질의는 네트워크 시작 전에 시큐리티 게이트키퍼(Security Gatekeeper) 선에서 원천 기각된다.

7. 마무리: 에이전트를 넘어 독자적 생태계로

단순히 AI 프롬프트를 튜닝하여 챗봇에게 질의하던 초창기 단계에서 벗어나, 이제 우리는 AI 에이전트가 로컬 도구들을 능수능란하게 활용할 수 있도록 가이드를 부여하는 시대를 살아가고 있다.

한 단계 더 나아가 Claude Code 플러그인과 사설 마켓플레이스 인프라는 분산되어 있는 소중한 개발 조직의 노하우와 컴파일 환경, 정적 컨벤션 룰셋, 그리고 보안 모니터링 체계를 고도로 규격화하여 전파할 수 있는 강력한 배포 바퀴다.

사내 개발 플랫폼의 미래는 에이전트의 영리함을 지속적으로 가공하고 동기화하는 것에 달려 있다. 지금 당장 사내 표준 아키텍처 컨벤션 검증 규칙을 품은 작지만 강력한 플러그인을 제작하여, 당신의 팀원들과 함께 더 안전하고 정밀하게 설계된 고속 개발 생태계를 시작해 보길 권한다.

'Claude' 카테고리의 다른 글

[Claude Code] 클로드 코드 에이전트 팀 & 에이전트 뷰 정리 (0)	2026.05.24
[Claude Code] 에이전틱 루프와 EPIC 워크플로우 구축하기 (1)	2026.05.24
[Claude Code] Claude Agent Skills 설계 패턴과 실무 활용 정리 (0)	2026.05.23
[Claude Code] Hooks 분석 : 개발 워크플로우를 통제하는 자동화 (0)	2026.05.18
[Claude Code] 서브에이전트(Subagents) 시스템 (0)	2026.05.10

coding_whale 님의 블로그

[Claude Code] 에이전트 확장 생태계 구축: Claude Code 플러그인 제작 및 커스텀 마켓플레이스 배포

1. 들어가며: 개별 프로젝트 커스터마이징의 한계를 넘어서

2. 패러다임 비교: 독립 실행형 구성 vs 플러그인

💡 네임스페이스(Namespace)의 안전성

3. 플러그인의 아키텍처 및 내부 구조 (Anatomy)

⚠️ 흔히 하는 실수: .claude-plugin/ 내부의 오염 방지

3.1 매니페스트 파일 (plugin.json) 명세

4. [실습] 나만의 플러그인 구축과 로컬 테스트

STEP 1: 디렉토리 및 매니페스트 구성

STEP 2: 스킬 핵심 지침 및 동적 인수 설계

STEP 3: --plugin-dir을 사용한 로컬 무설치 런타임 검증

5. 사내 커스텀 마켓플레이스(Custom Marketplace) 배포

5.1 marketplace.json 스키마 설계 및 strict 모드 적용

🧐 Strict 모드의 선택적 활용 (설계 의사결정의 키)

5.2 사용자 배포 및 등록 프로세스

6. 고급 운영 및 거버넌스 관리 (Enterprise Operations)

6.1 프라이빗 저장소 인증과 백그라운드 자동 업데이트

6.2 도커(Docker) 컨테이너 및 CI 환경 최적화 (Seed Dir)

Dockerfile 실전 템플릿 예시

6.3 엔터프라이즈 화이트리스트 제한 (strictKnownMarketplaces)

7. 마무리: 에이전트를 넘어 독자적 생태계로

'Claude' 카테고리의 다른 글

티스토리툴바

[Claude Code] 에이전트 확장 생태계 구축: Claude Code 플러그인 제작 및 커스텀 마켓플레이스 배포

1. 들어가며: 개별 프로젝트 커스터마이징의 한계를 넘어서

2. 패러다임 비교: 독립 실행형 구성 vs 플러그인

💡 네임스페이스(Namespace)의 안전성

3. 플러그인의 아키텍처 및 내부 구조 (Anatomy)

⚠️ 흔히 하는 실수: .claude-plugin/ 내부의 오염 방지

3.1 매니페스트 파일 (plugin.json) 명세

4. [실습] 나만의 플러그인 구축과 로컬 테스트

STEP 1: 디렉토리 및 매니페스트 구성

STEP 2: 스킬 핵심 지침 및 동적 인수 설계

STEP 3: --plugin-dir을 사용한 로컬 무설치 런타임 검증

5. 사내 커스텀 마켓플레이스(Custom Marketplace) 배포

5.1 marketplace.json 스키마 설계 및 strict 모드 적용

🧐 Strict 모드의 선택적 활용 (설계 의사결정의 키)

5.2 사용자 배포 및 등록 프로세스

6. 고급 운영 및 거버넌스 관리 (Enterprise Operations)

6.1 프라이빗 저장소 인증과 백그라운드 자동 업데이트

6.2 도커(Docker) 컨테이너 및 CI 환경 최적화 (Seed Dir)

Dockerfile 실전 템플릿 예시

6.3 엔터프라이즈 화이트리스트 제한 (strictKnownMarketplaces)

7. 마무리: 에이전트를 넘어 독자적 생태계로

'Claude' 카테고리의 다른 글

관련글

티스토리툴바