OMX - Skill System

시리즈: oh-my-codex 아키텍처 해부

이 시리즈는 OpenAI Codex CLI 확장 런타임인 oh-my-codex(OMX)의 내부 구조를 단계별로 해부하는 과정이다.

편	내용	핵심
0편	Overview	3-Plane 아키텍처, OMC와의 차이, 전체 흐름
1편	Codex CLI Foundation	Codex CLI 자체의 구조와 확장 포인트
2편	OMX Integration	OMX가 Codex에 어떻게 연결되나
3편 (본문)	Skill System	워크플로우를 어떻게 정의하나
4편	Prompt & Agent System	에이전트는 뭐고 어떻게 선택되나
5편	MCP Servers	어떤 MCP 도구를 쓸 수 있나
6편	State & Lifecycle	상태를 어떻게 유지하나
7편	Team Orchestration	Team 모드는 어떻게 동작하나
8편	Native & Spark	Rust 네이티브 도구는 뭔가

---

• Skill은 Codex CLI에 주입되는 마크다운 기반 행동 지침서 (코드가 아니라 프롬프트)
• SKILL.md 파일로 정의되며, XML 태그 섹션(Purpose, Steps, Execution_Policy 등)으로 구조화된 워크플로우 정의 단위
• $name 키워드 또는 AGENTS.md의 키워드 매칭으로 트리거되는 Codex의 행동 모드
• 설치 경로: ./.agents/skills/name/SKILL.md(프로젝트) 또는 ~/.agents/skills/name/SKILL.md(전역)

해당 개념이 필요한 이유

• 2편에서 AGENTS.md가 키워드를 감지하여 $ultrawork Skill을 실행하라고 Codex에게 지시하는 흐름을 이해했음
• 하지만 “ultrawork 모드에서 Codex가 구체적으로 어떻게 행동해야 하는지”의 정의가 빠져 있음
• Skill이 이 역할을 한다 — AGENTS.md가 “무엇을 실행할지” 결정하면, SKILL.md가 “어떻게 실행할지” 정의

AS-IS (OMC Skill — Claude Code 방식)

sequenceDiagram
    autonumber
    participant CC as Claude Code
    participant ST as Skill Tool
    participant SM as SKILL.md

    CC->>ST: Skill("omc:ultrawork") 호출
    ST->>SM: plugins/omc/skills/ultrawork/SKILL.md 로드
    SM-->>ST: 마크다운 내용 반환
    ST-->>CC: 프롬프트로 주입
    Note over CC: Skill Tool이 중개자 역할 (프로그래밍적 로드)

TO-BE (OMX Skill — Codex CLI 방식)

sequenceDiagram
    autonumber
    participant CX as Codex CLI (LLM)
    participant AM as AGENTS.md
    participant SM as skills/ultrawork/SKILL.md

    CX->>AM: 세션 시작 시 지침 로드
    AM-->>CX: "$ultrawork → SKILL.md를 읽어라" 지시
    CX->>SM: LLM이 직접 SKILL.md 파일 읽기
    SM-->>CX: 마크다운 내용을 context에 로드
    CX->>CX: SKILL.md 지침에 따라 행동 수행
    Note over CX: 중개자 없음 — LLM이 직접 파일 읽기 (확률론적)

SKILL.md Anatomy — XML 태그 구조

모든 SKILL.md는 YAML 프런트매터 + XML 태그 섹션으로 구성된다. XML 태그는 LLM이 구조를 명확히 파싱하도록 돕는 프롬프트 엔지니어링 패턴이다.

표준 구조

---
name: skill-name
description: Short description
---
 
<Purpose>           # 이 스킬이 무엇을 하고 왜 존재하는가
<Use_When>          # 이 스킬을 사용해야 하는 상황 (키워드 포함)
<Do_Not_Use_When>   # 다른 스킬을 써야 하는 상황 (대안 명시)
<Why_This_Exists>   # 이 모드가 필요한 동기
<Execution_Policy>  # 실행 제약과 도구 사용 정책
<Steps>             # 단계별 실행 절차
<Tool_Usage>        # MCP/도구 호출 계약
<Escalation_And_Stop_Conditions>  # 에스컬레이션·중단 조건
<Final_Checklist>   # 완료 전 체크리스트
<Advanced>          # (선택) 심화 내용

OMC SKILL.md와의 구조 비교

항목	OMC	OMX
호출 방식	Skill("omc:name") tool	$name 키워드 / 직접 파일 읽기
로드 메커니즘	Skill tool → SKILL.md 로드 (프로그래밍적)	Codex LLM이 파일 직접 읽기 (확률론적)
설치 위치	플러그인 내 skills/	.agents/skills/
Skill 수	29개	36개
XML 태그 패턴	거의 동일	거의 동일
새 Skill 종류	—	deep-interview, ralplan, visual-verdict, web-clone, ecomode, ai-slop-cleaner

구조는 거의 동일하다. OMC의 설계를 OMX가 계승하면서, Codex CLI 환경에 맞게 로드 메커니즘만 변경(Skill tool → LLM 직접 읽기)한 것이다.

36개 Skill 분류

오케스트레이션 Skill (핵심)

Skill	역할	키워드 트리거
team	N worker 병렬 조율 (tmux 기반)	team, swarm, coordinated team
autopilot	전체 자동화 파이프라인 (Layer 3)	autopilot, build me, I want a
ralph	검증 루프 — 완료까지 반복 (Layer 2)	ralph, don't stop, must complete, keep going
ultrawork	단순 병렬 실행 (Layer 1)	ultrawork, ulw, parallel
ultraqa	QA 사이클	ultraqa
ralplan	합의 기반 계획 (planner + architect + critic)	ralplan, consensus plan
cancel	활성 모드 취소	cancel, stop, abort

분석/리뷰 Skill

Skill	역할	키워드 트리거
plan	구조화된 작업 계획	plan this, plan the, let's plan
deep-interview	소크라테스식 요구사항 인터뷰 (Ouroboros)	interview, deep interview, ouroboros, don't assume
analyze	심층 분석	analyze, investigate
deepsearch	깊은 저장소 분석	(명시적 호출)
code-review	코드 리뷰 워크플로우	code review, review code
security-review	보안 감사	security review
frontend-ui-ux	UI/UX 평가	(명시적 호출)

유틸리티 Skill

Skill	역할
doctor	설치 상태 진단
omx-setup	초기 설정
hud	상태 대시보드
note	메모
trace	실행 추적
build-fix	빌드 실패 복구 (fix build, type errors)
tdd	TDD 워크플로우 (tdd, test first)
git-master	Git 작업
pipeline	빌드 파이프라인
ai-slop-cleaner	코드 정리/리팩터 (cleanup, refactor, deslop)
ecomode	토큰 절약 모드 (ecomode, eco, budget)
help	도움말
skill	스킬 목록 조회

특수 Skill

Skill	역할
visual-verdict	비주얼 QA — 스크린샷 비교, 구조화 JSON 출력
ask-claude	Claude에게 질문
ask-gemini	Gemini에게 질문
web-clone	웹사이트 복제 파이프라인 — Playwright 기반 브라우저 자동화 (web-clone, clone site)
configure-notifications	알림 게이트웨이 설정
worker	Team Worker 전용 (team 모드에서만 사용)
swarm	team의 호환 별칭
ralph-init	Ralph 초기화 전용
review	범용 리뷰

Keyword → Skill Mapping — 키워드 감지 메커니즘

2편에서 “AGENTS.md 내 키워드 테이블이 1차 감지를 담당하고, keyword-detector.ts가 상태 추적용 2차 보조”라는 구조를 배웠다. 여기서는 keyword-registry.ts의 우선순위 체계와 충돌 해결 로직을 깊이 다룬다.

우선순위 체계 (소스: src/hooks/keyword-registry.ts)

keyword-registry.ts는 39개 키워드 트리거를 { keyword, skill, priority, guidance } 형태로 정의한다. 우선순위가 높을수록 먼저 매칭된다.

우선순위	Skill	키워드 예시
11	ralplan	ralplan, consensus plan
10	autopilot, ultrawork	autopilot, build me, ultrawork, parallel
9	ralph	ralph, don't stop, must complete
8	deep-interview, plan, team, ultraqa	interview, team, swarm
7	analyze	analyze, investigate
6	tdd, build-fix, code-review, security-review	tdd, fix build, code review
5	cancel	cancel, stop, abort

충돌 해결 (소스: compareKeywordMatches)

사용자 입력에 여러 키워드가 동시에 매칭되면, 정렬 비교 함수 하나로 해결한다:

// src/hooks/keyword-registry.ts
export function compareKeywordMatches(
  a: { priority: number; keyword: string },
  b: { priority: number; keyword: string },
): number {
  if (b.priority !== a.priority) return b.priority - a.priority;     // 1. 높은 priority 승리
  if (b.keyword.length !== a.keyword.length) return b.keyword.length - a.keyword.length; // 2. 긴 키워드 승리
  return a.keyword.localeCompare(b.keyword);                          // 3. 알파벳 순
}

Array.sort(compareKeywordMatches) 한 번이면 최우선 매칭이 [0]에 온다. 구현이 단순한 이유는 복잡한 로직을 priority 숫자에 미리 인코딩했기 때문이다.

감지 계층 — Explicit vs Implicit

graph TD
    UI["사용자 입력: '$ralph refactor the API, use parallel'"]

    UI --> E["1차: Explicit 감지 — '$ralph'"]
    UI --> I["2차: Implicit 감지 — 'parallel' (ultrawork)"]

    E --> D["중복 제거: 스킬당 첫 매칭만 유지"]
    I --> D

    D --> R["결과: ralph (explicit, 우선), ultrawork (implicit)"]

    style E fill:#e8f0fe
    style I fill:#fef7e0

• Explicit ($skill): 좌→우 순서대로 감지, implicit보다 항상 우선
• Implicit (키워드 매칭): priority/length/alphabetical로 정렬
• 스킬당 첫 매칭만 유지 (중복 제거)

Execution Gate — ralplan-first 강제

실행형 키워드(ralph, autopilot, team, ultrawork)가 감지되었더라도, 프롬프트가 underspecified(모호)하면 ralplan으로 리다이렉트된다.

// src/hooks/keyword-registry.ts — 게이트 대상 키워드
export const EXECUTION_GATE_KEYWORDS = new Set<string>([
  'ralph', 'autopilot', 'team', 'ultrawork',
]);
 
export const GATE_BYPASS_PREFIXES = ['force:', '!'];
 
// 핵심 판단 함수: 프롬프트가 모호한지 결정
export function isUnderspecifiedForExecution(text: string): boolean {
  const trimmed = text.trim();
  if (!trimmed) return true;
 
  // escape hatch: force: 또는 ! 접두사 → 무조건 통과
  for (const prefix of GATE_BYPASS_PREFIXES) {
    if (trimmed.startsWith(prefix)) return false;
  }
 
  // well-specified 시그널 14개 패턴 중 하나라도 있으면 통과
  if (WELL_SPECIFIED_SIGNALS.some(p => p.test(trimmed))) return false;
 
  // 모드 키워드 제거 후 실질 단어 수 계산
  const stripped = trimmed
    .replace(/\b(?:ralph|autopilot|team|ultrawork|ulw|swarm)\b/gi, '')
    .trim();
  const effectiveWords = stripped.split(/\s+/).filter(w => w.length > 0).length;
 
  // 15단어 이하면 모호 → ralplan으로 리다이렉트
  if (effectiveWords <= 15) return true;
  return false;
}

well-specified 시그널 — 이 패턴 중 하나라도 매칭되면 “구체적”으로 판단하여 게이트를 통과시킨다:

// 14개 패턴 중 핵심 발췌
const WELL_SPECIFIED_SIGNALS: RegExp[] = [
  /\.\w{1,10}\b/,                    // 파일 확장자 (.ts, .md 등)
  /(?:^|\s)(?:src|lib|test)\//,      // 디렉토리 경로
  /\b(?:function|class|interface)\s/, // 코드 선언
  /[A-Z][a-z]+[A-Z]/,               // CamelCase 식별자
  /\b\d+\.\s/,                       // 번호 매긴 단계 (1. 2. 3.)
  /\b(?:must|should|accept)\b/i,     // 수용 기준 키워드
  /```/,                             // 코드 블록
  /\b(?:PR|commit|issue)\s*#?\d+/i,  // PR/커밋/이슈 참조
  // ... 총 14개
];

"ralph make it better" → 모드 키워드 제거 후 “make it better” = 3단어 → 모호 → ralplan 리다이렉트 "ralph refactor src/api/auth.ts to use JWT" → .ts 파일 확장자 + src/ 경로 → 구체적 → 바로 실행

게이트 적용 함수:

// src/hooks/keyword-detector.ts
export function applyRalplanGate(
  keywords: string[], text: string,
): { keywords: string[]; gateApplied: boolean } {
  // cancel 포함 시 게이트 안 함
  // ralplan 이미 있으면 게이트 안 함
  // planning 완료(PRD + test-spec 존재) 시 게이트 안 함
 
  if (!isUnderspecifiedForExecution(text)) return { keywords, gateApplied: false };
 
  // 실행형 키워드를 ralplan으로 교체
  const filtered = keywords.filter(k => !EXECUTION_GATE_KEYWORDS.has(k));
  if (!filtered.includes('ralplan')) filtered.push('ralplan');
  return { keywords: filtered, gateApplied: true };
}

Skill Composition — 3계층 합성 아키텍처

OMX 스킬의 핵심 설계 원리는 **계층적 합성(Layered Composition)**이다. 각 계층이 아래 계층을 감싸며 기능을 추가한다.

3계층 구조

graph TB
    subgraph L3["Layer 3: autopilot — 전체 자율 파이프라인"]
        A3["planning → execution → QA → validation"]
    end

    subgraph L2["Layer 2: ralph — 영속성 + 검증"]
        A2["세션 상태 유지 + architect 검증 + 재시도 루프"]
    end

    subgraph L1["Layer 1: ultrawork — 병렬성"]
        A1["독립 태스크 동시 실행 + 모델 라우팅"]
    end

    L3 -->|wraps| L2
    L2 -->|wraps| L1

    style L3 fill:#d4edda
    style L2 fill:#cce5ff
    style L1 fill:#fff3cd

계층	Skill	추가하는 기능	상태 영속성	검증
Layer 1	ultrawork	병렬 실행 + 모델 라우팅	X	경량 (빌드/테스트 통과)
Layer 2	ralph	세션 상태 + architect 검증 + 재시도	O	필수 (STANDARD tier 이상)
Layer 3	autopilot	전체 자율 파이프라인	O	전체 lifecycle

Ralph + Ultrawork 합성 상세

Ralph는 Ultrawork의 병렬 실행을 내부적으로 활용하면서, 영속성·검증·재시도를 감싸는 구조다.

sequenceDiagram
    autonumber
    participant U as 사용자
    participant R as Ralph (Layer 2)
    participant UW as Ultrawork (Layer 1)
    participant V as Architect 검증
    participant S as .omx/state/

    U->>R: "$ralph refactor API"
    R->>S: state_write(mode: "ralph", iteration: 1, phase: "executing")
    R->>R: Pre-context intake gate 확인
    Note over R: .omx/context/{slug}-{timestamp}.md 필수

    loop 최대 10회 반복
        R->>UW: 병렬 태스크 위임 (delegate)
        UW->>UW: 독립 태스크 동시 실행
        UW-->>R: 실행 결과 반환
        R->>S: state_write(phase: "verifying")
        R->>V: architect 검증 요청 (STANDARD tier 이상)
        V-->>R: 검증 결과
        alt 검증 통과
            R->>S: state_write(phase: "complete", completed_at: timestamp)
            R-->>U: 완료 보고
        else 검증 실패
            R->>S: state_write(phase: "fixing", iteration: N+1)
            Note over R: 다음 반복으로 계속
        end
    end

Ralph Planning Gate — ralplan-first 강제

Ralph가 활성화되면 PRD + test-spec 아티팩트가 존재해야 구현을 시작할 수 있다.

Ralph 활성 상태에서의 게이트 조건:
├── .omx/plans/prd-*.md 존재?      → YES → 다음 확인
│                                   → NO  → 구현 차단 (BLOCKED)
└── .omx/plans/test-spec-*.md 존재? → YES → 게이트 해제 (UNLOCKED)
                                    → NO  → 구현 차단 (BLOCKED)

게이트 상태는 AGENTS.md 오버레이에 UNLOCKED / BLOCKED로 주입된다. 두 파일이 모두 존재해야 비로소 current_phase: "executing"이 허용된다.

deep-interview (Ouroboros) — 소크라테스식 요구사항 인터뷰

deep-interview는 구현 전에 모호성을 제거하는 인터뷰 워크플로우다. “Ouroboros”라는 별명은 자기 참조적 반복 질문 루프에서 유래한다.

5단계 흐름

sequenceDiagram
    autonumber
    participant U as 사용자
    participant DI as deep-interview
    participant S as .omx/ (상태·아티팩트)
    participant EX as 실행 브릿지

    DI->>S: Phase 0: Preflight — context 스냅샷 생성
    Note over S: .omx/context/{slug}-{timestamp}.md

    DI->>DI: Phase 1: Initialize — depth 프로파일 설정
    Note over DI: quick(0.30) / standard(0.20) / deep(0.15)

    loop Phase 2: Interview Loop (ambiguity ≤ threshold까지)
        DI->>U: 1회 1질문 — 가장 약한 clarity 차원 타겟
        U-->>DI: 답변
        DI->>DI: ambiguity 점수 재계산
        DI->>S: state_write(rounds[], current_ambiguity)
    end

    Note over DI: Phase 3: Challenge Mode (round 4+)
    DI->>U: Contrarian(4+), Simplifier(6+), Ontologist(8+)

    DI->>S: Phase 4: Crystallize — transcript + spec 생성
    Note over S: .omx/interviews/ + .omx/specs/

    DI->>EX: Phase 5: Execution Bridge
    Note over EX: $ralplan / $autopilot / $ralph / $team / 추가 정제

Ambiguity 점수 — 가중치 기반 다차원 평가

차원	Greenfield 가중치	Brownfield 가중치
Intent (의도)	0.30	0.25
Outcome (결과)	0.25	0.20
Scope (범위)	0.20	0.20
Constraints (제약)	0.15	0.15
Success Criteria (성공 기준)	0.10	0.10
Context Clarity (맥락)	—	0.10

ambiguity = 1 - (각 차원의 clarity × 가중치)의 합

Challenge Mode — 가정 스트레스 테스트

모드	활성 시점	역할
Contrarian	round 4+	핵심 가정에 반론 제기
Simplifier	round 6+	최소 실행 가능 범위 탐색
Ontologist	round 8+ (ambiguity > 0.30)	본질적 재정의 요청

Input Lock — 자동 승인 차단

deep-interview가 활성화되면 자동 승인 단축어가 차단된다.

차단 대상: yes, y, proceed, continue, ok, sure, go ahead, next i should

이는 사용자가 인터뷰 질문에 대해 성의 없이 yes만 반복하여 모호성 제거를 우회하는 것을 방지한다. Lock은 인터뷰 완료(success), 에러(error), 중단(abort), 핸드오프(handoff) 시 해제된다.

visual-verdict — 비주얼 QA 워크플로우

visual-verdict는 스크린샷과 레퍼런스 이미지를 비교하여 구조화된 JSON 판정을 내리는 비주얼 QA 스킬이다.

입출력 계약

입력:

• reference_images[] — 1개 이상의 레퍼런스 이미지 경로
• generated_screenshot — 현재 출력 이미지
• category_hint (선택) — UI 카테고리 힌트 (예: hackernews, dashboard)

출력 — 필수 JSON 스키마:

{
  "score": 87,
  "verdict": "revise",
  "category_match": true,
  "differences": [
    "Top nav spacing is tighter than reference",
    "Primary button uses smaller font weight"
  ],
  "suggestions": [
    "Increase nav item horizontal padding by 4px",
    "Set primary button font-weight to 600"
  ],
  "reasoning": "Core layout matches, but style details still diverge."
}

필드	타입	설명
score	integer 0-100	시각적 일치도 점수
verdict	pass / revise / fail	판정 결과
category_match	boolean	의도된 UI 카테고리와의 일치 여부
differences[]	string[]	구체적 시각 차이 (레이아웃, 간격, 타이포그래피, 색상)
suggestions[]	string[]	differences에 대응하는 실행 가능한 수정 제안
reasoning	string	1-2문장 판정 근거 요약

Ralph 통합 — 반복 게이트

sequenceDiagram
    autonumber
    participant R as Ralph
    participant VV as visual-verdict
    participant S as .omx/state/

    loop Ralph 반복 루프
        R->>R: 코드 수정 작업 수행
        R->>VV: $visual-verdict 실행 (매 수정 전)
        VV-->>R: JSON 판정 반환
        R->>S: ralph-progress.json에 verdict 저장
        alt score ≥ 90
            Note over R: 통과 — 다음 단계로
        else score < 90
            Note over R: 미통과 — suggestions 기반으로 수정 계속
        end
    end

• Ralph 통합 시 통과 기준: score >= 90
• web-clone 통합 시 통과 기준: score >= 85 (visual + functional + structure 복합 판정)
• 매 수정 전 $visual-verdict를 먼저 실행하여 현재 상태를 평가 → 불필요한 수정 방지

Skill 로딩 메커니즘 — 디스커버리에서 실행까지

디스커버리 경로 (소스: src/utils/paths.ts)

// src/utils/paths.ts — 3개 탐색 경로 정의
export function projectSkillsDir(projectRoot?: string): string {
  return join(projectRoot || process.cwd(), '.agents', 'skills');  // 1순위
}
export function userSkillsDir(): string {
  return join(codexHome(), 'skills');  // ~/.codex/skills/ — 2순위
}
export function legacyUserSkillsDir(): string {
  return join(homedir(), '.agents', 'skills');  // 3순위 (레거시)
}
 
// 디스커버리: 프로젝트 → 사용자 순서, 같은 이름이면 프로젝트가 shadow
export async function listInstalledSkillDirectories(
  projectRoot?: string,
): Promise<InstalledSkillDirectory[]> {
  const orderedDirs = [
    { dir: projectSkillsDir(projectRoot), scope: 'project' },
    { dir: userSkillsDir(), scope: 'user' },
  ];
  // project skills shadow user skills with same name
}

같은 이름의 Skill이 프로젝트와 사용자 스코프 모두에 존재하면, 프로젝트 스코프가 승리(shadow). 쉐도잉된 스킬의 참조 라인은 세션 합본 AGENTS.md에서 제거된다.

Catalog Manifest (소스: src/catalog/manifest.json)

{
  "schemaVersion": 1,
  "catalogVersion": "2026.02.28.1",
  "skills": [
    {"name": "ralph", "category": "execution", "status": "active", "core": true},
    {"name": "swarm", "category": "execution", "status": "alias", "canonical": "team"}
  ]
}

• core skill (필수): ralplan, team, ralph, ultrawork, autopilot
• alias: swarm → team, ecomode → ultrawork (merged)
• 로드 시점에 스키마 유효성 검증

로드 흐름 요약 — AGENTS.md 경로 참조 + LLM 직접 읽기

SKILL.md는 AGENTS.md에 임베딩되지 않는다. AGENTS.md에는 스킬 파일의 경로 참조만 포함된다.

AGENTS.md 내 실제 참조 형식:

<!-- AGENTS.md keyword_detection 섹션 -->
| Keyword(s) | Skill | Action |
|-------------|-------|--------|
| "ralph", "don't stop", "must complete" | `$ralph` | Read `./.agents/skills/ralph/SKILL.md`, execute persistence loop |
| "autopilot", "build me", "I want a" | `$autopilot` | Read `./.agents/skills/autopilot/SKILL.md`, execute autonomous pipeline |

LLM은 이 테이블을 읽고, 키워드가 매칭되면 Action 열의 경로를 따라 SKILL.md를 직접 읽는다. 프로그래밍적 로드가 아니라 LLM의 파일 읽기 능력에 의존하는 확률론적 설계다.

프로젝트 스킬이 사용자 스킬을 shadow하는 메커니즘:

// src/hooks/agents-overlay.ts — 쉐도잉 처리의 핵심
const SKILL_REFERENCE_PATTERN = /\/skills\/([^/\s`]+)\/SKILL\.md/;
 
// 프로젝트 스코프에 같은 이름의 스킬이 있으면
// 사용자 스코프 스킬의 참조 라인을 AGENTS.md에서 제거
export function dropShadowedSkillReferenceLines(
  agentsMd: string,
  projectSkillNames: Set<string>,
): string {
  return agentsMd
    .split('\n')
    .filter(line => {
      const match = line.match(SKILL_REFERENCE_PATTERN);
      if (!match) return true;  // 스킬 참조가 아닌 라인은 유지
      const skillName = match[1];
      // 프로젝트에 같은 이름이 있으면 이 (사용자 스코프) 라인 제거
      return !projectSkillNames.has(skillName);
    })
    .join('\n');
}

이 함수가 omx launch 시점에 실행되어, 합본 AGENTS.md에서 쉐도잉된 사용자 스킬 참조를 제거한다. LLM이 보는 AGENTS.md에는 항상 가장 높은 우선순위의 스킬 경로만 남는다.

MCP 도구(state_write, memory_store 등)는 Skill 실행 중 상태 기록에 사용되며, SKILL.md 내 <Tool_Usage> 섹션에 사용 계약이 명시된다.

graph LR
    OL["agents-overlay.ts<br>launch 시 합본"] -->|"경로 참조 주입<br>+ shadow 처리"| AM["AGENTS.md"]
    AM -->|"LLM이 키워드 테이블 읽기"| CX["Codex CLI (LLM)"]
    CX -->|"Action 열의 경로 따라<br>직접 파일 읽기"| SM[".agents/skills/ralph/SKILL.md"]
    SM -->|"context에 로드"| CX
    CX -->|"상태 기록"| MCP["MCP Server<br>(state_write 등)"]

    PT["paths.ts<br>디스커버리"] -.->|"스킬 경로 해석"| OL
    MF["manifest.json"] -.->|"카탈로그 메타데이터"| OL

    style OL fill:#f0e6ff
    style AM fill:#fef7e0
    style CX fill:#e8f0fe

참고 문서

• OMX GitHub
• Codex CLI AGENTS.md Guide