지인이 만든 스킬 파일 몇 개를 폴더째로 받아서 제 코덱스(Codex)에 그냥 복사해 넣어봤습니다. 설치 명령도, 별도 설정도 없이 폴더 하나를 던져놨을 뿐인데 코덱스가 알아서 그걸 인식하고 바로 실행했습니다. 솔직히 좀 놀랐습니다. SKILL.md라는 파일 하나가 든 폴더면 새 능력이 뚝딱 생긴다니 말입니다. 한 번 만들어두면 매번 “이렇게 저렇게 해줘”라고 길게 설명하던 반복 작업을, 이제 코덱스가 알아서 골라 씁니다. 오늘은 지난 7편 마지막에 예고했던 바로 그 기능, 코덱스 스킬(Skill)을 직접 써본 이야기입니다.
7편에서 예약 자동화를 다루면서 “$ 기호는 플러그인이 아니라 스킬을 부를 때 쓰는 건데, 스킬은 8편에서 따로 다룰게요”라고 적어뒀습니다. 그 $가 바로 오늘의 주인공입니다. 자동화가 “정해진 시각에 정해진 일을 시키는 것”이었다면, 스킬은 “코덱스가 할 줄 아는 일 자체를 늘리는 것”에 가깝습니다. 결이 좀 다릅니다.
말로만 들으면 어려워 보이는데, 실제로는 이 시리즈에서 다룬 것 중에 제일 단순한 축이었습니다. 파일 하나만 이해하면 끝입니다. 그럼 이 “파일 하나”가 대체 뭔지부터 풀어보겠습니다.
스킬은 폴더 하나가 전부입니다 — SKILL.md의 정체
코덱스 스킬의 구조는 알고 나면 허무할 만큼 단순합니다. 스킬 하나 = 디렉토리(폴더) 하나입니다. 그 폴더 안에 SKILL.md라는 파일 하나만 있으면 스킬로 인정됩니다. 필요하면 그 안에 스크립트 파일이나 참고용 자료(reference) 파일을 같이 넣을 수도 있습니다. 핵심은 SKILL.md 딱 하나고, 나머지는 전부 선택입니다.
그럼 이 SKILL.md 안에는 뭐가 들었을까요. 크게 두 부분으로 나뉩니다.
- 위쪽 정보 칸(frontmatter) — 이 스킬의
name(이름)과description(설명)을 적는 곳입니다. “이 스킬이 뭐고, 언제 쓰는 건지”를 짧게 적어두는 명찰 같은 것입니다. - 아래쪽 지침 — “이 작업을 할 땐 이런 순서로, 이런 규칙으로 해라”라는 실제 실행 지침을 적는 곳입니다. 코덱스한테 넘겨주는 작업 설명서라고 보면 됩니다.
그러니까 스킬을 만든다는 건 거창한 프로그래밍이 아니라, 반복하던 작업 방식을 글로 한 번 정리해서 SKILL.md에 적어두는 것에 가깝습니다. 코딩을 몰라도 접근할 수 있는 이유가 바로 여기 있습니다.
SKILL.md, 이렇게 생겼습니다
감이 잘 안 잡힐 테니 아주 단순한 예를 하나 들어보겠습니다. 맨 위 정보 칸에 이름을 ‘주간보고정리’, 설명을 ‘매주 흩어진 업무 메모를 정해진 양식의 주간 보고서로 묶습니다’라고 적었다고 해보겠습니다. 그리고 그 아래 지침 칸에는 이렇게 제가 늘 하던 순서를 글로 적는 것입니다.
① 메모를 날짜순으로 정렬합니다 → ② 완료·진행중·보류 세 갈래로 분류합니다 → ③ 각 항목을 한 줄로 요약합니다 → ④ 정해둔 표 양식에 채워 넣습니다
보면 아시겠지만 어려운 코딩 문법이 아니라 그냥 사람이 읽는 설명서입니다. 이 파일 하나가 폴더에 들어가는 순간, 코덱스는 ‘주간보고정리’라는 기술을 새로 하나 배운 셈이 됩니다. 그다음부터는 “이번 주 메모 정리해줘” 한마디면 저 순서대로 알아서 돌아갑니다. 제가 머릿속으로만 반복하던 일 처리 방식을, 코덱스가 대신 외워주는 느낌입니다.
어디에 넣어야 코덱스가 알아볼까요
폴더를 아무 데나 둔다고 인식하진 않습니다. 정해진 자리가 있습니다.
- 개인용 스킬 —
~/.codex/skills/폴더에 넣습니다. 제 PC에서 어느 프로젝트를 작업하든 항상 따라다니는 제 전용 스킬입니다. - 프로젝트 전용 스킬 — 특정 프로젝트 폴더 안
.codex/skills/에 넣습니다. 그 프로젝트에서 일할 때만 쓰이는 스킬입니다.
여기서 편한 점이 하나 있습니다. 코덱스는 지금 작업 중인 폴더에서 시작해 저장소 맨 위 폴더까지 상위 경로를 쭉 훑으면서 스킬을 찾아줍니다. .agents/skills 폴더도 같이 스캔합니다. 그래서 “분명 넣었는데 왜 인식을 못 하지?” 하고 헤맬 일이 별로 없습니다.
제가 받은 건 스킬 폴더 세 개였는데, 세 폴더 모두 SKILL.md에다 스크립트가 담긴 폴더, 참고 자료 폴더, 그리고 agents/openai.yaml까지 나란히 들어 있는 똑같은 형태였습니다. ‘스킬 하나 = 이런 구성의 폴더 하나’라는 공식이 눈으로 확인됐습니다. 세 개를 지정된 자리에 나란히 복사했더니, /skills 목록에 세 개가 한꺼번에 딱 떴습니다. 뭔가 설치 프로그램을 돌리거나 재시작할 필요도 없었습니다.
실제로 부르는 법 — /skills 와 $
이제 넣어둔 스킬을 어떻게 쓸까요. 방법이 세 가지 있습니다.
- 목록으로 확인 — CLI나 IDE에서
/skills를 입력하면 지금 코덱스가 인식하고 있는 스킬 목록이 쭉 나옵니다. “내가 넣은 게 제대로 잡혔나” 확인할 때 제일 먼저 쓰는 명령입니다. - 직접 지목 — 프롬프트에
$를 입력하면 원하는 스킬을 콕 집어 부를 수 있습니다. 7편에서 예고했던 그 기호 맞습니다. 플러그인을 부르는@와 짝을 이루는, 스킬 전용 호출 기호입니다. - 알아서 쓰게 두기 — 사실 제일 신기했던 건 이거였습니다. 굳이 $로 부르지 않아도, 지금 시키는 작업이 어떤 스킬의 설명과 맞아떨어지면 코덱스가 알아서 그 스킬을 골라 씁니다. 명찰(description)을 잘 적어두면, 제가 호출하는 걸 깜빡해도 코덱스가 “아, 이건 이 스킬로 하면 되겠네” 하고 집어 듭니다.
제가 받은 스킬을 처음 돌려봤을 때도 딱 그랬습니다. 특별히 “이 스킬 써”라고 지시한 것도 아닌데, 관련된 작업을 시키니까 코덱스가 스스로 그 스킬을 찾아 실행했습니다. 폴더 하나 복사해 넣은 게 전부인데 말입니다. 이 “알아서 골라 쓰는” 지점이 스킬의 진짜 매력이었습니다.
MCP와 뭐가 다를까요 — 그리고 왜 같이 쓰면 강할까요
여기서 헷갈리기 딱 좋은 지점이 나옵니다. “어? 이거 5편에서 다룬 플러그인이랑 뭐가 다르지?” 싶으실 것입니다. 저도 처음엔 그랬습니다. 둘을 확실히 구분하고 넘어가야 나중에 안 헷갈립니다.
5편에서 다룬 MCP(플러그인) 연결은 외부 시스템에 접속하는 통로입니다. Figma, Linear, GitHub 같은 원격 서비스에 코덱스를 이어주는 다리 역할입니다. “바깥 세계와 연결”이 핵심입니다.
반면 스킬은 반복되는 작업을 재사용 가능한 워크플로우로 묶어두는 것입니다. 바깥과 연결하는 게 아니라, 제가 자주 하는 일의 순서와 규칙을 하나의 묶음으로 포장해두는 것입니다. 이쪽은 “작업 방식의 저장”이 핵심입니다.
정리하면 이렇습니다.
| 구분 | 스킬(Skill) | MCP·플러그인 |
|---|---|---|
| 하는 일 | 반복 작업을 워크플로우로 패키징 | 외부 서비스에 접속 |
| 비유 | 내 작업 방식 설명서 | 바깥 세계로 나가는 다리 |
| 예시 | 보고서 정리 순서, 정해둔 규칙 | Figma·Linear·GitHub 연결 |
| 만드는 법 | SKILL.md 파일 하나 | 서비스 연결·권한 승인 |
중요한 건, 둘이 경쟁 관계가 아니라 같이 쓰면 훨씬 강해진다는 것입니다. 조금 더 그림을 그려보겠습니다. ‘깃허브 이슈를 정해진 양식으로 정리하는 스킬’을 만든다고 해보겠습니다. 이슈를 실제로 가져오는 일은 GitHub이라는 바깥 서비스에 접속해야 하니 이건 MCP의 몫입니다. 반면 ‘가져온 이슈를 어떤 순서로, 어떤 표에 담을지’는 스킬이 담당합니다. 이때 스킬 폴더의 agents/openai.yaml에 “이 스킬은 GitHub MCP 도구가 필요하다”고 한 줄 적어두면, 코덱스가 그 스킬을 쓸 때 필요한 연결까지 알아서 챙깁니다. 통로는 MCP, 순서는 스킬 — 이렇게 역할이 갈립니다.
progressive disclosure — 스킬이 많아져도 안 무거운 이유
스킬을 이것저것 넣다 보면 이런 걱정이 듭니다. “이거 다 켜두면 코덱스가 느려지는 거 아냐?” 저도 그게 궁금했는데, 코덱스는 이 부분에서 꽤 영리하게 굴었습니다.
코덱스는 처음엔 각 스킬의 이름·설명·파일 위치만 기억해둡니다. SKILL.md 안에 적힌 긴 실행 지침 전체를 미리 다 읽어두진 않습니다. 그러다가 “아, 지금 이 작업엔 이 스킬을 써야겠다”고 판단이 서는 순간에만 해당 SKILL.md의 전체 내용을 불러옵니다. 필요할 때만 그 서랍을 여는 방식입니다.
이걸 어려운 말로 점진적 공개(progressive disclosure)라고 부르는데, 용어 자체는 몰라도 됩니다. 핵심만 기억하면 됩니다. 스킬을 열 개, 스무 개 넣어둬도 평소엔 명찰만 훑고 있으니 가볍고, 실제로 쓸 때만 무거운 지침을 펼칩니다. 책상 위에 두꺼운 매뉴얼을 다 펼쳐놓는 게 아니라, 표지 제목만 보고 있다가 필요한 것 한 권만 펴는 셈입니다. 덕분에 “많이 넣어두면 부담되는 거 아냐” 하는 걱정 없이 필요한 스킬을 마음껏 쌓아둘 수 있습니다.
agents/openai.yaml — 이름표와 연결 담당
방금 나온 agents/openai.yaml 파일을 조금만 더 짚고 가겠습니다. 이건 필수가 아니라 선택 사항입니다. 없어도 스킬은 잘 돌아갑니다. 다만 넣어두면 두 가지를 챙길 수 있습니다.
- 보이는 정보 다듬기 — 스킬을 목록에서 어떤 이름으로 보여줄지, 기본 프롬프트는 뭘로 할지 같은 화면상의 힌트를 정해둘 수 있습니다.
- 의존 도구 명시 — 앞서 말한 것처럼, 이 스킬이 어떤 MCP 도구에 기대고 있는지를 적어두는 곳입니다. 코덱스가 이걸 읽고 필요한 연결을 알아서 준비해줍니다.
제가 받은 스킬 폴더에도 이 agents/openai.yaml이 들어 있었는데, 덕분에 제가 따로 손볼 설정이 없었습니다. 만든 사람이 미리 이름표랑 필요한 연결을 다 적어둔 셈이라, 저는 폴더만 제자리에 복사하면 끝이었습니다. 스킬을 “받아서 바로 쓰기” 좋은 형태로 만들 수 있는 게 이 파일 덕분이었습니다. 나중에 누군가에게 제 스킬을 건네줄 때도, 이 파일까지 챙겨두면 받는 쪽이 훨씬 편합니다.
여기까지 오면 스킬이 어렵게 짜인 프로그램이 아니라, 잘 정리된 서류철 한 칸에 가깝다는 게 느껴지실 것입니다. 파일 하나, 이름 하나, 지침 몇 줄. 그게 전부인데도 코덱스가 할 줄 아는 일이 실제로 늘어난다는 게 이 기능의 묘미입니다. 그럼 처음 써볼 때 덜 헤매도록, 알아두면 좋은 실전 팁 몇 가지로 마무리 준비를 해보겠습니다.
처음 쓸 때 알아두면 좋은 것들
막상 써보면 대부분 그냥 됩니다. 그래도 미리 알아두면 덜 헤맬 것들 몇 가지만 짚어보겠습니다.
- 목록에 안 뜨면 위치부터 확인 —
/skills를 쳤는데 제가 넣은 스킬이 안 보이면, 십중팔구 폴더 위치가 지정된 자리(~/.codex/skills/또는 프로젝트의.codex/skills/)가 아닌 경우입니다. 경로만 맞춰주면 대부분 해결됩니다. - 설명(description)에 공을 들이기 — 코덱스가 알아서 스킬을 골라 쓰는 건 전적으로 이 설명을 보고 판단합니다. ‘이것저것 정리’처럼 두루뭉술하게 적으면 엉뚱할 때 튀어나오거나, 정작 필요할 때 안 잡힙니다. ‘언제, 무엇을’ 구체적으로 적을수록 코덱스가 정확히 고릅니다. 스킬을 만들 때 제일 공들일 부분이 사실 이 한 줄입니다.
- $와 @ 헷갈리지 않기 — $는 스킬, @는 플러그인입니다. 7편에서 짚었던 그 구분입니다. 스킬을 부르려다 @를 누르면 엉뚱한 플러그인 목록이 뜨니까 손이 기억할 때까지 잠깐 헷갈릴 수 있습니다.
- 스킬 자체엔 추가 결제가 없음 — 스킬은 그냥 파일일 뿐이라 따로 비용이 붙지 않습니다. 다만 코덱스를 돌리는 것 자체가 ChatGPT Plus 이상 유료 구독이 필요하다는 건 이 시리즈 내내 같습니다. 이미 Plus를 쓰고 있다면 스킬은 그 위에 얹어 씁니다.
그래서 이건 누구한테 좋을까요
솔직하게 말하면, 스킬은 모두에게 당장 필요한 기능은 아닙니다. 코덱스를 이따금 한 번씩 쓰는 정도라면 굳이 스킬까지 안 만들어도 됩니다. 그런데 다음에 해당하는 분이라면 얘기가 좀 달라집니다.
같은 작업을 매번 반복하는 사람. 매번 코덱스에게 “이건 이렇게, 저건 저렇게” 똑같은 규칙을 반복해서 설명하고 있다면, 그 설명을 SKILL.md 하나에 적어두는 게 훨씬 낫습니다. 한 번 적어두면 다음부턴 코덱스가 알아서 그 방식대로 일합니다. 매번 처음부터 설명하던 그 수고가 통째로 사라집니다.
팀이나 지인과 작업 방식을 공유하고 싶은 사람. 제가 오늘 경험한 게 딱 이거였습니다. 누군가 정리해둔 스킬 폴더를 그대로 받아서 복사만 하면, 그 사람의 작업 방식이 제 코덱스에도 똑같이 생깁니다. 설치 과정도, 복잡한 세팅도 없습니다. 폴더 하나 주고받으면 끝입니다. 잘 만든 작업 방식을 파일 하나로 나눠 가질 수 있다는 게, 써보니 생각보다 큰 장점이었습니다.
그럼 스킬과 MCP, 언제 뭘 써야 할까요. 간단합니다. 바깥 서비스에 연결해야 하면 MCP(플러그인), 제 작업 순서를 저장하고 싶으면 스킬. 그리고 “이 순서대로 일하되 중간에 외부 도구도 써야 한다”면 둘을 합칩니다. 그 합치는 지점이 바로 아까 본 agents/openai.yaml입니다.
이번 편까지 오면서 1편에서 설치와 첫 화면을 잡고, 5편에서 외부 연결을, 7편에서 자동화를 다뤘는데, 스킬은 그 위에 얹는 마지막 확장 같은 느낌입니다. 더 깊게 파고 싶은 분은 OpenAI 코덱스 공식 스킬 문서에 구조와 예시가 정리돼 있으니 한 번 보시길 권합니다.
폴더 하나 복사해 넣었더니 새 능력이 생기던 그 순간이 아직도 좀 신기합니다. 거창한 설치나 코딩 없이, SKILL.md 한 장으로 코덱스가 할 줄 아는 일이 늘어난다는 것. 반복 작업에 지쳐 있던 분이라면, 오늘 딱 하나만 만들어봐도 그 편함을 바로 느끼실 것입니다.
