스킬 빌드

에이전트 스킬을 사용하여 Codex에 작업별 기능을 추가하세요. 스킬은 Codex가 워크플로를 안정적으로 따를 수 있도록 지침, 리소스 및 선택적 스크립트를 패키징합니다. 스킬은 개방형 에이전트 스킬 표준을 기반으로 합니다.

스킬은 재사용 가능한 워크플로를 작성하기 위한 형식입니다. 플러그인은 재사용 가능한 스킬과 커넥터를 웹의 ChatGPT Work와 데스크톱 앱의 ChatGPT Work 및 Codex에 배포합니다. Codex CLI에서도 플러그인을 설치할 수 있습니다. 스킬로 워크플로 자체를 설계한 다음, 워크스페이스의 다른 사용자가 설치하도록 하려면 플러그인으로 패키징하세요.

스킬은 ChatGPT 데스크톱 앱, Codex CLI 및 IDE 확장 프로그램에서 사용할 수 있습니다.

ChatGPT 데스크톱 앱의 사이드바에서 스킬을 열어 프로젝트 전반에서 생성된 스킬을 확인하고 살펴보세요.

ChatGPT 데스크톱 앱에서 사용 가능한 스킬을 보여 주는 스킬 선택기(라이트 모드)

스킬은 컨텍스트를 효율적으로 관리하기 위해 점진적 공개를 사용합니다. Codex는 각 스킬의 이름, 설명 및 파일 경로로 시작합니다. Codex는 스킬을 사용하기로 결정할 때만 전체 SKILL.md 지침을 불러옵니다.

Codex는 작업에 적합한 스킬을 선택할 수 있도록 사용 가능한 스킬의 초기 목록을 컨텍스트에 포함합니다. 이 목록이 나머지 프롬프트를 과도하게 차지하지 않도록 모델 컨텍스트 창의 최대 2%만 사용하며, 컨텍스트 창의 크기를 알 수 없는 경우에는 최대 8,000자를 사용합니다. 설치된 스킬이 많으면 Codex가 먼저 스킬 설명을 줄입니다. 스킬 집합이 크면 Codex가 초기 목록에서 일부 스킬을 생략하고 경고를 표시할 수 있습니다.

이 예산은 초기 스킬 목록에만 적용됩니다. Codex가 스킬을 선택하면 해당 스킬의 전체 SKILL.md 지침을 계속 읽습니다.

스킬은 SKILL.md 파일과 선택적 스크립트 및 참조 자료를 포함하는 디렉터리입니다. SKILL.md 파일에는 name 및 description이 포함되어야 합니다.

my-skill/
├── SKILL.md          # Required: instructions and metadata
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates and resources
└── agents/
    └── openai.yaml   # Optional: appearance and dependency declarations

Codex가 스킬을 사용하는 방법

Codex는 다음 두 가지 방법으로 스킬을 활성화할 수 있습니다.

명시적 호출: 프롬프트에 스킬을 직접 포함합니다. CLI/IDE에서는 /skills을 실행하거나 $을 입력하여 스킬을 언급합니다.
암시적 호출: 작업이 스킬 description과 일치하면 Codex가 해당 스킬을 선택할 수 있습니다.

암시적 일치는 description에 따라 결정되므로 범위와 경계가 명확한 간결한 설명을 작성하세요. 설명이 줄어들더라도 Codex가 스킬을 일치시킬 수 있도록 주요 사용 사례와 트리거 단어를 앞부분에 배치하세요.

스킬 생성

이미 워크플로를 알고 있고 설명하는 것보다 보여 주는 편이 쉽다면 Record & Replay를 사용하세요. Codex가 워크플로를 녹화하고, 단계를 검사한 후 시연을 기반으로 재사용 가능한 스킬 초안을 작성합니다.

스킬을 직접 설명하려면 기본 제공 생성기를 사용하세요.

$skill-creator

생성기는 스킬의 기능, 활성화되어야 하는 시점 및 지침만 포함할지 스크립트도 포함할지를 묻습니다. 기본값은 지침만 포함하는 방식입니다.

SKILL.md 파일이 있는 폴더를 생성하여 스킬을 수동으로 만들 수도 있습니다.

---
name: skill-name
description: Explain exactly when this skill should and should not trigger.
---

Skill instructions for Codex to follow.

Codex는 스킬 변경 사항을 자동으로 감지합니다. 업데이트가 표시되지 않으면 Codex를 다시 시작하세요.

스킬 저장 위치

Codex는 저장소, 사용자, 관리자 및 시스템 위치에서 스킬을 읽습니다. 저장소의 경우 Codex는 현재 작업 디렉터리부터 저장소 루트까지 각 디렉터리의 .agents/skills을 스캔합니다. 두 스킬의 name이 같아도 Codex는 이를 병합하지 않으며, 둘 다 스킬 선택기에 표시될 수 있습니다.

스킬 범위	위치	권장 용도
`REPO`	`$CWD/.agents/skills` 현재 작업 디렉터리: Codex를 실행하는 위치입니다.	저장소 또는 코드 환경에 있는 경우 팀에서 작업 폴더와 관련된 스킬을 체크인할 수 있습니다. 예를 들어 특정 마이크로서비스나 모듈에만 관련된 스킬이 해당합니다.
`REPO`	`$CWD/../.agents/skills` Git 저장소 내에서 Codex를 실행할 때 CWD 위에 있는 폴더입니다.	중첩된 폴더가 있는 저장소의 경우 조직에서 상위 폴더의 공유 영역과 관련된 스킬을 체크인할 수 있습니다.
`REPO`	`$REPO_ROOT/.agents/skills` Git 저장소 내에서 Codex를 실행할 때 가장 위에 있는 루트 폴더입니다.	중첩된 폴더가 있는 저장소의 경우 조직에서 저장소를 사용하는 모든 사람과 관련된 스킬을 체크인할 수 있습니다. 이는 저장소의 모든 하위 폴더에서 사용할 수 있는 루트 스킬입니다.
`USER`	`$HOME/.agents/skills` 사용자의 개인 폴더에 체크인된 모든 스킬입니다.	사용자가 작업할 수 있는 모든 저장소에 적용되는 사용자 관련 스킬을 선별하는 데 사용합니다.
`ADMIN`	`/etc/codex/skills` 공유 시스템 위치의 머신 또는 컨테이너에 체크인된 모든 스킬입니다.	SDK 스크립트와 자동화에 사용하고, 머신의 각 사용자가 사용할 수 있는 기본 관리자 스킬을 체크인하는 데 사용합니다.
`SYSTEM`	OpenAI가 Codex에 번들로 제공합니다.	skill-creator 및 계획 스킬처럼 폭넓은 사용자에게 유용한 스킬입니다. 모든 사용자가 Codex를 시작할 때 사용할 수 있습니다.

Codex는 심볼릭 링크로 연결된 스킬 폴더를 지원하며 이러한 위치를 스캔할 때 심볼릭 링크 대상을 따릅니다.

이러한 위치는 작성 및 로컬 검색을 위한 것입니다. 단일 저장소를 넘어 재사용 가능한 스킬을 배포하거나 선택적으로 커넥터와 함께 묶으려면 플러그인을 사용하세요.

플러그인으로 스킬 배포

직접 만든 스킬 폴더는 로컬 작성 및 저장소 범위 워크플로에 가장 적합합니다. 재사용 가능한 스킬을 배포하거나, 두 개 이상의 스킬을 함께 묶거나, 스킬을 커넥터와 함께 제공하려면 플러그인으로 패키징하세요.

플러그인에는 하나 이상의 스킬을 포함할 수 있습니다. 앱 매핑, MCP 서버 구성 및 프레젠테이션 자산도 선택적으로 하나의 패키지에 묶을 수 있습니다.

로컬 사용을 위한 엄선된 스킬 설치

개인 로컬 Codex 설정에 기본 제공 스킬 이외의 엄선된 스킬을 추가하려면 $skill-installer을 사용하세요. 예를 들어 $linear 스킬을 설치하려면 다음과 같이 합니다.

$skill-installer linear

설치 프로그램에 다른 저장소에서 스킬을 다운로드하도록 요청할 수도 있습니다. Codex는 새로 설치된 스킬을 자동으로 감지합니다. 스킬이 표시되지 않으면 Codex를 다시 시작하세요.

로컬 설정과 실험에는 이 방법을 사용하세요. 직접 만든 스킬을 재사용 가능하게 배포하려면 플러그인을 사용하는 것이 좋습니다.

스킬 활성화 또는 비활성화

~/.codex/config.toml의 [[skills.config]] 항목을 사용하면 스킬을 삭제하지 않고 비활성화할 수 있습니다.

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

~/.codex/config.toml을 변경한 후 Codex를 다시 시작하세요.

선택적 메타데이터

agents/openai.yaml을 추가하여 ChatGPT 데스크톱 앱의 UI 메타데이터를 구성하고, 호출 정책을 설정하며, 스킬을 더 원활하게 사용할 수 있도록 도구 종속성을 선언하세요.

interface:
  display_name: "Optional user-facing name"
  short_description: "Optional user-facing description"
  icon_small: "./assets/small-logo.svg"
  icon_large: "./assets/large-logo.png"
  brand_color: "#3B82F6"
  default_prompt: "Optional surrounding prompt to use the skill with"

policy:
  allow_implicit_invocation: false

dependencies:
  tools:
    - type: "mcp"
      value: "openaiDeveloperDocs"
      description: "OpenAI Docs MCP server"
      transport: "streamable_http"
      url: "https://developers.openai.com/mcp"

allow_implicit_invocation(기본값: true): false인 경우 Codex는 사용자 프롬프트를 기반으로 스킬을 암시적으로 호출하지 않지만, 명시적 $skill 호출은 계속 작동합니다.

모범 사례

각 스킬이 하나의 작업에 집중하도록 하세요.
결정론적 동작이나 외부 도구가 필요한 경우가 아니라면 스크립트보다 지침을 우선하세요.
입력과 출력을 명시한 명령형 단계를 작성하세요.
스킬 설명에 프롬프트를 테스트하여 올바르게 활성화되는지 확인하세요.

더 많은 예는 GitHub CI 복구, PDF, Linear, openai/skills 및 에이전트 스킬 사양을 참조하세요. 설치 가능한 형태로 배포하려면 플러그인을 사용하는 것이 좋습니다.

최근 검색

추천 검색

문서 탐색