Codex Skills 완벽 정리: SKILL.md란 무엇이고 어떻게 쓰나요 (2026)

- 아래의 사실과 수치는 작성 시점(2026년 8월)의 공식 문서와 대조해 확인했어요. Codex Skills/Plugins 용어는 빠르게 바뀌고 있으니, 의존하기 전에 최신 문서를 확인해 주세요.

Codex Skills란 무엇인가요?

Codex 스킬은 지침(그리고 선택적으로 스크립트, 참조 자료, 에셋)을 하나로 묶어, 작업이 필요로 할 때만 Codex가 끌어오는 재사용 가능한 기능이에요. "데이터베이스 마이그레이션은 이렇게 해요"라고 세션마다 다시 설명하는 대신, 한 번 SKILL.md 파일로 적어두면 Codex가 필요할 때 불러와요.

먼저 확실히 짚어둘 구분이 있어요. Codex Skills는 OpenAI가 처음부터 발명한 형식이 아니에요. SKILL.md는 오픈 표준인 Agent Skills로, 표준 자체의 사이트에 따르면 "원래 Anthropic이 개발했고, 오픈 표준으로 공개되었으며, 점점 늘어나는 에이전트 제품들이 채택하고 있는" 것이에요. Anthropic이 Claude Code를 위해 먼저 출시했고(2025년 10월), OpenAI는 몇 주 만에 같은 파일 형식을 Codex와 ChatGPT에 채택했어요. 같은 SKILL.md, 두 생태계인 셈이죠.

실무적으로 스킬은 이래요. 이름, 그리고 트리거가 되는 description(항상 Codex에 보임), Markdown 본문(일치할 때만 로드됨)이에요. 반복적이고 작업 형태의 일을 위해 만들어졌어요. 예를 들어 lint 수정 루틴, 마이그레이션 체크리스트, changelog 형식 같은 것으로, 일반 지식이나 항상 켜져 있는 프로젝트 컨텍스트를 위한 게 아니에요. 그건 AGENTS.md의 몫이고, 뒤에서 다뤄요.

쓰기 전에 유용한 자가 점검이 있어요. 이걸 세션에 몇 번 넘게 붙여넣게 될까, 그리고 매번 대체로 같은 내용으로 유지될까 하는 거예요. 그렇다면 스킬에 어울려요. 만지는 파일이나 기능에 따라 단계가 바뀌거나, 그냥 "이 리포지토리가 어떻게 돌아가는지"에 대한 일반 지식이라면, 아마 다른 곳—문서, 주석, 아니면 AGENTS.md—에 속해요.

SKILL.md 파일의 구조

스킬은 슬러그를 따서 이름 붙인 폴더로, 필수 파일 하나와 최대 네 개의 선택 파일로 이뤄져요.

my-skill/
├── SKILL.md            (required)
├── scripts/            (optional - executable code)
├── references/         (optional - docs the skill can point to)
├── assets/             (optional - templates, static files)
└── agents/openai.yaml  (optional - Codex-specific UI + MCP metadata)

SKILL.md 자체는 YAML 프런트매터 뒤에 Markdown 지침이 이어져요. 필수 필드는 두 개뿐이에요.

---
name: changelog-writer
description: Turn a git diff into a changelog entry. Use when the
  user asks for a changelog, release notes, or "what changed".
---

# Changelog writer

1. Run `git diff --stat` and `git log -5 --oneline`.
2. Group changes by type: Added, Changed, Fixed.
3. Write 3-6 bullet points in the project's changelog format.

name은 식별자이고, description은 트리거예요. 스킬이 해당하는지 Codex가 판단하려고 읽는 한 줄이니, 모호하게("changelog에 도움돼요")가 아니라 정확하게("~할 때 사용해요") 써 주세요.

선택 항목인 agents/openai.yaml은 Codex 전용이에요. Claude Code나 다른 클라이언트에는 영향을 주지 않고, Codex/ChatGPT 안에서 스킬이 어떻게 보이고 동작하는지에만 관여해요. 현재 문서에 따르면 세 그룹의 필드를 다뤄요. 인터페이스(display_name, short_description, icon_small/icon_large, brand_color, default_prompt), 정책(allow_implicit_invocation, 기본값 true), 그리고 도구 의존성 목록(스킬이 필요로 하는 MCP 서버와 그 전송 방식 및 URL)이에요. 이 파일의 필드 이름은 제품과 함께 바뀌니, 프로덕션에서 의존하기 전에 최신 문서를 확인하세요.

Codex Skills의 작동 방식(점진적 공개)

스킬을 부담 없이 놓아둘 수 있게 해주는 메커니즘은 점진적 공개(progressive disclosure)라고 부르고, 공식 문서에 따르면 세 단계로 동작해요.

1. 발견(Discovery) - 시작할 때 Codex는 각 스킬의 name과 description만 읽어요. 스킬이 존재한다는 걸 알기엔 충분하지만, 아직 쓰기엔 부족하죠.
2. 활성화(Activation) - 프롬프트가 스킬의 description에 일치하면, Codex는 SKILL.md 본문 전체를 컨텍스트로 읽어 들여요.
3. 실행(Execution) - Codex는 지침을 따라, 필요에 따라 번들된 스크립트를 실행하거나 references/assets 파일을 끌어와요.

발견 단계에는 엄격한 예산이 있어요. 초기 스킬 목록(설치된 모든 스킬의 name과 description을 합친 것)은 모델 컨텍스트 윈도의 2%, 또는 컨텍스트 윈도 크기를 알 수 없을 때는 8,000자—해당하는 쪽—로 제한돼요. 경쟁 제품이 좀처럼 언급하지 않는 실제 한계죠. 장황한 스킬을 너무 많이 설치하면, 목록에 오르지 못하는 것들이 생겨요.

여기서 두 가지 실무적 결과가 따라와요. 첫째, description을 촘촘하게 쓰세요—다른 스킬을 위한 여지가 남고, 모호한 것("코드에 도움돼요")은 안정적으로 발동하지 않는 반면 정확한 것("사용자가 changelog를 요청할 때 사용해요…")은 발동해요. 둘째, 시간에 민감한 내용을 description에만 두지 마세요. 스킬이 실행되고 나서야 의미가 생기는 내용이라면, 트리거 줄이 아니라 본문에 넣으세요.

Codex가 스킬을 찾는 위치(스코프와 우선순위)

Codex는 가장 구체적인 것부터 가장 일반적인 것까지, 여러 위치를 스캔해 스킬을 찾아요. 이름이 일치하면, 더 구체적인 위치가 우선해요.

Codex가 스킬을 볼 수 있게 되면, 발동시키는 방법은 두 가지예요.

• 명시적(Explicit) - Codex CLI나 IDE에서 $skill-name을 입력하거나(둘러보려면 /skills), ChatGPT에서는 @skill-name을 입력해요.
• 암묵적(Implicit) - 그냥 작업을 평범한 말로 설명하면 돼요. Codex가 그것을 보이는 모든 스킬의 description과 대조해 자동으로 호출해요.

리포지토리 범위의 스킬은 .agents/skills/에 커밋해서 팀 전체가 받도록 하고, 개인적인 습관은 사용자 스코프 폴더에 두어 프로젝트를 넘나들며 따라오게 하세요.

Codex 스킬을 설치하고 만드는 방법

두 갈래예요. 누군가 쓴 것을 설치하거나, 직접 만드는 거죠.

기존 스킬 설치하기

Codex 세션 안에서, 내장된 인스톨러 스킬을 실행해요.

$skill-installer linear

현재 카탈로그의 이름이나 GitHub URL을 가리키면, 스킬이 여러분의 스킬 폴더로 복제돼요(기본은 사용자 스코프. 리포지토리 스코프로 하려면 프로젝트 경로를 넘기세요). 알아두면 좋은 최신 정보가 하나 있어요. OpenAI의 스킬 카탈로그는 이미 한 번 옮겨졌어요. GitHub의 openai/skills에는 지원 중단 배너가 붙어 openai/plugins를 가리키고 있어요—그리고 이 글을 쓰는 시점에, 그 후속 리포지토리 자체도 아카이브됐어요(읽기 전용, 대체는 안내되지 않음). 지금으로선 두 GitHub 리포지토리 모두 신뢰할 만한 현역 카탈로그가 아니에요. 공식 문서 페이지를 믿을 만한 유일한 링크로 삼고, $skill-installer의 기본 소스 목록은 계속 바뀔 거라고 예상하세요—스크립트 안에서 실행하기 전에, 실제로 무엇으로 연결되는지 확인하세요.

대화형 크리에이터로 직접 만들기

$skill-creator

이건 스킬 이름 짓기, 트리거가 되는 description 작성, 본문 초안 잡기를 대화형으로 안내한 뒤, 폴더를 여러분의 스킬 경로에 저장해요. 직접 재사용할 스킬이라면, 도구 자체보다 세 가지 습관이 더 중요해요.

1. description은 요약이 아니라 트리거처럼 쓰세요—"X할 때 사용해요"가 "X에 도움돼요"보다 나아요.
2. 본문은 작업 형태로 유지하세요. 하나의 구체적인 일이 아니라 항상 참인 프로젝트 컨텍스트를 문서화하고 있다면, 그건 스킬이 아니라 AGENTS.md에 속해요.
3. 두 호출 경로를 모두 테스트하세요—먼저 $your-skill로 명시적으로 불러 본문이 동작하는지 확인하고, 그다음 자연어로 암묵적으로 발동시켜 description이 실제로 발동하는지 확인하세요.

폴더와 파일을 손수 만들 수도 있어요—mkdir -p .agents/skills/my-skill && touch .agents/skills/my-skill/SKILL.md—대화형 크리에이터는 편의 도구일 뿐, 필수는 아니에요.

Codex Skills vs AGENTS.md vs Plugins—어느 게 필요할까요?

세 가지 기본 요소, 세 가지 역할이에요. 서로 경쟁하지 않아요—실제 Codex 구성 대부분은 둘, 또는 셋 모두를 동시에 써요.

공식적인 표현을 거의 그대로 옮기면, 스킬은 "특정 작업이나 워크플로를 위한 지침과 보조 리소스를 묶는" 것이고, 플러그인은 "스킬, 커넥터, 또는 둘 다를 포함할 수 있는 설치 가능한 번들"이에요. 그러니 플러그인은 스킬과 경쟁하는 네 번째 형식이 아니라, 하나 또는 여러 스킬을 함께 담고 커넥터 같은 스킬 외적인 것도 실을 수 있는 패키징 계층이에요.

AGENTS.md는 완전히 다른 차선에 있어요. 필요할 때 로드되는 게 아니라 항상 컨텍스트에 있어요—바로 그래서 이것에 대한 조언은 스킬과 정반대로 흘러가요. 길게가 아니라 짧게 유지하세요(명령, 강한 규칙, 핵심 경로). 모든 줄이 매 턴마다 토큰을 쓰기 때문이에요. 군더더기 없는 것을 쓰는 자세한 내용은 AGENTS.md vs CLAUDE.md vs SKILL.md를, Codex 고유의 AGENTS.md 탐색 순서는 Codex AGENTS.md 가이드를 참고하세요.

실제로 이 셋은 쌓이는 것이지, 서로를 대체하지 않아요. 전형적인 리포지토리라면 빌드/테스트 명령과 강한 규칙을 담은 짧은 AGENTS.md를 두고, 릴리스 노트나 특정 리팩터링 패턴처럼 반복되는 일을 위한 스킬 몇 개를 갖추고, 관련된 여러 스킬과 커넥터를 한꺼번에 싣는 플러그인 번들 하나를 설치할 수 있어요. 셋 중 어느 것도 다른 것을 대신하지 않고, 저마다 Codex가 언제 무엇을 알거나 해야 하는지에 대한 다른 질문에 답할 뿐이에요.

Codex Skills는 Claude Code Skills와 같은 건가요?

핵심에서는, 네—게다가 그건 분위기가 아니라 실제 1차 출처가 있어요. 표준 자체의 사이트인 agentskills.io는 "Claude Code"와 "ChatGPT & Codex"를 지원 클라이언트로 나란히 올려두고, 이 형식이 "원래 Anthropic이 개발했고, 오픈 표준으로 공개되었으며, 점점 늘어나는 에이전트 제품들이 채택해 왔다"고 밝히고 있어요.

여기서 정확히 해둘 필요가 있어요. OpenAI의 어떤 페이지도 "Claude Code와 호환된다"고 그 문구 그대로 말하진 않아요. 상호 호환이라는 주장은 표준 자체의 클라이언트 목록과 독립적인 제3자 글들에 근거한 것이지, OpenAI의 인용은 아니에요—그래서 이 글은 이렇게 표현해요. 같은 오픈 표준일 뿐, OpenAI가 Claude Code를 공식 보증한 건 아니라고요.

두 도구 사이를 실제로 오가는 것. 그건 SKILL.md 파일 그 자체예요—name, description, Markdown 본문, 그리고 scripts//references/assets 폴더요. 한 도구에서 스킬을 쓰면, 읽히지 않는 추가분까지 포함해 핵심 파일이 다른 도구에서도 동작해요.

오가지 않는 것은 각 도구의 클라이언트 전용 추가분이고, 이건 다른 쪽이 그냥 무시해요.

• Codex가 더하는 것: ChatGPT 데스크톱 UI 메타데이터와 MCP 도구 의존성을 위한 agents/openai.yaml이에요.
• Claude Code가 더하는 것: context: fork(스킬을 격리된 서브에이전트에서 실행)와 disable-model-invocation(부작용이 있는 스킬의 자동 발동을 막음)—자세한 분석은 Claude Code Skills 해설을 참고하세요.

실무적 요점: 클라이언트 전용 프런트매터 없이 스킬을 만들면 기본적으로 이식 가능해요. Codex 전용이나 Claude 전용 필드를 더해도 다른 도구는 그냥 무시할 뿐이에요—망가지지 않고, 다만 거기서 아무 일도 안 할 뿐이죠.

직접 쓰기 싫으신가요? 미리 만들어진 스킬·워크플로 키트

정확하고 개인적인 워크플로를 원할 때는 손수 스킬을 쓰는 것도 괜찮아요. 빈 SKILL.md에서 시작하기보다 잘 선별된 라이브러리에서 시작하고 싶다면, 바로 거기가 AgentKit이 솔직하게 메우는 빈틈이에요—Codex에 구체적으로 어떻게 끼워지는지는 Codex에서 AgentKit 사용하기에서, 아니면 곧장 agentkit.best에서 보세요. 이름이 겹치니 짧게 구분하자면, 이건 제휴 AgentKit(agentkit.best, CLI ak)이지 OpenAI 자체의 AgentKit/Agent Builder 제품이 아니에요.

경계를 분명히 해둘게요. Codex의 기본 스킬 기능은 무료이고 ChatGPT 플랜에 포함돼 있어요—여기에 구매가 필요한 건 없어요. AgentKit은 별개의 유료 부가 기능이에요. 미리 만들어진 스킬, 서브에이전트, 워크플로를 선별한 키트로, ak kit init engineer --target codex --global로 Codex에 설치하고, 각 SKILL.md를 직접 손으로 쓰는 대신 $ak:cook으로 실행해요. "누군가 이미 만들어 테스트해둔" 선택지이지, 스킬이 작동하기 위한 필수 요건은 아니에요.

FAQ

Codex Skills는 무료인가요?

네. 스킬은 Codex의 기본 기능이고 ChatGPT 플랜에 포함돼 있어요—자신의 SKILL.md 파일을 쓰고, 설치하고, 실행하는 데 추가 비용은 들지 않아요. 비용은 직접 만드는 대신 제3자의 미리 만들어진 키트를 사기로 할 때만 생겨요.

Codex 스킬과 AGENTS.md의 차이는 무엇인가요?

스킬은 온디맨드예요. 작업이 그 description에 일치할 때만 로드돼요. AGENTS.md는 항상 로드돼요. 매 턴 컨텍스트에 자리해요. 구체적이고 반복되는 일에는 스킬을, 항상 알고 있어야 할 명령과 규칙에는 AGENTS.md를 쓰세요.

Codex Skills가 Claude Code에서 동작하나요?

핵심 SKILL.md 파일은 동작해요—두 도구 모두 오픈 Agent Skills 표준을 읽고, agentskills.io는 둘 다 지원 클라이언트로 올려두고 있어요. 클라이언트 전용 추가분은 넘어가지 않아요. Codex의 agents/openai.yaml은 Claude Code가 무시하고, Claude Code의 context: fork / disable-model-invocation 필드는 Codex가 무시해요.

커스텀 Codex 스킬은 어디에 두나요?

리포지토리 전체라면: 리포지토리 루트의 .agents/skills/(팀도 받도록 커밋하세요). 개인용으로 모든 프로젝트에 적용하려면: $HOME/.agents/skills. Codex는 그 밖에도 현재 작업 디렉터리와 그 부모, 그리고 관리자용과 시스템 번들 위치를 그 순서대로 확인해요.

다른 사람의 스킬을 설치할 수 있나요?

네—Codex 안에서 $skill-installer를 실행하고, 카탈로그 이름이나 GitHub URL을 가리키면 스킬이 여러분의 스킬 폴더로 복제돼요. 제3자 스킬은 설치 전에, 새 의존성을 검토하듯 그 SKILL.md와 스크립트를 살펴보세요.

openai/skills는 아직 공식 스킬 카탈로그인가요?

아니요. GitHub의 openai/skills는 지원 중단되어 openai/plugins를 가리켜요—그리고 이 글을 쓰는 시점에, openai/plugins 자체도 아카이브됐어요(읽기 전용). 두 리포지토리 모두 현역 카탈로그가 아니에요. 대신 learn.chatgpt.com/docs/build-skills의 공식 문서를 쓰세요.

마무리

Codex 스킬은 폴더 하나, SKILL.md 파일 하나, 그리고 트리거 description이에요—그 이상 별난 건 없어요. AGENTS.md가 항상 켜져 있는 것과 달리 이건 온디맨드이고, 두 도구가 같은 오픈 Agent Skills 표준을 읽기에 Claude Code로 이식 가능하며, Codex 자체에 딸려 오기에 무료예요. 작게 시작하세요. Codex에 자꾸 다시 설명하게 되는 작업 하나를 골라, 촘촘한 description을 쓰고, 점진적 공개가 비용을 낮게 유지하도록 두세요. 라이브러리를 처음부터 쓰기 싫다면, AgentKit 같은 선별 키트가 유료 지름길이에요—필수는 아니고요. AGENTS.md가 스킬과 어떻게 나란히 놓이는지는 Codex AGENTS.md 가이드에서, 아직 전체 그림을 잡는 중이라면 Codex란 무엇인가에서 시작해 보세요.