Codex Skills

• Codex의 기능을 확장하는 태스크 특화 워크플로우 패키지
• SKILL.md 파일에 지시사항을 작성하면, Codex가 자동으로 도구로 인식
• 상황에 맞게 **Codex가 자동 호출(implicit)**하거나, 사용자가 $skill-name으로 직접 호출(explicit)
• Agent Skills 오픈 스탠다드(agentskills.io)를 따르며, Codex CLI / IDE Extension / Codex App 모두 지원

해당 개념이 필요한 이유

• 반복 워크플로우 제거: PR 리뷰, 로그 분류, 릴리즈 노트 등 반복 작업을 한 번 정의하고 재사용
• 팀 표준 공유: 프로젝트 스킬 디렉토리에 커밋하면 팀 전체가 동일한 워크플로우 사용
• Custom Prompt 대체: Codex에서 Custom Prompt는 deprecated — 재사용 가능한 워크플로우는 모두 Skill로 전환 권장
• Progressive Disclosure: 메타데이터만 먼저 로드하고, 실제 사용 시에만 전체 SKILL.md를 읽어 컨텍스트 효율 극대화

AS-IS

# 매번 수동으로 동일한 지시를 반복 입력
User: "이 PR 리뷰해줘. 정확성, 보안, 누락된 테스트 확인하고
       결과는 체크리스트 형태로..."

# 다음 번에도 동일한 내용을 또 입력
User: "이 PR 리뷰해줘. 정확성, 보안..."

TO-BE

# ~/.codex/skills/review-pr/SKILL.md (한 번만 정의)
---
name: review-pr
description: PR을 정확성, 보안, 테스트 관점에서 리뷰
---
PR을 다음 관점에서 리뷰하라:
1. 정확성 및 회귀 가능성
2. 보안 취약점
3. 누락된 테스트
결과는 체크리스트 형태로 출력.

# 이후에는 $ 멘션이면 끝
$review-pr

스킬 파일 구조

모든 스킬은 디렉토리 단위로 구성되며, SKILL.md가 진입점(entrypoint)이다:

my-skill/
├── SKILL.md              # 메인 지시사항 (필수)
├── agents/
│   └── openai.yaml       # UI 메타데이터, 호출 정책, 도구 의존성
├── scripts/              # 결정적 동작이 필요한 실행 스크립트
├── references/           # 참조 문서
└── assets/               # 템플릿, 아이콘 등 리소스

SKILL.md 작성법

SKILL.md는 두 부분으로 구성된다:

1. YAML Frontmatter (--- 사이): 스킬의 메타데이터 (name, description 필수)
2. Markdown Content: Codex가 따를 지시사항

---
name: fix-issue
description: GitHub 이슈를 수정한다
---
 
GitHub 이슈를 수정하라:
1. 이슈 설명 읽기
2. 요구사항 파악
3. 수정 구현
4. 테스트 작성
5. 커밋 생성

agents/openai.yaml

선택적 설정 파일로, UI 표시와 호출 정책을 제어한다:

interface:
  display_name: "User-facing name"
  short_description: "Brief description"
  icon_small: "./assets/small-logo.svg"
  icon_large: "./assets/large-logo.png"
  brand_color: "#3B82F6"
  default_prompt: "Optional surrounding prompt"
 
policy:
  allow_implicit_invocation: false  # true(기본): 자동 호출 허용
 
dependencies:
  tools:
    - type: "mcp"
      value: "openaiDeveloperDocs"
      description: "Tool description"
      transport: "streamable_http"
      url: "https://example.com"

필드	설명
interface	Codex App에서의 UI 표시 (아이콘, 색상, 이름)
policy.allow_implicit_invocation	false 시 Codex 자동 호출 차단, $skill-name 명시 호출만 가능
dependencies.tools	스킬이 의존하는 MCP Server 등 외부 도구 선언

스킬 저장 위치와 적용 범위

스킬 경로의 기준은 $CODEX_HOME 환경변수이며, 미설정 시 ~/.codex가 기본값이다.

위치	경로	적용 범위
Personal	$CODEX_HOME/skills/<name>/ (기본: ~/.codex/skills/)	내 모든 프로젝트
System	$CODEX_HOME/skills/.system/	빌트인 (skill-creator, skill-installer)

공식 소스 간 경로 불일치

공식 웹 문서(developers.openai.com/codex/skills, best-practices)는 .agents/skills/ 경로를 안내하지만, 공식 GitHub 소스(openai/codex)의 skill-installer와 install-skill-from-github.py는 $CODEX_HOME/skills/를 사용한다.

• GitHub: skill-installer SKILL.md — “Installs into $CODEX_HOME/skills/<skill-name> (defaults to ~/.codex/skills)”
• GitHub: install-skill-from-github.py — _codex_home() → os.environ.get("CODEX_HOME", "~/.codex")
• Changelog: 0.116.0 (2026-03-19) — “skill-creator: default new skills to ~/.codex/skills” (PR #14837)
• PR #14837: --path "${CODEX_HOME:-$HOME/.codex}/skills" 패턴으로 변경

본 문서는 GitHub 소스 + Changelog 기준으로 작성하였다. 웹 문서의 .agents/skills/는 0.116.0 이전 패턴이거나 문서 업데이트 지연으로 판단된다.

동명 스킬 충돌 처리

Codex에서 같은 이름의 스킬이 여러 위치에 존재하면, 병합이나 덮어쓰기 없이 모든 버전이 선택기에 함께 표시된다:

# Personal 스킬
~/.codex/skills/review-pr/SKILL.md
---
name: review-pr
description: 보안 중심으로 PR 리뷰
---

# 프로젝트 스킬 (같은 이름)
<project>/skills/review-pr/SKILL.md
---
name: review-pr
description: 팀 컨벤션 중심으로 PR 리뷰
---

사용자가 $ 또는 /skills로 스킬 목록을 열면:

> review-pr (~/.codex/skills)    — 보안 중심으로 PR 리뷰
> review-pr (<project>/skills)   — 팀 컨벤션 중심으로 PR 리뷰

사용자가 직접 원하는 버전을 선택해야 한다.

Claude Code와의 차이

	Codex	Claude Code
전략	모든 버전 공존 (사용자 선택)	우선순위로 하나만 적용
동명 충돌	선택기에 둘 다 표시	Enterprise > Personal > Project 순으로 상위가 하위를 덮어씀
장점	상황에 따라 다른 버전 사용 가능	설정 없이 일관된 동작 보장
단점	사용자가 매번 구분해야 함	하위 레벨 스킬이 의도치 않게 가려질 수 있음

호출 방식

방식	설명	예시
Explicit (명시적)	사용자가 직접 $ 멘션 또는 /skills 메뉴에서 선택	$review-pr, /skills
Implicit (자동)	Codex가 프롬프트와 description을 매칭하여 자동 선택	프롬프트: “이 PR 리뷰해줘” → review-pr 자동 호출

Progressive Disclosure 동작:

sequenceDiagram
    autonumber
    actor User
    participant Codex
    participant Skill as SKILL.md

    Note over Codex: 세션 시작 시<br/>모든 스킬의 name + description만 로드
    User->>Codex: "이 PR 리뷰해줘"
    Codex->>Codex: description 매칭<br/>"review-pr" 선택
    Codex->>Skill: SKILL.md 전체 로드
    Skill-->>Codex: 지시사항 반환
    Codex->>Codex: 지시사항에 따라 실행
    Codex-->>User: 결과 응답

스킬 설치와 관리

설치

스킬은 $CODEX_HOME/skills/<skill-name>에 설치된다 (기본: ~/.codex/skills/).

# 큐레이션된 스킬 (이름으로 설치)
$skill-installer linear
# → ~/.codex/skills/linear/ 에 설치
 
# 실험적 스킬 (GitHub URL로 설치)
$skill-installer install https://github.com/openai/skills/tree/main/skills/.experimental/create-plan
 
# 커스텀 경로 지정
$skill-installer install <url> --dest /custom/path

설치 후 Codex 재시작 필요.

비활성화

~/.codex/config.toml에서 개별 스킬 비활성화:

[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

스킬 카탈로그 (github.com/openai/skills)

카테고리	설명
.system	Codex 최신 버전에 자동 설치
.curated	커뮤니티 검증, 수동 설치 필요
.experimental	실험적, 테스트용

스킬 설계 원칙 (Best Practices)

원칙	설명
Single Responsibility	스킬 하나 = 하나의 작업
Instructions over Scripts	결정적 동작이 필요한 경우가 아니면 지시사항 우선
명확한 I/O	입력과 출력을 명시적으로 정의
트리거 문구 포함	description에 사용자가 자연스럽게 쓸 키워드 포함
2-3개 유스케이스부터	작동하는 것부터 시작, 엣지 케이스는 나중에

“같은 프롬프트를 반복하거나, 같은 워크플로우를 매번 교정하고 있다면, 그건 스킬이 되어야 한다.”

스킬 후보 작업 유형

• 로그 분류 및 분석
• 릴리즈 노트 작성
• PR 체크리스트 리뷰
• 마이그레이션 계획
• 텔레메트리/인시던트 요약
• 표준화된 디버깅 워크플로우

Claude Code Skills와 비교

항목	Codex Skills	Claude Code Skills
진입점	SKILL.md	SKILL.md
호출 문법	$skill-name	/skill-name
저장 위치	$CODEX_HOME/skills/ (기본: ~/.codex/skills/)	.claude/skills/
개인 스킬	~/.codex/skills/	~/.claude/skills/
UI 설정	agents/openai.yaml (별도 파일)	YAML frontmatter 내
자동 호출 차단	allow_implicit_invocation: false (yaml)	disable-model-invocation: true (frontmatter)
사용자 호출 차단	해당 옵션 없음	user-invocable: false
도구 의존성	dependencies.tools (yaml)	allowed-tools (frontmatter)
Subagent 위임	별도 Agent 정의 (.codex/agents/)	context: fork + agent (frontmatter)
설정 파일	AGENTS.md	CLAUDE.md
동명 스킬	모든 버전 공존 (사용자 선택)	우선순위로 상위가 하위 덮어씀
Custom Prompt	deprecated → Skill 전환 권장	해당 없음

Automation과의 관계

Codex App에서 Automation은 스킬을 스케줄 기반으로 실행하는 기능이다:

flowchart LR
    A["Skill<br/>(방법 정의)"] --> B["Automation<br/>(스케줄 정의)"]
    B --> C["백그라운드 실행<br/>→ 리뷰 큐"]

“Skills define the method, automations define the schedule.”

수동 실행이 예측 가능해진 후에만 Automation으로 전환한다.

활용 예시: 일일 이슈 분류, CI 실패 요약, 릴리즈 브리핑, 버그 스캔

트러블슈팅

문제	해결 방법
스킬이 트리거되지 않음	description에 사용자가 자연스럽게 말할 키워드 포함. $skill-name으로 직접 호출 시도
스킬이 너무 자주 트리거됨	description을 더 구체적으로 수정. allow_implicit_invocation: false 설정
설치 후 인식 안 됨	Codex 재시작 필요
스킬 비활성화	~/.codex/config.toml에서 enabled = false

참고 문서

• Codex Skills 공식 문서
• Skills GitHub 카탈로그
• Codex Best Practices
• Codex Subagents - 작업을 위임하는 하위 에이전트
• AGENTS.md 가이드 - 영구 컨텍스트 관리