Codex 스킬과 SKILL.md 이해하기: 반복 업무를 한 번만 설명하는 법

요약: 스킬은 반복 업무에 필요한 절차와 결과 형식을 재사용하도록 정리한 묶음입니다. 처음에는 한 가지 일을 위한 짧은 SKILL.md부터 작성해 보세요.

1. 스킬은 언제 유용할까?

매번 문서 검토를 부탁하면서 “오래된 명령을 찾아라, 코드와 설명을 비교해라, 결과를 표로 정리해라”를 반복한다면 이를 스킬로 정리할 수 있습니다. 프롬프트를 저장하는 것에서 한 단계 더 나아가, 사용할 때와 필요한 입력, 처리 절차, 결과 형식을 함께 묶는 방식입니다.

OpenAI 공식 설명에 따르면 스킬은 특정 작업의 지침과 보조 자료를 묶으며, 플러그인은 스킬이나 연결 도구 등을 포함할 수 있는 설치 가능한 묶음입니다. 따라서 스킬 이름이 있다고 외부 서비스 접속 기능이 반드시 생기는 것은 아닙니다. 절차가 있는지와 실제 사용할 도구가 있는지를 구분해야 합니다.

2. SKILL.md의 기본 구조

공식 작성 문서는 스킬 폴더 안에 SKILL.md를 두고 name과 description을 포함하도록 안내합니다. 필요한 경우 스크립트, 참조 자료, 템플릿 등을 추가할 수 있습니다. 처음에는 실행 코드 없이 업무 지침만 작성해도 됩니다.

---
name: docs-check
description: 프로젝트 문서의 명령과 경로를 검토하고 차이를 보고할 때 사용합니다.
---

프로젝트 문서 검토 지침

입력:
- 검토할 문서 경로
- 비교할 프로젝트 설정과 소스

수행:
1. 문서에 적힌 경로와 명령의 근거를 확인합니다.
2. 실제 프로젝트 설정과 다른 내용을 찾습니다.
3. 직접 확인한 사실과 추가 확인이 필요한 내용을 구분합니다.
4. 이 작업에서는 파일을 수정하지 않습니다.

출력:
- 문서 위치 / 차이 / 근거 / 권장 수정
- 검토하지 못한 범위

이 예시는 가상의 문서 검토 스킬입니다. 설치되어 있거나 실행해 본 스킬을 소개하는 것이 아니므로 실제 프로젝트에서 동작을 확인한 뒤 사용해야 합니다. 자동 수정까지 원한다면 그 단계와 변경 경계를 별도로 설계하세요.

3. description에는 사용하는 순간을 적기

“개발을 도와주는 최고의 스킬” 같은 문구는 어떤 요청에서 적용해야 하는지 알려 주지 못합니다. “README에 있는 실행 명령과 프로젝트 설정을 비교할 때 사용”처럼 상황을 적어 보세요. 비슷한 스킬이 여러 개라면 문서 검토와 코드 리뷰의 범위도 구분하는 것이 좋습니다.

본문에는 자신이 원하는 결과를 분명히 남깁니다. 문서의 문체를 고치는 것이 목적이라면 근거 확인보다 문장과 독자가 중심일 수 있습니다. 코드와 문서의 불일치를 찾는 작업이라면 경로와 설정이 중심입니다. 서로 다른 일을 하나의 거대한 스킬에 넣기보다 명확한 작업 하나로 시작하면 사용 결과를 평가하기 쉽습니다.

4. 불러온 뒤 기대한 방식으로 작동하는지 확인하기

공식 문서는 Codex에서 스킬을 명시적으로 선택하거나, 요청이 설명과 맞을 때 자동으로 적용할 수 있다고 안내합니다. CLI와 IDE에서는 $ 멘션 등 해당 환경의 선택 방법을 확인하세요. 로컬 스킬 경로도 현재 공식 문서의 안내를 따라야 하며, 예전 글에서 본 위치가 계속 같을 것이라고 가정하지 마세요.

$docs-check
README.md의 실행 안내를 검토해 주세요.
package.json과 관련 설정을 근거로 비교하고,
문서 위치, 차이, 근거, 권장 수정을 표로 정리해 주세요.
파일은 수정하지 말고 미확인 사항을 표시해 주세요.

첫 사용에서는 스킬이 필요한 문서를 읽는지, 약속한 형식으로 결과를 내는지, 하지 말라고 정한 변경을 하는지 확인합니다. 없는 파일을 실제로 읽었다고 보고하지 않는지도 점검하세요. 결과가 어긋나면 지침을 한 번에 길게 늘리기보다 잘못된 판단의 원인이 되는 부분을 보완하는 편이 관리하기 좋습니다.

5. 스킬이 기대대로 적용되지 않을 때

• 선택되지 않음: 설치 상태와 설명 문구가 실제 요청에 맞는지 확인합니다.
• 다른 스킬과 혼동됨: 이름과 적용 범위를 구분합니다.
• 지침이 너무 넓음: 입력, 완료 기준, 결과 형식을 한 업무에 맞춥니다.
• 외부 자료를 못 읽음: 스킬 지침과 실제 도구·접근 권한을 별도로 확인합니다.
• 결과를 비교하기 어려움: 근거 위치와 미확인 범위를 출력에 포함합니다.

남이 만든 스킬을 가져올 때는 지침과 포함된 스크립트를 확인하세요. 특정 업무의 지침을 재사용하는 것과 실행 권한을 넓히는 것은 다른 결정입니다. 처음에는 결과를 초안으로 확인할 수 있는 작업을 대상으로 설계하면 검토할 기준을 정하기 쉽습니다.

6. 프로젝트 안에 첫 스킬을 배치하기

처음 만드는 문서 검토 스킬은 프로젝트 안에 두면 지침과 코드의 변경을 함께 관리하기 쉽습니다. 현재 공식 문서는 저장소에서 .agents/skills 경로를 사용하는 로컬 스킬 탐색을 안내합니다. 다음은 저장소 루트에 docs-check 스킬을 배치하는 예시입니다. 상위 폴더와 사용자 범위에도 스킬이 있을 수 있으므로 같은 이름의 기존 스킬이 있는지 먼저 살펴보세요.

project/
  .agents/
    skills/
      docs-check/
        SKILL.md
  README.md
  package.json
  docs/

Windows PowerShell에서 폴더를 준비하려면 아래 명령을 사용할 수 있습니다. 먼저 프로젝트 루트에 있는지 확인하고, 생성한 폴더의 SKILL.md에 앞 절의 지침을 저장하세요. 아래 명령은 스킬 폴더를 만드는 예시이며 이 글에서 실제로 설치한 결과를 뜻하지 않습니다.

Get-Location
New-Item -ItemType Directory -Force -Path '.agents\skills\docs-check'
Get-ChildItem -LiteralPath '.agents\skills\docs-check'

스킬을 저장한 뒤에는 현재 클라이언트에서 선택 가능한지 확인합니다. 공식 문서는 Codex가 스킬 변경을 감지하고, 반영이 보이지 않을 때 재시작하도록 안내합니다. CLI에서는 /skills나 $ 멘션으로 직접 선택할 수 있습니다. 선택 목록에 안 보이면 파일명, name·description 메타데이터, 저장 위치부터 점검하세요. 스킬 본문을 더 길게 쓰는 것으로 설치 위치 오류를 해결할 수는 없습니다.

7. 이름과 설명을 업무 범위에 맞추기

스킬은 우선 이름과 설명으로 어떤 업무에 필요한지 판단됩니다. 본문에 훌륭한 절차가 있어도 설명이 “문서 관련 작업”뿐이면 작성·번역·요약·검토 중 어느 요청에 쓰는지 구분하기 어렵습니다. 한 업무의 시작 조건과 제외할 업무를 설명에 넣으면 적용 범위를 명확하게 만들 수 있습니다.

넓은 설명:
문서 작업을 도와주는 스킬입니다.

구체적인 설명:
README나 docs의 실행 명령·로컬 경로를
현재 프로젝트 설정과 비교해 오류를 보고할 때 사용합니다.
문체 수정·번역·외부 웹사이트 전체 검사는 대상으로 하지 않습니다.

실제 description은 YAML 메타데이터에서 올바른 문자열 형식으로 작성하세요. 길이를 늘리는 것보다 “언제 사용하고 무엇을 하지 않는가”가 먼저 읽히도록 적는 것이 좋습니다. 비슷한 이름의 스킬을 여러 개 만들기보다 docs-check처럼 역할을 찾을 수 있는 이름을 사용하고, 이미 같은 이름이 있으면 다른 명칭을 정할 수 있습니다. 공식 문서는 같은 이름의 스킬이 자동으로 합쳐지는 방식이 아니라고 안내합니다.

본문에는 판단해야 하는 선택을 남기세요. “모든 링크를 확인한다”는 말은 로컬 파일 경로와 외부 URL에 같은 방법을 적용하게 만들 수 있습니다. 로컬 경로는 저장소에서 존재 여부를 보고, 외부 URL은 현재 작업에서 웹 접근이 가능한지 먼저 구분합니다. 외부 검사를 범위에서 제외했다면 미검사라고 표시하면 됩니다. 접근하지 못한 자료를 정상으로 보고하지 않도록 결과 형식에 빈칸의 의미를 정하세요.

8. 문서 검토를 근거가 있는 보고로 만드는 절차

가상의 README에 npm run start가 적혀 있지만 현재 package.json에는 dev와 test만 있다고 가정하겠습니다. 이때 “start가 없다”는 사실과 “dev로 바꾸면 된다”는 제안은 구분해야 합니다. 개발 서버 시작 안내를 검토하는 것이라면 dev가 후보가 될 수 있지만, 운영 서버 시작 안내라면 다른 명령과 빌드 절차가 필요할 수 있습니다. 스크립트 이름만 비슷하다고 무조건 대체하지 마세요.

문서 검토 세부 절차
1. 문서에서 실행 명령과 로컬 파일 경로를 추출합니다.
2. 실행 명령은 해당 프로젝트 설정과 README 맥락을 함께 비교합니다.
3. 경로는 문서가 기준으로 삼는 폴더를 확인하고 존재 여부를 조사합니다.
4. 일치·불일치·미확인으로 구분합니다.
5. 불일치는 근거 파일과 필요한 수정안을 함께 보고합니다.
6. 판단 자료가 없으면 확인할 자료를 적고 문서를 임의로 수정하지 않습니다.

실패 분기
- 대상 문서 없음: 정확한 경로를 요청하고 검토 미실행으로 보고
- 설정 파일 없음: 다른 언어나 도구의 설정 위치를 조사
- 외부 링크 접근 불가: 실패와 미검사를 구분
- 명령의 목적 불분명: 개발·빌드·운영 중 용도를 확인

결과 표에는 위치와 근거를 넣어야 사람이 수정할 수 있습니다. “README가 오래됐습니다”는 발견 내용이 넓어서 다음 행동을 정하기 어렵습니다. “개발 서버 실행 절의 start 스크립트가 현재 설정에 없으며 dev의 역할을 확인해야 합니다”처럼 문서 위치와 판단을 연결하세요. 직접 명령을 실행하지 않았다면 스크립트 존재 확인과 실행 성공을 분리해야 합니다.

9. 스킬을 평가하고 고치는 작은 사례 모음

처음 스킬을 평가할 때는 같은 문서 한 번만 검토하지 말고 서로 다른 작은 상황을 넣어 보세요. 정상 안내, 존재하지 않는 명령, 문서가 없는 요청, 스킬 범위 밖의 요청을 구분하면 어디에서 판단이 어긋나는지 알 수 있습니다. 다음은 실행 결과가 아니라 평가할 입력과 기대 기준의 예시입니다.

• 정상 README: 없는 문제를 만들지 않고 확인한 근거를 보고하는가?
• 없는 스크립트: 설정에서 찾지 못했다는 사실과 수정 제안을 나누는가?
• 문서 경로 오류: 다른 파일을 대신 읽고 정상 검토한 것처럼 보고하지 않는가?
• 문체 수정 요청: 이 스킬의 검토 범위와 구분하는가?
• 외부 자료 미접근: 정상으로 단정하지 않고 미확인으로 표시하는가?

$docs-check
README.md의 개발 실행 안내와 로컬 설정 경로를 검토하세요.
문서 위치 | 일치 여부 | 실제 확인 근거 | 수정 제안 형식으로 보고하세요.
명령을 실행하지 않았다면 실행 성공으로 표현하지 마세요.
파일 수정은 하지 말고 필요한 다음 확인을 적어 주세요.

결과가 틀렸다면 잘못된 부분 하나에 대응하는 규칙만 보완합니다. 외부 URL을 읽지 못했는데 정상이라고 보고했다면 “외부 자료 미검사 표시”를 추가하면 됩니다. 특정 스크립트의 용도를 오해했다면 명령의 목적을 함께 비교하는 절차를 보완하세요. 실패할 때마다 긴 금지 문장을 더하면 정작 정상 작업 순서가 안 보일 수 있습니다.

절차가 안정된 뒤 보조 자료나 스크립트를 검토하세요. 사람이 고칠 표를 만드는 업무는 지침만으로 시작할 수 있습니다. 많은 파일에서 같은 경로를 추출하는 작업처럼 반복 계산이 분명해졌을 때 스크립트가 도움이 될 수 있습니다. 스크립트를 넣었다면 어떤 입력을 받고 어떤 파일을 바꾸는지 스킬 문서에 적어 결과를 검토할 수 있게 만드세요.

10. 자주 묻는 질문

스킬을 만들면 모델이 학습하나요? 이 글에서 다루는 스킬은 재사용할 지침과 자료를 제공하는 방식입니다. 모델을 별도로 학습시키는 절차로 이해하지 마세요.

스크립트가 꼭 필요한가요? 반복 절차와 결과 형식을 전달하는 업무는 지침만으로 시작할 수 있습니다. 계산이나 외부 도구가 필요한 경우에 추가를 검토하세요.

프로젝트 규칙도 전부 스킬로 만들까요? 모든 작업에 적용할 공통 규칙과 특정 업무에서만 필요한 절차를 구분하면 문서 관리가 쉬워집니다. 스킬에는 그 업무를 선택했을 때 필요한 내용부터 담으세요.

공식 출처 및 확인일: OpenAI 공식 문서: Skills & Plugins · OpenAI 공식 문서: Build skills. 2026년 10월 3일 확인. 예시는 자신의 프로젝트와 현재 기능에 맞게 조정하세요.