Codex Skills: 반복 작업을 위한 skill 만들기

일주일에 다섯 번씩 Codex에게 같은 내용을 설명한다면 — 보고서 서식 지정, 이메일 분류, 내 스타일에 맞춘 문안 준비 방법 등 — 그 지침을 skill에 한 번 기록해 둘 수 있습니다. 그러면 설명이 작업과 일치할 때 에이전트가 설명을 바탕으로 skill을 찾거나, 직접 호출할 수 있습니다. skill은 SKILL.md라는 텍스트 파일이 들어 있는 일반 폴더입니다. 기본적인 용도에는 프로그래밍이 필요하지 않습니다.

아래에서는 skill의 구조, Codex가 skill을 찾는 위치, 단계별 생성 방법, 비용에 따른 모델 선택 방법을 다룹니다. 명령어와 가격은 2026년 9월 20일 기준 OpenAI 공식 문서를 바탕으로 합니다. 여기서는 Codex 설치 방법을 반복하지 않습니다. OpenAI Codex: 개요, 설치 및 실행 방법 가이드를 참고하세요.

Ailoot 사용에 관한 실용적인 정보는 문서에서 확인할 수 있습니다.

Codex의 skill이란 무엇인가요?#

이 형식은 Agent Skills라고 합니다. Anthropic이 처음 개발하고 agentskills.io에 공개한 오픈 표준입니다. Codex, Claude Code 및 기타 호환 클라이언트를 포함한 여러 에이전트에서 지원합니다. 텍스트 지침만 포함한 단순한 skill은 폴더를 복사해 서로 이전할 수 있습니다. 스크립트, 종속성 또는 agents/openai.yaml 파일이 들어 있다면 이전 후 skill을 확인하세요. 일부 설정은 특정 클라이언트에만 적용됩니다.

이 로딩 방식은 점진적 공개라고 합니다. 에이전트는 skill의 이름과 설명을 사용해 언제 관련이 있는지 판단합니다. 작업이 설명과 일치하면 에이전트가 SKILL.md 전체를 읽고 따릅니다. 따라서 모든 지침을 컨텍스트에 불러오지 않고도 Codex에 수십 개의 skill을 둘 수 있습니다. 처음 불러오는 목록은 컨텍스트 창의 최대 2%(창 크기를 모르는 경우 8,000자)를 차지합니다. skill이 많으면 Codex는 먼저 설명을 줄이며, 매우 많으면 일부를 목록에서 생략하고 사용자에게 알릴 수 있습니다.

skill과 AGENTS.md는 혼동하기 쉽습니다. Codex는 모든 프로젝트 세션에서 이 파일을 읽습니다. 여기에는 기술 스택, 규칙, 코딩 스타일 같은 상시 규칙이 들어 있습니다. 반면 skill은 작업이 설명과 일치할 때 요청에 따라 로드됩니다. 따라서 상시 규칙은 AGENTS.md에, 단계가 있는 반복 절차는 skill에 넣으세요.

Hermes Agent skill도 비슷하게 작동하지만 저장 위치와 설치 방법이 다릅니다. 별도 가이드인 Hermes Agent Skills: 설치 및 생성에서 다룹니다. 이 글은 Codex만 다룹니다.

Skill은 무엇으로 구성되나요?#

skill 폴더는 다음과 같은 구조입니다.

my-skill/
  SKILL.md        - 필수: 메타데이터와 지침
  scripts/        - 선택: 실행 가능한 코드
  references/     - 선택: 필요할 때 불러올 문서
  assets/         - 선택: 템플릿과 리소스
  agents/
    openai.yaml   - 선택: 표시 설정 및 종속성

SKILL.md 파일은 하이픈 세 개로 둘러싼 메타데이터 블록으로 시작하며, 이어서 Markdown 형식의 지침이 나옵니다.

---
name: weekly-sales-report
description: CSV 내보내기 파일에서 주간 판매 보고서를 작성합니다. 주간 판매 보고서나 관리자별 요약을 요청받았을 때 사용합니다.
---

1. 사용자가 제공한 경로에 있는 내보내기 파일을 읽습니다.
2. 행을 관리자별로 그룹화하고 거래 건수와 총액을 계산합니다.
3. 이전 주의 파일이 가까운 위치에 있으면 이전 주와 비교합니다. 파일이 없다면 보고서에 그 사실을 분명히 씁니다.
4. 결과를 report.md에 저장합니다. 관리자별 표, 총액, 데이터가 뒷받침하는 범위에서 최대 세 가지 주요 변경 사항과 수치를 포함합니다.

OpenAI의 공식 권장 사항에서 가져온 세 가지 규칙입니다.

• 하나의 skill에는 하나의 작업을 담습니다. “내 마케팅을 전부 처리해” 대신 “이 내보내기 파일로 판매 보고서를 작성해”처럼 구체적인 작업을 고르세요. 더 큰 절차는 순서대로 호출할 수 있는 여러 skill로 나누세요.
• 입력과 출력을 분명히 밝혀 단계별로 직접 작성합니다. 무엇을 사용하고, 무엇을 하며, 결과를 어디에 둘지 명시하세요.
• 텍스트 지침부터 시작합니다. 파일 변환이나 외부 시스템 호출처럼 한 단계를 매번 똑같이 실행해야 할 때 scripts/에 스크립트를 사용하세요.

Codex는 description 필드를 바탕으로 작업에 맞는 skill을 선택하므로, 설명을 작업 이름과 그 작업을 설명할 때 자주 쓰는 표현으로 시작하세요.

Codex는 어디에서 skill을 찾나요?#

프로젝트용 skill을 코드와 함께 git에 저장하면 팀 전체가 같은 모음을 사용할 수 있어 편리합니다. 개인 skill은 이메일 작성 스타일처럼 개인적인 절차에 적합합니다. 서로 다른 수준에서 두 skill의 이름이 같아도 Codex는 합치지 않습니다. 둘 다 목록에 표시되어 선택이 어려워집니다. 이름을 서로 다르게 지정하세요.

참고로 Claude Code skill은 각각 자체 SKILL.md를 포함해 .claude/skills에 저장되며, 같은 오픈 표준을 사용합니다. 단순한 skill은 폴더를 복사해 이전할 수 있습니다. 이전한 다음에는 실행해 skill이 호출되는지 확인하세요. Claude Code 확장을 비교하려면 Skills, Subagents, MCP 또는 Plugins를 참고하세요.

Codex는 어떤 skill을 호출할지 어떻게 결정하나요?#

처음에는 명시적 호출이 더 확실합니다. Codex CLI에서 $weekly-sales-report를 입력해 특정 절차를 선택하세요. 암묵적 호출은 일상적인 작업에서 더 편리합니다. skill을 작성한 후 평소 쓰는 말로 테스트하세요. $ 없이 자기 말로 Codex에게 작업을 요청하고 skill을 선택하는지 확인합니다. 선택하지 않는다면 먼저 Codex가 /skills에서 skill을 볼 수 있는지, 로딩 폴더 중 하나에 skill이 있는지, skill이나 자동 호출이 비활성화되어 있는지 확인하세요. skill을 사용할 수 있고 설정도 올바르다면 description을 다듬어 작업과 요청을 표현할 때 흔히 쓰는 방식을 명시하세요.

skill을 명시적 명령으로만 사용할 수 있게 하려면 설정할 수도 있습니다. agents/openai.yaml의 allow_implicit_invocation: false 매개변수는 자동 호출을 끄지만 $name은 계속 작동합니다. ~/.codex/config.toml에서 skill을 삭제하지 않고 완전히 비활성화할 수도 있습니다.

[[skills.config]]
path = "/full/path/to/the/skill/SKILL.md"
enabled = false

config.toml을 수정한 뒤 Codex를 다시 시작하세요. Codex는 skill 폴더의 변경 사항을 자동으로 반영하지만 새 skill이 나타나지 않으면 Codex를 다시 시작하세요.

나만의 skill 만들기: 단계별 안내#

1. 작업 하나 고르기

   결과가 명확하고 정기적으로 반복하는 절차를 고르세요. 보고서, 표, 편지 또는 분석이 그 예입니다. 그런 결과를 받아 본 적이 없다면 먼저 에이전트와 함께 작업을 수동으로 완료하세요. 얻은 결과를 지침의 기준으로 삼으세요.

2. skill 만들기

   기본 제공 도우미로 skill을 만들려면 Codex 세션에 $skill-creator를 입력하세요. 도우미가 skill의 기능, 호출할 상황, 스크립트의 필요 여부를 물은 다음 기본 구조를 만들어 줍니다. 직접 만들려면 프로젝트에 .agents/skills 폴더를 만들고, 그 안에 .agents/skills/weekly-sales-report 같은 skill 하위 폴더를 만드세요. 위의 예시를 사용해 그 안에 SKILL.md 파일을 넣습니다.

3. 지침 작성하기

   입력과 출력을 분명히 밝혀 단계별 목록으로 작성하세요. 데이터 이전, 이름 변경, 계산처럼 정확성이 필요한 절차라면 모든 단계를 자세히 설명하세요. 문안 작성이나 논거 선택처럼 창의적인 작업에는 경계와 좋은 결과의 기준을 정하되 모델이 작업할 여지를 남겨 두세요.

4. 호출 테스트하기

   skill 이름을 말하지 않고 자신의 표현으로 Codex에게 작업을 요청하세요. 올바른 skill을 선택하면 해당 표현에 설명이 적절했던 것입니다. 그런 다음 $name으로 명시적 호출을 테스트하세요. skill이 호출되지 않으면 폴더 위치, /skills 목록 표시 여부, 위에서 설명한 비활성화 설정을 확인하세요. 새 skill이 목록에 나타나지 않으면 Codex를 다시 시작하세요. 명시적 호출은 작동하고 자동 호출도 허용되어 있지만, 자기 말로 한 요청에 Codex가 반응하지 않는다면 description의 시작 부분을 다듬으세요. 작업을 먼저 쓰고, 요청을 표현할 때 흔히 쓰는 방식을 뒤에 덧붙입니다. 다시 테스트하세요.

5. 실행 후 다듬기

   실행할 때마다 결과를 검토하고 skill에서 바꿀 내용을 에이전트에게 알려 주세요. “다음에는 요약 표에 비중을 표시하는 열을 추가해 줘.” 첫 버전이 원하는 결과를 내지 못했다면 피드백을 바탕으로 창의적인 작업용 skill을 다듬으세요.

OpenAI와 커뮤니티에서 만든 기성 skill은 $skill-installer와 skill 이름을 사용해 설치합니다. 다른 사람과 공유하려면 plugin으로 배포할 수 있습니다. 개인적으로 사용할 때는 필요하지 않은 별도의 패키징 방식입니다.

에이전트의 결과 확인하기#

확인 기준은 객관적일 수도, 주관적일 수도 있습니다. 객관적 기준은 측정할 수 있습니다. “보고서에 내보내기 파일의 관리자 12명이 모두 포함되어 있다” 또는 “표의 합계가 CSV 총액과 일치한다” 등이 그 예입니다. 이를 엄격한 요구 사항으로 기록하세요. 주관적 기준은 품질에 관한 것입니다. “내가 쓴 것처럼 읽힌다” 또는 “결론이 간결하다” 등이 있습니다. 이런 기준도 구체화할 수 있습니다. skill에 좋은 문단의 예를 넣고 에이전트에게 결과를 그 예와 비교하도록 요청하세요.

유용한 방법 중 하나는 검토 주기입니다. 결과를 준비한 뒤 에이전트가 기준 목록을 확인하고 발견한 문제를 수정한 다음에야 사용자에게 보여 줍니다. Anthropic에도 evaluator-optimizer라는 비슷한 방식이 있습니다. 한 에이전트가 작업하고 별도의 평가자가 검토해 피드백을 돌려주며, 승인될 때까지 과정이 반복됩니다. 하나의 skill 안에서는 보통 이를 단순화해 마지막에 목록과 대조하는 자체 점검으로 구현합니다. 단점도 기억하세요. 작업을 수행한 에이전트가 자기 실수를 알아채지 못할 수 있으므로 독립적인 평가자보다 효과가 약합니다.

보고서용 확인 블록의 예시입니다.

## 제출 전에 확인
- 내보내기 파일의 관리자가 모두 표에 들어 있는지 확인합니다. 누락된 사람이 없어야 합니다.
- 총액이 CSV 합계와 마지막 센트까지 일치해야 합니다.
- 모든 주요 변경 사항에는 근거 수치가 있어야 합니다. 비교할 데이터가 없다면 보고서에 그 사실을 명확히 씁니다.
- 파일이 report.md에 저장되어 있고 사용자에게 경로를 공유했는지 확인합니다.

Skill에는 어떤 모델을 선택해야 하나요?#

맨 오른쪽 열은 초기 확인에 적합한 작업을 제안합니다. 순위표나 비교 결과가 아닙니다. 기준 결과와 실행 결과를 비교한 뒤에야 skill에 적합한 모델을 찾을 수 있습니다.

표의 가격은 2026년 9월 20일 기준 모델 페이지의 API 요금이며 ChatGPT 구독 가격이 아닙니다. 구독을 이용할 때는 사용량이 구독 한도에 포함됩니다. 이 날짜 기준으로 Sol에는 최소 2026년 11월 21일까지 $4/$20의 프로모션 요금이 적용되며, 표준 가격은 $5/$30입니다. 대규모로 반복 실행하기 전에 가격 페이지를 확인하세요. OpenAI 프로모션은 변경될 수 있습니다.

같은 skill을 다음으로 저렴한 모델에서 실행하고 결과를 기준 결과와 비교하세요. 품질이 유지되면 그보다 더 저렴한 모델을 시험하세요. 품질이 떨어지면 이전 모델로 돌아가세요. 모델에는 effort 수준도 있습니다. Astra는 low부터 max까지, 5.6 제품군은 none부터 max까지입니다. 같은 기준으로 effort 수준도 시험하세요. 먼저 모델을 고르고 그다음 effort 수준을 선택합니다.

skill을 정기적으로 실행하면 비용이 반복해서 발생합니다. Astra의 입력 가격은 Luna의 50배이므로 같은 skill을 서로 다른 모델에서 사용하면 비용 차이가 눈에 띌 수 있습니다. 스크린샷과 문서를 분석하는 skill은 더 약한 모델에서 재작업이 필요해 오히려 비용이 더 들 수 있습니다.

Skill을 만들고 사용할 때 흔히 하는 실수#

• “모든 작업용” skill. 하나의 절차에는 하나의 skill을 사용하라는 것이 OpenAI의 권장 사항이기도 합니다. 보편적인 10페이지짜리 skill을 정확하게 설명하기는 어렵고, Codex는 설명을 바탕으로 작업에 맞는 skill을 선택합니다.
• 모호한 설명. “보고서 작성을 도와줍니다”라는 말만으로는 skill이 어떤 보고서에 쓰이는지 알기 어렵습니다. description의 시작 부분에 작업과 요청을 표현할 때 흔히 쓰는 방식을 적으세요.
• 결과가 정의되지 않은 지침. 무엇을 만들고 어디에 둘지 지정하지 않으면 실행할 때마다 결과가 달라질 수 있습니다.
• 점검 절차가 전혀 없음. 기준이 있는 마지막 단계가 없으면 결과가 미완성 초안일 수 있고, 전체를 직접 검토해야 합니다.
• 기본값으로 가장 성능이 뛰어난 모델 사용. 먼저 더 저렴한 모델로도 작업할 수 있는지 확인하세요. 같은 skill을 실행하고 결과를 기준 결과와 비교합니다. 품질이 유지될 때만 모델을 바꾸세요.
• 서로 다른 폴더에서 이름 중복. Codex는 이름이 같은 skill을 합치지 않아 적합한 skill을 선택하기가 어려워집니다.

시작하고 Claude Code로 skill 이전하기#

여러 에이전트와 작업한다면 텍스트 지침과 SKILL.md 파일만 들어 있는 폴더를 Claude Code로 이전할 수 있습니다. Claude Code에서는 skill이 .claude/skills에 저장되고 /name으로 호출됩니다. 스크립트, 종속성 또는 agents/openai.yaml이 있다면 이전 후 skill을 확인하세요. Claude Code skill 모음에 관한 가이드는 Claude Code Skills: 나만의 모음 만들기를, Codex와 Claude Code 비교는 Codex vs Claude Code를 참고하세요.

Ailoot 열기.