OpenAI 공식 문서 — Codex Skills 확장성

9. Skills와 앱 내 확장 흐름

Codex app는 CLI와 IDE Extension과 동일한 agent skills를 지원하며, 사이드바에서 팀이 만든 skills를 탐색하고 사용할 수 있습니다. 이 페이지에서는 Skills가 무엇인지, 왜 필요한지, 어떻게 만들고 사용하는지를 처음부터 차근차근 설명합니다.

이 페이지에서 배우는 것

• 1 Skills가 무엇인지 쉬운 비유로 이해하기
• 2 왜 Skills를 만들어야 하는지 (Skills 없이 겪는 문제점)
• 3 $ 기호로 Skill을 호출하는 방법
• 4 Skill을 처음부터 끝까지 만드는 5단계 가이드
• 5 바로 복사해서 쓸 수 있는 실전 Skill 예시 5가지
• 6 CLI, IDE Extension, App 세 환경에서 Skills가 어떻게 공유되는지
• 7 초보자가 자주 묻는 FAQ 5가지

Skills가 뭔가요?

가장 쉽게 설명하면, Skills는 레시피북입니다.

요리를 할 때를 떠올려 보세요. 달걀프라이를 만들 때마다 "프라이팬을 달구고, 기름을 두르고, 달걀을 깨서 넣고..."라고 매번 설명하면 번거롭겠죠? 대신 "달걀프라이"라는 레시피를 한 번 적어두면, 다음부터는 레시피 이름만 말하면 됩니다. 누가 만들든 같은 순서, 같은 방법으로 만들 수 있습니다.

Codex Skills도 같은 원리입니다. 반복되는 작업을 하나의 템플릿(레시피)으로 만들어 저장해 두면, 이름만 부르면 Codex가 그대로 실행해 줍니다. 팀원 누구나 동일한 품질의 결과를 얻을 수 있습니다.

왜 Skills를 만들어야 하나요?

Skills 없이 Codex를 사용하면 이런 문제가 생깁니다.

$ 호출이란?

Codex에서 Skill을 실행하는 방법은 매우 간단합니다. Composer(메시지 입력창)에서 달러 기호($)를 입력하면 등록된 Skill 목록이 나타납니다.

예를 들어 "code-review"라는 Skill을 등록해 두었다면 이렇게 사용합니다.

Skill 만들기: 처음부터 끝까지

Skill을 만드는 과정을 5단계로 나누어 설명합니다. 코딩 경험이 없어도 따라할 수 있습니다.

실전 Skill 예시 5가지

아래 예시들을 복사해서 바로 Skill로 등록할 수 있습니다. 팀 상황에 맞게 수정해서 사용하세요.

CLI / IDE / App에서 Skills가 공유되는 구조

Codex Skills의 큰 장점 중 하나는 어디서 만들든 어디서든 사용할 수 있다는 것입니다. 한 번 만든 Skill은 세 가지 환경 모두에서 동일하게 동작합니다.

Skill 주요 활용 분야

핵심 포인트

• 1 CLI와 IDE Extension과 동일한 skills 체계를 Codex App에서도 그대로 사용할 수 있습니다.
• 2 Composer에서 $ 입력으로 skill을 직접 호출할 수 있습니다.
• 3 활성화된 skill은 slash command 목록에도 나타나 빠르게 접근할 수 있습니다.
• 4 Automations와 skills를 결합하면 반복 작업의 품질과 일관성을 크게 향상시킬 수 있습니다.

Automations + Skills 결합 사례

Automations는 "언제 실행할지"를 정하고, Skills는 "무엇을 실행할지"를 정합니다. 이 둘을 결합하면 특정 시점에 정해진 Skill이 자동으로 실행됩니다.

Skill 추상화 우선순위

어떤 작업부터 Skill로 만들어야 할지 고민된다면, 아래 우선순위를 참고하세요. 팀 규칙이 강하고 반복 빈도가 높을수록 Skill로 만들었을 때 효과가 큽니다.

실전 팁

자주 묻는 질문 (FAQ)

다음 단계

Skills의 기본 개념을 이해했다면, 다음 단계로 넘어가 보세요.

• 위의 실전 예시 중 하나를 골라 직접 Skill로 등록해 보세요. 가장 자주 하는 작업부터 시작하는 것이 좋습니다.
• Automations 페이지를 읽고, 만든 Skill을 자동 트리거와 연결해 보세요.
• 팀원에게 Skill을 공유하고, 피드백을 받아 프롬프트를 개선하세요. 2~3번 반복하면 훨씬 좋은 결과를 얻습니다.
• 단축키, Slash Command 페이지를 참고해서 Skill 호출을 더 빠르게 하는 방법을 익혀보세요.

SKILL.md 파일 구조

Skill은 SKILL.md를 진입점으로 하는 디렉터리입니다. Codex는 frontmatter의 name·description으로 호출 여부를 판단합니다.

my-skill/
├─ SKILL.md              # 진입점 (필수, frontmatter 포함)
├─ scripts/              # 스킬에서 실행할 스크립트
├─ references/           # 참고 자료 / 데이터 파일
├─ assets/               # 이미지·바이너리 등 정적 자산
└─ agents/
   └─ openai.yaml        # display_name, icon, brand_color, allow_implicit_invocation

agents/openai.yaml의 policy.allow_implicit_invocation 기본값은 true이지만, implicit 호출은 단순 toggle이 아니라 frontmatter의 name·description 품질로 매칭됩니다 — description이 명확할수록 모델이 자동으로 해당 skill을 끌어옵니다. 자동 호출을 끄고 `/skills·$` 명시 호출만 받으려면 false로 둡니다.

디스커버리 경로 (우선순위)

공식 Skills 문서는 4단계 카테고리로 정리합니다 — REPO → USER → ADMIN → SYSTEM. 동일 이름의 skill은 병합되지 않으며, selector에 모두 표시될 수 있습니다(공식 문서 명시).

1. REPO — $CWD/.agents/skills, 상위 디렉터리 추적, $REPO_ROOT/.agents/skills
2. USER — $HOME/.agents/skills
3. ADMIN — /etc/codex/skills
4. SYSTEM — Codex 앱/CLI에 번들된 빌트인 skill

참고: .codex/skills는 공식 디스커버리 경로에 포함되지 않습니다. 팀 내부 컨벤션이 아닌 한 .agents/skills를 사용하세요.

Plugins — 여러 Skill을 묶어 배포하는 방식

로컬 저장소를 넘어 skill을 공유하려면 plugin으로 패키징하는 것이 공식 권장 방식입니다 — "skills should be packaged as plugins, which can bundle multiple skills with app mappings and MCP server configuration." 즉 plugin 하나가 묶을 수 있는 것:

• ✓여러 개의 skill — 한 도메인을 위한 단위 작업들을 함께 배포
• ✓App mappings — Codex 앱·CLI·IDE에서 어떻게 노출될지 정의
• ✓MCP server 설정 — 함께 등록할 MCP 서버 묶음 (`[mcp_servers.NAME]` 블록)

플러그인 마켓플레이스 (이미 사용 가능). OpenAI 공식 카탈로그 외에도 자체 마켓플레이스를 등록할 수 있습니다:

지원 소스 4종 — GitHub shorthand(owner/repo[@ref]) · HTTP/HTTPS Git URL · SSH Git URL · 로컬 디렉터리 경로. 빌트인 $skill-installer는 OpenAI 큐레이션 카탈로그를 사용합니다.

빌트인 Skill 관리 도구

• ✓$skill-creator — 새 skill을 안내형 UI로 작성. SKILL.md, agents/openai.yaml 템플릿을 자동 생성합니다.
• ✓$skill-installer <skill-name> — OpenAI 큐레이션 카탈로그에서 검증된 skill을 다운로드. (꺾쇠 < >는 placeholder 표기)
• ✓~/.codex/config.toml — [[skills.config]] 블록의 enabled = false로 특정 skill을 끄거나 별칭/환경변수를 덮어쓸 수 있습니다.

장점 / 단점 / 한계점