SKILL.md란? Codex 스킬 파일 구조와 작성·적용 확인법
Codex에게 홈페이지 수정을 부탁할 때마다 이런 말을 반복한 적 있나요?
“수정한 파일부터 확인해 줘. 모바일에서도 깨지지 않는지 살펴보고, 테스트를 실제로 돌렸는지 구분해서 보고해 줘.”
이런 작업 기준을 매번 긴 대화로 설명하는 대신 파일 하나에 정리해 두는 방법이 있습니다. 바로 SKILL.md입니다.
SKILL.md는 Codex 같은 AI 작업 도구가 특정 업무를 어떤 순서로 처리할지 설명하는 스킬(Skill)의 핵심 문서입니다. 쉽게 말해 AI에게 건네는 작업별 안내서입니다.
이 글에서는 플러그인이나 스킬 전체 기능을 넓게 소개하기보다, SKILL.md 파일 안에 무엇이 들어가고, 어떻게 작성하며, 읽혔는지 어떻게 확인하는지에 집중합니다.
이 글의 순서
- 1. SKILL.md 는 정확히 어떤 파일인가요?
- 2. SKILL.md 는 폴더 어디에 두나요?
- 3. 파일 안에는 무엇을 적어야 할까요?
- 4. name과 description은 어떻게 다를까요?
- 5. SKILL.md 하나면 충분한가요?
- 6. Codex는 SKILL.md 를 매번 통째로 읽나요?
- 7. SKILL.md 와 AGENTS.md 는 무엇이 다를까요?
- 8. 작성한 SKILL.md 가 실제로 인식되는지 확인하는 방법
- 9. 파일을 만들었는데 작동하지 않는다면?
- 10. 다른 사람이 만든 SKILL.md 도 믿고 사용해도 될까요?
- 11. 자주 묻는 질문(FAQ)
- 핵심 정리
- 함께 보면 좋은 글
1. SKILL.md는 정확히 어떤 파일인가요?
이름을 세 부분으로 나누면 쉽습니다.
- SKILL: 한 가지 업무를 잘 처리하도록 정리한 스킬.
- .md: 마크다운(Markdown)으로 작성된 일반 텍스트 파일이라는 뜻.
- 파일 전체: 스킬을 식별하는 정보와, 실제 수행할 절차가 함께 들어 있는 문서.
예를 들어 식당 주방에 '재료 손질 → 조리 → 위생 점검' 순서를 적은 작업 안내서가 있다고 생각해 보세요. 요리사가 필요할 때 그 안내서를 읽는 것처럼 Codex도 상황에 맞는 스킬 지침을 참고할 수 있습니다.
그러나 종이 안내서 자체가 요리를 하지는 못하듯,
SKILL.md만 만든다고 파일이 자동으로 수정되거나 웹사이트가 게시되는 것은 아닙니다. Codex에 해당 파일이 발견될 수 있어야 하고, 실제 작업 도구와 권한도 필요합니다.
2. SKILL.md는 폴더 어디에 두나요?
프로젝트 안에 별도의 스킬 폴더를 두는 방식이 있습니다. 예를 들어 개인 홈페이지의 변경 사항을 검수하는 스킬을 만든다면 다음과 같은 구조를 사용할 수 있습니다.
my-site/
├── index.html
└── .agents/
└── skills/
└── site-change-review/
└── SKILL.md
여기서 꼭 기억할 것은 폴더 이름은 스킬 이름, 파일 이름은 SKILL.md라는 점입니다.
my-site/: 설명을 위한 가상 웹사이트 프로젝트..agents/skills/: 프로젝트용 스킬을 두는 폴더의 한 예시.site-change-review/: '웹사이트 변경 검수'라는 스킬 이름.SKILL.md: 해당 스킬의 동작 원칙과 절차를 적는 필수 문서. 주의: 위 경로는 Codex 프로젝트에서 쓸 수 있는 예시입니다. 모든 AI 앱이나 모든 컴퓨터에서 언제나 같은 경로를 사용하는 것은 아닙니다. 사용 중인 Codex 버전과 개인·프로젝트별 스킬 설정을 확인하세요.
3. 파일 안에는 무엇을 적어야 할까요?
기본적으로 두 부분이 있습니다. 윗부분은 스킬을 소개하는 정보, 아랫부분은 실제 작업 절차입니다. 가장 간단한 형태는 다음과 같습니다.
---
name: site-change-review
description: Review website changes before publishing. Use when asked to inspect edited files, links, or mobile layout.
---
# 홈페이지 변경 검수
## 확인 순서
1. 사용자가 요청한 수정 범위를 확인한다.
2. 실제로 변경된 파일을 찾는다.
3. 내부 링크와 모바일 화면 문제를 점검한다.
4. 실제 실행한 테스트와 미실행 항목을 구분해 보고한다.
## 완료 보고
- 확인한 파일
- 발견한 문제
- 실행한 테스트와 결과
- 아직 확인하지 못한 사항
이 코드는 그대로 읽어 볼 수 있는 작성 예시이지, 이 글에서 실제로 설치해 실행한 결과가 아닙니다.
처음과 세 번째 줄의 --- 사이를 YAML 프런트매터(front matter)라고 부릅니다. 그 아래는 일반적인 Markdown 지침 본문입니다.
특히 name과 description이 중요합니다. Codex는 스킬을 고를 때 이 이름과 설명을 참고하므로, '무엇을 하는 스킬이며 언제 사용해야 하는지'가 분명해야 합니다.
4. name과 description은 어떻게 다를까요?
두 항목은 비슷해 보여도 역할이 다릅니다.
| 항목 | 의미 | 작성 예 |
|---|---|---|
name |
스킬을 구분하는 짧은 이름 | site-change-review |
description |
언제 사용할지 판단하는 설명 | 홈페이지 변경 검수를 요청받을 때 사용 |
나쁜 설명의 예는 description: Helps with coding.입니다. '코딩에 도움을 준다'는 말만으로는 언제 이 스킬이 필요한지 알기 어렵습니다.
조금 더 나은 설명은 다음과 같습니다.
name: site-change-review
description: Check changed website files, links, and mobile layout before release. Use when the user requests a site review or publishing readiness check.
이렇게 써 두면 어떤 작업에 적용할지가 더 명확해집니다. 다만 설명이 좋다고 스킬이 반드시 호출되거나 검사가 자동으로 통과하는 것은 아닙니다.
description은 작업 선택을 돕는 정보이고, 실제 검사 기준과 보고 양식은 그 아래의 Markdown 본문에 적습니다.
5. SKILL.md 하나면 충분한가요?
간단한 스킬이라면 그럴 수 있습니다. 하지만 복잡한 작업에는 추가 파일이 필요할 수 있습니다.
site-change-review/
├── SKILL.md
├── references/
│ └── review-rules.md
├── scripts/
│ └── check-links.py
└── assets/
└── report-template.md
예를 들면 다음과 같은 차이가 있습니다.
SKILL.md: 작업을 시작하고 끝내는 기준, 전체 진행 순서.references/: 자세한 품질 기준, 체크리스트 같은 참고 문서.scripts/: 필요한 환경에서 실행할 수 있는 검증용 프로그램.assets/: 결과 보고서 서식처럼 작업 결과에 활용할 자료. 추가 폴더는 모두 필수가 아닙니다. 처음부터 복잡하게 만들 필요 없이SKILL.md하나로 시작한 뒤 실제로 필요한 자료만 나누세요. 특히scripts/에 파일이 있다는 사실만으로 명령이 실행되는 것은 아닙니다. 스크립트 실행에는 별도 환경과 권한이 필요합니다.
6. Codex는 SKILL.md를 매번 통째로 읽나요?
그렇지는 않습니다. 공식 설명의 기본 개념은 먼저 스킬의 이름과 설명을 확인하고, 요청과 맞는 경우 자세한 지침을 불러오는 방식입니다. 예를 들어 사용자가 “블로그 문장을 자연스럽게 고쳐 줘”라고 요청했다면, 웹사이트 배포 전 검수 스킬이 항상 필요한 것은 아닙니다. 반대로 “홈페이지 변경 파일을 검수해 줘”라는 요청이라면 해당 스킬을 사용할 가능성이 더 큽니다. 따라서 다음 세 가지는 서로 구분해야 합니다.
- 컴퓨터에
SKILL.md파일이 존재한다. - 현재 Codex 환경에서 그 스킬을 발견하고 사용할 수 있다.
- 이번 요청에 해당 스킬이 실제로 적용되었다. 첫 번째가 참이어도 두 번째·세 번째까지 보장되지는 않습니다.
7. SKILL.md와 AGENTS.md는 무엇이 다를까요?
두 문서 모두 AI 작업을 돕지만 목적을 구분하면 편리합니다.
| 문서 | 어울리는 내용 |
|---|---|
AGENTS.md |
프로젝트 전체에 적용하려는 기본 작업 규칙 |
SKILL.md |
특정 상황에서 수행할 재사용 작업 절차 |
예를 들어 AGENTS.md에는 '사용자가 승인하기 전에는 사이트를 배포하지 않는다'는 프로젝트 공통 규칙을 둘 수 있습니다.
반면 site-change-review/SKILL.md에는 '변경 파일 목록 확인 → 링크 점검 → 모바일 검사 → 결과 보고'처럼 변경 검수 작업에만 필요한 상세 단계를 담는 편이 자연스럽습니다.
두 문서에 긴 규칙을 중복 작성하면 나중에 어느 쪽이 최신인지 헷갈릴 수 있습니다. 공통 원칙과 개별 작업 절차를 나누는 것이 핵심입니다.
8. 작성한 SKILL.md가 실제로 인식되는지 확인하는 방법
파일을 저장했다면 '잘 만들었겠지'라고 추측하지 말고 단계적으로 확인하세요.
첫 번째: 경로와 파일명을 확인합니다. 프로젝트 루트를 잘못 잡았거나 SKILL.md의 철자가 다르면 찾지 못할 수 있습니다.
두 번째: 내용의 맨 위를 확인합니다. --- 사이에 name과 description이 적절하게 들어 있는지 살펴보세요.
세 번째: Codex에 다음처럼 요청합니다.
이 프로젝트에서 site-change-review 스킬을 사용할 수 있는지 확인해 줘. 가능하다면 어떤
SKILL.md를 참고하는지와 적용할 작업을 설명해 줘. 아직 파일을 수정하거나 배포하지 마. 네 번째: 실제 작업과 별도로 읽기 전용 검수를 요청합니다. site-change-review 절차를 참고해서 변경한 웹페이지를 검토해 줘. 접근 가능한 파일부터 확인하고, 실제로 실행한 테스트와 실행하지 못한 테스트를 구분해서 보고해 줘. 배포하지 마. 다섯 번째: 결과에 근거가 있는지 확인합니다. 스킬 이름을 언급했다는 사실, 실제 파일을 열었다는 사실, 브라우저에서 모바일 화면을 검증했다는 사실은 서로 다릅니다. 필요하면 새 세션에서 스킬 목록을 다시 확인하세요. 정확한 표시 방법은 사용 중인 Codex 제품과 버전에 따라 다를 수 있습니다.9. 파일을 만들었는데 작동하지 않는다면?
처음에는 아래 문제부터 의심해 볼 수 있습니다. '
SKILL.md를 저장했는데 스킬이 안 보여요.' 프로젝트 폴더가 맞는지, 파일 이름의 대소문자가 정확한지, 스킬 폴더를 잘못 중첩하지 않았는지 확인합니다.name·description의 오타와 형식도 점검하세요. '스킬을 사용하라고 했는데 엉뚱한 작업을 해요.' 설명에 적용 시점이 너무 넓거나 모호할 수 있습니다.description에 언제 사용하고 어떤 결과를 만드는지 더 구체적으로 적어 보세요. 해당 작업을 명시적으로 요청하는 것도 도움이 됩니다. '모바일 검사를 하라고 썼는데 실제 화면 검사가 없어요.'SKILL.md에 '모바일 확인'을 적었다고 해서 브라우저나 화면 검사 도구가 자동으로 생기는 것은 아닙니다. 사용 가능한 실행 환경이 없으면 미검증으로 남기고, 추후 실제 검사해야 합니다. '배포 금지라고 적었으니 완전히 안전하겠죠?' 문서의 안내 문장은 실제 실행 권한 차단과 다릅니다. GitHub 푸시·파일 삭제·게시 등 영향 있는 행동에는 별도의 권한 설정과 사람의 승인이 중요합니다.10. 다른 사람이 만든
SKILL.md도 믿고 사용해도 될까요?내용을 읽지 않고 곧바로 실행하게 하는 것은 피하는 편이 좋습니다. 공개된 스킬에는 단순한 업무 설명뿐 아니라 셸 명령, 패키지 설치, 외부 서버 연결을 요구하는 지침이 담길 수도 있습니다. 이런 문서가 사용자에게 허용되지 않은 작업을 유도하지 않는지 먼저 확인해야 합니다. 특히 비밀번호·API 키·개인정보를 파일에 넣으라고 요구하거나, 검사와 관계없는 외부 주소로 자료를 보내라고 한다면 사용 전에 검토해야 합니다. 좋은 스킬의 기준은 '무슨 일이든 자동으로 해 준다'가 아닙니다. 수행 범위, 필요한 도구, 완료 기준, 사람이 승인할 지점이 분명한가가 더 중요합니다.
11. 자주 묻는 질문(FAQ)
Q1.
SKILL.md를 만들려면 코딩을 알아야 하나요?기본적인 파일은 일반 텍스트 편집기로 만들 수 있습니다. 마크다운 문법과 맨 위 YAML 구조만 이해하면 짧은 스킬 안내서를 작성할 수 있습니다. 다만 스크립트를 포함한 복잡한 작업은 추가 지식이 필요할 수 있습니다.
Q2.
SKILL.md와 일반 프롬프트는 똑같나요?둘 다 AI에게 작업 방법을 설명하지만, 프롬프트는 지금 하는 요청,
SKILL.md는 여러 작업에서 다시 활용할 수 있도록 보관하는 작업 지침 파일에 가깝습니다.Q3.
SKILL.md만 복사하면 다른 사람도 똑같은 결과를 얻나요?보장할 수 없습니다. 사용하는 Codex 버전, 프로젝트 내용, 연결 도구, 권한, 실제 데이터가 다를 수 있기 때문입니다. 다른 환경에서는 다시 검증해야 합니다.
Q4.
SKILL.md안에 API 키를 직접 넣어도 되나요?권장하지 않습니다. 스킬 파일이 다른 사람과 공유되거나 저장소에 올라갈 수 있으므로, 실제 비밀키는 적절한 자격증명 관리 방식으로 분리해야 합니다.
Q5. 스킬을 만든 순간 테스트도 자동으로 통과하나요?
아닙니다. 스킬은 어떻게 확인할지를 안내합니다. 실제 테스트를 실행하고 결과를 검증하는 일은 별도입니다.
Q6. 모든 업무를 하나의
SKILL.md에 적는 편이 좋나요?대개는 그렇지 않습니다. 웹페이지 검수, 자료 조사, 보고서 작성처럼 목적이 다른 업무는 스킬을 나누는 편이 적용 시점과 유지보수 측면에서 이해하기 쉽습니다.
핵심 정리
SKILL.md는 특정 일을 반복해서 잘 처리하도록 작업 방법을 정리해 둔 AI용 안내서입니다. 파일의 맨 위name과description은 스킬이 언제 필요할지를 알리는 역할을 하고, 그 아래 Markdown 본문은 실제 작업 순서와 보고 형식을 설명합니다. 처음 시작할 때는 간단한 검수 스킬 하나면 충분합니다. 파일 저장 → 스킬 인식 확인 → 작은 작업에서 적용 → 실행 증거 확인 순서로 시험해 보세요. 그리고 가장 중요한 점을 기억하세요.SKILL.md의 지침, 실제 프로그램의 실행 권한, 사람이 확인해야 하는 결과는 서로 다릅니다. 이 차이를 이해하면 스킬을 훨씬 안전하고 효율적으로 사용할 수 있습니다.