OMC - Skill Injector

이 문서는 2편 Hook System의 하위 개념으로, 18개 Hook 스크립트 중 skill-injector.mjs를 다룬다.

---

• skill-injector.mjs는 UserPromptSubmit Hook에서 사용자 프롬프트를 학습된 Skill 파일의 trigger와 매칭하여, 관련 Skill 내용을 Claude context에 주입하는 스크립트
• keyword-detector.mjs가 14개 매직 키워드를 하드코딩으로 감지하는 반면, skill-injector.mjs는 사용자가 학습시킨 Skill 파일의 trigger를 동적으로 매칭
• 3-tier 디렉토리에서 Skill을 탐색하고, 세션 캐싱으로 중복 주입을 방지하며, 최대 5개까지 매칭

작성일: 2026-03-15 소스: skill-injector.mjs

해당 개념이 필요한 이유

• keyword-detector.mjs는 14개 키워드만 감지 가능하다. 사용자가 자체 Skill을 만들어도 키워드 감지에는 반영되지 않는다
• skill-injector.mjs는 .md 파일의 YAML frontmatter에 triggers를 정의하면, 해당 trigger가 프롬프트에 포함될 때 자동으로 Skill 내용을 주입한다
• 이 스크립트는 hooks.json에서 UserPromptSubmit 이벤트의 두 번째 스크립트로 등록되어 있어, keyword-detector.mjs 이후에 실행된다

AS-IS

sequenceDiagram
    autonumber
    participant U as User
    participant CC as Claude Code

    U->>CC: "PR 준비해줘"
    CC->>CC: 학습된 Skill 존재하지만 매칭 수단 없음
    CC-->>U: 일반 응답 (Skill 무시)

TO-BE

sequenceDiagram
    autonumber
    participant U as User
    participant CC as Claude Code
    box OMC
    participant SI as skill-injector.mjs
    end

    U->>CC: "PR 준비해줘"
    CC->>SI: stdin: { prompt, cwd, session_id }
    SI->>SI: 3-tier 디렉토리에서 .md Skill 탐색
    SI->>SI: trigger "PR 준비" 매칭 (score: 10)
    SI-->>CC: { additionalContext: "<mnemosyne>Skill 내용</mnemosyne>" }
    CC->>CC: 주입된 Skill 지식으로 PR 준비 수행

keyword-detector.mjs와의 역할 분담

sequenceDiagram
    autonumber
    participant U as User
    participant CC as Claude Code
    box OMC
    participant KD as keyword-detector.mjs
    participant SI as skill-injector.mjs
    end

    U->>CC: 프롬프트 입력
    CC->>KD: UserPromptSubmit (1st, timeout 5s)
    KD->>KD: 14개 매직 키워드 매칭
    KD-->>CC: Skill 호출 지시 or 메시지 주입
    CC->>SI: UserPromptSubmit (2nd, timeout 3s)
    SI->>SI: 학습된 Skill trigger 매칭
    SI-->>CC: 매칭된 Skill 내용 context 주입

구분	keyword-detector.mjs	skill-injector.mjs
매칭 대상	14개 하드코딩 키워드	학습된 Skill 파일의 trigger
매칭 방식	정규식 패턴	trigger 키워드 포함 여부 (점수제)
출력 방식	Skill tool 호출 지시 or 메시지 직접 주입	<mnemosyne> 태그로 Skill 내용 주입
실행 순서	1st (5s)	2nd (3s)

3-tier Skill 디렉토리

graph TB
    subgraph Tier1["Tier 1: 프로젝트 레벨"]
        P[".omc/skills/*.md"]
    end

    subgraph Tier2["Tier 2: 글로벌 레벨"]
        G["~/.omc/skills/*.md"]
    end

    subgraph Tier3["Tier 3: 레거시"]
        L["~/.claude/skills/omc-learned/*.md"]
    end

    SI["skill-injector.mjs"] --> P
    SI --> G
    SI --> L

    P -->|"우선"| Result["매칭 후보"]
    G --> Result
    L --> Result

• 프로젝트 레벨이 우선 — 같은 Skill이 프로젝트와 글로벌에 모두 있으면 프로젝트 버전을 사용
• realpathSync()로 심볼릭 링크를 해결하여 중복 제거

Skill 파일 구조와 매칭 로직

YAML frontmatter의 triggers

---
name: pr-creator
triggers:
  - PR 준비
  - PR ready
  - 커밋하고 푸시
---
 
Skill 본문 내용...

parseSkillFrontmatterFallback()가 --- 구분자 사이에서 name과 triggers 배열을 추출한다.

스코어링 기반 매칭

graph LR
    Prompt["사용자 프롬프트"] --> Lower["소문자 변환"]
    Lower --> Check{"각 Skill의 trigger 순회"}
    Check -->|"trigger 포함"| Score["+10점"]
    Check -->|"미포함"| Skip["스킵"]
    Score --> Sort["점수 내림차순 정렬"]
    Sort --> Limit["상위 5개 반환"]

• 프롬프트를 소문자로 변환 후, 각 Skill 파일의 trigger를 순회하며 포함 여부를 검사
• trigger 1개 매칭당 10점 가산
• 점수 내림차순으로 정렬하여 최대 5개(MAX_SKILLS_PER_SESSION) 반환

세션 캐싱 — 중복 주입 방지

const injectedCacheFallback = new Map();  // sessionId → Set<skillPath>

• 한 세션에서 이미 주입된 Skill은 다시 주입하지 않는다
• session_id별로 주입된 Skill 경로의 Set을 유지
• 같은 세션에서 같은 trigger를 반복 입력해도 context가 불필요하게 커지지 않음

Bridge vs Fallback 아키텍처

graph TB
    SI["skill-injector.mjs"] --> Try{"dist/hooks/skill-bridge.cjs 로드 시도"}
    Try -->|"성공"| Bridge["Bridge 모드"]
    Try -->|"실패"| Fallback["Fallback 모드"]

    Bridge --> R1["RECURSIVE 디렉토리 탐색"]
    Bridge --> R2["영속 캐싱"]

    Fallback --> F1["NON-RECURSIVE 탐색"]
    Fallback --> F2["인메모리 캐싱 (세션 한정)"]

• Bridge 모드: 컴파일된 skill-bridge.cjs 번들을 사용. 재귀적 디렉토리 탐색, 영속 캐싱 지원
• Fallback 모드: Bridge 로드 실패 시 인라인 구현 사용. 비재귀 탐색, 인메모리 캐싱만 지원
• Fallback은 하위 호환성을 위한 것으로, 기능적으로는 동일한 결과를 반환

출력 형식 — <mnemosyne> 태그

formatSkillsMessage()가 매칭된 Skill들을 아래 형식으로 래핑한다:

<mnemosyne>
<skill-metadata>
{
  "name": "pr-creator",
  "path": ".omc/skills/pr-creator.md",
  "triggers": ["PR 준비", "PR ready"],
  "score": 20,
  "scope": "project"
}
</skill-metadata>
 
Skill 본문 내용...
 
---
</mnemosyne>

<mnemosyne>는 그리스 신화의 기억의 여신 므네모시네에서 따온 이름이다. OMC에서는 “Claude가 기억해야 할 학습된 지식”을 감싸는 OMC 자체 컨벤션으로 사용한다. Claude Code가 공식으로 제공하는 것은 additionalContext 문자열 필드뿐이며, 그 안에 어떤 형식을 사용할지는 플러그인이 자유롭게 결정한다. OMC는 XML 태그 형식을 선택하여 Claude가 경계를 인식하기 쉽게 했다.

• <skill-metadata>에 매칭 정보를 JSON으로 포함하여 디버깅 가능
• 복수 Skill 매칭 시 --- 구분자로 분리

keyword-detector.mjs와의 출력 형식 차이:

	keyword-detector.mjs	skill-injector.mjs
래핑	없음 (평문 지시)	<mnemosyne> 태그
목적	”이 Skill을 실행하라” 명령	”이 지식을 참고하라” 컨텍스트
예시	[MAGIC KEYWORD: ULTRAWORK]	<mnemosyne><skill-metadata>...</mnemosyne>

에러 처리

모든 에러는 graceful하게 처리된다:

// 어떤 에러가 발생해도 Claude Code 진행을 차단하지 않음
console.log(JSON.stringify({ continue: true, suppressOutput: true }));

• Skill 파일 읽기 실패, JSON 파싱 에러 등 모든 예외에서 { continue: true } 반환
• suppressOutput: true로 verbose 모드에서도 에러 노이즈를 숨김
• Hook 스크립트는 보조 기능이므로, 실패해도 본 작업이 중단되면 안 된다

참고 문서

• skill-injector.mjs 소스
• OMC - Hook System — Hook 시스템 전체 구조
• OMC - Keyword Detector — 같은 이벤트의 첫 번째 스크립트