스킬

스킬은 반복 가능한 워크플로와 도메인 지식을 Codex가 재사용할 수 있는 단위로 묶는 방법입니다. 지침, 참고 자료, 템플릿, 선택적 스크립트를 한 폴더에 담아 Codex가 같은 종류의 작업을 안정적으로 처리하게 합니다.

스킬은 open agent skills standard를 기반으로 하며 Codex CLI, IDE 확장, Codex 앱에서 사용할 수 있습니다.

언제 스킬을 쓰는가

스킬은 한 번만 필요한 요청이 아니라 반복해서 재사용할 절차에 적합합니다.

• 릴리스 절차, 리뷰 루틴, 문서 업데이트처럼 단계가 정해진 워크플로
• 팀 고유의 도메인 지식이나 판단 기준
• 예시, 참고 문서, 템플릿이 필요한 작업
• 검증 명령이나 데이터 준비처럼 보조 스크립트가 있으면 좋은 절차

항상 적용되어야 하는 저장소 규칙은 AGENTS.md에 두고, 특정 작업을 수행하는 절차는 스킬로 분리합니다. 예를 들어 "테스트는 항상 pnpm test로 실행한다"는 AGENTS.md에 어울리고, "릴리스 노트를 만들고 변경 로그를 검증한다"는 스킬에 어울립니다.

스킬은 워크플로를 정의하는 형식이고, 플러그인은 스킬과 앱 통합, MCP 서버를 설치 가능한 형태로 배포하는 단위입니다. 로컬에서 워크플로를 만들고 다듬을 때는 스킬 폴더로 시작하고, 다른 개발자에게 배포하거나 앱 통합과 함께 묶을 때는 플러그인으로 패키징합니다.

Codex가 스킬을 찾는 방식

Codex는 컨텍스트를 효율적으로 쓰기 위해 점진적 공개 방식을 사용합니다.

1. 처음에는 사용 가능한 스킬의 이름, 설명, 파일 경로만 봅니다.
2. 작업에 맞는 스킬을 선택하면 그때 SKILL.md 전체 지침을 읽습니다.
3. 참고 자료를 읽거나 스크립트를 실행하는 일은 필요한 경우에만 수행합니다.

스킬은 두 가지 방식으로 사용할 수 있습니다.

1. 명시적 호출: 프롬프트에서 $skill-name처럼 스킬을 직접 언급합니다. CLI와 IDE에서는 /skills를 실행하거나 $를 입력해 스킬을 선택할 수 있습니다.
2. 암시적 호출: 요청 내용이 스킬의 description과 맞으면 Codex가 스킬을 선택할 수 있습니다.

암시적 호출은 description에 크게 의존합니다. 설명에는 스킬이 필요한 상황, 필요하지 않은 상황, 핵심 키워드를 앞쪽에 간결하게 적는 것이 좋습니다.

스킬 구조

스킬은 SKILL.md 파일과 선택적 보조 디렉터리로 구성된 폴더입니다. SKILL.md에는 반드시 name과 description이 있어야 합니다.

my-skill/
├── SKILL.md      # 필수: 지침과 메타데이터
├── scripts/      # 선택: 실행 가능한 코드
├── references/   # 선택: 문서
├── assets/       # 선택: 템플릿과 리소스
└── agents/
    └── openai.yaml # 선택: 표시 정보와 의존성

scripts/에는 Codex가 워크플로 중 실행할 CLI 스크립트를 둘 수 있습니다. references/에는 긴 문서나 정책처럼 필요할 때만 읽을 자료를, assets/에는 템플릿이나 이미지 같은 리소스를 둡니다.

SKILL.md 예시는 다음과 같습니다.

---
name: commit
description: 변경 사항을 의미 있는 단위로 스테이징하고 커밋합니다. 사용자가 커밋을 만들거나, 커밋을 정리하거나, push 전에 브랜치를 정돈하려고 할 때 사용합니다.
---

1. `git add .`를 실행하지 않습니다. 목적에 따라 파일을 논리적인 단위로 나누어 스테이징합니다.
2. 커밋은 `feat`, `test`, `docs`, `refactor`, `chore` 같은 성격별로 분리합니다.
3. 변경 범위에 맞는 간결한 커밋 메시지를 작성합니다.
4. 각 커밋은 하나의 목적에 집중하고 리뷰하기 쉬운 크기로 유지합니다.

스킬 만들기

가장 빠른 방법은 내장 $skill-creator를 사용하는 것입니다.

$skill-creator

$skill-creator는 스킬이 무엇을 하는지, 언제 호출되어야 하는지, 지침만 둘지 스크립트도 포함할지 질문합니다. 기본값은 지침만 포함하는 스킬입니다.

폴더와 SKILL.md 파일을 만들어 수동으로 스킬을 만들 수도 있습니다.

---
name: skill-name
description: 이 스킬을 사용해야 하는 상황과 사용하지 말아야 하는 상황을 구체적으로 설명합니다.
---

Codex가 따라야 할 작업 지침을 작성합니다.

Codex는 스킬 변경을 자동으로 감지합니다. 업데이트가 보이지 않으면 Codex를 다시 시작합니다.

스킬 저장 위치

스킬은 전역 스킬로 둘 수도 있고 저장소별 스킬로 둘 수도 있습니다. 특정 프로젝트에만 적용되는 워크플로라면 저장소의 .agents/skills에 넣고, 여러 저장소에서 공통으로 쓰는 개인 워크플로라면 $HOME/.agents/skills에 둡니다.

Codex는 저장소, 사용자, 관리자, 시스템 위치에서 스킬을 읽습니다. 저장소 스킬은 현재 작업 디렉터리에서 저장소 루트까지 올라가며 각 디렉터리의 .agents/skills를 스캔합니다. 두 스킬이 같은 name을 공유해도 병합하지 않으며 둘 다 스킬 선택기에 나타날 수 있습니다.

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

이 위치들은 로컬 작성과 발견을 위한 것입니다. 단일 저장소를 넘어 배포하거나 앱 통합과 함께 묶을 때는 플러그인을 사용합니다.

스킬 설치와 배포

내장 스킬 외에 선별된 스킬을 로컬 Codex 설정에 추가하려면 $skill-installer를 사용합니다. 예를 들어 $linear 스킬을 설치하려면 다음을 실행합니다.

$skill-installer linear

$skill-installer에 다른 저장소에서 스킬을 다운로드하라고 요청할 수도 있습니다. Codex는 새로 설치된 스킬을 자동으로 감지합니다. 표시되지 않으면 Codex를 다시 시작합니다.

직접 스킬 폴더를 두는 방식은 로컬 작성과 저장소 범위 워크플로에 가장 적합합니다. 재사용 가능한 스킬을 배포하거나, 두 개 이상의 스킬을 함께 묶거나, 앱 통합과 함께 제공하려면 플러그인으로 패키징합니다.

플러그인은 하나 이상의 스킬을 포함할 수 있으며 앱 연결, MCP 서버 구성, 표시용 리소스도 함께 묶을 수 있습니다.

MCP와 함께 사용하기

워크플로가 이슈 트래커, 디자인 도구, 문서 서버 같은 외부 시스템을 필요로 한다면 스킬을 MCP와 함께 사용하는 것이 좋습니다. 스킬은 워크플로의 순서와 판단 기준을 정의하고, MCP는 그 워크플로가 외부 도구와 데이터에 접근하게 합니다.

스킬이 특정 MCP 서버에 의존한다면 agents/openai.yaml에 의존성을 선언할 수 있습니다. 이렇게 하면 Codex가 스킬 사용에 필요한 구성을 안내하거나 설치할 수 있습니다.

스킬 활성화 또는 비활성화

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

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

~/.codex/config.toml을 변경한 뒤 Codex를 다시 시작합니다.

앱 메타데이터와 호출 정책

Codex 앱의 UI 메타데이터를 구성하고, 호출 정책을 설정하고, 스킬 사용 경험을 더 매끄럽게 만들 도구 의존성을 선언하려면 agents/openai.yaml을 추가합니다.

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 호출은 계속 작동합니다.

컨텍스트 예산

Codex는 작업에 맞는 스킬을 선택할 수 있도록 사용 가능한 스킬의 초기 목록을 컨텍스트에 포함합니다. 프롬프트의 나머지를 밀어내지 않도록 이 목록은 모델 컨텍스트 창의 약 2% 또는 컨텍스트 창을 알 수 없을 때 약 8,000자로 제한됩니다.

설치된 스킬이 많으면 Codex는 먼저 스킬 설명을 줄입니다. 매우 큰 스킬 세트에서는 일부 스킬이 초기 목록에서 생략될 수 있으며 Codex가 경고를 표시합니다.

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

모범 사례

• 각 스킬은 하나의 작업에 집중하게 합니다.
• 결정적 동작이나 외부 도구가 필요한 경우가 아니라면 스크립트보다 지침을 선호합니다.
• 명시적 입력과 출력을 가진 명령형 단계를 작성합니다.
• 스킬 설명을 실제 프롬프트로 테스트해 의도한 상황에서 호출되는지 확인합니다.

더 많은 예시는 github.com/openai/skills와 agent skills specification을 참고하십시오.