[ChatGPT] Codex skill과 서브에이전트, 헷갈리는 지점만 다시 정리

Codex를 보다 보면 skill이랑 서브에이전트가 자꾸 비슷해 보입니다. 둘 다 일을 잘하게 만드는 장치처럼 보이기 때문입니다. 그런데 이 둘은 겉보기와 달리 맡는 역할이 꽤 다릅니다. 이 차이를 제대로 못 잡으면, skill에 넣어야 할 걸 서브에이전트로 풀려고 하고, 반대로 역할 분담이 필요한 일을 skill 하나로 억지로 해결하려고 하게 됩니다.

가장 먼저 잡아두면 좋은 문장은 이겁니다. 서브에이전트는 “누가 일을 나눠서 할 것인가”에 가깝고, skill은 “그 일을 어떤 방식으로 처리할 것인가”에 가깝다. 이 한 줄만 정확히 이해해도 Codex를 보는 눈이 꽤 달라집니다.

핵심만 먼저 정리하면
서브에이전트는 분업이고, skill은 절차 재사용입니다.

---

둘은 서로 대체하는 기능이 아니다

초보자가 가장 자주 하는 오해가 있습니다. “skill이 있으면 서브에이전트는 없어도 되는 거 아닌가?” 혹은 “서브에이전트가 더 고급 기능이니까 skill은 나중에 봐도 되는 거 아닌가?” 같은 생각입니다. 그런데 실제로는 둘이 경쟁하는 기능이 아니라, 다른 문제를 푸는 도구에 가깝습니다.

예를 들어 보겠습니다. PR 하나를 검토한다고 했을 때, 보안 위험, 버그 가능성, 테스트 누락, 프레임워크 문서 확인을 한 에이전트가 다 볼 수도 있습니다. 하지만 이걸 멀티 에이전트 워크플로로 나누면 탐색 담당, 리뷰 담당, 문서 확인 담당처럼 역할이 쪼개집니다. 이건 사람을 나누는 문제에 가깝습니다.

반대로, 버그 수정할 때마다 “재현 → 원인 확인 → 최소 수정 → 검증 → 요약” 같은 순서를 반복하고 있다면, 그건 역할을 나눌 문제라기보다 매번 같은 절차를 다시 설명하고 있는 문제에 가깝습니다. 이럴 때 들어가는 게 skill입니다.

상황	더 잘 맞는 것	왜 그런가
매번 같은 작업 절차를 반복함	skill	같은 지시를 반복하지 않게 해주기 때문
보안, 테스트, 문서 확인처럼 관점이 갈라짐	서브에이전트	역할을 나눠 병렬로 보는 편이 더 자연스럽기 때문
프로젝트 공통 규칙을 계속 설명해야 함	AGENTS.md	저장소 전체에 적용되는 기본 규칙이기 때문
브라우저, 문서 서버, 외부 로그 도구가 필요함	MCP	외부 시스템 연결 문제가 핵심이기 때문

즉, skill과 서브에이전트를 같은 선상에서 비교하면 자꾸 꼬입니다. 하나는 작업 방식을 고정하는 도구이고, 다른 하나는 작업자 구성을 나누는 도구입니다.

---

skill이 먼저 필요한 경우는 생각보다 단순하다

skill이 필요한 순간은 의외로 화려하지 않습니다. 오히려 아주 현실적입니다. 비슷한 프롬프트를 세 번 이상 반복하고 있다면, 그때부터는 skill을 의심해볼 만합니다. 버그 수정, 릴리스 노트 초안, 작업 로그 정리, 커밋 전 체크리스트 같은 일들이 여기에 잘 들어갑니다.

여기서 중요한 건 skill이 “똑똑한 성격”을 부여하는 기능이 아니라는 점입니다. skill은 어디까지나 작업 절차를 묶어두는 디렉터리에 가깝습니다. 그래서 이름보다 description이 더 중요하고, 멋진 소개 문구보다 “언제 켜져야 하는지”가 더 중요합니다.

예를 들어 아래처럼 쓰는 게 초보자에게는 훨씬 낫습니다.

---
name: bugfix-helper
description: >
  화면 오류를 원인 중심으로 찾고
  최소 수정으로 마무리할 때 쓰는 스킬
---

1. 먼저 재현 조건을 확인한다.
2. 관련 파일 범위를 좁힌다.
3. 최소 수정으로 해결한다.
4. 필요한 검증 방법을 정리한다.
5. 마지막에 원인과 수정 내용을 요약한다.

이런 형태가 좋은 이유는, 읽는 사람도 이해하기 쉽고 Codex도 언제 써야 하는지 판단하기 쉽기 때문입니다. 반대로 “React 관련 작업을 돕는 skill”처럼 넓게 써버리면, 나중에 호출 기준이 흐려지고 결과도 애매해지기 쉽습니다.

예전 글이나 예시를 찾다 보면 custom prompt가 나올 때도 있는데, 지금 흐름에서는 재사용 가능한 지시는 skill 쪽으로 이해하는 편이 더 맞습니다.

---

서브에이전트가 필요한 순간은 일이 갈라질 때다

반대로 서브에이전트는 “같은 일을 반복한다”보다 “일이 여러 갈래로 나뉜다”는 신호에서 시작합니다. 특히 PR 리뷰, 코드베이스 탐색, UI 재현과 코드 수정이 함께 얽힌 버그, 문서 확인이 필요한 변경 같은 작업에서 체감이 큽니다.

이런 작업을 한 에이전트에게 다 맡기면 가능은 합니다. 다만 중간 탐색 로그, 테스트 출력, 스택 트레이스, 브라우저 재현 기록이 한 대화에 계속 섞이기 시작하면 메인 흐름이 지저분해지기 쉽습니다. 그래서 공식 문서도 컨텍스트 오염이나 컨텍스트 로트를 줄이기 위한 방식으로 서브에이전트 워크플로를 설명합니다.

쉽게 말하면 이렇습니다. 메인 에이전트는 팀장처럼 요구사항과 최종 정리에 집중하고, 서브에이전트는 탐색, 리뷰, 검증 같은 잡음을 각자 맡아서 처리한 뒤 요약만 돌려주는 구조입니다. 그래서 서브에이전트는 “더 똑똑한 한 명”이라기보다 “역할이 나뉜 작은 팀”에 가깝습니다.

다만 여기에는 꼭 붙는 조건이 있습니다. Codex가 서브에이전트를 자동으로 막 띄우는 건 아니라는 점입니다. 역할을 나눠 달라고 사용자가 분명히 요청해야 하고, 각 서브에이전트가 따로 모델과 도구를 쓰기 때문에 토큰과 시간이 더 들 수 있습니다. 작은 작업까지 무조건 멀티 에이전트로 가는 게 정답은 아닙니다.

현재 브랜치를 main과 비교해서 검토해줘.

보안, 버그, 테스트 취약성,
문서 확인 항목마다
서브에이전트 1개씩 나눠 병렬로 확인하고,

모든 결과가 모이면
항목별 핵심만 요약해줘.

이 프롬프트가 좋은 이유는 단순합니다. “나눠라”가 분명하고, “마지막엔 요약만 달라”도 분명하기 때문입니다. 초보자일수록 멀티 에이전트를 추상적으로 이해하려 하지 말고, 이렇게 사람 나누듯이 말하는 편이 훨씬 체감이 빠릅니다.

---

그래서 둘을 같이 쓰면 언제 좋아지나

skill과 서브에이전트는 서로 대체재가 아니라서, 오히려 같이 붙었을 때 더 선명해지는 경우가 많습니다. 예를 들어 탐색 담당 서브에이전트는 코드 경로만 좁히고, 수정 담당 서브에이전트는 최소 수정 원칙을 따르게 만들고 싶다고 해보겠습니다. 이때 역할 분담은 서브에이전트가 맡고, “최소 수정 원칙”이나 “마지막 요약 형식” 같은 재사용 규칙은 skill이 맡는 식으로 분리할 수 있습니다.

조금 익숙해지면 여기서 한 단계 더 갈 수도 있습니다. 커스텀 에이전트는 부모 세션의 설정을 상속할 수 있고, 그 안에 skills.config도 포함됩니다. 즉, 어떤 서브에이전트는 부모가 쓰는 skill을 그대로 물려받고, 어떤 서브에이전트는 특정 skill만 꺼버리도록 조정할 수도 있습니다.

이 말이 실전에서 왜 중요하냐면, 역할마다 필요한 매뉴얼이 다를 수 있기 때문입니다. 예를 들어 문서 확인 담당 에이전트에게는 “코드 편집용 skill”이 방해가 될 수 있고, 반대로 수정 담당 에이전트에게는 “최소 수정 버그픽스 skill”이 잘 맞을 수 있습니다.

name = "ui_fixer"
description = "문제 원인이 확인된 뒤 작은 수정만 담당하는 에이전트"

developer_instructions = """
원인이 확인된 뒤에만 수정한다.
관련 없는 파일은 건드리지 않는다.
바뀐 동작만 검증한다.
"""

[[skills.config]]
path = "/Users/me/.agents/skills/docs-editor/SKILL.md"
enabled = false

이 예시가 보여주는 건 단순합니다. 에이전트는 역할이고, skill은 작업 매뉴얼이며, 둘은 같은 자리에 있는 기능이 아니라는 점입니다. 그래서 둘을 함께 쓰면 “누가 무엇을 할지”와 “그걸 어떤 방식으로 할지”를 각각 따로 제어할 수 있습니다.

---

초보자는 어떤 순서로 시작하는 게 가장 덜 헷갈릴까

처음부터 다 한 번에 붙이면 오히려 흐름을 놓치기 쉽습니다. 그래서 시작 순서는 단순한 쪽이 좋습니다.

1. 먼저 AGENTS.md부터 정리합니다. 프로젝트 실행 방법, 테스트 명령, 금지 규칙처럼 저장소 공통 규칙을 먼저 고정합니다.
2. 그다음 skill 하나만 만듭니다. 버그 수정용이든 작업 로그 정리용이든, 정말 자주 반복하는 일 하나만 골라서 시작합니다.
3. 일이 자연스럽게 갈라질 때만 서브에이전트를 붙입니다. 리뷰 관점이 여러 개거나, 재현·탐색·수정이 분리될 때가 적당합니다.
4. 처음에는 2~3개 정도만 나눕니다. 너무 많이 나누면 초보자 입장에서는 결과를 읽는 쪽이 더 어려워집니다.
5. max_depth는 기본값에 가깝게 두는 편이 안전합니다. 깊이를 키우면 에이전트가 에이전트를 다시 낳는 구조가 생길 수 있어서 추적이 금방 어려워집니다.
6. 탐색용이나 리뷰용 에이전트는 가능한 한 read-only에 가깝게 둡니다. 처음부터 수정 권한까지 넓히는 것보다 훨씬 덜 불안합니다.

입문자 추천선
처음에는 “skill 하나 + 서브에이전트 둘 정도”만으로도 충분합니다. 너무 많은 역할과 규칙을 한 번에 넣으면, 무엇이 효과가 있었는지 오히려 알기 어려워집니다.

---

헷갈리는 포인트를 마지막으로 한 번만 더 정리하면

skill은 Codex를 “다른 성격의 존재”로 바꾸는 기능이 아닙니다. 특정 일을 할 때 매번 반복하던 절차를 재사용하게 만드는 기능에 가깝습니다. 반면 서브에이전트는 “이 일을 여러 사람이 나눠 하면 더 낫겠다”는 순간에 등장하는 구조입니다.

그래서 버그 수정 체크리스트, 작업 로그 정리, PR 설명 형식처럼 반복되는 절차가 문제라면 skill 쪽으로 생각하는 게 맞습니다. 보안 리뷰, 문서 확인, 브라우저 재현, 코드 경로 추적처럼 관점이 갈라지는 작업이라면 서브에이전트가 먼저 떠오르는 게 자연스럽습니다.

그리고 둘이 함께 붙는 순간, Codex는 단순히 “말 잘 듣는 채팅창”에서 조금 더 작업 환경처럼 보이기 시작합니다. 누가 맡을지와 어떻게 처리할지를 따로 설계할 수 있기 때문입니다. 이 차이가 감으로 잡히면, skill과 서브에이전트를 더 이상 비슷한 기능으로 보지 않게 됩니다.

정리하면 이렇습니다. skill은 반복성이고, 서브에이전트는 분업입니다. 이 두 개를 따로 이해해두면, 나중에 커스텀 에이전트나 자동화로 넘어갈 때도 훨씬 덜 꼬입니다.