Skill Creator
이 스킬은 효과적인 스킬을 생성하기 위한 지침을 제공합니다.
스킬 소개
스킬은 특화된 지식, 워크플로우, 도구를 제공하여 Codex의 기능을 확장하는 모듈식의 독립적인 폴더입니다. 특정 도메인이나 작업에 대한 "온보딩 가이드"로 생각하면 됩니다. 이는 Codex를 범용 에이전트에서 어떤 모델도 완전히 보유할 수 없는 절차적 지식을 갖춘 특화 에이전트로 변환합니다.
스킬이 제공하는 것
- 특화된 워크플로우 - 특정 도메인을 위한 다단계 절차
- 도구 통합 - 특정 파일 형식 또는 API 작업을 위한 지침
- 도메인 전문성 - 회사별 지식, 스키마, 비즈니스 로직
- 번들 리소스 - 복잡하고 반복적인 작업을 위한 스크립트, 참조 자료, 에셋
핵심 원칙
간결함이 핵심
컨텍스트 창은 공공재입니다. 스킬은 Codex가 필요로 하는 모든 것(시스템 프롬프트, 대화 기록, 다른 스킬의 메타데이터, 실제 사용자 요청)과 컨텍스트 창을 공유합니다.
기본 가정: Codex는 이미 매우 똑똑합니다. Codex가 이미 가지고 있지 않은 컨텍스트만 추가하세요. 각 정보 조각에 대해 질문하세요: "Codex가 이 설명을 정말로 필요로 할까?" 그리고 "이 문단이 그 토큰 비용을 정당화할까?"
장황한 설명보다는 간결한 예제를 선호하세요.
적절한 자유도 설정
작업의 취약성과 변동성에 맞게 구체성 수준을 조정하세요:
높은 자유도(텍스트 기반 지침): 여러 접근 방식이 유효하고, 결정이 컨텍스트에 따라 달라지거나, 경험 법칙이 접근 방식을 안내할 때 사용합니다.
중간 자유도(의사 코드 또는 매개변수가 있는 스크립트): 선호되는 패턴이 존재하고, 약간의 변형이 허용되거나, 구성이 동작에 영향을 미칠 때 사용합니다.
낮은 자유도(특정 스크립트, 적은 매개변수): 작업이 취약하고 오류가 발생하기 쉬우며, 일관성이 중요하거나, 특정 순서를 따라야 할 때 사용합니다.
Codex가 길을 탐험하는 것으로 생각하세요: 절벽이 있는 좁은 다리에는 특정 가드레일(낮은 자유도)이 필요한 반면, 열린 들판은 많은 경로(높은 자유도)를 허용합니다.
검증 무결성 보호
반복 중에 하위 에이전트를 사용하여 스킬이 현실적인 작업에서 작동하는지 또는 의심되는 문제가 실제인지 검증할 수 있습니다. 이는 수정 후 스킬의 동작, 출력 또는 실패 모드에 대한 독립적인 검토를 원할 때 가장 유용합니다. 새 하위 에이전트를 시작할 수 있는 경우에만 이 작업을 수행하세요.
검증을 위해 하위 에이전트를 사용하는 경우 이를 평가 표면으로 취급하세요. 목표는 스킬이 일반화되는지 여부를 알아내는 것이지, 다른 에이전트가 유출된 컨텍스트로부터 답변을 재구성할 수 있는지 여부가 아닙니다.
예제 프롬프트, 출력, diff, 로그 또는 트레이스와 같은 원시 아티팩트를 선호하세요. 검증을 수행하는 데 필요한 최소 작업-로컬 컨텍스트를 제공하세요. 검증에 명시적으로 필요한 경우가 아니라면 의도된 답변, 의심되는 버그, 의도된 수정 또는 이전 결론을 전달하지 마세요.
스킬의 구성
모든 스킬은 필수 SKILL.md 파일과 선택적 번들 리소스로 구성됩니다:
skill-name/
├── SKILL.md (필수)
│ ├── YAML 프론트매터 메타데이터 (필수)
│ │ ├── name: (필수)
│ │ └── description: (필수)
│ └── 마크다운 지침 (필수)
├── agents/ (권장)
│ └── openai.yaml - 스킬 목록 및 칩용 UI 메타데이터
└── 번들 리소스 (선택)
├── scripts/ - 실행 가능한 코드 (Python/Bash 등)
├── references/ - 필요에 따라 컨텍스트에 로드하기 위한 문서
└── assets/ - 출력에 사용되는 파일 (템플릿, 아이콘, 글꼴 등)
SKILL.md (필수)
모든 SKILL.md는 다음으로 구성됩니다:
- 프론트매터(YAML):
name및description필드를 포함합니다. 이것들은 Codex가 스킬이 사용되는 시점을 결정하기 위해 읽는 유일한 필드이므로, 스킬이 무엇인지, 언제 사용되어야 하는지를 명확하고 포괄적으로 설명하는 것이 매우 중요합니다. - 본문(마크다운): 스킬 사용을 위한 지침 및 안내입니다. 스킬이 트리거된 후에만 로드됩니다(있는 경우).
에이전트 메타데이터 (권장)
- 스킬 목록 및 칩용 UI 관련 메타데이터
- 값을 생성하기 전에
references/openai_yaml.md를 읽고 해당 설명과 제약 조건을 따르세요 - 사용자 대상
display_name,short_description,default_prompt를 스킬을 읽어서 생성하세요 --interface key=value를scripts/generate_openai_yaml.py또는scripts/init_skill.py에 전달하여 결정론적으로 생성하세요- 업데이트 시:
agents/openai.yaml이 여전히 SKILL.md와 일치하는지 검증하고, 오래된 경우 재생성하세요 - 명시적으로 제공된 경우에만 다른 선택적 인터페이스 필드(아이콘, 브랜드 색상)를 포함하세요
- 필드 정의 및 예제는
references/openai_yaml.md를 참조하세요
번들 리소스 (선택)
스크립트 (scripts/)
결정론적 신뢰성이 필요하거나 반복적으로 재작성되는 작업을 위한 실행 가능한 코드(Python/Bash 등)입니다.
- 포함 시기: 동일한 코드가 반복적으로 재작성되거나 결정론적 신뢰성이 필요할 때
- 예시: PDF 회전 작업을 위한
scripts/rotate_pdf.py - 이점: 토큰 효율적, 결정론적, 컨텍스트에 로드하지 않고 실행 가능
- 참고: 패치 또는 환경별 조정을 위해 Codex가 스크립트를 계속 읽어야 할 수 있습니다.
참조 (references/)
Codex의 프로세스와 사고를 알리기 위해 필요에 따라 컨텍스트에 로드하기 위한 문서 및 참고 자료입니다.
- 포함 시기: Codex가 작업 중 참조해야 할 문서의 경우
- 예제: 재무 스키마용
references/finance.md, 회사 NDA 템플릿용references/mnda.md, 회사 정책용references/policies.md, API 사양용references/api_docs.md - 사용 사례: 데이터베이스 스키마, API 문서, 도메인 지식, 회사 정책, 상세 워크플로 가이드
- 이점: SKILL.md를 간결하게 유지하고, Codex가 필요하다고 판단할 때만 로드됨
- 모범 사례: 파일이 큰 경우(>10,000단어) SKILL.md에 grep 검색 패턴을 포함하세요
- 중복 방지: 정보는 SKILL.md 또는 참조 파일 중 하나에만 있어야 하며, 둘 다에 있으면 안 됩니다. 자세한 정보는 스킬의 진정한 핵심이 아닌 한 참조 파일을 선호하세요. 이렇게 하면 SKILL.md를 간결하게 유지하면서 컨텍스트 창을 차지하지 않고 정보를 검색할 수 있습니다. SKILL.md에는 필수적인 절차적 지침과 워크플로 안내만 유지하고, 상세 참조 자료, 스키마, 예제는 참조 파일로 옮기세요.
에셋 (assets/)
컨텍스트에 로드되지 않고 Codex가 생성하는 출력 내에서 사용되는 파일입니다.
- 포함 시기: 스킬이 최종 출력에 사용될 파일이 필요할 때
- 예제: 브랜드 에셋용
assets/logo.png, PowerPoint 템플릿용assets/slides.pptx, HTML/React 보일러플레이트용assets/frontend-template/, 타이포그래피용assets/font.ttf - 사용 사례: 템플릿, 이미지, 아이콘, 보일러플레이트 코드, 글꼴, 복사하거나 수정하는 샘플 문서
- 이점: 출력 리소스를 문서와 분리하여 Codex가 파일을 컨텍스트에 로드하지 않고 사용할 수 있음
스킬에 포함하지 말아야 할 것
스킬은 해당 기능을 직접 지원하는 필수 파일만 포함해야 합니다. 다음을 포함한 불필요한 문서나 보조 파일을 만들지 마세요:
- README.md
- INSTALLATION_GUIDE.md
- QUICK_REFERENCE.md
- CHANGELOG.md
- etc.
스킬은 AI 에이전트가 당면한 작업을 수행하는 데 필요한 정보만 포함해야 합니다. 생성 과정, 설정 및 테스트 절차, 사용자 대상 문서 등에 대한 보조 컨텍스트를 포함해서는 안 됩니다. 추가 문서 파일을 만들면 복잡성과 혼란만 가중됩니다.
점진적 공개 설계 원칙
스킬은 컨텍스트를 효율적으로 관리하기 위해 3단계 로딩 시스템을 사용합니다.
- 메타데이터(이름 + 설명) - 항상 컨텍스트에 있음(~100단어)
- SKILL.md 본문 - 스킬이 트리거될 때(<5,000단어)
- 번들 리소스 - Codex가 필요에 따라 로드(무제한, 스크립트를 컨텍스트 창에 읽지 않고 실행할 수 있으므로)
점진적 공개 패턴
컨텍스트 팽창을 최소화하기 위해 SKILL.md 본문을 필수 사항으로 유지하고 500줄 미만으로 유지하세요. 이 한도에 가까워지면 콘텐츠를 별도의 파일로 분할하세요. 콘텐츠를 다른 파일로 분할할 때는 SKILL.md에서 해당 파일을 참조하고 언제 읽어야 하는지 명확히 설명하여 스킬 사용자가 해당 파일의 존재와 사용 시기를 알 수 있도록 하는 것이 매우 중요합니다.
핵심 원칙: 스킬이 여러 변형, 프레임워크 또는 옵션을 지원하는 경우 SKILL.md에는 핵심 워크플로우와 선택 지침만 유지하세요. 변형별 세부 사항(패턴, 예제, 구성)은 별도의 참조 파일로 이동하세요.
패턴 1: 참조가 포함된 상위 수준 가이드
# PDF 처리
## 빠른 시작
pdfplumber로 텍스트 추출:
[코드 예제]
## 고급 기능
- **양식 채우기**: 전체 가이드는 [FORMS.md](https://raw.githubusercontent.com/openai/codex/main/FORMS.md) 참조
- **API 참조**: 모든 메서드는 [REFERENCE.md](https://raw.githubusercontent.com/openai/codex/main/REFERENCE.md) 참조
- **예제**: 일반적인 패턴은 [EXAMPLES.md](https://raw.githubusercontent.com/openai/codex/main/EXAMPLES.md) 참조
Codex는 필요할 때만 FORMS.md, REFERENCE.md 또는 EXAMPLES.md를 로드합니다.
패턴 2: 도메인별 구성
여러 도메인이 있는 스킬의 경우 관련 없는 컨텍스트 로드를 피하기 위해 도메인별로 콘텐츠를 구성하세요:
bigquery-skill/
├── SKILL.md (개요 및 탐색)
└── reference/
├── finance.md (수익, 청구 지표)
├── sales.md (기회, 파이프라인)
├── product.md (API 사용량, 기능)
└── marketing.md (캠페인, 기여도)
사용자가 영업 지표에 대해 물으면 Codex는 sales.md만 읽습니다.
마찬가지로 여러 프레임워크 또는 변형을 지원하는 스킬의 경우 변형별로 구성하세요:
cloud-deploy/
├── SKILL.md (워크플로우 + 공급자 선택)
└── references/
├── aws.md (AWS 배포 패턴)
├── gcp.md (GCP 배포 패턴)
└── azure.md (Azure 배포 패턴)
사용자가 AWS를 선택하면 Codex는 aws.md만 읽습니다.
패턴 3: 조건부 세부 사항
기본 콘텐츠를 표시하고 고급 콘텐츠로 연결하세요:
# DOCX 처리
## 문서 만들기
새 문서에는 docx-js를 사용하세요. [DOCX-JS.md](https://raw.githubusercontent.com/openai/codex/main/DOCX-JS.md) 참조.
## 문서 편집
간단한 편집의 경우 XML을 직접 수정하세요.
**변경 내용 추적**: [REDLINING.md](https://raw.githubusercontent.com/openai/codex/main/REDLINING.md) 참조
**OOXML 세부 사항**: [OOXML.md](https://raw.githubusercontent.com/openai/codex/main/OOXML.md) 참조
Codex는 사용자가 해당 기능을 필요로 할 때만 REDLINING.md 또는 OOXML.md를 읽습니다.
중요 지침:
- 깊게 중첩된 참조를 피하세요 - SKILL.md에서 참조는 한 수준 깊이로 유지하세요. 모든 참조 파일은 SKILL.md에서 직접 링크되어야 합니다.
- 더 긴 참조 파일 구조화 - 100줄이 넘는 파일의 경우 상단에 목차를 포함하여 Codex가 미리 볼 때 전체 범위를 볼 수 있도록 하세요.
스킬 생성 프로세스
스킬 생성에는 다음 단계가 포함됩니다:
- 구체적인 예제를 통해 스킬 이해
- 재사용 가능한 스킬 콘텐츠 계획 (스크립트, 참조, 에셋)
- 스킬 초기화 (init_skill.py 실행)
- 스킬 편집 (리소스 구현 및 SKILL.md 작성)
- 스킬 검증 (quick_validate.py 실행)
- 실제 사용 및 복잡한 스킬의 사전 테스트를 기반으로 반복
이 단계를 순서대로 따르고 적용할 수 없는 명확한 이유가 있는 경우에만 건너뛰세요.
스킬 이름 지정
- 소문자, 숫자, 하이픈만 사용하세요. 사용자가 제공한 제목을 하이픈 케이스로 정규화하세요 (예: "Plan Mode" ->
plan-mode). - 이름을 생성할 때는 64자 미만(문자, 숫자, 하이픈)의 이름을 생성하세요.
- 동작을 설명하는 짧고 동사로 시작하는 구문을 선호하세요.
- 명확성이나 트리거링을 개선할 때는 도구별로 네임스페이스를 지정하세요 (예:
gh-address-comments,linear-address-issue). - 스킬 폴더 이름을 스킬 이름과 정확히 일치하게 지정하세요.
1단계: 구체적인 예제를 통한 스킬 이해
스킬의 사용 패턴이 이미 명확하게 이해된 경우에만 이 단계를 건너뛰세요. 기존 스킬로 작업할 때도 유용하게 사용할 수 있습니다.
효과적인 스킬을 만들려면 스킬이 어떻게 사용될지에 대한 구체적인 예제를 명확히 이해하세요. 이러한 이해는 사용자의 직접적인 예제나 사용자 피드백을 통해 검증된 생성된 예제에서 얻을 수 있습니다.
예를 들어 이미지 편집기 스킬을 구축할 때 관련 질문은 다음과 같습니다:
- "이미지 편집기 스킬은 어떤 기능을 지원해야 할까요? 편집, 회전, 그 외 다른 것?"
- "이 스킬이 어떻게 사용될지 몇 가지 예를 들어주시겠어요?"
- "사용자가 '이 이미지에서 적목 현상을 제거해줘' 또는 '이 이미지를 회전해줘'와 같은 요청을 할 것이라고 상상할 수 있습니다. 이 스킬이 사용될 다른 방법을 상상하시나요?"
- "사용자가 이 스킬을 트리거하기 위해 무엇을 말해야 할까요?"
- "이 스킬을 어디에 만들어야 할까요? 선호하는 곳이 없다면 Codex가 자동으로 발견할 수 있도록
$CODEX_HOME/skills(또는CODEX_HOME이 설정되지 않은 경우~/.codex/skills)에 배치하겠습니다."
사용자를 압도하지 않으려면 단일 메시지에서 너무 많은 질문을 하지 마세요. 가장 중요한 질문부터 시작하고 필요에 따라 후속 질문을 하여 효과를 높이세요.
스킬이 지원해야 할 기능에 대한 명확한 감이 잡히면 이 단계를 마무리하세요.
2단계: 재사용 가능한 스킬 콘텐츠 계획
구체적인 예제를 효과적인 스킬로 전환하려면 각 예제를 분석하세요:
- 처음부터 예제를 실행하는 방법 고려
- 이러한 워크플로우를 반복적으로 실행할 때 도움이 될 스크립트, 참조 및 에셋 식별
예시: pdf-editor 스킬을 구축하여 "이 PDF를 회전하는 것을 도와주세요"와 같은 쿼리를 처리할 때 분석 결과는 다음과 같습니다:
- PDF를 회전하려면 매번 동일한 코드를 다시 작성해야 함
- 스킬에 저장할
scripts/rotate_pdf.py스크립트가 도움이 될 것임
예시: "나를 위한 할 일 앱을 만들어 줘" 또는 "트레킹 실적을 추적하는 대시보드를 만들어 줘"와 같은 쿼리를 위한 frontend-webapp-builder 스킬을 설계할 때:
- 각 쿼리는 다른 React 구성 요소와 페이지가 필요함
references/components.md에 있는 일반적인 UI 구성 요소 참조가 처음부터 구축하는 데 도움이 될 수 있음references/setup.md에 있는 설정 템플릿이 초기 프로젝트 구성을 가속화할 수 있음
이 단계에서는 무엇을 구축할지에 대한 아이디어와 SKILL.md 구조의 개요를 산출해야 합니다. 여기에서는 아직 파일을 만들지 마세요. 다음 단계에서 init_skill.py가 처리합니다.
3단계: 스킬 초기화 (init_skill.py 실행)
scripts/init_skill.py는 단일 인수인 스킬 이름을 받아서 필수 디렉토리와 SKILL.md 템플릿으로 구성된 표준 스킬 구조를 생성합니다. 그런 다음 생성된 SKILL.md를 열고 적절한 프론트매터와 지침으로 채웁니다.
$CODEX_HOME/skills(또는 CODEX_HOME이 설정되지 않은 경우 ~/.codex/skills)에 스킬을 생성합니다.
스킬이 생성되면 해당 내용이 무엇인지, 어떤 리소스를 포함해야 하는지에 대한 명확한 아이디어가 있어야 합니다. 스킬을 자세히 편집할 준비가 된 것입니다.
init_skill.py를 찾을 수 없는 경우 스크립트를 찾거나 init_skill.py를 생성하는 스킬 리포지토리 또는 코드 베이스의 파일 구조를 확인하세요.
4단계: 스킬 편집 (리소스 구현 및 SKILL.md 작성)
SKILL.md에 포괄적인 지침을 작성하세요:
- 스킬의 목적과 기능을 명확히 설명하세요
- 코드 예제를 포함하세요: 예제는 간결해야 하며 일반적인 항목에 대한 정확한 API 호출을 보여줘야 합니다
- 일반적인 작업을 위한 명확한 단계별 지침을 제공하세요
- 관련 도구 및 방법에 대한 지침이 포함되어야 함
- 독립형으로 유지하면서 관련된 경우 외부 참조 연결
모범 사례:
- SKILL.md 본문을 500줄 미만으로 유지하세요
- 긴 섹션을 참조 파일로 이동하고 SKILL.md에서 참조하세요
- 명확하고 구체적인 프롬프트 예제를 사용하세요
- 적절한 수준의 자유도와 지침을 유지하세요
- SKILL.md 상단에 있는 프론트매터에서 스킬 메타데이터를 정확하게 유지하세요
- 스킬에 불필요한 Readme 또는 문서 파일을 만들지 마세요
5단계: 스킬 검증 (quick_validate.py 실행)
scripts/quick_validate.py를 실행하면 일반적인 문제가 있는지 스킬이 검사됩니다:
- 필수 파일 존재(SKILL.md, agents/openai.yaml)
- 프론트매터에 유효한 이름 및 설명 필드가 있는지 확인
- SKILL.md의 마크다운 구조 확인
- 참조된 파일이 존재하는지 확인
- agents/openai.yaml이 SKILL.md와 일치하는지 확인
- 불필요한 파일(README.md, INSTALLATION_GUIDE.md) 확인
검증을 통과한 경우에만 스킬을 사용할 준비가 된 것입니다.
6단계: 실제 사용 및 복잡한 스킬 사전 테스트를 기반으로 반복
스킬 사용 패턴을 모니터링하고 피드백을 수집하세요. 실제 사용 데이터를 기반으로 지침, 예제 및 리소스를 정기적으로 업데이트하세요.
복잡한 스킬의 경우: 사용자에게 보내기 전에 실제 작업에서 스킬을 전방 테스트하세요. 예제 프롬프트로 시작하고, 스킬이 올바르게 실행되는지, 출력이 예상대로인지 확인하세요.
사전 테스트 접근 방식:
- 스킬이 처리하도록 설계된 현실적인 프롬프트 생성
- 스킬이 활성화된 상태에서 프롬프트 실행
- 응답의 품질과 정확성 검증
- 발견된 문제를 기반으로 스킬 수정
- 프롬프트 복잡성 및 변형을 점진적으로 증가시키면서 반복