코덱스 Skills 제대로 만들기: 반복 작업을 프롬프트에서 워크플로로 바꾸는 법

같은 발행 절차, 마이그레이션 검사, 디자인 자산 생성 규칙을 매번 긴 프롬프트로 복사한다면 Skill 후보가 맞다. Skill은 SKILL.md와 필요한 리소스를 한 폴더에 묶어 Codex가 해당 작업에서만 읽고 실행하게 한다.

중요한 점은 “프롬프트를 파일로 저장한다”에서 끝나지 않는다는 것이다. 언제 이 Skill을 선택해야 하는지, 어떤 파일을 순서대로 읽을지, 제공된 스크립트와 템플릿을 어떻게 재사용할지까지 설계해야 반복 가능한 워크플로가 된다.

Skill이 필요한 작업과 필요 없는 작업

좋은 후보는 입력만 달라지고 절차는 반복되는 작업이다. 예를 들어 영상 대본을 받아 출처를 대조하고, 정해진 기사 구조로 변환하고, 빌드·발행까지 검증하는 과정은 여러 단계와 자산을 공유한다.

한 번만 쓰는 기능 요구는 프롬프트가 낫다. 모델이 기본적으로 잘하는 일반 코드 읽기·테스트까지 Skill로 포장하면 선택지가 늘고 설명이 잘릴 뿐이다.

• 적합: 반복 발행, 특정 포맷 변환, 조직 고유 검수, 도구 연동 절차
• 부적합: 단순 설명, 한 줄 수정, 일반적인 코딩 상식, 수시로 바뀌는 일회성 요구

좋은 Skill 폴더의 구조

루트의 SKILL.md에는 발동 조건과 핵심 흐름을 둔다. 긴 참고자료는 references/, 반복 실행은 scripts/, 템플릿과 시각 자산은 assets/처럼 나누면 필요한 것만 점진적으로 읽을 수 있다.

SKILL.md에서 관련 파일의 상대 경로와 읽어야 할 조건을 명확히 쓴다. 사용자가 이미 준 요구를 무시하거나 작업 범위를 확대하는 지침은 넣지 않는다.

my-workflow/
├── SKILL.md
├── references/
│   ├── source-policy.md
│   └── review-checklist.md
├── scripts/
│   └── validate-output.sh
└── assets/
    └── article-template.md

설명은 짧고 발동 조건은 구체적으로

Codex는 설치된 Skill의 이름과 설명을 보고 사용할지 판단한다. OpenAI는 Skill이 많을 때 설명이 컨텍스트에 맞게 축약될 수 있으므로 가능한 짧게 쓰되 적용 시점을 분명히 하라고 권한다.

“데이터베이스, 쿼리, 모델, 저장 작업에서 사용”처럼 넓은 설명은 평범한 코딩에도 발동한다. “PostgreSQL 스키마 마이그레이션을 생성하거나 검증할 때 사용”처럼 사용자 목표와 경계를 쓴다.

나쁜 설명
데이터베이스와 관련된 모든 작업을 돕는다.

좋은 설명
PostgreSQL 스키마 마이그레이션을 생성·검증하고 롤백 절차를 확인할 때 사용한다.

SKILL.md에는 결정 순서와 실패 처리를 써라

좋은 지침은 모든 문장을 강제 규칙으로 만들지 않는다. 입력을 확인하고, 필요한 참조만 읽고, 제공 스크립트를 재사용하고, 검증 실패 시 어디까지 자동 수정할지 순서를 적는다.

사용자 승인이 필요한 외부 변경, 비밀정보 취급, 파괴적 작업은 경계를 명시한다. Skill은 새로운 권한을 만드는 장치가 아니다. 현재 샌드박스와 승인 정책 안에서 실행된다.

Skill이 많을수록 좋은 것이 아니다

비슷한 Skill 세 개가 모두 “문서 작업에 사용”이라고 주장하면 Codex는 선택하기 어렵다. 설명이 겹치지 않도록 하나는 API 문서, 하나는 마케팅 페이지, 하나는 릴리스 노트처럼 사용자 목표를 분리한다.

새 모델로 바뀔 때는 낡은 비계를 삭제한다. 모델이 기본적으로 수행하는 탐색·테스트를 반복 지시하거나, 다른 Skill과 충돌하는 자율성 규칙을 누적하지 않는다.

배포 전 Skill 점검표

실제 사용자 문장으로 발동 테스트를 해본다. 반드시 발동해야 하는 요청과 발동하면 안 되는 인접 요청을 함께 적어보면 설명의 범위를 확인할 수 있다.

스크립트가 있다면 큰 코드 블록을 다시 생성하게 하지 말고 실행·수정하게 한다. 템플릿과 자산도 재사용하도록 경로를 명시한다.

• 설명에 사용자 목표와 발동 조건이 있는가
• SKILL.md가 불필요하게 모든 참조를 먼저 읽게 하지 않는가
• 스크립트·템플릿을 재사용하는가
• 실패·승인·중단 조건이 있는가
• 다른 Skill과 역할이 겹치지 않는가

자주 묻는 질문