AGENTS.md와 SKILL.md의 차이: Codex에는 무엇을 어디에 써야 할까

이 글에서 사용하는 주요 용어 정의

용어	정의
AGENTS.md	Codex가 저장소에서 지속적으로 따라야 할 규칙과 작업 정보를 적는 프로젝트 지침 파일
SKILL.md	특정 요청에 맞는 반복 작업 절차와 참고 자료를 묶는 Skill의 핵심 파일
Skill metadata	Skill 이름과 호출 조건을 설명해 Codex가 관련성을 판단하게 하는 정보
Plugin	Skill과 외부 서비스 연결, 도구 등을 함께 배포할 수 있는 설치형 번들

---

도입

AGENTS.md와 SKILL.md는 모두 Codex에게 지침을 전달하지만 역할은 다릅니다. AGENTS.md는 이 저장소에서 항상 지켜야 할 규칙, SKILL.md는 특정 작업을 수행할 때 불러오는 절차에 가깝습니다.

두 파일의 차이를 모르고 모든 내용을 한곳에 넣으면 프로젝트 지침은 길어지고, 작업과 무관한 절차까지 매번 컨텍스트를 차지합니다. 반대로 반드시 지켜야 할 규칙을 Skill에만 넣으면 해당 Skill이 선택되지 않은 요청에서 규칙이 빠질 수 있습니다.

기준일: 2026년 7월 31일. Codex의 설정 형식은 바뀔 수 있으므로 실제 적용 전 최신 공식 문서를 확인하세요.

AGENTS.md와 SKILL.md는 어떻게 다른가

AGENTS.md는 프로젝트의 기본 규칙이다

AGENTS.md에는 저장소에서 계속 적용할 내용을 적습니다. 사용하는 언어, 테스트 명령, 파일 배치, 보안 원칙처럼 작업 종류가 달라도 유지돼야 하는 정보가 적합합니다.

예를 들어 IT 블로그 프로젝트라면 다음처럼 쓸 수 있습니다.

# 프로젝트 규칙

- 한국어로 작성한다.
- 최신 API 정보는 공식 문서에서 확인한다.
- 실행하지 않은 코드를 검증했다고 표현하지 않는다.
- 완성 원고는 output/drafts에 저장한다.

Codex 공식 매뉴얼에 따르면 루트의 AGENTS.md는 프로젝트 지침으로 사용되고, 하위 디렉터리에 더 가까운 지침 파일이 있으면 해당 범위에서 우선할 수 있습니다. 하나의 저장소 안에서도 프런트엔드와 백엔드 규칙을 나눌 수 있는 이유입니다.

SKILL.md는 필요할 때 불러오는 작업 절차다

Skill은 하나의 폴더이며 중심에 SKILL.md가 있습니다. 여기에 이름, description, 실제 작업 절차를 작성하고 필요하면 references, scripts, assets 같은 리소스를 함께 둡니다.

.agents/skills/blog-pipeline/
├─ SKILL.md
├─ references/
│  └─ artifact-contract.md
└─ agents/
   └─ openai.yaml

Codex는 먼저 Skill의 이름과 description 같은 메타데이터를 보고 현재 요청과 관련 있는지 판단합니다. 관련될 때 전체 지침을 읽으므로, 모든 프로젝트 규칙을 Skill 본문에 중복할 필요가 없습니다.

핵심 차이를 표로 비교하면

기준	AGENTS.md	SKILL.md
목적	저장소의 지속 규칙	반복 가능한 특정 작업
적용 시점	해당 디렉터리 범위의 작업 전반	요청과 Skill 목적이 맞을 때
대표 내용	코딩 규칙, 테스트, 금지 사항, 경로	단계, 입력·출력, 예외 처리, 템플릿
배치	저장소 루트 또는 하위 디렉터리	Skill 이름의 독립 폴더
함께 둘 수 있는 것	프로젝트 설명 중심	references, scripts, assets 등
좋은 예	"모든 변경 후 단위 테스트 실행"	"릴리스 노트를 생성하고 검수하는 절차"

구분 기준은 간단합니다. 작업 종류와 상관없이 지켜야 한다면 AGENTS.md, 특정 결과를 반복해서 만드는 절차라면 Skill이 적합합니다.

두 파일은 어떻게 함께 쓰나

이 블로그 저장소는 두 파일을 함께 사용합니다. AGENTS.md는 한국어, 공식 출처, 산출물 경로와 QA 원칙을 정합니다. blog-pipeline/SKILL.md는 리서치, 집필, 검수, Schema 생성 순서를 정의합니다.

사용자 요청
   ↓
AGENTS.md에서 프로젝트 공통 규칙 적용
   ↓
요청과 맞는 blog-pipeline Skill 선택
   ↓
01_research → 02_draft → 03_qa → 04_schema

이렇게 나누면 브랜드 규칙을 바꿀 때는 프로젝트 지침이나 설정만 고치고, 파이프라인 단계를 바꿀 때는 Skill만 수정할 수 있습니다.

무엇을 어디에 써야 할까

AGENTS.md에 적합한 내용

• 저장소의 목적과 기본 언어
• 빌드, 테스트, 린트 명령
• 변경하면 안 되는 파일과 보안 규칙
• 작업 결과를 저장할 공통 위치
• 모든 에이전트가 따라야 할 품질 기준

SKILL.md에 적합한 내용

• 작업이 시작되는 조건
• 필요한 입력과 기대하는 출력
• 실행할 단계와 순서
• 실패했을 때의 재시도 또는 중단 조건
• 작업에만 필요한 템플릿, 스크립트, 참고 자료

한 문장을 어디에 넣을지 애매하다면 "이 Skill을 사용하지 않는 작업에서도 반드시 지켜야 하는가?"를 물어보면 됩니다. 그렇다면 AGENTS.md가 더 안전합니다.

실제 적용에서 생기는 문제

AGENTS.md가 너무 길어지는 경우

모든 절차와 예시를 AGENTS.md에 넣으면 매 작업의 컨텍스트가 커집니다. 공통 규칙만 남기고 긴 업무 절차는 Skill과 reference 파일로 분리하세요.

Skill description이 모호한 경우

description이 "도움이 되는 Skill"처럼 추상적이면 언제 사용해야 하는지 판단하기 어렵습니다. 무엇을 하고 어떤 요청에서 사용해야 하는지를 한 문장에 넣는 편이 좋습니다.

같은 규칙이 여러 파일에 반복되는 경우

중복된 지침은 나중에 서로 다른 내용으로 바뀔 수 있습니다. 한 규칙의 기준 파일을 정하고 다른 파일은 해당 경로를 안내하도록 구성하세요.

마무리

AGENTS.md는 프로젝트의 지속적인 운영 규칙이고, SKILL.md는 특정 결과를 만드는 재사용 절차입니다. 하나를 선택해 다른 하나를 버리는 관계가 아닙니다.

먼저 저장소 전체가 항상 지켜야 할 내용을 AGENTS.md에 짧게 적으세요. 그다음 반복되는 작업 중 단계와 산출물이 일정한 것을 Skill로 분리하면 프로젝트 지침과 자동화 절차를 깔끔하게 관리할 수 있습니다.

참고 자료

• OpenAI Codex Manual
• OpenAI Developers - Skills
• OpenAI Help Center - Plugins in Codex