Codex Skill Discovery (app-server spawn)

• Codex Skill Discovery는 codex 바이너리가 스킬 파일을 탐색하는 계층적 파일 시스템 스캔 메커니즘
• HOME(USER-level)과 cwd(PROJECT-level) 두 경로를 동시에 스캔하여 스킬 목록을 구성하는 이중 레벨 디스커버리 구조
• app-server JSON-RPC 프로토콜의 thread/start와 skills/list 두 메서드를 통해 제어되는 세션 기반 스킬 라우팅

해당 개념이 필요한 이유

• 자체 서비스가 codex를 spawn하여 사용할 때, 서비스 전용 스킬(예: 사내 DB 검색)이 사용자의 글로벌 CLI에 노출되지 않아야 한다
• 반대로, 사용자가 글로벌하게 설정한 스킬은 서비스에서도 사용 가능해야 한다
• codex 바이너리 버전이 사용자마다 다를 수 있는 상황에서도 서비스가 일관되게 동작해야 한다

케이스 A: 서비스는 사용자의 글로벌 CLI가 아닌 자체 바이너리를 사용한다

바이너리 해석 경로

사용자가 npm install -g @openai/codex로 설치한 글로벌 CLI는 /opt/homebrew/bin/codex 등에 위치한다. 서비스는 이것을 사용하지 않는다.

서비스 프로젝트의 package.json에 @openai/codex를 의존성으로 선언하고, 프로젝트 내에서 npm install을 실행하면 프로젝트의 node_modules/ 안에 codex 바이너리가 설치된다. 서비스는 이 로컬 바이너리를 해석하여 spawn한다:

my-service/
└── node_modules/
    └── @openai/codex-darwin-arm64/
        └── vendor/
            └── aarch64-apple-darwin/
                └── codex/
                    └── codex  ← 이 바이너리를 spawn

// package.json — 캐럿 없이 고정 버전
{ "@openai/codex": "0.105.0" }

사용자가 글로벌에 0.98.0을 쓰든 0.116을 쓰든, 서비스는 항상 프로젝트 node_modules/에 설치된 0.105.0 바이너리를 spawn한다. 글로벌 CLI와 서비스의 바이너리는 완전히 별개의 설치다.

Q1. 사용자의 글로벌 스킬 X를 서비스에서 사용할 수 있는가?

YES. 사용자가 ~/.agents/skills/X/ (또는 레거시 ~/.codex/skills/X/)에 설치한 글로벌 스킬은 서비스에서도 발견된다.

이유: spawn 시 process.env를 그대로 전달하므로 HOME 환경변수가 유지된다. codex 바이너리는 항상 HOME 기반의 USER-level 경로(~/.agents/skills/ + ~/.codex/skills/)를 스캔한다.

sequenceDiagram
    autonumber
    participant User as 사용자 환경
    participant App as Service Backend
    participant Codex as codex (번들 바이너리)
    participant GS as ~/.agents/skills/
    participant PS as {appDataDir}/.agents/skills/

    User->>GS: 스킬 X 설치 (글로벌 CLI로)
    App->>Codex: spawn(codexBinaryPath, env: { HOME=~ })
    App->>Codex: thread/start(cwd=appDataDir)
    Codex->>GS: HOME 기준 스캔 → 스킬 X 발견 ✅
    Codex->>PS: cwd 기준 스캔 → 사내 DB 검색 스킬 발견 ✅
    Codex-->>App: 스킬 X + 사내 DB 검색 스킬 모두 사용 가능

실제 예시

Q. 글로벌에 study-guard 스킬을, 프로젝트에 내부 DB 접근 스킬을 설정했다. 서비스에서 둘 다 사용할 수 있는가?

A. 둘 다 사용 가능하다.

글로벌 스킬 (USER-level):
  ~/.agents/skills/study-guard/

프로젝트 스킬 (PROJECT-level):
  {appDataDir}/.agents/skills/access-db/

서비스가 codex를 spawn하면:

1. spawn 시 process.env가 그대로 전달 → HOME=~ → ~/.agents/skills/study-guard/ 발견 ✅
2. thread/start에서 cwd를 서비스 데이터 디렉토리로 설정 → {appDataDir}/.agents/skills/access-db/ 발견 ✅

두 레벨의 합집합으로 동작하므로, 세션에서 study-guard와 access-db 스킬 모두 사용 가능하다.

sequenceDiagram
    autonumber
    participant App as Service Backend
    participant Codex as codex (번들 바이너리)
    participant GS as ~/.agents/skills/study-guard/
    participant PS as {appDataDir}/.agents/skills/access-db/

    App->>Codex: spawn(codexBinaryPath, env: { HOME=~ })
    App->>Codex: thread/start(cwd=appDataDir)
    Codex->>GS: HOME 기준 스캔 → study-guard 발견 ✅
    Codex->>PS: cwd 기준 스캔 → access-db 스킬 발견 ✅
    Codex-->>App: study-guard + access-db 모두 사용 가능

핵심은 바이너리는 번들된 것을 사용하지만, HOME은 사용자 것을 그대로 유지한다는 점이다. 바이너리 버전과 스킬 디스커버리 경로는 별개의 문제다.

케이스 B: 바이너리 버전 핀닝과 사용자 간 독립성

시나리오: 현재 소스코드 기준 — 양쪽 경로 모두 스캔

소스코드 분석 결과, 현재 codex는 .codex/skills/와 .agents/skills/를 동시에 스캔한다. User scope에서 ~/.codex/skills/는 deprecated이지만 하위 호환을 위해 유지된다.

구분	사용자 A (레거시 경로 사용)	사용자 B (현재 권장 경로 사용)
글로벌 스킬 위치	~/.codex/skills/	~/.agents/skills/
서비스 바이너리	0.105.0 (동일)	0.105.0 (동일)
서비스에서 글로벌 스킬 발견	✅ (deprecated 경로도 스캔)	✅ (현재 권장 경로 스캔)

A와 B 모두 서비스에서 정상 동작한다. codex 바이너리가 양쪽 경로를 모두 스캔하므로, 사용자가 어느 경로에 스킬을 설치했든 발견된다.

사용자 A (레거시 경로):
  서비스: {cwd}/.codex/skills/ ✅ + ~/.codex/skills/ ✅ (deprecated but scanned)
                                  + ~/.agents/skills/ ✅ (current)

사용자 B (현재 권장 경로):
  서비스: {cwd}/.codex/skills/ ✅ + ~/.codex/skills/ ✅ (deprecated but scanned)
                                  + ~/.agents/skills/ ✅ (current)

결론: 서비스의 핵심 동작은 사용자의 글로벌 CLI 버전과 완전히 독립적이다. package.json에 버전을 핀닝했기 때문이다. 또한 양쪽 경로를 모두 스캔하므로 경로 마이그레이션 과도기에도 문제없다.

서비스 측 스킬 배포 전략

소스코드 분석 결과 codex는 .codex/skills/와 .agents/skills/를 동시에 스캔하므로, 어느 한 경로에만 배포하면 충분하다. 서비스는 현재 권장 경로인 .agents/skills/에 배포한다.

1. 단일 경로 배포 (현재 서비스 구현)

skill-deployer.service.ts에서 {appDataDir}/.agents/skills/에 배포:

function getCodexSkillsTarget(): string {
  return path.join(getAppDataDir(), ".agents", "skills");
}

codex 바이너리가 repo_agents_skill_roots() 함수를 통해 cwd 경로 상의 .agents/skills/를 스캔하므로, thread/start에서 cwd=appDataDir로 설정하면 자동 발견된다.

2. 미래 deprecated 제거에 대한 방어

현재 .codex/skills/(Project scope)는 deprecated가 아니지만, 향후 제거될 가능성에 대비하여 .agents/skills/를 사용하는 것이 안전하다. 만약 미래에 .agents/skills/도 경로가 변경된다면, symlink 배포로 대응할 수 있다:

공식 문서: “Codex supports symlinked skill folders and follows symlink targets when scanning these locations.”

3. skills/list 검증 (선택)

바이너리 업그레이드 시 스킬 발견 상태를 검증할 수 있다:

const skillsResult = await peer.request("skills/list", {
  cwds: [APP_DATA_DIR],
});
 
const expectedSkills = ["access-db", "internal-search"];
const foundSkills = skillsResult.skills.map(s => s.name);
const missing = expectedSkills.filter(s => !foundSkills.includes(s));
 
if (missing.length > 0) {
  logger.error(`스킬 미발견: ${missing.join(", ")} — 경로 마이그레이션 필요`);
}

skills/list는 읽기 전용 조회이므로, 세션 동작에 영향 없이 스킬 발견 상태를 검증할 수 있다.

스킬 디스커버리의 두 레벨

Level	경로	상태	결정 요소	설명
USER (글로벌)	~/.agents/skills/	현재 권장	spawn 시 HOME 환경변수	모든 codex 세션에서 항상 스캔
USER (글로벌)	~/.codex/skills/	deprecated (하위 호환)	spawn 시 CODEX_HOME	하위 호환용으로 여전히 스캔
PROJECT (프로젝트)	{cwd}/.codex/skills/	active	thread/start의 cwd 파라미터	프로젝트 config layer 기준
PROJECT (프로젝트)	{root~cwd}/.agents/skills/	현재 권장	thread/start의 cwd 파라미터	프로젝트 루트~cwd 사이 모두 스캔

두 레벨은 합집합으로 동작한다. USER 경로와 PROJECT 경로를 모두 스캔한 후, dedupe_skill_roots_by_path()로 중복을 제거하고 발견된 모든 스킬을 해당 세션에서 사용 가능하게 만든다.

HOME과 cwd는 스킬만을 위한 설정이 아니다

HOME과 cwd는 codex 전반에 영향을 주는 설정이며, 스킬 디스커버리는 그 중 하나의 부가 효과일 뿐이다.

HOME (spawn 환경변수) — ~/.codex/ 전체 + ~/.agents/ 를 결정:

경로	용도
~/.codex/config.toml	codex 설정 (모델, API 키 경로 등)
~/.codex/auth/	인증 정보
~/.codex/db/	codex 내부 데이터
~/.codex/certs/	TLS 인증서
~/.codex/skills/	USER-level 스킬 (deprecated, 하위 호환)
~/.agents/skills/	USER-level 스킬 (현재 권장)

process.env로 HOME을 그대로 전달하는 이유는 사용자의 codex 설정, 인증 정보 등을 모두 활용하기 위해서다.

cwd (thread/start 파라미터) — 세션의 작업 디렉토리 전반을 결정:

영향	설명
명령 실행	codex가 셸 명령을 실행할 때의 작업 디렉토리
파일 접근	상대 경로 기준점 (파일 읽기/쓰기)
샌드박스 경계	sandbox_workspace_write 모드의 workspace 루트
프로젝트 설정	{cwd}/.codex/ 프로젝트 레벨 설정
프로젝트 스킬	{cwd}/.codex/skills/ + {cwd}/.agents/skills/ PROJECT-level 스킬

cwd를 서비스 데이터 디렉토리로 설정하는 본래 목적은 codex의 파일 작업과 명령 실행을 해당 디렉토리 안에서 수행하도록 하는 것이고, PROJECT-level 스킬 디스커버리는 그에 따라오는 부가 효과다.

코드에서 두 레벨이 설정되는 위치

// 1단계: spawn — 프로세스 생성
const spawnEnv = {
  ...process.env,                                      // HOME 포함 → USER-level 디스커버리 근거
  TOOL_CLI: "/path/to/skill/script/tool-cli",          // 스킬이 사용할 CLI 경로
  TOOL_BASE_URL: `http://localhost:${backendPort}`,    // 스킬 → 서비스 API 통신 주소
  TOOL_USER_ID: userId,                                // 요청 사용자 식별
};
const child = spawn(codexBinaryPath, ["app-server", ...flags], {
  stdio: ["pipe", "pipe", "pipe"],
  env: spawnEnv,
});
 
// 2단계: thread/start — 세션 생성
await peer.request("thread/start", {
  model: "o4-mini",
  cwd: APP_DATA_DIR,   // → PROJECT-level 디스커버리 근거
  approvalPolicy: "never",
});

설정 위치	결정하는 것	글로벌 스킬 X	사내 DB 검색 스킬
spawn env (...process.env)	HOME → ~/.agents/skills/ + ~/.codex/skills/	여기서 발견	-
thread/start (cwd)	cwd → {appDataDir}/.agents/skills/ + {appDataDir}/.codex/skills/	-	여기서 발견

사용자의 글로벌 스킬 X는 thread/start가 아니라 spawn 시 전달된 HOME 환경변수로 인해 발견된다. spawnEnv에서 HOME을 제거하거나 다른 값으로 덮어쓰면 글로벌 스킬 X는 발견되지 않는다.

cwd가 스킬 디스커버리에서 하는 역할

HOME(spawn 환경변수)이 이미 글로벌 스킬 접근을 제공하는데, cwd(thread/start 파라미터)는 추가적인 프로젝트 스코프 경로를 제공한다:

사용자가 codex CLI 직접 사용:
  spawn HOME=~                         → ~/.agents/skills/                    (글로벌 스킬 X ✅)
  thread/start cwd=~/projects/myapp    → ~/projects/myapp/.agents/skills/     (사내 DB 검색 스킬 ❌)

서비스가 spawn:
  spawn HOME=~                         → ~/.agents/skills/                    (글로벌 스킬 X ✅)
  thread/start cwd=appDataDir          → {appDataDir}/.agents/skills/         (사내 DB 검색 스킬 ✅)

cwd가 다르기 때문에 동일한 HOME을 공유하면서도 서비스 전용 스킬을 격리할 수 있다.

JSON-RPC 메서드: skills/list vs thread/start

codex app-server는 JSON-RPC 2.0 프로토콜로 통신한다. 스킬 관련 메서드는 두 가지다.

thread/start

세션을 생성하고 스킬 디스커버리를 트리거하는 메서드.

{
  "method": "thread/start",
  "params": {
    "model": "o4-mini",
    "cwd": "/path/to/service/data",
    "approvalPolicy": "never"
  }
}

cwd가 PROJECT-level 스킬 탐색 경로를 결정한다. 이 메서드가 호출되면 codex는 USER-level(HOME 기반)과 PROJECT-level(cwd 기반)을 모두 스캔하여 세션의 스킬 목록을 구성한다.

skills/list

현재 사용 가능한 스킬 목록을 조회하는 읽기 전용 메서드.

{
  "method": "skills/list",
  "params": {
    "perCwdExtraUserRoots": ["/additional/path"]
  }
}

perCwdExtraUserRoots 파라미터로 추가 탐색 경로를 지정할 수 있지만, 이것은 조회 전용이다. 해당 경로의 스킬 목록을 볼 수 있을 뿐, 세션에서 사용 가능하게 만드는 것은 아니다. thread/start에는 이 파라미터가 존재하지 않으므로, API를 통한 추가 경로 주입으로는 세션의 스킬 디스커버리에 영향을 줄 수 없다. 이것이 물리적 파일 배포 방식이 가장 안정적인 이유다.

thread/start의 cwd vs spawn의 cwd 옵션

두 가지 cwd는 다른 레이어에서 동작한다:

설정 방법	레이어	역할
spawn(binary, args, { cwd: path })	OS-level	codex 프로세스의 작업 디렉토리
thread/start { cwd: path }	JSON-RPC 파라미터	스킬 디스커버리 + 명령 실행 경로

spawn 옵션의 cwd를 설정하면 codex 프로세스의 OS-level 작업 디렉토리가 변경된다. thread/start에서 cwd를 생략하면 프로세스의 OS-level cwd를 fallback으로 사용할 가능성이 있지만, 이는 문서화된 동작이 아닌 구현 세부사항에 의존하는 것이다. thread/start에 cwd를 명시적으로 설정하는 것이 안정적이다.

.codex/skills/ vs .agents/skills/ — 소스코드 기반 분석

실제 소스코드 (codex-rs/core/src/skills/loader.rs)

둘 다 스캔된다. 단, scope별로 역할이 다르다.

// 상수 정의
const AGENTS_DIR_NAME: &str = ".agents";
const SKILLS_DIR_NAME: &str = "skills";

User scope — ~/.codex/skills/ (deprecated) + ~/.agents/skills/ (current)

ConfigLayerSource::User { .. } => {
    // Deprecated user skills location (`$CODEX_HOME/skills`), kept for backward
    // compatibility.
    roots.push(SkillRoot {
        path: config_folder.as_path().join(SKILLS_DIR_NAME),  // ~/.codex/skills
        scope: SkillScope::User,
    });
 
    // `$HOME/.agents/skills` (user-installed skills).
    if let Some(home_dir) = home_dir {
        roots.push(SkillRoot {
            path: home_dir.join(AGENTS_DIR_NAME).join(SKILLS_DIR_NAME),  // ~/.agents/skills
            scope: SkillScope::User,
        });
    }
}

Project scope — {cwd}/.codex/skills/ (active) + {cwd~root}/.agents/skills/ (active)

ConfigLayerSource::Project { .. } => {
    // deprecated 주석 없음 — 정상 경로
    roots.push(SkillRoot {
        path: config_folder.as_path().join(SKILLS_DIR_NAME),  // {project}/.codex/skills
        scope: SkillScope::Repo,
    });
}

추가로 repo_agents_skill_roots() 함수가 프로젝트 루트부터 cwd까지 모든 디렉토리에서 .agents/skills/를 스캔한다:

fn repo_agents_skill_roots(config_layer_stack: &ConfigLayerStack, cwd: &Path) -> Vec<SkillRoot> {
    let project_root = find_project_root(cwd, &project_root_markers);
    let dirs = dirs_between_project_root_and_cwd(cwd, &project_root);
    for dir in dirs {
        let agents_skills = dir.join(AGENTS_DIR_NAME).join(SKILLS_DIR_NAME);
        if agents_skills.is_dir() {
            roots.push(SkillRoot { path: agents_skills, scope: SkillScope::Repo });
        }
    }
}

전체 스캔 경로 (우선순위순)

Scope	경로	상태	코드 근거
Repo	{project}/.codex/skills/	Active (deprecated 아님)	ConfigLayerSource::Project
Repo	{root~cwd}/.agents/skills/	Active (현재 권장)	repo_agents_skill_roots()
User	~/.codex/skills/	Deprecated (하위 호환)	ConfigLayerSource::User + 주석
User	~/.agents/skills/	Active (현재 권장)	ConfigLayerSource::User + AGENTS_DIR_NAME
System	~/.codex/skills/.system/	Active (번들)	system_cache_root_dir()
Admin	/etc/codex/skills/	Active	ConfigLayerSource::System

핵심: deprecated는 User scope의 ~/.codex/skills/만 해당

소스코드의 // Deprecated user skills location ($CODEX_HOME/skills) 주석은 User scope의 ~/.codex/skills/에만 적용된다. Project scope의 {project}/.codex/skills/는 deprecated가 아니며 정상적인 프로젝트 설정 경로다.

CODEX_HOME은 왜 사용하지 않는가

CODEX_HOME은 ~/.codex 전체를 대체한다. 스킬뿐 아니라 config, auth, DB, certs까지 모두 영향받는다.

환경변수	영향 범위	스킬 격리 적합성
HOME	OS 전체 홈 디렉토리	❌ 과도함
CODEX_HOME	codex 전체 상태 (config, auth, DB, certs, skills)	❌ 과도함
cwd (thread/start)	PROJECT-level 스킬 경로만	✅ 정확히 적합

예시로 보는 HOME vs CODEX_HOME의 차이

사용자의 실제 환경이 아래와 같다고 가정한다:

~/.codex/
├── config.toml          ← 사용자 설정 (모델: o4-mini, sandbox: off 등)
├── auth/
│   └── credentials.json ← 사용자의 OpenAI API 키
├── db/
│   └── history.sqlite   ← 대화 히스토리
├── log/
│   └── codex.log
└── skills/
    └── study-guard/     ← 사용자의 글로벌 스킬

방법 1: HOME을 변경하는 경우

const child = spawn(codexBinaryPath, ["app-server"], {
  env: { ...process.env, HOME: "/opt/service" },  // ← HOME 변경
});

결과:

항목	경로	상태
config.toml	/opt/service/.codex/config.toml	❌ 없음 — 사용자 설정 유실
auth	/opt/service/.codex/auth/	❌ 없음 — API 키 유실, 인증 실패
DB	/opt/service/.codex/db/	❌ 없음 — 히스토리 유실
글로벌 스킬	/opt/service/.codex/skills/	❌ 없음 — study-guard 유실
SSH/GPG 등	/opt/service/.ssh/, .gnupg/	❌ OS 전체에 영향

HOME은 codex뿐 아니라 OS 전체의 홈 디렉토리를 바꾸므로, 자식 프로세스가 실행하는 모든 셸 명령(git, ssh 등)에도 영향을 준다. 모든 것이 깨진다.

방법 2: CODEX_HOME을 변경하는 경우

const child = spawn(codexBinaryPath, ["app-server"], {
  env: { ...process.env, CODEX_HOME: "/opt/service/codex-state" },  // ← CODEX_HOME 변경
});

결과:

항목	경로	상태
config.toml	/opt/service/codex-state/config.toml	❌ 없음 — 사용자 설정 유실
auth	/opt/service/codex-state/auth/	❌ 없음 — API 키 유실, 인증 실패
DB	/opt/service/codex-state/db/	❌ 없음 — 히스토리 유실
글로벌 스킬 (CODEX_HOME 기반)	/opt/service/codex-state/skills/	❌ 없음 — study-guard 유실
SSH/GPG 등	~/.ssh/, ~/.gnupg/	✅ 영향 없음

HOME보다는 범위가 좁지만(OS에는 영향 없음), codex의 모든 상태를 통째로 격리한다. 스킬만 분리하려 했는데 config, auth, DB까지 모두 잃는다. 소스 코드에서도 CODEX_HOME은 config.toml, auth/, db/, log/, skills/ 등 codex 전체 상태 디렉토리의 루트로 사용된다.

방법 3: cwd를 변경하는 경우 (권장)

const child = spawn(codexBinaryPath, ["app-server"], {
  env: { ...process.env },  // ← HOME 그대로 유지
});
 
await peer.request("thread/start", {
  cwd: "/opt/service/app-data",  // ← cwd만 서비스 디렉토리로 설정
});

결과:

항목	경로	상태
config.toml	~/.codex/config.toml	✅ 사용자 설정 유지
auth	~/.codex/auth/	✅ API 키 유지
DB	~/.codex/db/	✅ 히스토리 유지
글로벌 스킬	~/.agents/skills/study-guard/	✅ 유지
서비스 전용 스킬	/opt/service/app-data/.agents/skills/access-db/	✅ 추가 발견
SSH/GPG 등	~/.ssh/, ~/.gnupg/	✅ 영향 없음

기존 모든 것을 유지하면서, 서비스 전용 스킬만 추가된다. cwd는 PROJECT-level 경로만 변경하므로 USER-level 상태(config, auth, DB, 글로벌 스킬)에 전혀 영향을 주지 않는다.

한 눈에 비교

HOME 변경:        ████████████████████████████  모든 것이 바뀜 (OS + codex 전체)
CODEX_HOME 변경:  ░░░░░░░░████████████████████  codex 전체 상태가 바뀜 (config + auth + DB + skills)
cwd 변경:         ░░░░░░░░░░░░░░░░░░░░░░░░████  PROJECT-level 스킬 경로만 바뀜
                  ├── OS ──┤├── codex 상태 ──┤├─ 스킬 ─┤

참고 문서

• Codex Skills Documentation
• Codex App Server Protocol
• GitHub Issue #14941 - skill-creator wrong path
• GitHub Issue #15149 - configurable skill directories
• GitHub Issue #9752 - project-level skills trust