Chapter 09. Skills 만들기

Codex를 처음 쓸 때는 누구나 비슷한 실수를 합니다. 매번 비슷한 말을 길게 써서 일을 맡깁니다.

"PR 리뷰할 때는 보안도 봐주고, 테스트도 확인하고, 마이그레이션이 있으면 위험도 체크하고, 코멘트는 severity를 붙여서 정리해줘."

처음에는 이 방식도 괜찮습니다. 하지만 세 번째부터는 피곤해집니다. 열 번째부터는 팀마다 말이 달라지고, 스무 번째부터는 결과 품질도 흔들립니다. 이때 필요한 것이 바로 Skills입니다. Skills는 반복 프롬프트를 재사용 가능한 작업 단위로 바꿔, Codex가 매번 설명을 다시 들어야 하는 도구가 아니라 점점 더 축적되는 시스템이 되게 만듭니다.¹

Skills는 프롬프트가 아니라 작업 단위다

Skills를 한 문장으로 말하면, 특정 작업을 안정적으로 수행하게 만드는 작은 워크플로 패키지입니다. 지침만 넣는 것이 아니라, 필요하면 스크립트와 참고 문서, 템플릿까지 함께 묶을 수 있습니다.¹

여기서 AGENTS.md와 역할을 구분하면 훨씬 이해가 빨라집니다.

AGENTS.md는 "이 저장소에서 Codex가 어떻게 행동해야 하는가"를 알려주는 저장소 운영 설명서에 가깝습니다. 반면 Skill은 "이 종류의 작업을 어떤 순서와 기준으로 처리할 것인가"를 알려주는 작업 플레이북입니다.

쉽게 말해 AGENTS.md가 회사 건물 입구의 안내 데스크라면, Skill은 각 부서의 표준 작업 매뉴얼입니다. 안내 데스크는 어디로 가야 하는지 알려주고, 매뉴얼은 그 일을 어떻게 하는지 알려줍니다.

이 차이를 이해하면 언제 무엇을 넣어야 할지도 명확해집니다. 저장소 공통 규칙, 테스트 명령, 절대 건드리면 안 되는 디렉터리는 AGENTS.md에 둡니다. PR 리뷰 절차, 마이그레이션 점검 순서, 릴리스 체크리스트처럼 반복 가능한 작업은 Skill로 뺍니다.

스킬은 어떻게 생겼나

Skill은 폴더 하나로 구성됩니다. 핵심은 SKILL.md이고, 나머지는 필요할 때 붙입니다.²

next-supabase-pr-review/
├── SKILL.md
├── agents/
│   └── openai.yaml
├── scripts/
│   └── collect_changed_files.sh
├── references/
│   ├── review-checklist.md
│   └── rls-safety.md
└── assets/
    └── review-comment-template.md

이 구조를 보면 감이 옵니다.

• SKILL.md는 필수입니다. 이름, 설명, 그리고 Codex가 따라야 할 핵심 절차가 들어갑니다.

• scripts/는 반복해서 같은 코드를 짜게 될 때 넣습니다. 예를 들어 변경 파일 목록 수집, PR 메타데이터 정리, 특정 테스트 실행처럼 결정적으로 같은 동작이 필요한 경우입니다.

• references/는 참고 자료를 넣는 곳입니다. 예를 들어 RLS 정책 점검 기준, 팀의 API 계약, 배포 정책 같은 문서가 여기에 잘 어울립니다.

• assets/는 출력물에 쓰일 템플릿이나 리소스를 둡니다. 리뷰 코멘트 템플릿, PR 설명 템플릿, 보고서 형식 파일 같은 것들입니다.²

중요한 점은, Skill은 "길게 쓰는 것"보다 "적절히 나누는 것"이 더 중요하다는 것입니다. SKILL.md에 모든 것을 욱여넣으면 처음엔 든든해 보이지만, 실제로는 컨텍스트만 비대해지고 트리거 품질도 떨어집니다.

SKILL.md의 최소 구조

SKILL.md는 앞부분의 메타데이터와 본문으로 나뉩니다. 메타데이터에서 특히 중요한 것은 name과 description입니다. Codex는 이 설명을 보고 어떤 Skill을 쓸지 판단합니다.²

---
name: next-supabase-pr-review
description: Use this skill when reviewing pull requests in a Next.js + Supabase app. Check auth changes, database migrations, RLS policies, API routes, and test impact before merge. Do not use it for feature planning or UI copywriting.
---

# Next.js + Supabase PR Review

## Goal
Review pull requests consistently and produce a severity-based review summary.

## Inputs
- Changed files and diff
- Test or CI results
- Migration files
- Related issue or PR description

## Workflow
1. Summarize the scope in three sentences or fewer.
2. Inspect auth-related changes first.
3. If `supabase/migrations/` changed, read `references/rls-safety.md`.
4. Check whether tests cover the changed behavior.
5. Produce findings in Must fix / Should fix / Nice to have / Questions.

## Guardrails
- Do not approve migration changes without reading them line by line.
- Flag any RLS change with possible user-impact.
- Prefer evidence-based comments over vague opinions.

이 예시에서 핵심은 세 가지입니다.

첫째, description은 언제 쓰는지와 언제 쓰지 않는지를 동시에 말합니다. 이게 있어야 Codex가 엉뚱한 상황에서 스킬을 꺼내 들지 않습니다.

둘째, 본문은 작업 절차와 판단 기준 위주로 씁니다. Skill은 장문의 철학 문서가 아니라, 실제로 일을 시킬 때 따라야 하는 절차서여야 합니다.

셋째, 변형이 많은 세부 내용은 references/로 보냅니다. 예를 들어 RLS 정책, 팀별 리뷰 규칙, 프론트엔드 접근성 체크리스트는 필요할 때만 읽게 해야 효율적입니다.²

progressive disclosure: 스킬은 필요한 만큼만 읽힌다

Skills의 가장 중요한 설계 원리는 progressive disclosure, 한국어로 하면 점진적 공개입니다. 쉽게 말해, Codex는 시작할 때 모든 스킬 본문을 다 읽지 않습니다. 우선 이름과 설명만 보고 있다가, 해당 스킬이 필요해 보일 때만 SKILL.md 본문을 읽고, 그다음 필요하면 references/나 scripts/를 더 봅니다.²³

이 구조가 왜 중요할까요? 이유는 간단합니다. 컨텍스트 창은 공짜가 아니기 때문입니다. 대화 기록도 들어가야 하고, 현재 작업 파일도 읽어야 하고, AGENTS.md도 참고해야 합니다. 그런데 스킬마다 장문의 설명을 매번 다 올리면, 정작 지금 해야 할 작업에 쓸 공간이 줄어듭니다.

비유하자면 이렇습니다.

엘리베이터 앞 안내판에는 각 층 이름만 적어 둡니다. 회의실 안에 들어가서야 상세한 자료집을 펼칩니다. 창고 문을 열어 실제 장비를 꺼내는 건 정말 필요할 때만 합니다. Skills의 메타데이터, 본문, 리소스가 바로 그런 3단 구조입니다.³

그래서 좋은 Skill은 두껍지 않습니다. 오히려 뼈대가 선명합니다. 핵심 절차만 본문에 두고, 프레임워크별 차이, 긴 API 문서, 팀 고유 정책은 reference 파일로 분리합니다.²

좋은 description이 스킬 품질의 절반이다

많은 사람이 Skill을 만들면서 본문만 공들여 씁니다. 그런데 실제로는 description이 훨씬 중요합니다. Codex는 description을 보고 스킬을 자동 선택할 수 있기 때문입니다.²⁴

나쁜 description은 대체로 두 가지 유형입니다.

• 너무 넓다. 예를 들면 "코드를 리뷰할 때 사용한다."

• 너무 모호하다. 예를 들면 "좋은 개발을 도와준다."

이런 설명은 마치 검색창에 "좋은 것"이라고 입력하는 것과 비슷합니다. 맞을 수도 있지만, 대부분은 엉뚱합니다.

좋은 description은 세 가지를 담습니다.

• 어떤 상황에서 쓰는가

• 어떤 기준으로 일하는가

• 언제는 쓰지 말아야 하는가

예를 들어 다음 두 설명을 비교해 봅시다.

나쁜 예:

description: Pull request를 리뷰할 때 사용한다.

좋은 예:

description: Use this skill when reviewing pull requests in a Next.js + Supabase product. Focus on auth flow changes, RLS policies, schema migrations, API route safety, and test impact before merge. Do not use this skill for greenfield feature planning, UI copywriting, or design critique.

두 번째 설명은 트리거 정확도가 높습니다. 한국 개발자 실무에서는 특히 이런 식의 구체성이 중요합니다. 이유는 우리가 다루는 스택이 꽤 정해져 있기 때문입니다. Next.js + Supabase, Express + MongoDB, React Native 슈퍼앱 클론, 사내 백오피스 등은 점검 포인트가 뚜렷합니다. 그 포인트를 description에 녹여야 자동 호출이 똑똑해집니다.

본문은 자세함보다 자유도 설계가 중요하다

Skill 본문을 쓸 때는 "얼마나 자세히 쓰느냐"보다 "얼마나 자유롭게 움직이게 둘 것이냐"를 먼저 생각해야 합니다.²

작업마다 필요한 자유도가 다릅니다.

• 여러 접근이 가능한 작업은 텍스트 지침 중심으로 둡니다. 예를 들어 PR 설명 요약, 리팩터링 아이디어 비교, 테스트 전략 제안 같은 일입니다.

• 선호 패턴은 있지만 상황별 차이가 있는 작업은 의사코드나 파라미터화된 스크립트를 섞습니다. 예를 들어 배포 전 점검, 린트+타입체크+테스트 순서 정리 같은 일입니다.

• 실수 비용이 큰 작업은 구체적 스크립트와 낮은 자유도로 묶습니다. 예를 들어 데이터 마이그레이션 검증, 보안 스캔, 배포 태그 생성 같은 일입니다.²

이 원리를 놓치면 두 가지 문제가 생깁니다. 너무 빡빡하면 사소한 예외마다 깨지고, 너무 느슨하면 매번 결과가 흔들립니다. 좋은 Skill은 좁은 다리에서는 난간을 세우고, 넓은 들판에서는 방향만 잡아줍니다.

개인 스킬, 팀 스킬, 시스템 스킬은 어디에 둘까

Skill은 범위에 따라 두는 자리가 달라집니다. 실무에서는 이 구분이 꽤 중요합니다. 어디에 놓느냐가 곧 누가 쓸 수 있느냐를 결정하기 때문입니다.⁴⁵

개인 스킬은 보통 ~/.codex/skills/ 아래에 둡니다. 모든 프로젝트에서 쓰는 나만의 작업 방식이 여기에 어울립니다. 예를 들면 커밋 메시지 정리, 개인 블로그 초안 생성, PR 리뷰 톤 정리 같은 것입니다.⁴

프로젝트 또는 팀 스킬은 저장소 안의 .codex/skills/ 아래에 두는 식으로 관리할 수 있습니다. 이 위치에 두면 팀원들이 같은 워크플로를 공유하기 쉬워집니다. 예를 들어 next-supabase-pr-review, vercel-predeploy-check, mongo-index-audit 같은 스킬은 팀 스킬에 잘 맞습니다.⁴

시스템 스킬은 Codex가 기본 제공하거나, 조직 차원에서 관리하는 공용 스킬에 가깝습니다. skill-creator처럼 도구 자체를 확장하는 역할을 맡는 경우가 여기에 속합니다.⁵

실무 팁을 하나 더 보태면, 개인 스킬은 취향을 담고, 팀 스킬은 규칙을 담는 편이 좋습니다.

개인의 문체, 요약 스타일, 즐겨 쓰는 체크 방식은 전역 스킬로 빼면 됩니다. 반대로 테스트 기준, 리뷰 severity 체계, 마이그레이션 점검 순서처럼 모두가 같아야 하는 것은 저장소 스킬로 두는 편이 낫습니다.

스킬 호출: 직접 부를 수도 있고, Codex가 알아서 쓸 수도 있다

Skill은 두 가지 방식으로 동작합니다. 하나는 직접 부르는 방식이고, 다른 하나는 자동으로 선택되게 만드는 방식입니다.⁵⁴

직접 호출은 의도가 분명해서 좋습니다. 예를 들어 아래처럼 쓸 수 있습니다.

$next-supabase-pr-review review this PR before merge

또는 /skills로 목록을 보고 골라 쓸 수도 있습니다.⁵

반대로 description을 잘 써 두면, 사용자가 "이 PR에서 Supabase migration 위험한 부분 봐줘"라고 말했을 때 Codex가 알아서 적절한 스킬을 고를 수 있습니다.⁵

처음에는 명시적 호출부터 시작하는 편이 좋습니다. 자동 선택은 편리하지만, description 품질이 낮으면 엉뚱한 스킬이 튀어나올 수 있기 때문입니다. 팀에 배포하기 전에는 직접 호출 → 트리거 테스트 → 자동 호출 허용 순으로 가는 것이 안전합니다.

첫 번째 스킬 만들기: PR 리뷰 자동화 스킬

이제 진짜로 하나 만들어 봅시다. 가장 추천하는 첫 스킬은 PR 리뷰 자동화입니다. 이유는 명확합니다. 거의 모든 팀이 반복하고, 기준이 흔들리기 쉽고, 결과를 바로 체감할 수 있기 때문입니다.

예시는 한국 개발자가 많이 만드는 Next.js + Supabase 서비스로 잡아보겠습니다. 로그인, 대시보드, 구독 결제, 관리자 화면이 있는 SaaS라고 생각하면 됩니다.

1단계: 스킬의 범위를 좁힌다

처음부터 "모든 코드 리뷰"를 잡지 마세요. 그 순간 description이 흐려집니다.

좋은 첫 범위는 이런 식입니다.

• Next.js + Supabase 서비스의 PR 리뷰

• 인증, API 라우트, DB 마이그레이션, 테스트 영향 검토

• 결과는 severity 기반 코멘트로 정리

이 정도면 충분히 좁고, 실제로 자주 쓰입니다.

2단계: 폴더를 만든다

.codex/skills/next-supabase-pr-review/
├── SKILL.md
├── references/
│   ├── review-checklist.md
│   └── rls-safety.md
├── scripts/
│   └── collect_review_context.sh
└── assets/
    └── review-output-template.md

여기서 욕심을 줄이는 게 중요합니다. 첫 버전은 SKILL.md 하나로도 됩니다. 다만 RLS나 마이그레이션처럼 길어질 내용은 처음부터 references/로 분리할 준비를 해 두는 편이 좋습니다.

3단계: SKILL.md를 쓴다

아래는 책용으로 다듬은 예시입니다.

---
name: next-supabase-pr-review
description: Use this skill when reviewing pull requests for a Next.js + Supabase product. Focus on auth flow changes, route handlers, schema migrations, RLS policies, environment variable safety, and test impact. Do not use this skill for feature ideation, UI copywriting, or design-only feedback.
---

# Next.js + Supabase PR Review

## Goal
Pull request를 병합하기 전에 기능 영향, 데이터 안전성, 인증 흐름, 테스트 누락 가능성을 일관된 기준으로 검토한다.

## Inputs
- PR 설명
- 변경 파일 목록과 diff
- 테스트/CI 결과
- 관련 이슈 링크

## Workflow
1. PR의 범위를 세 문장 이내로 요약한다.
2. 인증 관련 파일(`middleware.ts`, `lib/auth`, `app/api`)을 먼저 확인한다.
3. `supabase/migrations/` 변경이 있으면 `references/rls-safety.md`를 읽는다.
4. 환경변수 추가·변경이 있으면 서버 전용/클라이언트 노출 여부를 구분한다.
5. 테스트가 없거나 부족하면 어떤 테스트가 필요한지 제안한다.
6. 결과를 Must fix / Should fix / Nice to have / Questions 형식으로 정리한다.

## Guardrails
- 근거 없는 추측성 리뷰를 하지 않는다.
- 스키마 변경은 반드시 데이터 영향 관점에서 본다.
- 보안 이슈는 severity와 영향 범위를 함께 적는다.

## Output
- 범위 요약
- 주요 리스크
- 항목별 리뷰 코멘트
- 머지 전 확인할 사항

이 예시가 좋은 이유는 화려해서가 아니라, 재사용성이 높기 때문입니다. 누가 써도 비슷한 기준으로 리뷰하게 만들고, 중요한 파일을 먼저 보게 하며, 출력 형식까지 고정해 줍니다.

4단계: reference 파일로 세부 기준을 분리한다

references/review-checklist.md에는 공통 점검 항목을 넣을 수 있습니다. 예를 들어 인증 우회 가능성, 입력 검증, 에러 처리, 테스트 누락 유형 등을 정리합니다.

references/rls-safety.md에는 Supabase 특유의 위험 포인트를 담습니다. 예를 들어 정책 변경 시 익명 사용자 접근, 팀 단위 멀티테넌시 누수, 서비스 롤 키 사용 구간 같은 항목이 들어갈 수 있습니다.

이렇게 나누면 SKILL.md는 짧고 명확하게 유지되고, 세부 내용은 필요한 순간에만 꺼내 볼 수 있습니다. 바로 progressive disclosure의 효과입니다.²³

5단계: 출력 템플릿을 asset으로 둔다

리뷰 결과 형식이 들쭉날쭉하면 스킬 품질이 흔들려 보입니다. 이럴 때 assets/review-output-template.md를 두면 좋습니다.

## Scope

## Must fix

## Should fix

## Nice to have

## Questions

## Merge recommendation

이 템플릿은 거창한 기술이 아닙니다. 하지만 팀으로 가면 이런 사소한 일관성이 엄청난 힘을 발휘합니다. 회의 시간이 줄고, 리뷰 톤이 정리되고, "이 PR은 왜 승인됐지?" 같은 잡음도 줄어듭니다.

스킬이 망하는 패턴

Skill은 잘 만들면 강력하지만, 못 만들면 그냥 오래된 프롬프트 보관함이 됩니다. 특히 아래 패턴은 빨리 피하는 것이 좋습니다.²⁶

• 한 스킬에 너무 많은 역할을 넣는 경우

• 이전 대화 맥락에 의존하게 만드는 경우

• 스크립트 없이도 될 일을 무조건 코드로 푸는 경우

• description을 짧게만 쓰고 트리거를 운에 맡기는 경우

• SKILL.md 안에 참고 문서를 전부 복붙하는 경우

특히 한 스킬, 한 작업 원칙은 거의 법칙에 가깝습니다. PR 리뷰 스킬은 PR 리뷰만 잘하면 됩니다. 여기에 커밋 메시지 생성, 릴리스 노트 작성, 이슈 트리아지까지 다 넣으면 결국 아무것도 잘 못하게 됩니다.⁶

또 하나 중요한 원칙은 zero context assumption입니다. Skill은 "이전 대화에서 이미 알고 있겠지"를 기대하면 안 됩니다. 누가 언제 어떤 세션에서 호출해도 돌아가야 합니다.⁶

팀에서 스킬을 굴릴 때의 운영 팁

개인 실험 단계와 팀 운영 단계는 다릅니다. 팀에서 쓰기 시작하면 스킬도 사실상 작은 내부 도구가 됩니다.

첫째, 스킬 이름을 업무 언어에 맞추세요. 팀에서 "릴리스 점검", "배포 전 확인", "RLS 리뷰"라고 부르면 스킬 이름도 그 감각에 맞는 편이 좋습니다. 사람이 실제로 쓰는 표현과 멀어질수록 자동 호출 품질이 떨어집니다.

둘째, AGENTS.md에서 어떤 스킬을 언제 쓰는지 연결해 주세요. AGENTS.md가 라우터이고 Skill이 실행 매뉴얼이라는 관점으로 보면, 둘을 연결하는 순간 팀 전체 워크플로가 훨씬 자연스러워집니다.

셋째, 스킬의 성능은 "멋진 문장"이 아니라 "사라진 반복 설명"으로 측정하세요. 같은 프롬프트를 세 번 이상 썼다면 스킬 후보입니다. 반대로 한 달 동안 아무도 다시 안 쓰는 스킬은 과감히 합치거나 삭제하는 편이 낫습니다.

넷째, 팀 스킬은 코드처럼 리뷰하세요. description 변경 하나가 자동 호출 결과를 바꿀 수 있으니, 스킬도 PR로 관리하는 것이 좋습니다.

결국 스킬은 팀의 암묵지를 파일로 만드는 일이다

지금까지의 내용을 한 줄로 줄이면 이렇습니다.

Skill은 잘 쓰는 프롬프트가 아니라, 반복되는 팀 판단을 파일로 굳히는 방식이다.

그래서 스킬을 만들기 시작하면 Codex의 성격도 달라집니다. 예전에는 "그때그때 말 잘 알아듣는 도구"였다면, 이제는 "한 번 가르치면 다음부터는 같은 기준으로 일하는 시스템"이 됩니다.

이 변화가 꽤 큽니다. 특히 혼자 만드는 1인 SaaS든, 여러 명이 붙는 스타트업이든, 일관성이 생기는 순간 AI의 효율이 갑자기 올라갑니다.

다음 장에서는 이 Skills를 개인 자산에서 팀 배포 자산으로 확장하는 방법, 즉 Plugins로 워크플로를 배포하는 법을 다뤄보겠습니다.

참고

¹Agent Skills - Codex | OpenAI Developers

²skills/skills/.system/skill-creator/SKILL.md at main · openai/skills · GitHub

³Progressive Disclosure Model | openai/skills | DeepWiki

⁴Codex CLI Skills: Install & Use SKILL.md (2026 Guide)

⁵Codex에 공식적으로 도입된 Skills | GeekNews

⁶Codex Skills Deep Dive: Progressive Disclosure, Triggers, and Best Practices