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을 끄거나 별칭/환경변수를 덮어쓸 수 있습니다.

장점 / 단점 / 한계점