OMC - Skill System

시리즈: 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 패턴

---

• OMC의 Skill은 Claude의 행동을 지시하는 프롬프트 기반 워크플로우 정의 파일
• 코드가 아니라 마크다운이며, SKILL.md에 작성된 지침이 Claude의 context에 주입되어 행동을 변경하는 구조
• 공식 Skill 시스템(YAML frontmatter + 마크다운 본문) 위에 OMC 자체 컨벤션(XML 태그 구조, 키워드 자동 감지, 3계층 합성)을 얹은 확장 사용 패턴

해당 개념이 필요한 이유

• 2편(Hook System)에서 keyword-detector가 “ultrawork skill을 실행하라”고 Claude에게 지시하는 것까지 학습
• 하지만 **“ultrawork 모드에서 Claude가 어떻게 행동해야 하는지”**의 정의가 빠져 있음
• Skill이 이 빈 칸을 채움 — Hook이 트리거라면 Skill은 지침서

AS-IS

sequenceDiagram
    autonumber
    participant H as keyword-detector (Hook)
    participant CC as Claude Code

    H-->>CC: additionalContext: "ultrawork skill을 실행하라"
    CC->>CC: "ultrawork가 뭔데?"
    Note over CC: 행동 지침이 없으므로 아무것도 달라지지 않음

TO-BE

sequenceDiagram
    autonumber
    participant H as keyword-detector (Hook)
    participant CC as Claude Code
    participant ST as Skill Tool
    participant SK as skills/ultrawork/SKILL.md

    H-->>CC: additionalContext: "ultrawork skill을 실행하라"
    CC->>ST: Skill("oh-my-claudecode:ultrawork")
    ST->>SK: SKILL.md 파일 로드
    SK-->>CC: 마크다운 내용이 Claude context에 주입
    Note over CC: "독립 작업은 병렬로 실행하라"<br/>"Task(run_in_background=true) 사용"<br/>지침에 따라 행동

공식 Skill 시스템 vs OMC 확장

OMC의 Skill은 공식 Skill 시스템 위에 구축된다. 공식 기능과 OMC 고유 기능을 구분하는 것이 중요하다.

구분	공식 Claude Code	OMC 확장
파일 구조	YAML frontmatter + 마크다운 본문	마크다운 본문을 XML 태그로 구조화
호출 방식	/skill-name 또는 Claude 자동 호출	+ 키워드 자동 감지 (Hook 연동)
인자 전달	$ARGUMENTS, $0, $1 등	동일
실행 격리	context: fork → subagent 실행	동일
도구 제한	allowed-tools frontmatter	동일
스킬 학습	없음	skill-injector.mjs / mnemosyne 자동 주입
스킬 합성	없음	3계층 합성 (Guarantee > Enhancement > Execution)
우선순위	없음	resolveConflicts() 키워드 우선순위

공식 Skill 시스템의 상세 스펙은 Claude Code Skills 참고

SKILL.md 구조 — 공식 + OMC 컨벤션

공식 부분: YAML frontmatter

---
name: ultrawork
description: Parallel execution engine for high-throughput task completion
---

공식 frontmatter 필드 중 OMC 스킬이 활용하는 것:

필드	OMC 활용 예
name	ultrawork, ralph, autopilot 등
description	Claude 자동 호출 판단에 사용
aliases	team 스킬의 별칭 목록 (빈 배열)

OMC 컨벤션: XML 태그 본문

OMC는 마크다운 본문을 XML 태그로 구조화한다. 이건 OMC 자체 컨벤션이지, 공식 스펙이 아니다.

<Purpose>
병렬 실행 엔진. 독립 작업을 동시에 실행하여 처리 시간을 줄인다.
</Purpose>
 
<Use_When>
여러 작업이 동시에 실행 가능할 때
</Use_When>
 
<Do_Not_Use_When>
보장된 완료가 필요할 때 (→ ralph 사용)
</Do_Not_Use_When>
 
<Execution_Policy>
독립 작업은 Task(run_in_background=true)로 동시 실행.
</Execution_Policy>
 
<Steps>
1. 작업 분석 → 2. 에이전트 선택 → 3. 병렬 실행 → 4. 결과 검증
</Steps>

태그	역할
<Purpose>	이 Skill이 뭘 하는지
<Use_When>	언제 사용해야 하는지
<Do_Not_Use_When>	언제 사용하면 안 되는지
<Execution_Policy>	실행 규칙 (핵심 지침)
<Steps>	단계별 절차
<Examples>	좋은/나쁜 사용 예시
<Advanced>	고급 설정, 다른 Skill과의 관계

XML 태그를 쓰는 이유: Claude가 구조화된 지시를 더 정확하게 따르기 때문. 단순 마크다운보다 태그로 감싸면 섹션 경계가 명확해진다.

Skill 호출 경로 3가지

graph TD
    subgraph Path1["경로 1: 키워드 자동 감지 (OMC 고유, 가장 일반적)"]
        U1["사용자: 'ultrawork refactor API'"] --> KD1["keyword-detector.mjs (Hook)"]
        KD1 -->|"additionalContext 주입"| CC1["Claude: Skill tool 호출"]
        CC1 --> SK1["SKILL.md 로드"]
    end

    subgraph Path2["경로 2: 슬래시 커맨드 (공식 기능)"]
        U2["사용자: /oh-my-claudecode:ultrawork"] --> CC2["Claude Code 직접 호출"]
        CC2 --> SK2["SKILL.md 로드"]
    end

    subgraph Path3["경로 3: 학습된 스킬 자동 주입 (OMC 고유)"]
        U3["사용자: '테스트 먼저 작성해줘'"] --> SI3["skill-injector.mjs (Hook)"]
        SI3 -->|"mnemosyne 태그로 주입"| CC3["Claude context에 스킬 내용 추가"]
    end

경로 1이 OMC의 핵심 패턴: Hook(2편)이 키워드를 감지 → Skill(3편)이 지침을 주입 → Agent(4편)가 실행.

OMC의 28개 Skill 분류

워크플로우 Skill (핵심)

Skill	줄 수	역할	키워드 트리거
ultrawork	128	병렬 실행 엔진	ultrawork, ulw
ralph	214	검증 루프 (완료까지 반복)	ralph
autopilot	189	전체 자동화 (아이디어→코드)	autopilot, fullsend
team	967	N개 worker 병렬 조율	/team (명시적만)
cancel	317	활성 모드 취소	cancelomc, stopomc
ccg	—	Claude-Codex-Gemini 3모델 병렬 실행	ccg
ralplan	—	합의 기반 반복 계획	ralplan

유틸리티 Skill

Skill	역할
omc-setup	초기 설정
omc-doctor	설치 상태 진단
hud	상태 대시보드 (HUD = Heads-Up Display. 터미널 하단 status line에 현재 활성 모드, 서브에이전트 수 등을 실시간 표시. ~/.claude/hud/omc-hud.mjs가 settings.json의 statusLine과 연결되어 동작)
note	메모
learner	스킬 학습/추출
trace	에이전트 흐름 추적
release	릴리즈 자동화

team 스킬이 967줄로 가장 크다 — 사실상 하나의 오케스트레이션 시스템.

Skill Composition — 3계층 합성 (OMC 고유)

여러 Skill이 동시에 활성화될 때 3계층으로 합성된다:

graph TB
    subgraph Guarantee["Guarantee Layer (보장)"]
        R["ralph: 완료될 때까지 멈추지 마라<br/>→ Stop hook에서 종료 차단"]
    end

    subgraph Enhancement["Enhancement Layer (강화)"]
        UW["ultrawork: 병렬로 실행하라<br/>→ 실행 방식을 변경"]
    end

    subgraph Execution["Execution Layer (실행)"]
        REQ["사용자의 실제 요청<br/>→ refactor the API"]
    end

    Guarantee --> Enhancement --> Execution

예: ralph refactor the API 입력 시:

1. ralph Skill 활성화 → “완료까지 반복” 보장
2. ralph는 내부적으로 ultrawork도 활성화 → “병렬 실행” 강화
3. 실제 작업: API 리팩터링 실행

keyword-detector.mjs의 resolveConflicts()가 우선순위를 관리:

cancel > ralph > autopilot > ultrawork > ccg > ralplan > ...

나만의 플러그인을 만든다면

최소 Skill 정의:

my-plugin/
└── skills/
    └── my-workflow/
        └── SKILL.md

---
name: my-workflow
description: My custom workflow for code review
---
 
<Purpose>
코드 리뷰를 자동화하는 워크플로우
</Purpose>
 
<Steps>
1. 변경된 파일 목록 확인
2. 각 파일의 diff 분석
3. 리뷰 코멘트 생성
</Steps>

plugin.json에 "skills": "./skills/" 설정하면 Claude Code가 자동 인식. /my-plugin:my-workflow로 호출 가능.

키워드 자동 감지까지 원하면 keyword-detector에 키워드를 등록해야 하지만, 그건 Hook 영역이다.

Deep Dive 토픽

• SKILL.md Anatomy — frontmatter, XML 태그 섹션, 각 태그의 역할
• Skill Composition — 3계층 합성, resolveConflicts 우선순위
• Skill Invocation Flow — 키워드 감지 → Skill tool → SKILL.md 로드 전체 흐름
• Learned Skills — skill-injector, mnemosyne 태그, 자동 학습/추출

참고 문서

• Claude Code Skills 공식 문서
• Claude Code Skills — 공식 Skill 시스템 개념 정리

---

다음: 4편 Agent System — Skill이 “병렬로 에이전트를 활용하라”고 지시했다. 에이전트가 뭐고, 어떻게 정의되고, 어떤 기준으로 선택되는지를 다음 파트에서 다룬다.