OpenAI의 Skills 설명 및 설치 사용법

Skills 이란?

AI 도구를 쓰다 보면 반복적으로 같은 프롬프트를 입력하는 순간이 반드시 온다. 코드 리뷰 요청, 테스트 코드 생성, 로그 분석 등 매번 같은 일을 다시 설명하는 건 생각보다 비효율적이다.

이 문제를 해결하는 핵심이 바로 “Skills"다. 쉽게 말하면 자주 쓰는 작업을 하나의 “재사용 가능한 명령"으로 만들어두는 기능이다.

한 번 잘 만들어두면 매번 길게 설명할 필요 없이 짧은 트리거만으로 동일한 결과를 얻을 수 있다.

즉, Skills은 재사용 가능한 워크플로우를 작성하기 위한 포맷이고, Codex CLI 뿐 아니라 IDE 확장 프로그램, Codex 앱에서 사용할 수 있다.

핵심 구조

Skill는 복잡해 보이지만 구조는 단순하다. 핵심은 “입력 → 처리 → 출력” 흐름이다.

• 입력: 사용자 요청 (예: “이 코드 테스트 만들어줘”)
• 처리: 정의된 프롬프트 로직
• 출력: 결과물 (테스트 코드, 설명 등)

여기서 중요한 건 단순히 프롬프트를 저장하는 게 아니라 “역할 + 규칙 + 출력 형식"까지 포함한다는 점이다.

예를 들어 단순한 요청과 Skill의 차이는 다음과 같다.

일반 요청:

• “이 코드 테스트 코드 만들어줘”

Skill:

• 역할: 테스트 코드 전문가
• 규칙: Kotest 사용, WebFlux 고려
• 출력: 바로 실행 가능한 코드

이 차이 하나로 결과 퀄리티가 완전히 달라진다.

Skills 설치하기

스킬은 명령어로 쓰거나 직업 파일을 넣어서 손쉽게 설치할 수 있다.

방법 1: 공식 카탈로그에서 설치

OpenAI Codex의 공식 스킬 카탈로그는 AI 에이전트가 특정 작업을 반복적으로 수행할 수 있도록 지침, 스크립트, 리소스를 묶어둔 폴더 구조의 모듈이다.

공식 저장소 (GitHub): openai/skills에서 Codex용 스킬 카탈로그를 확인할 수 있다.

• https://github.com/openai/skills

Codex에서 Skill 실치는 $skill-installer를 실행하면 된다.

$skill-installer {스킬명}

예를 들어, screenshot 이라는 skill를 설치하는 방법은 다음과 같다.

$skill-installer screenshot

실행을 하면, ~/.codex/skills/ 폴더에 마크다운 형태의 명세(SKILL.md) 등의 파일 생성된다.

다음 파일들은 screenshot 이라는 Skill 설치해서 생성된 파일이다.

.codex
└── skills
    └── screenshot
        ├── agents
        │   └── openai.yaml
        ├── assets
        │   ├── screenshot-small.svg
        │   └── screenshot.png
        ├── LICENSE.txt
        ├── scripts
        │   ├── ensure_macos_permissions.sh
        │   ├── macos_display_info.swift
        │   ├── macos_permissions.swift
        │   ├── macos_window_info.swift
        │   ├── take_screenshot.ps1
        │   └── take_screenshot.py
        └── SKILL.md

설치 후 Codex를 재시작하면 바로 사용 가능하다.

방법 2: GitHub URL을 입력해서 설치

GitHub URL을 직접 입력해서 설치할 수도 있다.

$skill-installer https://github.com/openai/skills/tree/main/skills/.curated/{스킬명}

방법 3: 프로젝트 루트에 직접 추가

프로젝트 루트에 .agents/skills/ 폴더를 만들고 스킬 폴더를 넣으면 된다. 이를 Git push하면 팀원 모두가 바로 사용할 수 있다.

Codex에서 Skill을 사용하기

Codex는 두 가지 방식으로 스킬을 사용할 수 있다.

명시적 호출 (Explicit invocation)

CLI/IDE에서는 프롬프트에 ${스킬명}을 입력하여 스킬 지정하여 직접 호출할 수 있다.

예를 들어, screenshot 이라는 skill를 설치하는 방법은 다음과 같다.

$screenshot https://www.devkuma.com --fullpage

또는 /skills 명령을 사용 가능한 스킬 목록을 확인한 뒤 선택한다.

암시적 호출 (Implicit invocation)

작업 내용을 설명하면, Codex가 자동으로 알맞는 스킬을 찾아서 실행해 준다.

예를 들어, “이 PR의 코멘트들을 반영해줘"라고 하면, gh-address-comments 스킬이 자동으로 실행된다.

• 작업 내용이 스킬의 description과 일치하면 Codex가 자동 선택

암시적 매칭은 skills/SKILL.md 파일 내에 description와 일치하면 Codex가 자동 선택된다.

Skill 기본 파일 구조

Codex는 먼저 각 스킬의 이름, 설명, 파일 경로만 참고하고, 실제로 해당 스킬을 사용하기로 결정했을 때만 SKILL.md 전체 내용을 로드한다.

Codex는 적절한 스킬을 선택할 수 있도록 초기 컨텍스트에 사용 가능한 스킬 목록을 포함한다.
이 목록은 프롬프트 공간을 과도하게 차지하지 않도록 제한되며, 전체 컨텍스트의 약 2% 또는 최대 8,000자 수준이다.
스킬이 많을 경우 설명이 먼저 축약되며, 매우 많은 경우 일부 스킬은 목록에서 제외되고 경고가 표시된다.

이 제한은 초기 스킬 목록에만 적용된다. Codex가 특정 스킬을 선택하면 해당 스킬의 SKILL.md 전체 내용을 읽는다.

하나의 스킬은 SKILL.md 파일과 선택적인 스크립트 및 리소스로 구성된 디렉토리다.

my-skill/
├── SKILL.md        # 필수: 지침 + 메타데이터
├── scripts/        # 선택: 실행 코드
├── references/     # 선택: 문서
├── assets/         # 선택: 템플릿, 리소스
└── agents/
    └── openai.yaml # 선택: UI 및 의존성 설정

• SKILL.md
  • 필수 파일로 name, description 그리고 Codex가 따라야 할 핵심 절차가 들어간다.
• scripts/
  • 선택 사항으로 반복해서 같은 코드를 짜게 될 때 넣는다.
  • 예를 들어, 변경 파일 목록 수집, PR 메타데이터 정리, 특정 테스트 실행처럼 결정적으로 같은 동작이 필요한 경우이다.
• references/
  • 선택 사항으로 참고 자료를 넣는 곳이다.
  • 예를 들어, RLS 정책 점검 기준, 팀의 API 계약, 배포 정책 같은 문서가 여기에 잘 어울린다.
• assets/
  • 선택 사항으로 출력물에 쓰일 템플릿이나 리소스를 둔다.
  • 리뷰 코멘트 템플릿, PR 설명 템플릿, 보고서 형식 파일 같은 것 들이다.

Skill 만들기

공식 스킬만 사용하기에는 부족하다. 본인 또는 팀에서의 워크플로우를 위해서 커스텀 스킬을 필요할 수 있다.

커스컴 스킬을 만들기 위해서는 위에서 언급한 SKILL.md 파일을 만들어야 한다.

SKILL.md 작성법:

---
name: skill-name
description: 이 스킬이 언제 실행되고, 언제 실행되지 않아야 하는지 명확히 설명
---

Codex가 따라야 할 스킬 지침 작성

여기서 description이 가장 중요하다. 여기 작성된 내용이 암시적 매칭은 이 description에 의존하므로, 명확하고 간결하게 작성해야 한다.

• 핵심 사용 사례를 앞쪽에 배치
• 트리거 키워드를 명확히 작성
• 설명이 잘려도 매칭 가능하도록 작성
• 한국어와 영어 키워드를 모두 포함
• 실제로 입력할만한 표현을 나열
• 이 스킬이 하지 않는 것도 명시 (잘못된 매칭 방지)

description 예시:

description: "PR 리뷰 코멘트를 자동으로 반영한다. '리뷰 반영', 'PR 코멘트', 'address comments', 'fix review' 등에 반응한다. 코드 리뷰 자체를 수행하지는 않다."

기본 생성기로 만들기

직접 SKILL.md 파일을 작성해도 되지만, 기본 생성기를 사용하는 것을 추천한다.

$skill-creator

이 생성기는 다음을 질문한다:

• 스킬이 하는 작업
• 언제 실행되어야 하는지
• 스크립트를 포함할지 여부 (기본은 instruction-only)

Codex는 스킬 변경을 자동으로 감지한다. 변경 사항이 반영되지 않으면 Codex를 재시작하면 된다.

Skill 저장 위치

Codex는 여러 위치에서 Skill을 로딩한다.

Codex는 심볼릭 링크된 스킬 폴더도 지원한다.

이 위치들은 로컬 개발 및 탐색용이다. 외부 배포를 원하면 plugin을 사용하는 것이 좋다.

선택적 메타데이터

agents/openai.yaml을 추가하면, UI 및 정책 설정 가능하다.

interface:
  display_name: "사용자에게 보이는 이름"
  short_description: "간단 설명"
  icon_small: "./assets/small-logo.svg"
  icon_large: "./assets/large-logo.png"
  brand_color: "#3B82F6"
  default_prompt: "기본 프롬프트"

policy:
  allow_implicit_invocation: false

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

• allow_implicit_invocation 기본값: true
• false로 설정하면 자동 호출 비활성화 (명시적 호출은 가능)

Skill 활성화 / 비활성화

원하지 않는 스킬이 있다면, 삭제하지 않고 ~/.codex/config.toml에서 활성화 여부 설정할 수 있다.

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

설정 변경 후 Codex 재시작 필요하다.

플러그인으로 스킬 배포

로컬 스킬 폴더는 개발 및 테스트에 적합하다.

다음과 같은 경우 plugin으로 패키징하는 것이 좋다:

• 재사용 가능한 스킬 배포
• 여러 스킬을 하나로 묶기
• 앱 연동 포함

플러그인은 다음을 포함할 수 있다:

• 여러 개의 스킬
• 앱 매핑
• MCP 서버 설정
• UI 자산

Claude Skills를 Codex에서 활용

Claude, Codex 도구 모두 같은 Agent Skills 오픈 표준(agentskills.io)을 따르기 때문에 같은 SKILL.md 포맷을 쓰고, Anthropic의 Skills 리포지토리를 Codex에서도 활용할 수 있다.

방법은 간단하다:

1. Claude Skills 저장소를 .agents/skills/에 복제한다.
2. list-skills 스크립트를 추가한다.
   • skills 폴더의 SKILL.md를 읽어 JSON 출력한다.
3. AGENTS.md에 “list-skills를 실행하여 사용 가능한 skills를 확인하라” 지침 추가한다.

이렇게 하면 Claude Code용으로 만든 스킬을 Codex에서도 그대로 활용할 수 있다.
단, 이 방법은 커뮤니티에서 발견된 활용법이며 OpenAI/Anthropic이 공식 지원하는 상호 운용 기능은 아니다.

기본적인 스킬은 상호 호환이 가능하다. 다만 각 도구의 확장 기능(Claude Code의 allowed-tools, Codex의 .system 디렉토리 등)은 호환되지 않을 수 있다.

Claude Code Skills vs Codex Skills 비교

실무에서 이렇게 쓰면 생산성 햐상

스킬은 Codex CLI, IDE 확장 프로그램, Codex 앱에서 사용할 수 있다.

단순히 만드는 것보다 중요한 건 “어디에 쓰느냐"다. 실제로 효과가 컸던 사례를 몇 가지 공유한다.

1. 로그 분석 자동화
   • WebFlux 로그는 비동기 흐름 때문에 분석이 어렵다. Skill로 “로그 해석 전문가"를 만들어두면 복잡한 로그도 구조적으로 설명해준다.
2. 테스트 코드 표준화
   • 팀마다 테스트 스타일이 다른 문제를 Skills로 해결할 수 있다. 규칙을 강제하면 모든 코드가 동일한 스타일로 생성된다.
3. 반복 업무 제거
   • API 문서 생성
   • 에러 메시지 분석
   • 코드 리팩토링 제안

이런 작업은 Skills로 만들어두면 거의 자동화 수준으로 처리된다.

핵심은 “자주 하는 작업은 무조건 Skill로 만든다"는 기준을 세우는 것이다.

정리: Codex Skills는 개발 생산성의 핵심 도구다

Codex Skills는 단순한 프롬프트 저장 기능이 아니다. 반복 작업을 자동화하고 결과의 품질을 표준화하는 강력한 도구다.

처음에는 하나만 만들어도 충분하다. 테스트 코드 생성, 로그 분석, 코드 리뷰 중 가장 자주 하는 작업부터 시작해보자.

한 번 익숙해지면 “이걸 왜 이제 썼지?“라는 생각이 들 정도로 개발 흐름이 바뀐다.

FAQ

Q1. Codex Skills는 언제 사용하는 게 좋은가?

반복적으로 같은 요청을 3번 이상 한다면 바로 Skill로 만드는 게 좋다. 특히 테스트 코드 생성, 문서화, 로그 분석 같은 작업에 효과적이다.

Q2. Skill이 많아지면 관리가 어려워지지 않나?

그래서 네이밍과 목적 정의가 중요하다. “test-webflux”, “log-analyzer"처럼 명확하게 구분하면 관리가 쉬워진다.

Q3. 초보자도 바로 사용할 수 있을까?

가능하다. 복잡한 로직 없이 Role, Rules, Output만 명확히 정의하면 된다. 오히려 초보자일수록 반복 작업을 줄이는 데 큰 도움이 된다.