핵심 표면
역할 나누기
- AGENTS.md: 저장소 규칙과 기본 지침
- Skills: 반복 가능한 작업 절차 패키지
- MCP: 외부 시스템과 도구 연결
- Automations: 정기적으로 돌아가는 백그라운드 작업
반복 작업을 올리는 순서
1. 수동 프롬프트로 한 번 잘 되는지 확인
2. 자주 쓰이면 Skill로 승격
3. 외부 시스템이 필요하면 MCP 연결
4. 정기 점검이 되면 Automation으로 예약연결 구조
네 층은 경쟁 관계가 아니라 서로 보완하는 역할 분담이다
AGENTS.md, Skills, MCP, Automations는 경쟁 관계가 아니라 서로 보완하는 층입니다. AGENTS.md는 저장소 규칙과 에이전트 기본 행동을 담고, Skills는 반복 절차를 패키지화하며, MCP는 저장소 밖 시스템에 연결하고, Automations는 그 위에서 정기 실행을 맡습니다. 이 역할을 혼동하면 AGENTS.md에 모든 것을 몰아넣거나, 수동으로도 검증되지 않은 프롬프트를 바로 자동화로 올리는 실수가 생깁니다.
Skills는 매번 긴 프롬프트를 반복하는 비용을 줄이는 패키지다
Skills는 SKILL.md와 선택적 스크립트, 레퍼런스, 에셋으로 구성되는 재사용 워크플로우입니다. 반복 작업을 매번 긴 프롬프트로 다시 설명할 필요를 줄여 줍니다. 예를 들어 "PR 리뷰 전 체크리스트 실행"이나 "새 모듈 생성 절차"처럼 팀 안에서 자주 되풀이되는 작업을 Skill로 만들어 두면, 다음에는 Skill 이름만 부르면 됩니다. 수동 프롬프트로 한 번 안정적으로 작동함을 확인한 뒤에 Skill로 올리는 순서가 중요합니다.
현재 공식 문서 기준으로 Skills는 전역 사용자 디렉터리에도 둘 수 있고, 저장소 안 .agents/skills에 체크인해 팀과 공유할 수도 있습니다. 또한 Skill은 메타데이터부터 읽고 필요할 때만 SKILL.md, 레퍼런스, 스크립트를 여는 progressive disclosure 흐름으로 동작하므로, 이름과 설명을 짧고 명확하게 두는 편이 중요합니다.
MCP는 Codex가 저장소 밖 세계와 연결되는 표준 인터페이스다
MCP는 외부 도구, 문서 서버, 이슈 트래커 같은 로컬 저장소 밖 시스템에 Codex를 연결할 때 쓰는 표준 인터페이스입니다. MCP 없이는 Codex가 GitHub 이슈를 직접 읽거나 Jira 티켓 상태를 확인하는 작업을 할 수 없습니다. MCP를 도입할 때는 어떤 도구가 파일이나 외부 상태를 실제로 바꾸는지 먼저 파악하고, 권한 범위를 의식적으로 좁히는 것이 중요합니다.
공식 customization 문서는 MCP 서버가 tools, resources, prompts를 각각 노출할 수 있다고 설명합니다. Skill이 MCP에 의존하면 agents/openai.yaml에 그 의존성을 선언해 Codex가 설치와 연결을 자동으로 맞추게 하는 흐름도 문서화되어 있습니다.
Automations는 수동 검증이 선행된 작업에만 적합하다
Automations는 Codex app에서 백그라운드로 정기 실행되는 작업이며, Git 저장소에서는 로컬 프로젝트나 Worktree 중 어디에서 돌릴지 고를 수 있습니다. 공식 가이드는 자동화를 바로 스케줄링하기보다, 먼저 일반 스레드에서 수동으로 시험해 프롬프트와 diff 품질을 확인한 뒤 일정 작업으로 승격하라고 권합니다. 아직 수동으로도 안정적이지 않은 프롬프트를 바로 자동화하면 실패를 예약하는 셈입니다.
AGENTS / Skill / MCP / Automation을 나누는 기준
- AGENTS.md: 저장소 규칙과 기본 동작
- Skill: 반복 절차를 재사용 가능한 패키지로 고정
- MCP: 외부 시스템과 연결
- Automation: 검증 끝난 작업을 주기적으로 실행언제 무엇을 붙일까
| 상황 | 적합한 선택 |
|---|---|
| 저장소 규칙과 에이전트 기본 행동을 정의할 때 | AGENTS.md |
| 반복 가능한 절차를 패키지로 저장할 때 | Skill (SKILL.md) |
| 외부 시스템에 Codex를 연결해야 할 때 | MCP |
| 수동 검증이 완료된 작업을 정기 실행할 때 | Automation |
| Worktree에서 격리해 자동화를 실행할 때 | Worktree 기반 자동화 선택 |
주의할 점
아직 수동으로도 안정적이지 않은 프롬프트를 바로 자동화하면 실패를 예약하는 셈이 됩니다. 먼저 일반 스레드에서 결과를 검증하고, 그다음 Skill이나 Automation으로 올리는 순서를 지키는 편이 안전합니다.
실패 예시
- 팀 배포 점검 절차를 한 번도 수동 검증하지 않고 곧바로 Automation 으로 등록함
- 결과: 실패한 프롬프트가 정기적으로 반복 실행되고, 어떤 입력이 빠졌는지도 추적하기 어려워짐
- 대응: 수동 프롬프트 -> Skill 정리 -> 필요 시 MCP 연결 -> 마지막에 Automation 등록 순서를 지킨다참고 링크
3 sources