OMC - Plugin Anatomy

시리즈: oh-my-claudecode 내부 구조부터 플러그인 개발까지

이 시리즈는 Claude Code 플러그인 시스템의 내부 동작을 단계별로 해부하고, 최종적으로 나만의 플러그인을 직접 개발하는 것까지 도달하는 과정이다.

편	내용	핵심
1편 (본문)	Plugin Anatomy	plugin.json 하나로 시작하는 플러그인 뼈대
2편	Hook System	이벤트 → stdin JSON → 스크립트 → stdout JSON
3편	Skill System	SKILL.md로 워크플로우를 정의하는 방법
4편	Agent System	Task tool로 위임되는 실제 작업 수행자
5편	MCP Tools Bridge	LSP, AST 등 커스텀 도구 서버
6편	State & Lifecycle	.omc/ 상태 관리와 모드 지속
7편	Parallel Orchestration	Ultrawork, Team, Autopilot, Ralph 패턴

---

• Claude Code Plugin은 Claude Code의 기능을 확장하는 자기완결적 디렉토리 단위 패키지
• .claude-plugin/plugin.json 매니페스트 하나로 식별되며, 나머지 컴포넌트는 전부 선택
• Hook, MCP, Skill, Agent, LSP 5가지 확장 채널을 필요한 것만 골라 조합하는 구조

해당 개념이 필요한 이유

• Claude Code는 기본 도구(Read, Write, Edit, Bash 등)만 제공
• 전문 에이전트 오케스트레이션, 워크플로우 자동화, IDE급 도구 같은 확장 기능을 연결하려면 플러그인 구조를 이해해야 함
• oh-my-claudecode(OMC)가 이 플러그인 시스템을 활용하므로, OMC 기반 플러그인 개발의 첫 단추

AS-IS

sequenceDiagram
    autonumber
    participant U as User
    participant CC as Claude Code

    U->>CC: "API 리팩터해줘"
    CC->>CC: 기본 도구만 사용 (Read, Edit, Bash)
    CC-->>U: 단순 응답
    Note over CC: 확장 기능 없음, 커스텀 도구 없음

TO-BE

sequenceDiagram
    autonumber
    participant U as User
    participant CC as Claude Code
    participant PJ as plugin.json
    participant H as Hook Scripts
    participant M as MCP Server
    participant S as Skills

    U->>CC: "ultrawork refactor the API"
    CC->>PJ: 플러그인 로드
    PJ->>H: hooks.json 참조
    PJ->>M: .mcp.json 참조
    PJ->>S: skills/ 참조
    H-->>CC: 키워드 감지, 모드 지속
    S-->>CC: 워크플로우 지침 주입
    M-->>CC: LSP, AST 등 커스텀 도구 제공
    CC-->>U: 멀티에이전트 오케스트레이션 응답

plugin.json — 유일한 필수 파일

공식 문서 기준, 매니페스트(plugin.json)조차 선택이다. 없으면 Claude Code가 디렉토리 이름에서 플러그인 이름을 추론하고, 기본 위치의 컴포넌트를 자동 발견한다.

매니페스트를 포함할 경우 name이 유일한 필수 필드:

// .claude-plugin/plugin.json — 최소 형태
{
  "name": "my-plugin"
}

필드	필수 여부	역할
name	필수	플러그인 식별자, skill 네임스페이스 접두사
version	선택	시맨틱 버저닝. 캐시 갱신 판단 기준
description	선택	플러그인 매니저에 표시
skills	선택	skills 디렉토리 커스텀 경로 (기본: ./skills/)
mcpServers	선택	MCP 설정 경로 (기본: ./.mcp.json)
hooks	선택	Hook 설정 경로 (기본: ./hooks/hooks.json)
agents	선택	Agent 파일 경로 (기본: ./agents/)
lspServers	선택	LSP 설정 경로 (기본: ./.lsp.json)

Q) “Skill은 필수인가? 3채널 중 필수인 것이 있나?”

• 공식 문서 기준 전부 선택. plugin.json마저 선택이다
• 컴포넌트가 하나도 없으면 유용하지 않을 뿐, 동작 자체는 가능하다
• 최소한의 플러그인: plugin.json에 name만 넣고 Hook 하나 등록하면 충분하다

5가지 확장 채널과 통신 방식

채널	등록 파일	통신 방식	기본 위치
Hook	hooks/hooks.json	이벤트 → stdin JSON → 스크립트 → stdout JSON	hooks/hooks.json
MCP	.mcp.json	JSON-RPC → MCP 서버 프로세스 → 도구 응답	.mcp.json
Skill	skills/	Skill tool 호출 → SKILL.md 텍스트를 context에 주입	skills/
Agent	agents/	Task tool → 에이전트 마크다운 로드 → subagent 실행	agents/
LSP	.lsp.json	Language Server Protocol → 코드 인텔리전스	.lsp.json

커스텀 경로를 plugin.json에 지정하면 기본 위치에 추가되는 것이지, 대체하는 것이 아니다.

$CLAUDE_PLUGIN_ROOT 환경변수

“내 플러그인이 어디에 설치되어 있는지”를 Claude Code가 알려주는 변수.

항목	내용
누가 설정?	Claude Code가 자동으로
언제?	플러그인 로드 시점
스코프	플러그인별 (글로벌 아님)
값	플러그인 루트 디렉토리의 절대 경로

// hooks.json에서 사용
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/format-code.sh"
 
// .mcp.json에서 사용
"args": ["${CLAUDE_PLUGIN_ROOT}/bridge/mcp-server.cjs"]

OMC 소스에서도 이 변수로 “플러그인으로 실행 중인가?”를 판단한다:

// src/installer/index.ts
export function isRunningAsPlugin(): boolean {
  return !!process.env.CLAUDE_PLUGIN_ROOT;
}

MCP 서버 이름 "t" — 64글자 제한 문제

OMC의 .mcp.json에서 MCP 서버 이름이 "t" 한 글자인 이유:

변경 전: mcp__omc-tools__lsp_diagnostics  (접두사 15자)
변경 후: mcp__t__lsp_diagnostics           (접두사 6자)

• Claude Code에 MCP 도구 이름 64글자 제한이 존재
• omc-tools로 등록하면 도구 이름이 이 제한을 초과
• PR #252 / Issue 241에서 수정: 접두사를 15자 → 6자로 줄여 해결
• 토큰 절약이 아닌 하드 리밋 문제

설치 흐름과 파일 배치

sequenceDiagram
    autonumber
    participant U as User
    participant NPM as npm
    participant GP as Global Path<br/>/usr/local/lib/node_modules/omc/
    participant CC as Claude Code
    participant PC as Plugin Cache<br/>~/.claude/plugins/cache/

    U->>NPM: npm install -g oh-my-claudecode
    NPM->>GP: 패키지 파일 전체 설치<br/>(scripts/, bridge/, skills/, agents/ 등)
    Note over GP: scripts/run.cjs, bridge/mcp-server.cjs<br/>이미 빌드되어 패키지에 포함

    U->>GP: omc setup
    GP->>CC: ~/.claude/settings.json 업데이트

    Note over CC: 다음 세션 시작 시
    CC->>PC: 플러그인 파일을 캐시로 복사
    CC->>CC: CLAUDE_PLUGIN_ROOT = 캐시 경로 설정
    CC->>GP: ${CLAUDE_PLUGIN_ROOT}/scripts/run.cjs 실행

Q) “scripts/run.cjs는 언제 설치되는 거야?”

• npm install 시점에 npm 글로벌 경로에 설치됨 (빌드된 번들이 패키지에 이미 포함)
• 별도 복사가 아니라, $CLAUDE_PLUGIN_ROOT가 그 경로를 가리키는 구조
• 마켓플레이스 설치 시에는 ~/.claude/plugins/cache/로 복사됨

나만의 플러그인 최소 구조

my-plugin/
├── .claude-plugin/
│   └── plugin.json       ← name만 있으면 플러그인 인식
├── hooks/
│   └── hooks.json        ← 원하는 이벤트만 등록
└── scripts/
    └── my-hook.mjs       ← stdin JSON 읽고 stdout JSON 출력

Q) “.mjs는 무슨 확장자야?”

• ES Module JavaScript 확장자 (import/export 문법 사용)
• .cjs는 CommonJS (require/module.exports)
• .mjs로 명시하면 package.json 설정과 무관하게 항상 ES Module로 동작 보장

OMC의 plugin.json 실제 내용

{
  "name": "oh-my-claudecode",
  "version": "4.8.0",
  "description": "Multi-agent orchestration system for Claude Code",
  "author": { "name": "oh-my-claudecode contributors" },
  "repository": "https://github.com/Yeachan-Heo/oh-my-claudecode",
  "license": "MIT",
  "keywords": ["claude-code", "plugin", "multi-agent", "orchestration"],
  "skills": "./skills/",
  "mcpServers": "./.mcp.json"
}

Hook은 plugin.json에 명시하지 않았지만 기본 위치(hooks/hooks.json)에서 자동 발견된다.

참고 문서

• Create plugins - Claude Code Docs
• Plugins reference - Claude Code Docs