[아티클 02] 코덱스 스킬로 코덱스 CLI 슈퍼 파워 제공하기
MCP 연결을 통해 코덱스 CLI와 외부 도구 연동으로 더 편하게 바이브 코딩하는 방법을 익혔다면, 이제는 우리 팀만의 고유한 업무 스타일과 구체적인 절차를 내재화할 차례입니다. 디자인 규정이나 보고서 양식처럼 매번 반복해서 설명하기 번거로웠던 지식을 하나의 패키지로 묶어 관리하는 기능이 바로 스킬입니다. MCP가 코덱스에게 망치와 톱이라는 도구를 쥐여준 것이라면, 스킬은 가구를 만드는 구체적인 매뉴얼을 전수하는 것과 같습니다. 이번 장에서는 복잡한 코딩 없이 자연어만으로 코덱스에게 특별한 업무 수행 능력을 부여하고, 생산성을 극대화하는 스킬 활용법을 자세히 살펴보겠습니다.
스킬, AI를 위한 업무 매뉴얼
스킬Skill은 코덱스에게 특정 도메인의 전문 지식과 업무 절차를 가르치는 패키지입니다. 예를 들어, 신입 사원에게 업무를 줄 때, 매번 “엑셀 켜서, 1열에 날짜 넣고, 폰트는 맑은 고딕 쓰고…”라고 하나하나 지시하지 않습니다. 대신 “주간 보고서 매뉴얼대로 작성해줘”라고 간단하면서도 명확히 지시하죠. 이때 신입 사원이 참고하는 매뉴얼과 업무 양식이 바로 스킬에 해당합니다. 다음은 MCP, AGENTS.md와 더불어 코덱스 에이전트의 컨텍스트를 구성하는 스킬의 구성을 보여줍니다.
스킬은 기본적으로 폴더 구조로 구성되어 있으며, 각 폴더 안에는 반드시 SKILL.md 파일이 존재해야 합니다. 또한 스킬을 구성하는 각 폴더는 ~/.codex/skills/ 경로에 생성합니다. 예를 들어 pdf 작업에 특화된 스킬을 생성할 때는 ~/.codex/skills/pdf, 디자인 작업에 특화된 스킬을 생성할 때는 ~/.codex/skills/canvas와 같이 작성합니다. 폴더 이름은 자유롭게 정해도 스킬을 실행하는 데 문제는 없지만, 해당 스킬이 어떤 작업을 수행하는지 직관적으로 알 수 있도록 이름을 정하는 것이 좋습니다. 스킬은 단순히 텍스트만 담고 있는 것이 아니라, 다양한 참고 자료와 실행 코드를 유연하게 포함할 수 있습니다. 다음은 스킬의 폴더 구조를 보여줍니다.
그림에서 볼 수 있듯이 pdf 스킬 폴더는 SKILL.md 외에도 참고 자료를 모아둔 references 폴더 다음에 md 파일이 생성되어 있음을 볼 수 있습니다. 또한 코덱스 CLI에게 pdf 작성을 어떻게 할지 가이드하는 forms.md 파일과 코덱스가 실제로 PDF 변환 작업을 수행할 때 실행할 파이썬 스크립트인 convert.py 파일도 생성되어 있습니다. 이처럼 스킬을 활용하면 코덱스에게 가이드뿐만 아니라 어떤 스크립트를 실행해 특정 작업을 수행해야 하는지도 구체적으로 지시할 수 있습니다.
스킬 명령어 사용하기
스킬 명령어를 직접 사용하겠습니다. 여기서는 PDF 작업에 특화된 스킬을 구성하는 실습을 통해 간단한 명령만으로 도구를 호출하고 작업을 실행하는 과정을 통해, 코덱스 에이전트가 어떻게 외부 기능을 활용하는지 살펴봅니다.
01 VSCode에서 ~/.codex/config.toml 파일에 다음 코드를 입력하여 스킬 사용을 허용합니다.
```config.toml
[features]
skills = true
```
02 다음으로 ~/.codex/skills 경로 다음에 example-pdf 폴더를 생성합니다.
03 example-pdf 폴더에 SKILL.md 파일을 작성합니다.
```SKILL.md
---
name: example-pdf
description: Extract text and tables from PDFs; use when PDFs, forms, or document extraction are mentioned.
---
# PDF Processing
- Use pdfplumber to extract text.
- For form filling, see FORMS.md.
SKILL_EXAMPLE
```
위 마크다운 파일을 보면 name과 description이라고 되어 있는 부분이 있습니다. 그리고 위아래가 ---로 둘러싸인 이 부분을 YAML 프런트매터Front-matter 영역이라고 부릅니다. 이곳에는 스킬의 이름과 설명을 작성합니다. name과 description은 중간에 줄 바꿈 없이 작성해야 하며 name은 100자, description은 500자 제한이 있습니다. 프런트매터 아래에는 스킬에 대한 정의와 작업 시 참조해야 하는 파일에 대한 가이드를 작성합니다. 위에서 작성한 SKILL.md에는 FORMS.md를 참조해야 한다고 명시되어 있습니다. 우선 FORMS.md 작성은 생략하고 이렇게 만든 스킬을 코덱스 CLI에서 사용할 수 있는지 확인하겠습니다.
04 코덱스 CLI를 실행하고 /skills 명령어를 입력해 정상적으로 인식되는지 확인합니다.
05 명령어 /skills를 입력하면 입력창에 $ 기호가 자동으로 채워지며, 현재 코덱스에서 사용할 수 있는 스킬 목록이 나타납니다. 매번 /skills 명령어를 입력하는 과정이 번거롭다면 입력창에 바로 $를 사용해 $example-pdf와 같이 스킬을 직접 호출할 수도 있습니다.
06 이제 스킬이 잘 작동하는지 확인하기 위해 임의의 PDF 파일을 요약해 달라고 요청하겠습니다. 이번 실습에서는 오픈AI에서 무료로 제공하는 코덱스 활용 사례 관련 PDF 파일을 내려받아 사용하겠습니다.
코덱스 활용 사례 관련 PDF 파일 : cdn.openai.com/pdf/6a2631dc-783e-479b-b1a4-af0cfbd38630/how-openai-uses-codex.pdf
[나] : $example-pdf ~/Desktop/how-openai-uses-codex.pdf를 요약해줘.
[AI] :
코덱스 CLI는 ~/.codex/skills/ 경로에 저장된 스킬 정보를 이미 파악하고 있습니다. 따라서 사용자가 평소처럼 단순하게 요청해도, 코덱스가 문맥을 분석하여 적절한 스킬을 자동으로 감지하고 실행합니다.
스킬의 4가지 특징 및 MCP와의 차이점
스킬과 MCP는 모두 LLM이 외부 기능을 활용하도록 돕는다는 점에서는 공통적이지만, 역할과 적용 범위에서는 분명한 차이가 있습니다. 특히 스킬은 모델이 ‘어떤 일을 할 수 있는가’에 초점을 둔 실행 단위라면, MCP는 그 스킬과 도구들이 일관되게 연결되도록 돕는 통신 규약에 가깝습니다. 먼저 스킬이 가진 핵심적인 4가지 특징부터 차근차근 살펴보겠습니다.
조합 기능
조합 기능인 Composable으로 여러 스킬을 마치 레고 블록처럼 조립하여 복잡한 작업을 수행할 수 있습니다. 예를 들어 자료 조사 스킬과 보고서 작성 스킬을 함께 사용하여 “자료 조사해서 보고서를 써줘.”라는 복합적인 작업을 명령어 한 번으로 처리할 수 있습니다.
높은 이식성
스킬은 폴더 형태로 구성되어 있습니다. 따라서 한 번 만든 스킬을 다른 동료의 컴퓨터나 다른 프로젝트에서도 그대로 복사해서 사용할 수 있는 높은 이식성Portable을 가집니다. 깃허브에는 이미 수많은 바이브 코더들이 만들어둔 양질의 스킬들이 공유되어 있습니다. 이 스킬들을 코덱스 CLI로 가져와 즉시 활용할 수 있습니다. 이번에는 앤트로픽에서 공식적으로 제공하는 스킬들을 내 코덱스 환경으로 가져와 사용하겠습니다.
01 다음 깃허브 anthropics/skills로 이동한 다음 오른쪽 위에 있는 [<> Code]에서 로컬에 있는 명령어를 복사합니다. 터미널을 열고 복사한 명령어를 입력하여 anthropics/skills 저장소를 내 컴퓨터로 복제하는 작업인 클론을 실행합니다.
깃허브 anthropics/skills : github.com/anthropics/skills
02 클론한 저장소의 skills 폴더 안에 있는 다양한 스킬을 내 코덱스 환경으로 가져오겠습니다. ~/.codex/skills/ 다음에 복사합니다.
03 복사가 완료되면 코덱스 CLI를 실행하여 추가한 스킬들이 정상적으로 인식되고 사용할 수 있는지 확인합니다.
이처럼 다른 사람이 만든 스킬을 팀 내에서 같이 공유하면 구성원 모두가 일관된 경험과 결과를 얻을 수 있습니다. 한 가지 유의해야 할 점은 스킬을 설치했다고 해서 바이브 코딩의 책임이 바이브 코더에서 코덱스로 완전히 넘어간 것은 아닙니다. 다음은 스킬의 선택권을 코덱스에게 완전히 위임하는 프롬프트입니다.
[나] : 이 데이터를 분석해서 광고 포스터를 만들어줘
다음은 명확하게 어떤 스킬을 사용할지 코덱스에게 프롬프트에 직접적으로 알려주는 프롬프트 예시입니다.
[나] : $xlsx를 사용해 엑셀 파일을 분석하고, $canvas-design을 사용해 광고 포스터를 만들어줘.
AI는 도구일 뿐 최종 판단과 책임은 여전히 사용자에게 있습니다. 또한 스킬의 종류가 많아질수록 AI도 헷갈릴 수 있으므로, 명시적으로 스킬 이름을 언급하여 작업을 요청하는 것이 훨씬 효과적입니다.
토큰 효율성을 높이는 스킬 로딩 방식
코덱스에서 사용되는 스킬의 종류가 많아질수록 “사용하지도 않는 스킬의 내용까지 모두 로드해 컨텍스트 윈도우를 낭비하지 않을까?”라는 걱정을 할 수 있습니다. 하지만 실제로는 그런 걱정을 할 필요가 없습니다. 코덱스는 모든 스킬의 상세 내용을 한 번에 읽지 않습니다. 대신, 각 스킬이 어떤 파일에 정의되어 있는지만 SKILL.md 파일을 통해 관리합니다. 예를 들어 다음 그림에 보이는 docx 스킬을 살펴보면 해당 스킬의 핵심 진입점은 docx/SKILL.md 파일입니다. 이 파일에는 워드 문서를 다루는 데 필요한 모든 코드와 설명이 직접 들어 있는 것이 아니라, ooxml/scripts/unpack.py 파일이나 동일 경로에 있는 pack.py 파일, 관련 가이드 문서인 docx-js.md 등과 같이 스킬을 구성하는 실제 파일들의 경로 정보만 정리되어 있습니다.
코덱스는 이 정보를 바탕으로 워드 문서를 읽거나 작성하는 작업이 실제로 필요할 때에만 해당 파이썬 스크립트나 문서를 선택적으로 불러옵니다. 이 구조 덕분에 수천 줄에 달하는 스킬 명세나 코드가 있더라도 컨텍스트를 불필요하게 소모하지 않고, 필요한 순간에 필요한 스킬만 정확히 사용할 수 있습니다. 결과적으로 코덱스는 단순히 마크다운 글을 생성하는 수준을 넘어 docx 스킬처럼 파이썬 스크립트를 실행해 실제 파일을 생성하거나, 문서를 분석·가공하는 실질적인 작업까지 수행할 수 있습니다.
MCP와 스킬, 무엇이 다른가요?
앞서 배운 MCP와 스킬, 두 기술은 어떤 점이 다를까요? 핵심 차이를 비교하겠습니다. MCP와 비교되는 스킬의 가장 큰 특징이자 장점은 단순함입니다. 스킬은 마크다운 파일과 약간의 YAML 메타데이터, 그리고 선택적으로 실행되는 스크립트를 폴더에 저장해두는 것만으로 충분합니다. 이것만으로도 에이전트는 특정 도메인에 특화된 작업을 완벽하게 수행할 수 있습니다. 또한 스킬 폴더를 만들어두면 코덱스 CLI뿐만 아니라 제미나이 CLI, 클로드 코드 등 서로 다른 에이전트 간에도 같은 작업 방식을 준수하여 결과물을 얻을 수 있습니다. 더욱이 마크다운을 에이전트에게 전달하는 방식은 MCP가 생기기 전 우리가 익숙하게 사용하던 프롬프트 엔지니어링과 매우 유사하기 때문에 별도의 복잡한 학습 곡선 없이도 누구나 쉽게 작성할 수 있다는 장점이 있습니다.
반면 MCP는 LLM 애플리케이션과 구글 드라이브, 수파베이스 등 외부 데이터소스 간의 연결을 위한 표준 프로토콜입니다. 때문에 클라이언트, 호스트, 서버, 리소스, 프롬프트, 도구 등 다소 생소하게 느껴질 수도 있는 컴포넌트 개념을 학습해야 합니다. 또한 MCP는 에이전트가 직접 외부 데이터 소스에 접근하고 수만 개의 컨텍스트 토큰을 소비해 문제 해결 방식을 스스로 추론해야 한다는 점에서 토큰 사용량을 많이 차지한다는 지적을 받아왔습니다. 따라서 업계에서는 작업 수행 방법을 설명하고 지시하는 데는 MCP보다 스킬이 컨텍스트 윈도우 사용에 있어 훨씬 효율적이라고 평가합니다.
물론 스킬이 MCP를 완전히 대체하는 것은 아닙니다. 외부 시스템을 연결해 특정 데이터를 불러오거나 작성해야 할 경우, 여전히 MCP는 LLM 애플리케이션과 외부 시스템을 잇는 연결 표준 프로토콜로 유용합니다.