Claude Code Skills & Plugins 아키텍처
TL;DR
- Claude Code, Skills, Plugins, SKILL.md, plugin.json, Marketplace, Namespace, 네임스페이스, oh-my-claudecode, superpowers, 에이전트 오케스트레이션, SemVer, 버전 관리, 확장성, Hooks, MCP, LSP, Lazy Loading, 프론트매터
- Claude Code Skills & Plugins 아키텍처를 알아두면 설계 판단과 구현 선택을 더 분명하게 할 수 있다.
- 원문 전체는 아래 상세 내용에 그대로 포함했다.
1. 개념
Claude Code, Skills, Plugins, SKILL.md, plugin.json, Marketplace, Namespace, 네임스페이스, oh-my-claudecode, superpowers, 에이전트 오케스트레이션, SemVer, 버전 관리, 확장성, Hooks, MCP, LSP, Lazy Loading, 프론트매터
2. 배경
Claude Code Skills & Plugins 아키텍처가 등장한 배경과 문제 상황을 이해하는 데 도움이 된다.
3. 이유
Claude Code Skills & Plugins 아키텍처를 알아두면 설계 판단과 구현 선택을 더 분명하게 할 수 있다.
4. 특징
Claude Code Skills & Plugins 아키텍처의 특징, 장단점, 적용 포인트를 원문에서 자세히 확인할 수 있다.
5. 상세 내용
Claude Code Skills & Plugins 아키텍처
1. Skill이란?
┌─────────────────────────────────────────────────────────────────┐
│ Skill = Claude Code의 확장 단위 (원자) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 정의: │
│ Claude에게 특정 도메인의 지식과 행동 규칙을 주입하는 │
│ "온디맨드 프롬프트 확장 패키지" │
│ │
│ 핵심 구조: │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ ~/.claude/skills/simplify/ │ │
│ │ ├── SKILL.md ← 메타데이터(YAML) + 지시사항(MD) │ │
│ │ ├── examples/ ← 참고 파일 (선택) │ │
│ │ └── templates/ ← 템플릿 (선택) │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │
│ SKILL.md 예시: │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ --- │ │
│ │ name: simplify │ │
│ │ description: Review changed code for quality │ │
│ │ --- │ │
│ │ │ │
│ │ (마크다운 본문: Claude에게 전달되는 지시사항) │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │
│ 호출 방법: /simplify (사용자) 또는 자동 감지 (Claude) │
│ │
└─────────────────────────────────────────────────────────────────┘
Skill의 동작 원리
┌─────────────────────────────────────────────────────────────────┐
│ Skill 로딩 메커니즘 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 1단계: 앱 시작 시 │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ 모든 SKILL.md의 name + description만 스캔 │ │
│ │ → 시스템 컨텍스트에 <available_skills> 목록으로 주입 │ │
│ │ → 전체 컨텍스트 윈도우의 약 2%만 소비 │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │
│ 2단계: 호출 시 (온디맨드) │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ 사용자가 /simplify 입력 │ │
│ │ 또는 Claude가 description을 보고 자동 판단 │ │
│ │ → 그때서야 SKILL.md 전체 내용 로딩 │ │
│ │ → 토큰 비용은 실제 사용 시에만 발생 │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │
│ 핵심: Lazy Loading 방식 │
│ → 수십 개 스킬이 등록되어 있어도 미사용 스킬은 비용 0 │
│ │
└─────────────────────────────────────────────────────────────────┘
SKILL.md 프론트매터 옵션
┌─────────────────────────────────────────────────────────────────┐
│ 프론트매터로 Skill 동작 제어 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────────────────┬─────────────────────────────┐ │
│ │ 필드 │ 효과 │ │
│ ├───────────────────────────┼─────────────────────────────┤ │
│ │ disable-model-invocation │ 사용자만 호출 가능 │ │
│ │ : true │ Claude 자동 호출 불가 │ │
│ ├───────────────────────────┼─────────────────────────────┤ │
│ │ user-invocable: false │ Claude만 호출 가능 │ │
│ │ │ 백그라운드 지식용 │ │
│ ├───────────────────────────┼─────────────────────────────┤ │
│ │ context: fork │ 격리된 서브에이전트에서 │ │
│ │ │ 실행 (메인 윈도우 보호) │ │
│ ├───────────────────────────┼─────────────────────────────┤ │
│ │ allowed-tools │ Skill 활성화 시 사용 │ │
│ │ │ 가능한 도구 제한 │ │
│ ├───────────────────────────┼─────────────────────────────┤ │
│ │ model │ 특정 모델 강제 지정 │ │
│ │ │ (haiku/sonnet/opus) │ │
│ └───────────────────────────┴─────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
2. Plugin이란?
┌─────────────────────────────────────────────────────────────────┐
│ Plugin = 확장의 묶음 (분자) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 정의: │
│ 여러 확장 타입(Skills, Agents, Hooks, MCP, LSP)을 │
│ 하나의 네임스페이스 아래 묶어서 버전 관리하고 │
│ 배포할 수 있는 패키지 │
│ │
│ 비유: │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ Skill = npm 패키지 하나의 개별 함수 │ │
│ │ Plugin = npm 패키지 자체 (여러 함수 + 설정 + 의존성) │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │
│ Plugin 디렉토리 구조: │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ my-plugin/ │ │
│ │ ├── .claude-plugin/ │ │
│ │ │ └── plugin.json ← 매니페스트 (이름/버전/설명) │ │
│ │ ├── skills/ ← SKILL.md 디렉토리들 │ │
│ │ │ ├── autopilot/SKILL.md │ │
│ │ │ ├── analyze/SKILL.md │ │
│ │ │ └── ralph/SKILL.md │ │
│ │ ├── agents/ ← 커스텀 서브에이전트 정의 │ │
│ │ ├── hooks/ │ │
│ │ │ └── hooks.json ← 이벤트 핸들러 │ │
│ │ ├── .mcp.json ← MCP 서버 설정 │ │
│ │ ├── .lsp.json ← LSP 서버 설정 │ │
│ │ └── settings.json ← 기본 설정 │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
plugin.json 매니페스트
┌─────────────────────────────────────────────────────────────────┐
│ plugin.json = Plugin의 신분증 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ { │
│ "name": "oh-my-claudecode", ← 네임스페이스가 됨 │
│ "version": "3.3.8", ← SemVer 버전 관리 │
│ "description": "Multi-agent orchestration system", │
│ "author": { "name": "Yeachan Heo" }, │
│ "repository": "https://github.com/...", │
│ "license": "MIT", │
│ "skills": "./skills/" ← 스킬 디렉토리 지정 │
│ } │
│ │
│ name 필드가 핵심: │
│ → 이 값이 모든 스킬의 접두사가 됨 │
│ → /oh-my-claudecode:autopilot │
│ → /oh-my-claudecode:analyze │
│ → /oh-my-claudecode:ralph │
│ │
└─────────────────────────────────────────────────────────────────┘
3. Plugin Skill vs 일반 Skill: 근본적 차이
┌─────────────────────────────────────────────────────────────────┐
│ 일반 Skill vs Plugin Skill 비교 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┬──────────────────┬───────────────────────┐ │
│ │ 항목 │ 일반 Skill │ Plugin Skill │ │
│ ├──────────────┼──────────────────┼───────────────────────┤ │
│ │ 위치 │ ~/.claude/ │ ~/.claude/plugins/ │ │
│ │ │ skills/{name}/ │ cache/{org}/{name}/ │ │
│ │ │ │ {version}/skills/ │ │
│ ├──────────────┼──────────────────┼───────────────────────┤ │
│ │ 호출 │ /simplify │ /omc:autopilot │ │
│ │ │ (접두사 없음) │ (네임스페이스:이름) │ │
│ ├──────────────┼──────────────────┼───────────────────────┤ │
│ │ 메타데이터 │ SKILL.md만 │ plugin.json + │ │
│ │ │ │ SKILL.md │ │
│ ├──────────────┼──────────────────┼───────────────────────┤ │
│ │ 버전 관리 │ 없음 │ SemVer + Git SHA │ │
│ │ │ (수동 관리) │ (자동 추적) │ │
│ ├──────────────┼──────────────────┼───────────────────────┤ │
│ │ 배포 │ 수동 복사 │ Marketplace에서 │ │
│ │ │ │ 한 줄 설치 │ │
│ ├──────────────┼──────────────────┼───────────────────────┤ │
│ │ 네임스페이스│ 없음 │ plugin.json의 │ │
│ │ │ (이름 충돌 위험)│ name이 접두사 │ │
│ ├──────────────┼──────────────────┼───────────────────────┤ │
│ │ 번들링 │ 단일 스킬만 │ Skills + Agents + │ │
│ │ │ │ Hooks + MCP + LSP │ │
│ ├──────────────┼──────────────────┼───────────────────────┤ │
│ │ 스코프 │ 개인/프로젝트 │ User / Project / │ │
│ │ │ │ Local / Managed │ │
│ ├──────────────┼──────────────────┼───────────────────────┤ │
│ │ 업데이트 │ 수동 │ Marketplace에서 │ │
│ │ │ │ 자동 감지 │ │
│ └──────────────┴──────────────────┴───────────────────────┘ │
│ │
│ 한 줄 요약: │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ 일반 Skill = 개인 노트 │ │
│ │ Plugin Skill = 출판된 책 (ISBN 있고, 서점에서 팔림) │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
호출 방식의 차이
┌─────────────────────────────────────────────────────────────────┐
│ 호출 방식 비교 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ [일반 Skill] │
│ 사용자: /simplify │
│ 코드: Skill(skill="simplify") │
│ 에이전트: Task(subagent_type="executor") │
│ │
│ [Plugin Skill] │
│ 사용자: /oh-my-claudecode:autopilot │
│ 코드: Skill(skill="oh-my-claudecode:autopilot") │
│ 에이전트: Task(subagent_type="oh-my-claudecode:executor") │
│ │
│ 콜론(:) 앞 = Plugin의 name (네임스페이스) │
│ 콜론(:) 뒤 = Plugin 내부의 Skill 이름 │
│ │
│ 왜 이렇게 하나? │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ Plugin A에 /autopilot 있음 │ │
│ │ Plugin B에 /autopilot 있음 │ │
│ │ │ │
│ │ 네임스페이스 없으면? → 충돌! 어느 것을 실행할지 모름 │ │
│ │ 네임스페이스 있으면? → /a:autopilot vs /b:autopilot │ │
│ │ 명확하게 구분됨 │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
4. Plugin이 등장한 배경
┌─────────────────────────────────────────────────────────────────┐
│ Plugin 이전의 세계 (문제) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 상황: 개발자들이 강력한 Claude Code 설정을 만들어냄 │
│ → 공유하고 싶지만 방법이 없음 │
│ │
│ 공유하려면: │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ 1. SKILL.md 파일을 수동으로 복사/붙여넣기 │ │
│ │ 2. CLAUDE.md에 설정 내용 직접 붙여넣기 │ │
│ │ 3. hooks 설정 수동으로 따라하기 │ │
│ │ 4. MCP 서버 설정 별도로 하기 │ │
│ │ 5. 에이전트 정의 따로 복사하기 │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │
│ 문제점: │
│ ├── 버전 관리 없음: 원본이 업데이트되면? 수동으로 다시 복사 │
│ ├── 이름 충돌: 두 사람이 같은 이름의 스킬 만들면? │
│ ├── 파편화: Skills, Hooks, Agents를 각각 따로 설치해야 함 │
│ ├── 발견 불가: 좋은 스킬이 있어도 찾을 방법이 없음 │
│ └── 일관성 없음: 같은 팀인데 각자 다른 버전 사용 │
│ │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ Plugin 이후의 세계 (해결) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 설치: │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ claude plugin install oh-my-claudecode │ │
│ │ │ │
│ │ → Skills 30개+ 자동 설치 │ │
│ │ → Agents 32개 자동 등록 │ │
│ │ → Hooks 자동 설정 │ │
│ │ → MCP 서버 자동 연결 │ │
│ │ → 모두 oh-my-claudecode: 네임스페이스 아래 │ │
│ │ → 버전 3.3.8로 고정, Git SHA 추적 │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │
│ 해결된 것: │
│ ├── 버전 관리: SemVer + Git SHA로 정확한 버전 추적 │
│ ├── 이름 충돌: 네임스페이스로 완전 격리 │
│ ├── 원클릭 설치: 모든 구성요소가 함께 설치됨 │
│ ├── Marketplace: 검색 가능한 Plugin 레지스트리 │
│ └── 팀 일관성: project 스코프로 .claude/settings.json에 고정 │
│ │
└─────────────────────────────────────────────────────────────────┘
핵심: 배포(Distribution) 문제의 해결
┌─────────────────────────────────────────────────────────────────┐
│ Plugin이 해결한 근본 문제 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Before (일반 Skill만 있던 시절): │
│ │
│ 개발자 A ──[수동 복사]──→ 개발자 B │
│ │ │ │
│ │ v1.0 수정 │ v1.0 그대로 │
│ │ → v1.1 │ → 업데이트 모름 │
│ │ │ → 점점 달라짐 │
│ ▼ ▼ │
│ 서로 다른 버전, 호환 안 됨 │
│ │
│ After (Plugin 시스템): │
│ │
│ 개발자 A ──[Marketplace에 publish] │
│ │ │
│ ┌─────┴─────┐ │
│ ▼ ▼ │
│ 개발자 B 개발자 C │
│ (install) (install) │
│ │ │ │
│ ▼ ▼ │
│ v3.3.8 v3.3.8 ← 모두 같은 버전 │
│ │ │ │
│ (update) (update) │
│ ▼ ▼ │
│ v3.4.0 v3.4.0 ← 동시 업데이트 │
│ │
└─────────────────────────────────────────────────────────────────┘
5. Marketplace와 설치 시스템
┌─────────────────────────────────────────────────────────────────┐
│ Marketplace = Plugin의 앱 스토어 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Marketplace란? │
│ Git 기반 레지스트리로, Plugin을 검색하고 설치할 수 있는 저장소 │
│ │
│ 등록 과정: │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ # 1. Marketplace 추가 │ │
│ │ /plugin marketplace add https://github.com/org/marketplace │ │
│ │ │ │
│ │ # 2. Plugin 설치 │ │
│ │ /plugin install oh-my-claudecode │ │
│ │ │ │
│ │ # 3. 스코프 지정 (팀 공유용) │ │
│ │ claude plugin install my-plugin --scope project │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │
│ 설치 후 파일 구조: │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ ~/.claude/plugins/ │ │
│ │ ├── installed_plugins.json ← 설치된 Plugin 레지스트리 │ │
│ │ ├── known_marketplaces.json ← 등록된 Marketplace 목록 │ │
│ │ └── cache/ ← 실제 Plugin 코드 (격리) │ │
│ │ ├── omc/oh-my-claudecode/3.3.8/ │ │
│ │ │ ├── .claude-plugin/plugin.json │ │
│ │ │ ├── skills/ │ │
│ │ │ ├── agents/ │ │
│ │ │ └── hooks/ │ │
│ │ └── claude-plugins-official/superpowers/4.3.1/ │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │
│ 보안: │
│ Marketplace의 Plugin 코드를 직접 사용하지 않고 │
│ cache/ 디렉토리에 복사하여 격리된 환경에서 실행 │
│ │
└─────────────────────────────────────────────────────────────────┘
스코프 시스템
┌─────────────────────────────────────────────────────────────────┐
│ Plugin 스코프 = 누가 이 Plugin을 사용할 수 있나? │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┬──────────────────────┬──────────────────────┐ │
│ │ 스코프 │ 설정 파일 │ 용도 │ │
│ ├──────────┼──────────────────────┼──────────────────────┤ │
│ │ user │ ~/.claude/ │ 개인용, 모든 프로젝 │ │
│ │ │ settings.json │ 트에서 사용 │ │
│ ├──────────┼──────────────────────┼──────────────────────┤ │
│ │ project │ .claude/ │ 팀 공유, VCS에 │ │
│ │ │ settings.json │ 커밋하여 팀 전체 적용│ │
│ ├──────────┼──────────────────────┼──────────────────────┤ │
│ │ local │ .claude/ │ 프로젝트별 개인용 │ │
│ │ │ settings.local.json │ .gitignore 대상 │ │
│ ├──────────┼──────────────────────┼──────────────────────┤ │
│ │ managed │ 관리자 설정 │ 조직 전체 강제 적용 │ │
│ │ │ │ 읽기 전용 │ │
│ └──────────┴──────────────────────┴──────────────────────┘ │
│ │
│ 팀에서 가장 강력한 사용법: │
│ project 스코프로 설치 → .claude/settings.json 커밋 │
│ → 팀원 전원이 같은 Plugin, 같은 버전 사용 │
│ │
└─────────────────────────────────────────────────────────────────┘
6. Plugin이 일반 Skill보다 효과적인 상황
┌─────────────────────────────────────────────────────────────────┐
│ 언제 어떤 것을 쓸 것인가? │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 일반 Skill이 적합한 경우: │
│ ├── 개인용 워크플로우 ("나만 쓰는 코드 리뷰 규칙") │
│ ├── 프로젝트 고유 설정 ("이 프로젝트의 API 규칙") │
│ ├── 빠른 실험 ("이 아이디어 한번 시험해보자") │
│ └── 단일 스킬 ("하나의 행동 패턴만 정의") │
│ │
│ Plugin이 적합한 경우: │
│ ├── 팀/커뮤니티 공유 ("우리 팀 전원이 같은 도구 사용") │
│ ├── 복합 시스템 ("30개 스킬 + 32개 에이전트 + Hooks") │
│ ├── 버전 관리 필수 ("v3.3.8에서 버그 있으니 v3.4.0으로") │
│ ├── 여러 프로젝트에서 재사용 ("어디서든 같은 도구") │
│ └── 에이전트+스킬+훅 통합 ("하나의 체계로 묶어야 함") │
│ │
│ 공식 문서의 가이드: │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ ┌──────────┬───────────────┬─────────────────────────┐ │ │
│ │ │ 접근법 │ 스킬 이름 │ 적합한 상황 │ │ │
│ │ ├──────────┼───────────────┼─────────────────────────┤ │ │
│ │ │ 일반 │ /hello │ 개인, 프로젝트 한정, │ │ │
│ │ │ Skill │ (짧은 이름) │ 빠른 실험 │ │ │
│ │ ├──────────┼───────────────┼─────────────────────────┤ │ │
│ │ │ Plugin │ /plugin:hello│ 팀 공유, 커뮤니티 배포, │ │ │
│ │ │ Skill │ (네임스페이스)│ 버전 릴리즈, 재사용 │ │ │
│ │ └──────────┴───────────────┴─────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
7. 실제 Plugin 사례
┌─────────────────────────────────────────────────────────────────┐
│ 대표적인 Plugin 비교 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────┬──────────────────┬───────────────────┐ │
│ │ │ oh-my-claudecode │ superpowers │ │
│ ├──────────────────┼──────────────────┼───────────────────┤ │
│ │ 버전 │ 3.3.8 │ 4.3.1 │ │
│ ├──────────────────┼──────────────────┼───────────────────┤ │
│ │ 스킬 수 │ 40+ │ 15+ │ │
│ ├──────────────────┼──────────────────┼───────────────────┤ │
│ │ 에이전트 수 │ 32 │ - │ │
│ ├──────────────────┼──────────────────┼───────────────────┤ │
│ │ 핵심 철학 │ "오케스트레이터"│ "규율과 검증" │ │
│ │ │ 멀티 에이전트 │ 개발 프로세스 │ │
│ │ │ 병렬 실행 │ 품질 보장 │ │
│ ├──────────────────┼──────────────────┼───────────────────┤ │
│ │ 대표 스킬 │ autopilot │ test-driven- │ │
│ │ │ ultrawork │ development │ │
│ │ │ ralph │ systematic- │ │
│ │ │ analyze │ debugging │ │
│ ├──────────────────┼──────────────────┼───────────────────┤ │
│ │ 번들 내용 │ Skills + │ Skills만 │ │
│ │ │ Agents + │ (순수 프로세스 │ │
│ │ │ Hooks + │ 가이드) │ │
│ │ │ CLAUDE.md │ │ │
│ ├──────────────────┼──────────────────┼───────────────────┤ │
│ │ 접두사 │ oh-my-claudecode│ superpowers │ │
│ └──────────────────┴──────────────────┴───────────────────┘ │
│ │
│ Plugin이 아니었다면? │
│ oh-my-claudecode의 40개 스킬 + 32개 에이전트 + hooks를 │
│ 수동으로 각각 설치해야 함 → 사실상 불가능 │
│ │
└─────────────────────────────────────────────────────────────────┘
8. Plugin 내부에서 Skill이 합성되는 방식
┌─────────────────────────────────────────────────────────────────┐
│ oh-my-claudecode의 3계층 스킬 합성 모델 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Plugin 내부의 스킬들은 단독으로 동작하지 않고 │
│ 계층적으로 합성(compose)되어 동작한다. │
│ │
│ 구조: │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ [실행 스킬] + [0~N개 향상 스킬] + [보장 스킬(선택)] │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │
│ 예시: "ulw: fix errors" │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ 실행: default (기본 동작) │ │
│ │ 향상: ultrawork (병렬 에이전트 실행) │ │
│ │ 향상: git-master (커밋 규칙 적용) │ │
│ │ → 세 스킬이 런타임에 합성되어 하나의 행동으로 │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │
│ 예시: "ralph ulw: refactor auth" │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ 실행: default │ │
│ │ 향상: ralph (완료까지 반복) │ │
│ │ 향상: ultrawork (병렬) │ │
│ │ 보장: architect (최종 검증) │ │
│ │ → 네 스킬이 합성 → "병렬로 빠르게 + 끝까지 + 검증" │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │
│ 이런 합성이 가능한 이유: │
│ Plugin이 CLAUDE.md를 통해 키워드 → 스킬 매핑 규칙을 │
│ 오케스트레이션 계층으로 주입하기 때문 │
│ → 일반 Skill로는 이런 합성 불가능 │
│ │
└─────────────────────────────────────────────────────────────────┘
9. 아키텍처 전체 그림
┌─────────────────────────────────────────────────────────────────┐
│ Claude Code 확장성 아키텍처 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Claude Code 확장 │
│ │ │
│ ├── Skills (원자 = 가장 작은 확장 단위) │
│ │ ├── SKILL.md + 보조 파일들 │
│ │ ├── 특정 도메인의 지식/행동 규칙 정의 │
│ │ ├── /skill-name 으로 호출 (접두사 없음 = 독립형) │
│ │ └── 위치: ~/.claude/skills/ 또는 .claude/skills/ │
│ │ │
│ └── Plugins (분자 = 여러 원자의 묶음) │
│ ├── plugin.json 매니페스트 │
│ ├── Skills + Agents + Hooks + MCP + LSP 번들 │
│ ├── /plugin-name:skill-name 으로 호출 (네임스페이스) │
│ ├── Marketplace에서 설치/업데이트/공유 │
│ └── 위치: ~/.claude/plugins/cache/{org}/{name}/{ver}/ │
│ │
│ 관계: │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ Plugin은 Skill을 포함한다 (contains) │ │
│ │ Plugin의 Skill은 네임스페이스가 붙는다 (namespaced) │ │
│ │ 독립 Skill은 Plugin 밖에 존재한다 (standalone) │ │
│ │ 둘 다 SKILL.md라는 같은 포맷을 사용한다 (same format) │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
10. 정리
┌─────────────────────────────────────────────────────────────────┐
│ 요약 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Skill이란? │
│ └── Claude에게 도메인 지식을 주입하는 온디맨드 프롬프트 패키지 │
│ │
│ Plugin이란? │
│ └── 여러 Skill + Agent + Hook을 묶어 버전 관리하고 배포하는 패키지│
│ │
│ 왜 Plugin이 필요한가? │
│ ├── 배포: 수동 복사 → 한 줄 설치 │
│ ├── 버전: 관리 없음 → SemVer + Git SHA │
│ ├── 충돌: 이름 충돌 위험 → 네임스페이스 격리 │
│ ├── 번들: 각각 따로 설치 → 모든 구성요소 한번에 │
│ └── 팀: 각자 다른 버전 → project 스코프로 일관성 │
│ │
│ 언제 일반 Skill? │
│ └── 개인용, 프로젝트 한정, 빠른 실험, 단일 행동 규칙 │
│ │
│ 언제 Plugin? │
│ └── 팀 공유, 커뮤니티 배포, 복합 시스템, 버전 관리 필수 │
│ │
│ 핵심 원칙: │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ "Skill은 지식의 단위, │ │
│ │ Plugin은 배포의 단위" │ │
│ │ │ │
│ │ Skill = 무엇을 할 수 있는가 (what) │ │
│ │ Plugin = 어떻게 전달하고 관리하는가 (how) │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
관련 키워드
Claude Code, Skills, Plugins, SKILL.md, plugin.json, Marketplace, Namespace, 네임스페이스, oh-my-claudecode, superpowers, 에이전트 오케스트레이션, SemVer, 버전 관리, 확장성, Hooks, MCP, LSP, Lazy Loading, 프론트매터