Codex Skills: 생성, 실행 및 코드 리뷰 작업을 통한 검증

Codex의 Skills 메커니즘

공식 문서에 기술된 스킬(skills) 메커니즘은 시스템 컨텍스트에 과부하를 주지 않고도 전문화된 작업을 위한 지침과 템플릿을 에이전트에 연결합니다.

스킬은 필수 파일인 SKILL.md를 포함하는 디렉터리입니다. YAML 프론트매터에는 name과 description 필드가 필수이며, 본문에는 모델을 위한 규칙이 포함됩니다:

.agents/skills/boundary-review/
└── SKILL.md

Codex는 점진적 공개(progressive disclosure)를 사용합니다. 시작 시 사용 가능한 스킬의 압축된 인덱스를 생성합니다. SKILL.md의 전체 텍스트는 에이전트가 특정 스킬을 적용하기로 결정하는 시점에만 읽어 들입니다.

스킬 탐색은 네 가지 수준에서 수행됩니다:

1. 저장소 (REPO): 현재 디렉터리 및 Git 루트까지의 상위 경로에 있는 .agents/skills.
2. 사용자 (USER): $HOME/.agents/skills.
3. 관리자 (ADMIN): /etc/codex/skills.
4. 시스템 (SYSTEM): 환경 시스템 디렉터리 (번들 제공).

호출은 명시적($name 접두사 사용) 방식이나 암시적(프롬프트와 description 간의 시맨틱 일치) 방식으로 수행됩니다. 가용성과 충돌 관리는 config.toml 파일에서 처리됩니다.

사전 요구사항 및 격리 환경

이 시나리오를 재현하려면 다음이 필요합니다:

• Python 3;
• 설치 및 인증이 완료된 Codex CLI 명령줄 인터페이스.

테스트 데이터는 2026-09-16에 Codex CLI 버전 0.153.3을 기준으로 기록되었습니다.

모든 명령은 Git 저장소 외부의 준비된 로컬 디렉터리에서 실행됩니다. SKILL.md의 텍스트 지침은 모델의 동작을 유도하지만 운영체제 수준의 격리를 보장하지는 않으므로, 다음 플래그를 사용하여 실행합니다:

• --ephemeral: 세션 상태 저장을 방지합니다;
• --skip-git-repo-check: Git이 없는 격리된 폴더에서의 실행을 허용합니다;
• --sandbox read-only: 실행 환경 수준에서 프로세스의 쓰기 권한을 제한합니다.

CLI는 전역 구성을 상속받고 서드파티 훅에 대한 서비스 경고를 출력할 수 있으므로, 실제 검증은 대상 스킬의 읽기 이벤트에 전적으로 의존합니다.

boundary-review 스킬 생성

현재 디렉터리에 스킬 디렉터리를 생성합니다:

mkdir -p .agents/skills/boundary-review

.agents/skills/boundary-review/SKILL.md 파일에 다음 내용을 저장합니다:

---
name: boundary-review
description: Review Python pagination code for boundary errors and show one minimal failing input. Use when asked to review pagination boundaries.
---
Read the provided Python file. Do not edit it. Begin your answer with BOUNDARY_REVIEW. Report a specific failing input, expected and actual result, and a minimal correction. Do not inspect files outside this project.

이 텍스트 지침은 모델이 파일을 수정하는 것을 금지하며, 하나의 실패 입력값을 반드시 보고하면서 BOUNDARY_REVIEW 신호 마커로 응답을 시작하도록 요구합니다.

결함이 있는 테스트 파일

페이지 수를 계산할 때 흔히 발생하는 오프바이원(off-by-one) 오차가 포함된 pages.py 파일을 생성합니다:

def page_count(total, size):
    return total // size + 1

size > 0 및 total >= 0 조건에서 이 함수는 경계값에서 실패합니다. total = 1 및 size = 1일 때 1 대신 2를 반환합니다. 또한 빈 목록인 total = 0에 대해서도 함수는 1을 반환합니다.

호출 실행 및 검증

명령 프로세서가 $ 기호를 환경 변수로 해석하지 않도록 쿼리는 작은따옴표로 전달합니다.

1. 이름을 통한 명시적 호출

스킬을 직접 지정하여 명시적 검사를 실행합니다:

codex exec --ephemeral --skip-git-repo-check --sandbox read-only 'Review pages.py using $boundary-review'

모델이 다음 결과를 반환합니다:

BOUNDARY_REVIEW

Failing input:
page_count(1, 1)

Expected result: 1
Actual result: 2

Minimal correction:
def page_count(total, size):
    return (total + size - 1) // size

마커 텍스트는 프롬프트의 컨텍스트로부터 생성될 수도 있으므로, BOUNDARY_REVIEW 마커의 존재 자체만으로는 SKILL.md가 로드되었음을 증명하지 못합니다. 2026-09-16의 실제 실행에서는 시스템 로그에 .agents/skills/boundary-review/SKILL.md 파일을 읽는 명령 이벤트가 기록되었습니다. 로그의 파일 읽기 이벤트, BOUNDARY_REVIEW 접두사, 그리고 page_count(1, 1) 반례의 조합이 대상 지침의 실행을 확증합니다.

2. 설명을 통한 암시적 호출

$boundary-review 식별자를 언급하지 않고 자연어로 작업을 작성합니다:

codex exec --ephemeral --skip-git-repo-check --sandbox read-only 'Review the pagination boundaries in pages.py'

이 실행 로그에서도 쿼리 문구와 description 필드의 일치 덕분에 .agents/skills/boundary-review/SKILL.md 읽기가 기록되었습니다. 에이전트는 BOUNDARY_REVIEW 마커와 입력값 (1, 1)에 대한 실패 분석을 포함하는 유사한 구조화된 응답을 생성했습니다.

로직 검증 및 독자를 위한 단계

로컬 Python 인터프리터를 사용하여 함수의 초기 동작을 확인합니다:

python3 -c "from pages import page_count; print(page_count(1, 1))"

명령이 2를 출력하여 결함이 있음을 확인합니다.

2026-09-16의 기준 실행에서는 원본 pages.py 파일이 수정되지 않은 상태로 유지되었으며, 수정된 파일에 대한 CLI 재실행은 수행되지 않았습니다. total >= 0 및 size > 0 조건에서 제안된 공식 (total + size - 1) // size의 수학적 정확성은 다음 경계값 세트를 통해 검증되었습니다:

• (0, 10) -> 0;
• (1, 1) -> 1;
• (10, 10) -> 1;
• (11, 10) -> 2.

독자가 직접 수정하려면 pages.py를 다음과 같이 변경할 수 있습니다:

def page_count(total, size):
    if total == 0:
        return 0
    return (total + size - 1) // size

변경 사항을 저장한 후 독자는 어설션 검사를 실행할 수 있습니다:

python3 -c "from pages import page_count; assert page_count(0, 10) == 0; assert page_count(1, 1) == 1; assert page_count(10, 10) == 1; assert page_count(11, 10) == 2; print('OK')"

수동 파일 편집 후 명령의 예상 실행 결과는 OK입니다.

문제 해결

스킬이 검색되지 않거나 자동으로 호출되지 않는 경우:

1. 파일 경로: 작업 디렉터리를 기준으로 한 경로가 정확히 .agents/skills/<skill-name>/SKILL.md인지 확인합니다.
2. 레지스트리 갱신: 활성 세션 중에 파일이 추가된 경우, 디렉터리를 다시 검색하도록 CLI 프로세스를 다시 시작합니다.
3. 구성 차단: ~/.codex/config.toml을 확인합니다. 스킬이 비활성화된 경우 다음과 같은 항목이 로드를 차단합니다:

   [[skills.config]]
   path = "/полный/путь/к/.agents/skills/boundary-review/SKILL.md"
   enabled = false

   해당 블록을 삭제하거나 enabled = true로 설정합니다.
4. 이름 충돌: 저장소와 사용자 수준에서 동일한 name이 존재하는 경우 우선순위 규칙으로 인해 모호성이 발생할 수 있습니다.
5. description의 정확도: 암시적 호출의 경우 주요 트리거(“pagination boundaries”, “boundary errors”)가 설명의 앞부분에 위치해야 합니다.
6. 서드파티 스킬: 외부 패키지를 로드해야 하는 경우 진입점은 $skill-installer 유틸리티입니다. 모든 서드파티 스킬은 실행 전에 SKILL.md 파일과 scripts/ 디렉터리에 대한 필수적인 수동 감사가 필요합니다. 설명된 시나리오에서는 서드파티 컴포넌트가 설치되지 않았습니다.