2 분 소요

요약

반복되는 Codex 작업을 매번 프롬프트에 길게 적는 것은 유지보수하기 어렵다. 블로그 글 작성, 릴리스 노트 작성, 코드 리뷰, 마이그레이션 점검처럼 절차가 반복된다면 skill로 분리하는 편이 낫다.

skill은 Codex에게 새로운 “지식 덩어리”를 무조건 많이 주는 장치가 아니다. 특정 작업에서만 필요한 절차, 참고자료, 스크립트를 필요할 때 불러오는 재사용 단위다.

문서 정보

  • 작성일: 2026-04-23
  • 검증 기준일: 2026-04-23
  • 문서 성격: analysis
  • 테스트 환경: 실행 테스트 없음. OpenAI Codex 공식 문서를 바탕으로 한 skill 설계 기준 정리.
  • 테스트 버전: OpenAI Codex 문서 2026-04-23 확인본

문제 정의

반복 절차를 AGENTS.md에 계속 추가하면 지침 파일이 길어진다. 반대로 매번 요청에 붙이면 누락과 편차가 생긴다. 이 중간에 필요한 것이 재사용 가능한 작업 단위다.

이 글은 어떤 작업을 skill로 만들고, skill에는 무엇을 담아야 하는지 정리한다.

확인된 사실

공식 문서 기준: Codex skill은 작업별 기능과 전문성을 확장하기 위한 구조이며, instructions, resources, optional scripts를 패키징할 수 있다. 근거: OpenAI, Agent Skills

공식 문서 기준: skill은 SKILL.md 파일을 가진 디렉터리이며, scripts, references, assets, agents 폴더를 선택적으로 포함할 수 있다. SKILL.md에는 name과 description이 필요하다. 근거: OpenAI, Agent Skills

공식 문서 기준: Codex는 skill metadata를 먼저 보고, 작업이 skill과 맞는다고 판단할 때 전체 SKILL.md 지침을 로드하는 progressive disclosure 방식을 사용한다고 설명한다. 근거: OpenAI, Agent Skills

공식 문서 기준: skill은 명시적으로 호출할 수 있고, 작업이 skill description과 맞을 때 Codex가 암묵적으로 선택할 수도 있다. 근거: OpenAI, Agent Skills

직접 재현한 결과

직접 재현 없음: 이 글은 새 skill을 만든 뒤 Codex의 선택률을 측정한 실험이 아니다. 공식 문서의 skill 구조를 기준으로 반복 작업 분리 기준을 정리한다.

해석 / 의견

내 판단으로는 아래 조건을 만족하면 skill 후보로 볼 수 있다.

  • 같은 절차를 여러 번 반복한다.
  • 절차가 길어 AGENTS.md에 넣기 부담스럽다.
  • 참고자료나 템플릿이 필요하다.
  • 스크립트로 자동화할 일부 단계가 있다.
  • 작업의 입력과 출력 형식이 비교적 안정적이다.

skill의 최소 구조는 아래처럼 잡을 수 있다.

---
name: blog-writing
description: 기술 블로그 글을 검증 가능한 구조로 작성하거나 개정할 때 사용한다.
---

# Blog Writing

## When to use

- 새 기술 글 작성
- 기존 글 검증 구조 보강

## Workflow

1. 저장소 지침을 읽는다.
2. 템플릿을 확인한다.
3. 사실, 직접 재현, 의견을 분리한다.
4. 참고자료를 공식 문서 우선으로 연결한다.
5. 한계와 예외를 남긴다.

의견: 좋은 skill은 “많이 알려주는 문서”보다 “같은 절차를 반복 가능하게 만드는 작은 운영 단위”에 가깝다. description이 특히 중요하다. Codex가 언제 이 skill을 써야 하는지 판단하는 첫 단서가 되기 때문이다.

한계와 예외

한두 번만 하는 작업을 모두 skill로 만들 필요는 없다. skill이 많아지면 어떤 skill을 언제 써야 하는지 관리해야 한다.

또한 skill은 검증을 자동으로 보장하지 않는다. skill 안에 절차를 적어도, 실제 품질은 테스트, 리뷰, CI 같은 검증 계층과 함께 봐야 한다.

참고자료

댓글남기기

참고