Ch6. 프롬프트/스킬 설계

Codex는 명확한 목표·제약·검증 기준이 있을수록 안정적으로 동작합니다. 시니어 개발자는 프롬프트를 "작업 명세" 수준으로 작성하고, 반복 패턴은 Skills로 체계화하는 것이 핵심입니다.

프롬프트 = 작업 명세(시니어용 포맷)

아래 6가지만 고정해도 결과 품질이 안정됩니다.

목표: 무엇을 만들거나 고칠지(정확한 산출물)
범위: 수정 가능한 폴더/파일, 제외할 영역(Non-goals)
제약: 보안/성능/호환성/코딩 컨벤션, "절대 하지 말 것"
검증: 통과해야 하는 테스트/체크, 재현/검증 명령
리스크: 변경 위험이 큰 지점(마이그레이션, 스키마 변경, 배포 영향)
출력 포맷: 최종 응답 형식(예: 체크리스트, diff 요약, JSON 스키마 등)

[목표]
- ...

[범위]
- 수정 가능: ...
- 제외: ...

[제약]
- ...

[검증]
- ...

[리스크]
- ...

[출력]
- ...

컨텍스트를 "정확히" 주는 법

@로 파일을 찍어서 준다: 작성기에서 @ 입력 시 퍼지 파일 검색이 동작합니다. Tab/Enter로 삽입
/mention으로 파일/폴더 첨부: 레포 전체 대신 지금 볼 파일/폴더를 지정해 작업 시간 절감
Ctrl+G로 외부 에디터: 긴 프롬프트는 외부 에디터에서 작성(VISUAL/EDITOR 환경변수 설정)
긴 세션은 /compact로 정리: 긴 실행 뒤에는 요약을 남겨 컨텍스트 윈도우를 절약
작업 루틴 고정: /diff → /review → 테스트 → 요약을 팀 기본으로

음성 입력 (실험적, 0.105.0+)

스페이스바를 길게 누르면 음성 받아쓰기가 시작됩니다. 손이 바쁠 때 빠른 지시에 유용합니다.

지속 규칙: AGENTS.md(레포에 남는 계약)

Codex는 작업 전에 AGENTS.md 파일을 자동으로 읽습니다.

탐색 순서:

~/.codex/AGENTS.override.md (또는 AGENTS.md) — 사용자 전역 설정
프로젝트 루트에서 현재 디렉토리까지 순회하며 각 경로의 AGENTS.override.md → AGENTS.md

AGENTS.md는 현재 60,000+ 오픈소스 프로젝트에 채택되어 있으며, Linux Foundation 산하 Agentic AI Foundation이 표준을 관리합니다.

팀에서는 아래를 표준화하면 효과가 큽니다.

레포 루트에 1개: 공용 규칙(금지/허용, 커밋 규칙, 테스트 규칙)
서브디렉토리별로 추가: 모노레포/서비스별 특이사항(폴더 규칙, 소유권, 도메인 용어)
리뷰 가능한 형태로: 규칙은 코드와 같이 리뷰/변경 관리("문서가 곧 정책")
피드백 루프: 반복되는 실수 → AGENTS.md에 규칙 추가, 불필요한 문서 탐색 → 라우팅 가이드 추가

Skills 체계 (정식)

Skills는 SKILL.md + 선택적 scripts/references/assets로 구성된 재사용 가능한 워크플로우 번들입니다.

디렉토리 구조

my-skill/
├── SKILL.md           (필수: name, description 포함)
├── scripts/           (선택: 실행 스크립트)
├── references/        (선택: 참조 문서)
├── assets/            (선택: 템플릿, 리소스)
└── agents/
    └── openai.yaml    (선택: UI 메타데이터, 의존성)

SKILL.md 최소 구조

---
name: release-notes
description: PR 기반 릴리즈 노트 자동 생성. PR이 머지된 후 트리거.
---
1. 최근 머지된 PR 목록을 수집
2. 각 PR의 변경사항을 요약
3. 카테고리별로 정리된 릴리즈 노트 생성

스킬 위치(탐색 순서)

위치	경로	용도
CWD	`.agents/skills`	폴더별 스킬
부모	`../.agents/skills`	중첩 레포 워크플로우
레포 루트	`$REPO_ROOT/.agents/skills`	조직 공용 레포 스킬
사용자	`$HOME/.agents/skills`	개인 크로스 레포 스킬
관리자	`/etc/codex/skills`	시스템 기본값/자동화
내장	번들	skill-creator, plan 등

Progressive Disclosure

Codex는 스킬의 메타데이터(name, description)만 먼저 로드하고, 실제 사용 시에만 전체 SKILL.md를 읽습니다. 이를 통해 많은 스킬이 등록되어 있어도 컨텍스트 윈도우를 절약합니다.

스킬 호출

명시적: 추천 목록이나 문맥 힌트로 스킬을 확인한 뒤 $skill-name으로 직접 호출
암묵적: 사용자 프롬프트가 스킬의 description에 매칭되면 Codex가 자동 선택
설치: $skill-installer로 외부 레포에서 스킬 설치

config에서 스킬 비활성화

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

agents/openai.yaml (선택)

interface:
  display_name: '릴리즈 노트'
  short_description: 'PR 기반 릴리즈 노트 생성'
  brand_color: '#3B82F6'

policy:
  allow_implicit_invocation: false # 명시적 호출만 허용

dependencies:
  tools:
    - type: 'mcp'
      value: 'github'
      description: 'GitHub MCP 서버'

Plugins와 `@plugin` 멘션 (0.110.0~0.117.0)

최근 릴리스에서는 Skills/MCP/apps를 플러그인 단위로 묶어 배포하는 흐름이 강화됐습니다.

Plugin catalog: 로컬 marketplace 또는 config 기반으로 skills/MCP/app connector를 로드
세션 시작 시 플러그인 인벤토리 주입: Codex가 어떤 플러그인이 활성화되어 있는지 먼저 알고 시작
@plugin 멘션: 채팅에서 특정 플러그인을 직접 언급하면, 관련된 MCP/app/skill 컨텍스트를 의도적으로 붙일 수 있음
제품 범위 플러그인 sync (0.117.0): 시작 시 product-scoped plugin을 동기화하고 설치 상태를 더 일관되게 유지
/plugins 브라우저 (0.117.0): 플러그인을 전용 메뉴에서 탐색·설치·제거하는 흐름이 추가됨

실전 팁:

플러그인 이름은 짧고 모호하지 않게 유지합니다
"한 플러그인 = 한 업무 컨텍스트" 원칙을 지키면 @plugin 멘션 품질이 좋아집니다
위험한 외부 시스템 플러그인은 기본 비활성화하고, 승인 가능한 팀만 enable 하세요

[예시]
- "@release-notes 플러그인 기준으로 이번 변경을 요약해줘"
- "@figma-mcp 컨텍스트를 포함해서 이 화면 수정 포인트를 정리해줘"
- "@jira-triage 플러그인으로 이 이슈를 분류하고 다음 액션을 제안해줘"

플러그인 Marketplace와 라이프사이클 관리 (0.113.0)

0.113.0부터 플러그인 워크플로우가 대폭 확장되었습니다. Marketplace 검색, 메타데이터 강화, 설치 시 인증 검사, 삭제 엔드포인트가 추가되어 플러그인의 전체 라이프사이클을 관리할 수 있습니다.

Marketplace 검색

플러그인을 로컬 config에서만 관리하던 방식에서 벗어나, 중앙 marketplace에서 검색·설치할 수 있습니다.

# marketplace에서 플러그인 검색
codex plugin search "release-notes"

# 검색 결과에서 바로 설치
codex plugin install @org/release-notes-plugin

강화된 메타데이터 (`plugin/list`)

plugin/list 응답에 버전, 의존성, 권한 요구사항, 호환 모델 등 풍부한 메타데이터가 포함됩니다. 팀에서 플러그인 호환성을 사전 검증하거나, CI에서 플러그인 인벤토리를 자동 감사할 때 유용합니다.

설치 시 인증 검사

외부 API를 사용하는 플러그인은 설치 시점에 필요한 인증 정보(API 키, OAuth 토큰 등)가 있는지 자동으로 검사합니다. 인증이 누락되면 설치가 차단되며, 필요한 설정 안내가 표시됩니다.

보안 강화

설치 시 인증 검사 덕분에 "플러그인은 설치됐지만 런타임에 권한 오류"가 나는 문제를 사전에 방지할 수 있습니다.

플러그인 삭제 (`plugin/uninstall`)

더 이상 사용하지 않는 플러그인을 깔끔하게 제거할 수 있습니다.

# 플러그인 삭제
codex plugin uninstall @org/release-notes-plugin

플러그인 설치 프롬프트 (0.116.0)

0.116.0부터 Codex가 누락된 플러그인의 설치를 자동으로 제안합니다. 프롬프트나 스킬이 특정 플러그인을 필요로 하지만 아직 설치되지 않은 경우, Codex가 설치 여부를 묻는 프롬프트를 표시합니다.

Suggestion allowlist: config에서 설치 제안이 허용되는 플러그인 목록을 지정할 수 있어, 승인되지 않은 플러그인이 무분별하게 제안되는 것을 방지합니다
원격 동기화: 플러그인 설치/제거 상태가 원격으로 동기화되어, 여러 머신에서 동일한 플러그인 환경을 유지할 수 있습니다
팀 운영 시에는 allowlist를 조직 표준으로 관리하고, 원격 동기화를 통해 개발자 간 환경 편차를 줄이는 것을 권장합니다

0.117.0 이후 운영 포인트

플러그인이 1급 워크플로우가 되면서 "문서에서만 설명하는 선택 기능"이 아니라, 실제 세션 시작과 slash command UX에 직접 연결되는 운영 단위가 됐습니다. 팀 표준 스킬·MCP·앱을 배포한다면 plugin 단위로 묶고 /plugins 경로를 온보딩 문서에 포함하는 편이 좋습니다.

내장 시스템 스킬 비활성화 (0.114.0)

0.114.0부터 config에서 번들된 시스템 스킬을 일괄 비활성화하는 스위치가 추가되었습니다. 조직 자체 스킬만 사용하거나, 시스템 스킬과의 충돌을 방지하고 싶을 때 유용합니다.

[skills]
disable_bundled = true   # 내장 스킬(skill-creator, plan 등) 비활성화

주의

내장 스킬을 비활성화하면 $skill-creator, $plan 등 기본 제공 스킬을 사용할 수 없습니다. 대체 스킬이 준비된 상태에서만 활성화하세요.

참고 문서

Prompting 가이드: https://developers.openai.com/codex/prompting (영어)
Skills: https://developers.openai.com/codex/skills (영어)
AGENTS.md 가이드: https://developers.openai.com/codex/guides/agents-md (영어)
Customization: https://developers.openai.com/codex/concepts/customization (영어)
슬래시 커맨드: https://developers.openai.com/codex/cli/slash-commands (영어)
Team Config(스킬/규칙 공유): https://developers.openai.com/codex/team-config (영어)
Rules: https://developers.openai.com/codex/rules (영어)
GitHub Releases: https://github.com/openai/codex/releases (영어)

프롬프트 = 작업 명세(시니어용 포맷)

아래 6가지만 고정해도 결과 품질이 안정됩니다.

목표: 무엇을 만들거나 고칠지(정확한 산출물)
범위: 수정 가능한 폴더/파일, 제외할 영역(Non-goals)
제약: 보안/성능/호환성/코딩 컨벤션, "절대 하지 말 것"
검증: 통과해야 하는 테스트/체크, 재현/검증 명령
리스크: 변경 위험이 큰 지점(마이그레이션, 스키마 변경, 배포 영향)
출력 포맷: 최종 응답 형식(예: 체크리스트, diff 요약, JSON 스키마 등)

[목표]
- ...

[범위]
- 수정 가능: ...
- 제외: ...

[제약]
- ...

[검증]
- ...

[리스크]
- ...

[출력]
- ...

컨텍스트를 "정확히" 주는 법

@로 파일을 찍어서 준다: 작성기에서 @ 입력 시 퍼지 파일 검색이 동작합니다. Tab/Enter로 삽입
/mention으로 파일/폴더 첨부: 레포 전체 대신 지금 볼 파일/폴더를 지정해 작업 시간 절감
Ctrl+G로 외부 에디터: 긴 프롬프트는 외부 에디터에서 작성(VISUAL/EDITOR 환경변수 설정)
긴 세션은 /compact로 정리: 긴 실행 뒤에는 요약을 남겨 컨텍스트 윈도우를 절약
작업 루틴 고정: /diff → /review → 테스트 → 요약을 팀 기본으로

음성 입력 (실험적, 0.105.0+)

스페이스바를 길게 누르면 음성 받아쓰기가 시작됩니다. 손이 바쁠 때 빠른 지시에 유용합니다.

지속 규칙: AGENTS.md(레포에 남는 계약)

Codex는 작업 전에 AGENTS.md 파일을 자동으로 읽습니다.

탐색 순서:

~/.codex/AGENTS.override.md (또는 AGENTS.md) — 사용자 전역 설정
프로젝트 루트에서 현재 디렉토리까지 순회하며 각 경로의 AGENTS.override.md → AGENTS.md

AGENTS.md는 현재 60,000+ 오픈소스 프로젝트에 채택되어 있으며, Linux Foundation 산하 Agentic AI Foundation이 표준을 관리합니다.

팀에서는 아래를 표준화하면 효과가 큽니다.

레포 루트에 1개: 공용 규칙(금지/허용, 커밋 규칙, 테스트 규칙)
서브디렉토리별로 추가: 모노레포/서비스별 특이사항(폴더 규칙, 소유권, 도메인 용어)
리뷰 가능한 형태로: 규칙은 코드와 같이 리뷰/변경 관리("문서가 곧 정책")
피드백 루프: 반복되는 실수 → AGENTS.md에 규칙 추가, 불필요한 문서 탐색 → 라우팅 가이드 추가

Skills 체계 (정식)

Skills는 SKILL.md + 선택적 scripts/references/assets로 구성된 재사용 가능한 워크플로우 번들입니다.

디렉토리 구조

my-skill/
├── SKILL.md           (필수: name, description 포함)
├── scripts/           (선택: 실행 스크립트)
├── references/        (선택: 참조 문서)
├── assets/            (선택: 템플릿, 리소스)
└── agents/
    └── openai.yaml    (선택: UI 메타데이터, 의존성)

SKILL.md 최소 구조

---
name: release-notes
description: PR 기반 릴리즈 노트 자동 생성. PR이 머지된 후 트리거.
---
1. 최근 머지된 PR 목록을 수집
2. 각 PR의 변경사항을 요약
3. 카테고리별로 정리된 릴리즈 노트 생성

스킬 위치(탐색 순서)

위치	경로	용도
CWD	`.agents/skills`	폴더별 스킬
부모	`../.agents/skills`	중첩 레포 워크플로우
레포 루트	`$REPO_ROOT/.agents/skills`	조직 공용 레포 스킬
사용자	`$HOME/.agents/skills`	개인 크로스 레포 스킬
관리자	`/etc/codex/skills`	시스템 기본값/자동화
내장	번들	skill-creator, plan 등

Progressive Disclosure

스킬 호출

명시적: 추천 목록이나 문맥 힌트로 스킬을 확인한 뒤 $skill-name으로 직접 호출
암묵적: 사용자 프롬프트가 스킬의 description에 매칭되면 Codex가 자동 선택
설치: $skill-installer로 외부 레포에서 스킬 설치

config에서 스킬 비활성화

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

agents/openai.yaml (선택)

interface:
  display_name: '릴리즈 노트'
  short_description: 'PR 기반 릴리즈 노트 생성'
  brand_color: '#3B82F6'

policy:
  allow_implicit_invocation: false # 명시적 호출만 허용

dependencies:
  tools:
    - type: 'mcp'
      value: 'github'
      description: 'GitHub MCP 서버'

Plugins와 `@plugin` 멘션 (0.110.0~0.117.0)

최근 릴리스에서는 Skills/MCP/apps를 플러그인 단위로 묶어 배포하는 흐름이 강화됐습니다.

Plugin catalog: 로컬 marketplace 또는 config 기반으로 skills/MCP/app connector를 로드
세션 시작 시 플러그인 인벤토리 주입: Codex가 어떤 플러그인이 활성화되어 있는지 먼저 알고 시작
@plugin 멘션: 채팅에서 특정 플러그인을 직접 언급하면, 관련된 MCP/app/skill 컨텍스트를 의도적으로 붙일 수 있음
제품 범위 플러그인 sync (0.117.0): 시작 시 product-scoped plugin을 동기화하고 설치 상태를 더 일관되게 유지
/plugins 브라우저 (0.117.0): 플러그인을 전용 메뉴에서 탐색·설치·제거하는 흐름이 추가됨

실전 팁:

플러그인 이름은 짧고 모호하지 않게 유지합니다
"한 플러그인 = 한 업무 컨텍스트" 원칙을 지키면 @plugin 멘션 품질이 좋아집니다
위험한 외부 시스템 플러그인은 기본 비활성화하고, 승인 가능한 팀만 enable 하세요

[예시]
- "@release-notes 플러그인 기준으로 이번 변경을 요약해줘"
- "@figma-mcp 컨텍스트를 포함해서 이 화면 수정 포인트를 정리해줘"
- "@jira-triage 플러그인으로 이 이슈를 분류하고 다음 액션을 제안해줘"

플러그인 Marketplace와 라이프사이클 관리 (0.113.0)

Marketplace 검색

플러그인을 로컬 config에서만 관리하던 방식에서 벗어나, 중앙 marketplace에서 검색·설치할 수 있습니다.

# marketplace에서 플러그인 검색
codex plugin search "release-notes"

# 검색 결과에서 바로 설치
codex plugin install @org/release-notes-plugin

# 플러그인 삭제
codex plugin uninstall @org/release-notes-plugin

플러그인 설치 프롬프트 (0.116.0)

Suggestion allowlist: config에서 설치 제안이 허용되는 플러그인 목록을 지정할 수 있어, 승인되지 않은 플러그인이 무분별하게 제안되는 것을 방지합니다
원격 동기화: 플러그인 설치/제거 상태가 원격으로 동기화되어, 여러 머신에서 동일한 플러그인 환경을 유지할 수 있습니다
팀 운영 시에는 allowlist를 조직 표준으로 관리하고, 원격 동기화를 통해 개발자 간 환경 편차를 줄이는 것을 권장합니다

0.117.0 이후 운영 포인트

내장 시스템 스킬 비활성화 (0.114.0)

[skills]
disable_bundled = true   # 내장 스킬(skill-creator, plan 등) 비활성화

주의

내장 스킬을 비활성화하면 $skill-creator, $plan 등 기본 제공 스킬을 사용할 수 없습니다. 대체 스킬이 준비된 상태에서만 활성화하세요.

참고 문서

Prompting 가이드: https://developers.openai.com/codex/prompting (영어)
Skills: https://developers.openai.com/codex/skills (영어)
AGENTS.md 가이드: https://developers.openai.com/codex/guides/agents-md (영어)
Customization: https://developers.openai.com/codex/concepts/customization (영어)
슬래시 커맨드: https://developers.openai.com/codex/cli/slash-commands (영어)
Team Config(스킬/규칙 공유): https://developers.openai.com/codex/team-config (영어)
Rules: https://developers.openai.com/codex/rules (영어)
GitHub Releases: https://github.com/openai/codex/releases (영어)

Ch6. 프롬프트/스킬 설계

목차

Ch6. 프롬프트/스킬 설계

목차