이전 글에서 서브에이전트를 먼저 본 이유는 단순합니다. Codex를 이해할 때는 “누가 일하느냐”와 “어떻게 일하느냐”를 분리해서 보는 편이 훨씬 덜 헷갈리기 때문입니다. 이번 글에서 다룰 skill은 바로 그 두 번째, 즉 일하는 방식 쪽에 가깝습니다.

초보자가 skill을 처음 보면 대개 이렇게 받아들입니다. “아, 자주 쓰는 프롬프트 저장해두는 기능이구나.” 완전히 틀린 말은 아니지만, 그렇게만 보면 중요한 부분을 놓치게 됩니다. skill은 그냥 문장을 저장하는 메모장이 아니라, 반복되는 작업 흐름을 Codex가 다시 꺼내 쓸 수 있게 묶어두는 작은 업무 카드에 더 가깝습니다.

예를 들어 버그를 고칠 때마다 늘 비슷한 순서를 밟는 사람이 있습니다. 재현 조건을 먼저 보고, 관련 파일을 좁히고, 최소 수정으로 끝내고, 마지막에 원인과 검증 결과를 정리하는 식입니다. 이런 패턴이 한두 번이 아니라 계속 반복된다면, 그때부터는 긴 프롬프트를 매번 다시 쓰는 것보다 skill로 정리하는 쪽이 훨씬 편해집니다.

한 줄로 먼저 잡아두면
서브에이전트가 역할 분담이라면, skill은 작업 절차 재사용에 가깝습니다.

스킬은 정확히 무엇인가

공식 문서 기준으로 skill은 SKILL.md를 중심으로, 설명서와 자료, 필요하면 스크립트까지 함께 묶어놓은 디렉터리입니다. 중요한 건 “한 파일”이 아니라 “한 묶음”이라는 점입니다. 그래서 skill은 단순 문구 저장보다 조금 더 실무적인 단위로 생각하는 편이 맞습니다.

또 Codex는 skill을 처음부터 전부 길게 읽는 방식이 아닙니다. 먼저 이름과 설명, 경로 같은 메타데이터를 보고, 지금 작업과 맞아떨어질 때만 본문을 깊게 읽습니다. 그래서 초보자에게 정말 중요한 건 거창한 구성보다도 이 skill이 언제 쓰여야 하는지 설명을 분명하게 적는 것입니다.

구성 요소 무슨 역할인가 초보자식 비유
프롬프트 지금 당장 원하는 요청 메신저로 보내는 즉석 지시
AGENTS.md 프로젝트 공통 규칙 팀 운영 수칙
skill 반복 업무 절차와 기준 자주 꺼내 쓰는 작업 카드
MCP 외부 도구 연결 외부 공구함 연결선
서브에이전트 역할을 나눈 작업자 리뷰 담당, 탐색 담당 같은 분업

여기서 핵심만 다시 말하면 이렇습니다. skill은 Codex를 다른 사람으로 바꾸는 기능이 아닙니다. 이미 있는 에이전트가, 특정 일을 할 때 더 일정한 방식으로 움직이게 만드는 기능에 가깝습니다.

왜 초보자에게도 스킬이 중요한가

skill은 고급 사용자 전용 옵션처럼 보이지만, 의외로 초보자에게 더 유용한 면이 있습니다. 코딩 경험이 많지 않을수록 같은 설명을 여러 번 반복하면서도, 매번 조금씩 다른 말을 하게 되기 쉽기 때문입니다. 그러면 결과도 흔들립니다. 어떤 날은 테스트를 챙기고, 어떤 날은 건너뛰고, 어떤 날은 설명이 너무 길어집니다.

반대로 skill을 써두면 작업의 기준이 눈에 보이기 시작합니다. “이건 버그 수정용”, “이건 PR 리뷰용”, “이건 작업 로그 정리용”처럼 역할이 분리되고, 결과물의 결도 조금씩 맞춰집니다. Codex를 그때그때 말 잘 듣는 채팅창처럼 쓰는 단계에서, 반복 작업을 다루는 도구처럼 쓰는 단계로 넘어가는 느낌이라고 보면 이해가 쉽습니다.

  • 프롬프트를 매번 길게 다시 쓰지 않아도 됩니다.
  • 작업 결과가 들쭉날쭉해지는 문제를 줄이기 좋습니다.
  • 혼자 쓸 때도 편하고, 팀으로 쓸 때는 더 편해집니다.
  • CLI, IDE, 앱을 오가도 작업 방식이 덜 흔들립니다.

이럴 때 skill을 떠올리면 됩니다
같은 프롬프트를 자꾸 재활용하고 있거나, 같은 수정 방식을 매번 다시 설명하고 있다면, 이미 skill로 만들 시점에 가까워진 경우가 많습니다.

스킬은 실제로 어떻게 생겼나

초보자가 가장 먼저 보면 좋은 건 거창한 구조가 아니라, “아, 결국 폴더 단위로 관리되는구나” 하는 감각입니다. 공식 문서 기준으로 프로젝트 안에서는 보통 .agents/skills 계열을 떠올리면 됩니다. 사용자 개인 스킬은 홈 디렉터리 아래에 두고, 프로젝트 전용 스킬은 저장소 안에 두는 식입니다.

my-project/
└─ .agents/
   └─ skills/
      └─ bugfix-helper/
         ├─ SKILL.md
         ├─ references/
         └─ scripts/

처음에는 여기서 겁먹을 필요가 없습니다. 사실상 처음 필요한 건 SKILL.md 하나입니다. references나 scripts는 나중에 정말 필요할 때 붙여도 됩니다. 시작을 무겁게 만들수록, 초보자는 skill 자체보다 구조에 먼저 질리기 쉽습니다.

아주 단순한 형태는 이렇게 시작해도 충분합니다.

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

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

이 예시를 보면 감이 옵니다. skill은 “멋진 문장”보다 반복 순서가 보이는 설명이 더 중요합니다. 스킬 이름도 중요하지만, 실제로는 description이 호출 조건에 가깝습니다. 그래서 이름을 예쁘게 짓는 것보다, 언제 써야 하고 언제 쓰지 말아야 하는지를 또렷하게 적는 편이 훨씬 낫습니다.

CLI에서 스킬 쓰는 방법

CLI는 가장 직선적인 표면입니다. 터미널을 열고 프로젝트 폴더로 들어간 뒤 Codex를 실행하면, 그 디렉터리를 기준으로 읽고 수정하고 명령을 돌릴 수 있습니다. 터미널이 익숙한 사람에겐 제일 빠르고, 낯선 사람에겐 조금 무뚝뚝해 보일 수 있지만, 구조를 이해하기에는 오히려 선명한 편입니다.

기본 시작은 단순합니다. 설치하고, 프로젝트 폴더로 가고, 실행하면 됩니다.

npm i -g @openai/codex

cd my-project
codex

처음 실행할 때는 로그인 과정이 따라오고, 이후부터는 그 자리에서 바로 작업을 이어갈 수 있습니다. skill도 여기서 바로 만들 수 있습니다. 초보자라면 수동 작성보다 먼저 내장 생성기를 한 번 써보는 편이 좋습니다.

$skill-creator

이 생성기는 “무슨 일을 하는 스킬인지”, “언제 켜져야 하는지”, “스크립트가 필요한지”를 순서대로 물어보는 방식이라 입문자에게 특히 편합니다. 처음에는 instruction-only 스타일로 시작하는 편이 무난합니다. 즉, 자동화 욕심부터 내지 말고 먼저 설명서형 스킬부터 만드는 쪽이 좋습니다.

호출도 어렵지 않습니다. CLI에서는 /skills로 목록을 보거나, $로 skill을 직접 언급해 불러올 수 있습니다.

$bugfix-helper
로그인 버튼을 누르면 흰 화면이 뜹니다.
원인부터 찾고,
최소 수정으로 고쳐주세요.
마지막에 바뀐 파일과
검증 방법도 같이 정리해주세요.

설정도 알아두면 좋습니다. CLI와 IDE는 ~/.codex/config.toml 계층을 함께 쓰기 때문에, 승인 정책이나 기본 모델 같은 공통 습관을 한곳에서 관리할 수 있습니다. 특정 skill을 지우지 않고 잠시 끄고 싶을 때는 아래처럼 다룰 수 있습니다.

[[skills.config]]
path = "/project/.agents/skills/bugfix-helper/SKILL.md"
enabled = false

CLI를 조금 더 오래 쓰게 되면 유용한 명령도 생깁니다. 예를 들어 이전 작업을 다시 이어가고 싶을 때는 codex resume가 꽤 쓸 만합니다. 세션을 완전히 새로 시작하기보다, 같은 저장소 상태와 맥락을 끌고 오는 쪽이 더 자연스러운 경우가 많기 때문입니다.

윈도우에서 CLI를 쓸 때
윈도우에서도 Codex를 돌릴 수는 있지만, 공식 문서는 CLI 쪽에서 WSL 기준 흐름을 꽤 중요하게 다룹니다. 특히 저장소가 이미 WSL 안에 있거나 리눅스 도구 체인이 필요한 경우라면, 처음부터 WSL 기준으로 잡는 편이 덜 꼬입니다.

IDE에서 스킬 쓰는 방법

IDE는 초보자에게 가장 무난한 시작점입니다. 코드가 눈앞에 있고, 어떤 파일을 보고 있는지도 분명하고, 선택한 코드 조각을 그대로 문맥에 태우기 쉽기 때문입니다. 공식 문서 기준으로 Codex IDE 확장은 VS Code 계열 에디터에서 쓰는 흐름을 중심으로 안내되고, Cursor나 Windsurf 같은 VS Code 호환 환경도 포함합니다.

처음 흐름은 보통 이렇게 잡으면 됩니다.

  1. 에디터에 Codex 확장을 설치합니다.
  2. 프로젝트 폴더를 연 상태에서 Codex 패널을 엽니다.
  3. ChatGPT 계정이나 API 키로 로그인합니다.
  4. 현재 열린 파일, 선택 영역, @file 참조를 활용해 작업을 시작합니다.
  5. 필요하면 /skills 또는 $skill-name으로 skill을 불러옵니다.

IDE의 장점은 문맥이 따라붙는다는 데 있습니다. “이 파일을 보고 얘기하는지”, “지금 선택한 함수가 뭔지”가 눈에 보이기 때문에, CLI보다 짧은 프롬프트로도 훨씬 자연스럽게 작업이 이어지는 경우가 많습니다.

@src/components/LoginForm.tsx
$bugfix-helper

선택한 코드 기준으로
오류 원인을 먼저 설명하고,
최소 수정으로 고쳐주세요.
테스트가 필요하면
어떤 명령을 돌릴지도 적어주세요.

설정 면에서는 IDE도 CLI와 멀리 떨어져 있지 않습니다. 일부 UI 옵션은 에디터 설정에서 바꾸지만, 기본 모델, 승인 방식, 샌드박스 같은 핵심 동작은 공유 config.toml에서 관리합니다. 그래서 CLI에서 잡아둔 습관이 IDE에도 이어지고, 반대로 IDE에서 바꾼 공통 설정이 CLI에도 영향을 주는 식입니다.

또 하나 초보자가 꼭 알아둘 건 승인 모드입니다. IDE에서는 보통 Agent가 기본입니다. 이 모드에서는 작업 디렉터리 안에서 읽기, 수정, 명령 실행을 비교적 자연스럽게 처리합니다. 다만 그보다 넓은 범위나 네트워크 접근까지 자동으로 허용하는 Agent (Full Access)는 말 그대로 권한이 커지므로, 초보자라면 급할 때만 신중하게 쓰는 편이 좋습니다. 설계만 하고 싶을 때는 Chat 모드가 더 편한 경우도 많습니다.

윈도우에서 IDE를 쓸 때는 이 점이 중요합니다
공식 문서 기준으로 Windows에서 IDE의 agent mode는 현재 WSL 흐름이 사실상 핵심입니다. 단순히 “선택 옵션” 정도로 보지 말고, 윈도우 사용자라면 초기에 함께 세팅해야 할 기본 조건으로 생각하는 편이 덜 헷갈립니다.

추가로 IDE에서는 slash command도 꽤 유용합니다. 예를 들어 /local, /cloud, /review, /status 같은 명령으로 작업 모드를 바꾸거나 현재 상태를 확인할 수 있습니다. 초보자에게는 기능을 다 외우는 것보다, 채팅 입력창에서 슬래시를 눌러 어떤 제어가 가능한지 한 번씩 훑어보는 습관이 더 중요합니다.

윈도우 앱에서는 스킬을 어떻게 쓰나

Codex 앱은 에디터보다는 조금 더 관제실 같은 표면입니다. 공식 문서 기준으로 Windows 앱은 네이티브로 돌아가고, PowerShell과 Windows 샌드박스를 쓰는 흐름이 기본이며 필요하면 WSL 방식도 잡을 수 있습니다. 코드 한 줄 한 줄을 에디터에서 보는 느낌보다, 여러 작업을 병렬로 돌리고 검토하는 감각이 더 잘 살아납니다.

앱에서는 보통 이런 흐름으로 이해하면 쉽습니다.

  1. 프로젝트를 추가합니다.
  2. 새 스레드를 열면서 작업 방식을 고릅니다.
  3. Local, Worktree, Cloud 중 하나를 선택합니다.
  4. 사이드바의 Skills에서 현재 프로젝트와 연결된 skill을 확인합니다.
  5. diff, Git, 터미널, 스레드 기록을 보면서 작업을 이어갑니다.

이 중에서 skill과 가장 직접적으로 연결되는 부분은 Skills 사이드바입니다. 앱은 CLI와 IDE에서 쓰는 것과 같은 skill을 지원하고, 팀에서 만든 skill도 사이드바에서 둘러보기 쉽게 보여줍니다. 그래서 skill이 파일 시스템 어딘가에 숨어 있는 설정처럼 느껴지지 않고, 실제로 꺼내 쓰는 도구처럼 보이기 시작합니다.

새 스레드를 만들 때 나오는 모드도 초보자에게 꽤 중요합니다. 작은 수정이거나 지금 열어둔 프로젝트를 바로 손보고 싶다면 Local이 편합니다. 반대로 현재 작업을 건드리지 않고 시도해보고 싶다면 Worktree가 더 안전합니다. 긴 작업이나 따로 돌려두고 싶은 일은 Cloud가 잘 맞습니다. 처음에는 Local로 시작하고, 조금 익숙해지면 Worktree를 붙이는 순서가 대체로 무난합니다.

앱의 장점은 skill만 보이는 게 아니라, 그 skill이 만든 결과를 검토하는 흐름도 함께 있다는 점입니다. diff 창에서 변경 내용을 보고, Git 기능으로 커밋이나 푸시를 하고, 내장 터미널로 빌드나 테스트까지 확인할 수 있습니다. 즉, “스킬을 불러 작업시키는 것”에서 끝나지 않고, 그 결과를 점검하는 자리까지 한 화면 안에서 이어지는 편입니다.

스킬을 앱에서 조금 더 보기 좋게 다루고 싶다면, 나중에는 agents/openai.yaml도 붙여볼 수 있습니다. 이 파일은 필수는 아니지만, 앱에서 skill의 표시 이름이나 짧은 설명, 기본 프롬프트를 더 보기 좋게 다듬는 데 도움이 됩니다.

interface:
  display_name: "Bugfix Helper"
  short_description: "버그 수정용 체크리스트"
  default_prompt: "원인부터 찾고 최소 수정으로 고쳐줘"

policy:
  allow_implicit_invocation: false

여기서 마지막 줄도 꽤 실용적입니다. 어떤 skill은 자동으로 불리기보다, 내가 명시적으로만 쓰고 싶은 경우가 있습니다. 그럴 때는 암묵 호출을 끄고, 필요할 때만 직접 불러도 됩니다. 초보자 단계에서는 필수는 아니지만, skill이 많아질수록 이런 구분이 꽤 유용해집니다.

앱에서 기억해둘 한 줄
skill이 방법을 정리해둔 것이라면, 앱은 그 방법을 여러 프로젝트와 스레드 위에서 관리하고 검토하는 자리에 가깝습니다.

좋은 스킬은 어떻게 쓰는가

skill을 처음 만들 때 가장 흔한 실수는 한 skill에 너무 많은 일을 넣는 것입니다. 버그 수정, 코드 리뷰, 릴리스 노트 초안, 로그 정리까지 전부 한곳에 넣어버리면 결국 아무 상황에도 애매한 스킬이 되기 쉽습니다. 공식 가이드도 반복해서 강조하는 방향은 비슷합니다. 스킬 하나에는 일 하나, 이 원칙이 초보자에게도 가장 안전합니다.

또 description은 대충 써도 되는 부가 정보가 아닙니다. Codex가 지금 작업과 이 skill이 맞는지를 판단할 때 핵심 단서가 되기 때문입니다. 그래서 “React 관련 작업”처럼 넓게 쓰기보다, “화면 오류를 원인 중심으로 찾고 최소 수정으로 끝낼 때”처럼 범위를 좁히는 편이 더 낫습니다.

처음부터 모든 걸 자동화하려 하지 않는 것도 중요합니다. instruction-only skill 하나를 먼저 만들고, 실제로 몇 번 써본 뒤에 부족한 부분만 references나 scripts를 붙이는 편이 훨씬 덜 헷갈립니다. 시작 단계에서 필요한 건 화려함보다 재현성입니다.

좋은 시작 피하는 편이 좋은 시작
버그 수정용, 리뷰용처럼 역할을 좁혀서 시작 하나의 skill에 여러 일을 한꺼번에 몰아넣기
description에 언제 써야 하는지 분명히 적기 이름만 멋있고 설명은 두루뭉술하게 쓰기
instruction-only로 가볍게 시작 처음부터 스크립트와 자동화까지 한 번에 넣기
몇 번 써본 뒤 필요한 자료만 덧붙이기 한 번도 안 써보고 구조부터 복잡하게 만들기

실전에서 많이 쓰는 작은 습관도 있습니다. 작업 기준이 자주 바뀌지 않는다면 AGENTS.md로 올리고, 특정 작업 절차라면 skill로 두는 식입니다. 바깥 도구나 실시간 정보가 꼭 필요하면 MCP를 붙이고, 역할을 나눠야 할 만큼 일이 복잡하면 서브에이전트를 붙이는 식으로 층을 나눠 생각하면 훨씬 정리가 잘 됩니다.

짤막한 팁과 자주 하는 실수

  • skill이 안 보이면 재시작도 의심해보세요. 문서상 자동 감지는 되지만, 변경이 바로 안 잡히면 재시작으로 해결되는 경우가 있습니다.
  • 기본 제공 skill도 있습니다. 예를 들어 $skill-creator는 첫 skill을 만들 때 꽤 유용합니다.
  • 예전 글에서 custom prompts를 봤다면 업데이트가 필요할 수 있습니다. 현재 공식 흐름은 재사용 가능한 지시를 skill 쪽으로 보는 편입니다.
  • 설정은 한 군데에서 습관처럼 관리하는 편이 좋습니다. 개인 기본값은 ~/.codex/config.toml, 프로젝트 전용 동작은 저장소 쪽 설정으로 나누면 덜 꼬입니다.
  • 작업이 안정된 뒤에야 자동화를 붙이는 편이 좋습니다. skill이 아직 들쭉날쭉한데 자동화부터 돌리면, 불편이 반복될 뿐입니다.
  • 권한은 처음부터 넓히지 않는 편이 안전합니다. 특히 Full Access는 편해 보여도, 초반에는 기본 승인 흐름으로 감을 잡는 쪽이 낫습니다.
  • Windows에서는 표면마다 느낌이 다릅니다. 앱은 네이티브 사용 흐름이 비교적 자연스럽고, CLI나 IDE는 WSL 기준으로 잡을 때 편한 경우가 많습니다.

외워두면 좋은 말
skill은 방법을 정리하고, automation은 일정을 정리합니다. 작업이 아직 흔들리면 automation보다 skill부터 다듬는 편이 맞습니다.

마무리

Codex skill은 대단한 비밀 기능이라기보다, 내가 반복하는 작업 방식을 정리해두는 습관에 가깝습니다. 그래서 오히려 초보자에게 더 중요할 수 있습니다. 프롬프트를 길게 쓰는 재주보다, 반복되는 일의 구조를 알아보는 눈이 먼저 생기기 때문입니다.

정리하면 이렇게 볼 수 있습니다. CLI는 가장 직선적이고, IDE는 가장 무난하며, 윈도우 앱은 여러 작업을 함께 관리하기 좋습니다. 그런데 어느 표면을 쓰든 skill의 본질은 같습니다. 자주 반복하는 일을, Codex가 다시 꺼내 쓸 수 있게 정리해두는 것. 그 감만 잡히면 skill이라는 말이 훨씬 덜 어렵게 느껴질 겁니다.

다음 단계로 넘어간다면, 거창한 자동화보다 작은 실험이 더 좋습니다. 예를 들어 “버그 수정용”, “작업 로그 정리용”처럼 하나만 골라 SKILL.md를 직접 써보는 겁니다. 그 순간부터 Codex는 그냥 코드 물어보는 창이 아니라, 조금 더 일하는 방식이 잡힌 도구처럼 보이기 시작할 가능성이 큽니다.

'AI에이전트 > Chatgpt' 카테고리의 다른 글

[ChatGPT] Codex skill과 서브에이전트, 헷갈리는 지점만 다시 정리  (0) 2026.03.26
스킬보다 먼저 봐야 할 Codex 서브에이전트: 멀티 에이전트 입문 가이드  (0) 2026.03.24