Codex Skills — 반복 프롬프트를 재사용 가능한 워크플로우로 바꾸기

공식 참고 자료: Skills · Best Practices · Automations

커리큘럼 흐름

Codex 시작하기 — 설치, 첫 작업, 체크포인트까지 — 입문 루프
Codex 지시문 — AGENTS.md를 진짜 쓸모 있게 만드는 법 — 저장소 규칙
Codex 샌드박싱 — 권한, 승인, 클라우드 환경 이해하기 — 권한과 승인
Codex 작업 설계 — 소원 말고 이슈처럼 프롬프트 쓰기 — 좋은 task shape 만들기
Codex Skills — 반복 프롬프트를 재사용 가능한 워크플로우로 바꾸기 — 반복 워크플로우를 재사용 자산으로 만들기 ← 현재 문서
Codex 서브에이전트 — 병렬 실행과 위임 패턴 — 병렬 실행과 위임
Codex MCP — 외부 컨텍스트를 복붙 대신 연결하기 — 외부 시스템 연결
Codex 리뷰와 자동화 — /review, worktree, 반복 엔지니어링 운영하기 — 반복 작업 운영
Codex Worktrees — 브랜치 충돌 없이 병렬 실행하기
Codex 핸드오프 — 병렬 레인을 머지 가능한 결과로 연결하기
Codex 검증 루프 — 머지 전에 동작을 증명하기
Codex 릴리스 준비도 — 프로덕션 전 최종 게이트
Codex 첫날 안전 루프 — 초반 실수를 줄이는 입문 워크플로우
Codex 팀 딜리버리 플레이북 — 중급 레인 운영
Codex 고위험 변경 거버넌스 — 크리티컬 릴리스를 위한 고급 통제
Codex 운영 매뉴얼 — 팀의 일/주/릴리스 리듬 정렬하기
Codex 사고 복구 플레이북 — 프로덕션 압박 상황에서의 결정론적 대응
Codex 사고 후 하드닝 루프 — 복구를 내구성 있는 통제로 전환하기
Codex 카오스 복원력 드릴 — 실패가 오기 전에 리허설하기
Codex 복원력 지표와 SLO — 실패 전에 신뢰성을 측정하기
Codex Ralph 지속 루프 — 긴 작업을 검증 가능한 완료까지 가져가기

이 문서에서 참고한 공식 문서

skill의 기본 구조와 progressive disclosure — Skills
개인 skill과 저장소 공유 skill 위치 — Best practices
안정화된 반복 작업을 automation으로 스케줄링 — Automations

언제 프롬프트를 skill로 올려야 할까

같은 작업을 세 번 이상 반복하면서 매번 비슷한 설명을 복붙한다면, 이제 프롬프트가 아니라 skill 문제일 가능성이 큽니다.

좋은 skill 후보:

릴리즈 노트 초안 만들기
PR 리뷰 체크리스트 적용
특정 에러 유형 triage
문서 frontmatter 정리
레거시 API 마이그레이션 후속 작업
온보딩 환경 점검
정기적인 docs drift 확인

즉, 입력 패턴과 출력 기대치가 반복되는 작업이 잘 맞습니다. 반대로 요구사항이 매번 완전히 달라지고 종료 조건도 제각각이라면, 아직은 일회성 프롬프트가 더 맞을 수 있습니다.

skill의 기본 구조

Skills 문서 기준으로 skill은 디렉터리 하나입니다.

my-skill/
  SKILL.md           # 필수
  scripts/           # 선택
  references/        # 선택
  assets/            # 선택
  agents/openai.yaml # 선택 메타데이터/의존성

핵심은 SKILL.md입니다. 공식 문서는 SKILL.md에 name과 description이 반드시 있어야 한다고 설명합니다. 나머지 요소는 반복 절차를 안정적으로 실행하기 위한 보조 자산입니다.

scripts/ → 반복 명령, 포맷 변환, 검증 스크립트
references/ → 예시, 표준 문서, 체크리스트, 샘플 출력
assets/ → 아이콘, 템플릿, 보조 리소스
agents/openai.yaml → UI 메타데이터, 호출 정책, tool/MCP 의존성을 선택적으로 선언

중요한 포인트: Codex는 skill을 한 번에 다 읽지 않는다

Skills 문서는 Codex가 먼저 메타데이터(name, description, path 등) 를 보고, 필요하다고 판단될 때만 SKILL.md 전체를 불러온다고 설명합니다.

이게 중요한 이유는 세 가지입니다.

context를 낭비하지 않음
description 품질이 skill 선택 정확도를 좌우함
너무 포괄적인 skill보다 좁고 잘 설명된 skill이 더 잘 선택됨

즉, SKILL.md 본문을 길게 쓰는 것만큼 처음 읽히는 메타데이터를 정확하게 쓰는 것이 중요합니다.

skill을 호출하는 두 방법

명시적 호출

CLI/IDE에서 /skills를 보거나 $skill-name 형태로 직접 언급합니다. 이 방식은 사람이 어떤 workflow를 쓸지 확실히 알고 있을 때 좋습니다.

암묵적 호출

Codex가 description을 보고 "이 작업은 저 skill이 맞다"고 판단하면 스스로 사용합니다. 이 방식은 skill 설명이 충분히 구체적일 때 잘 동작합니다.

그래서 description에는 적어도 아래가 들어가야 합니다.

무엇을 하는가
언제 쓰는가
무엇을 하지 않는가
결과물이 어떤 형태인가

`SKILL.md`에 꼭 들어가야 할 것

실무에서 좋은 SKILL.md는 긴 산문보다 실행 규칙이 잘 정리되어 있습니다.

최소한 아래 항목을 고려하세요.

skill 이름과 한 줄 설명
언제 이 skill을 써야 하는지
입력으로 무엇을 기대하는지
실행 순서
성공 조건과 종료 조건
실패 시 fallback
필요한 스크립트나 참고 자료 위치

간단한 뼈대는 아래처럼 잡을 수 있습니다.

---
name: release-notes
description: 최근 merged PR과 issue를 바탕으로 주간 릴리즈 노트 초안을 만든다.
---
 
## Use this when
- 주간 배포 공지가 필요할 때
- PR 목록은 있지만 사람 손으로 요약하는 데 시간이 오래 걸릴 때
 
## Inputs
- 비교할 브랜치 또는 기간
- 포함/제외할 폴더
 
## Steps
1. 관련 변경 목록 수집
2. user-facing change와 internal chore 분리
3. 초안 생성
4. 누락 항목 체크
 
## Done when
- 초안이 지정 포맷을 따른다
- 변경 근거가 누락되지 않는다
- 사람이 검토하기 쉬운 섹션 구조를 가진다

좋은 description을 쓰는 법

description이 모호하면 Codex도 skill을 잘못 고르기 쉽습니다. 아래 비교를 보세요.

나쁨:

문서를 도와주는 skill

좋음:

제품 문서의 frontmatter 누락 필드를 찾고, 기존 문서 패턴에 맞춰 수정 초안을 제안한다.
문서 구조를 전면 재작성하는 작업에는 사용하지 않는다.

좋은 description은 scope와 금지 범위를 같이 보여줍니다. 이게 암묵적 호출 정확도를 높입니다.

personal skill과 team-shared skill을 나누는 기준

Best practices 문서 기준으로 보통 위치는 이렇게 나뉩니다.

개인 skill → $HOME/.agents/skills
팀 공유 skill → 저장소 내부 .agents/skills

둘의 역할을 섞지 않는 것이 중요합니다.

개인 skill에 적합한 것

개인 생산성 습관
특정 개인 도구나 계정에 묶인 workflow
여러 저장소에서 두루 쓰는 개인 요약/정리 절차

팀 공유 skill에 적합한 것

저장소 규칙을 전제로 하는 workflow
팀 리뷰 포맷, 문서 포맷, 배포 루틴
신규 구성원이 바로 재사용해야 하는 절차
MCP, scripts, AGENTS 규칙과 결합된 팀 표준 작업

팀 공유 skill을 저장소에 두면 "이 팀이 반복 작업을 어떻게 처리하는가"가 코드와 함께 남습니다. 그래서 온보딩과 리뷰 품질이 좋아집니다.

좋은 skill 설계법

1. 범위를 좁혀라

"모든 문서를 고품질로 바꿔라"보다 "frontmatter를 점검하고 누락 필드를 채워라"가 낫습니다.

2. 시작 조건과 종료 조건을 적어라

언제 써야 하는지, 언제 끝났다고 보는지를 써두면 암묵적 호출과 자동 실행 품질이 좋아집니다.

3. `SKILL.md`에 모든 걸 밀어 넣지 마라

반복 명령은 scripts/, 표준 예시는 references/로 분리하세요. 그러면 SKILL.md는 운영 안내서 역할에 집중할 수 있습니다.

4. 기존 저장소 패턴을 참조하라

"우리 스타일대로"보다 "이 폴더의 기존 문서처럼"이 더 잘 작동합니다.

5. 검증 루프를 포함하라

skill이 실제 편집이나 생성까지 한다면, 마지막에 무엇을 검증해야 하는지 적어야 합니다. 예: lint, 특정 스크립트, 샘플 diff 점검.

`scripts/`와 `references/`를 어떻게 나누면 좋을까

초보자가 많이 헷갈리는 지점이라, 간단히 기준을 잡아두면 좋습니다.

`scripts/`에 두기 좋은 것

반복 shell 명령
frontmatter 보정 스크립트
결과물 검증 스크립트
외부 데이터 정리용 작은 유틸

`references/`에 두기 좋은 것

좋은 결과물 예시
팀 문체 가이드
체크리스트 템플릿
도메인별 기준 문서

판단 기준은 간단합니다. 실행되는 것은 scripts/, 읽히는 것은 references/ 입니다.

skill, AGENTS, MCP, automation의 역할 분리

이 넷은 자주 같이 쓰이지만 역할이 다릅니다.

AGENTS.md = 저장소의 지속 규칙
skill = 반복 워크플로우
MCP = 외부 시스템 접근
automation = 안정화된 반복 작업의 스케줄링/백그라운드 실행
프롬프트 = 오늘 해야 하는 구체적인 요청

구분이 흐려지면 관리가 어려워집니다. 예를 들어 저장소 전체 규칙은 skill이 아니라 AGENTS.md에 있어야 하고, 외부 문서 접근은 skill 설명이 아니라 MCP 구성에 있어야 합니다.

subagent가 더 맞는 경우도 있다

skill은 반복 절차를 패키징하는 데 좋습니다. 반면 아래는 skill만으로 해결되지 않을 수 있습니다.

병렬 코드베이스 탐색
구현안 여러 개 비교
탐색/구현/검증을 동시에 돌리는 작업
대규모 리팩터링처럼 역할 분담이 필요한 작업

이런 경우는 subagent 요청이나 worktree 기반 병렬 흐름이 더 잘 맞습니다. 즉, skill은 반복 절차, subagent는 병렬 역할 분담에 강합니다.

automation과 조합하면 진가가 난다

Automations 문서에 따르면 안정된 반복 작업은 background에서 스케줄링할 수 있습니다. 여기서 skill은 automation의 재사용 가능한 본문이 됩니다.

예를 들어:

매주 release notes draft 생성
최근 커밋 요약
docs drift 점검
특정 폴더 lint/triage
배포 전 체크리스트 초안 생성

이런 작업은 프롬프트 하나보다 skill + automation 조합이 오래갑니다. "사람이 매번 같은 설명을 붙이는 상태"에서 벗어나기 쉽기 때문입니다.

MCP와 결합되는 skill 예시

skills는 외부 맥락이 필요할 때 MCP와 자연스럽게 이어집니다.

예시:

bug-triage skill이 issue tracker MCP와 incident 문서를 먼저 읽음
docs-sync skill이 공식 문서 MCP를 조회한 뒤 drift를 점검함
release-notes skill이 PR, ticket, changelog 시스템을 함께 참조함

이 조합이 강한 이유는 명확합니다. skill은 순서를 고정하고, MCP는 필요한 근거를 공급합니다.

바로 써먹는 skill 설계 체크리스트

새 skill을 만들기 전에:

정말 반복 작업인가?
입력과 출력이 비교적 일정한가?
description만 읽어도 언제 써야 하는지 명확한가?
긴 설명 대신 scripts/와 references/로 분리할 수 있는가?
팀 규칙이라면 저장소 공유 위치에 두는 것이 맞는가?

처음 만든 뒤에는:

이름이 지나치게 넓지 않은가?
성공 조건이 측정 가능한가?
너무 많은 예외 케이스를 한 skill에 몰아넣지 않았는가?
실제 사용 후 자주 수정되는 단계가 무엇인지 보였는가?

안정화된 뒤에는:

매번 수동으로 실행할 필요가 있는가?
automation으로 승격할 가치가 있는가?
관련 MCP 조회나 검증 스크립트를 더 붙일 수 있는가?

빠르게 기억할 운영 원칙

다섯 가지만 기억한다면 아래를 기억하세요.

먼저 SKILL.md를 만들고 description을 좁고 정확하게 쓴다.
Codex는 본문보다 metadata를 먼저 본다는 점을 잊지 않는다.
개인 skill과 팀 공유 skill의 경계를 의식적으로 나눈다.
반복 기계 작업은 scripts/, 안정 예시는 references/나 assets/로 뺀다.
manual workflow가 안정화된 뒤에만 automation으로 올린다.

흔한 실패 패턴

“skill을 만들었는데 거의 호출되지 않는다”

대개 description이 너무 넓거나, 언제 써야 하는지가 불분명합니다.

“`SKILL.md`가 너무 길어서 유지보수가 어렵다”

실행 가능한 부분과 참고 자료를 분리하지 않았을 가능성이 큽니다.

“개인 workflow를 팀 skill로 올려서 아무도 못 쓴다”

개인 계정, 개인 도구, 개인 취향에 강하게 묶여 있으면 팀 공유보다는 개인 skill이 맞습니다.

“automation에 올렸더니 예외 상황에서 자주 실패한다”

아직 skill이 충분히 안정화되지 않았을 수 있습니다. 자동화는 보통 사람이 여러 번 수동으로 돌려 본 뒤 올리는 편이 낫습니다.

빠른 시작용 미니 예시

예를 들어 문서 frontmatter 점검 skill을 만든다면 이렇게 생각할 수 있습니다.

SKILL.md에는 사용 시점, 금지 범위, 종료 조건을 적는다.
scripts/validate-frontmatter.js에는 실제 검사 로직을 둔다.
references/good-frontmatter.md에는 팀 예시를 둔다.
반복 사용 후 안정되면 automation에 연결한다.

이 구조를 잡아두면 사람도 읽기 쉽고, Codex도 선택하기 쉬우며, 나중에 자동화하기도 쉬워집니다.

반복 작업이 쌓이기 시작했다면, Codex를 더 잘 쓰는 다음 단계는 프롬프트 장인이 되는 것이 아니라 좋은 skill을 쌓고, 팀과 공유하고, 안정화되면 automation까지 올리는 팀이 되는 것입니다.

연결된 가이드