코덱스 스킬 설치와 사용: 폴더 위치부터 첫 호출까지

내 여러 프로젝트에서 사용할 스킬은 ~/.agents/skills에, 팀과 함께 사용할 스킬은 저장소의 .agents/skills에 둬요. ~는 내 계정의 홈 폴더를 뜻해요. 예를 들어 개인 회의록 스킬의 파일 경로는 ~/.agents/skills/meeting-notes/SKILL.md가 돼요.

Codex는 저장소 안에서 시작한 현재 작업 폴더부터 저장소 최상위까지의 .agents/skills를 확인해요. 하위 서비스에서만 필요한 스킬이라면 해당 폴더에 두고 그 위치에서 시작해 보세요. 로컬 폴더 배치 안내이므로 플러그인으로 설치한 스킬의 내부 파일을 이 경로로 옮길 필요는 없어요.

Codex에 기본 제공되는 $skill-installer를 불러 설치 가능한 스킬이나 저장소의 스킬을 요청할 수 있어요. 아래는 설치할 항목을 고르기 전에 목록을 확인하는 요청 예시예요.

$skill-installer 설치할 수 있는 스킬 중 문서 정리와 관련된 것을 보여 줘. 각 스킬의 용도와 필요한 도구를 설명해 줘. 아직 설치하지 마.

직접 받은 폴더라면 SKILL.md와 참조 파일이 함께 있는지 확인한 뒤 사용할 범위의 경로에 둬요. 스크립트나 외부 연결이 필요한 경우에는 배포자의 준비물도 확인해 주세요. 폴더가 인식됐다는 사실과 실행 환경이 갖춰졌다는 사실은 따로 확인해야 해요.

meeting-notes 폴더를 만들고 아래 내용을 SKILL.md로 저장해 보세요. 코드 실행 없이 글을 정리하는 연습용 예시예요. 파일 맨 위의 name은 이름, description은 어떤 요청에서 사용할지 설명하는 항목이에요.

---
name: meeting-notes
description: 회의 메모에서 결정 사항과 후속 작업을 정리할 때 사용해요. 일반 문서 요약에는 사용하지 않아요.
---

# 회의록 정리
1. 제공된 메모만 읽고 결정 사항과 후속 작업을 구분해요.
2. 담당자와 기한은 메모에 명시된 경우에만 적어요.
3. 빠진 담당자나 기한은 ‘미정’으로 표시해요.
4. 결정 사항, 할 일, 확인할 질문 순서로 답해요.
5. 메모에 없는 결론을 추가하지 않았는지 대조해요.

Codex에 만들기를 맡기고 싶다면 ‘$skill-creator로 개인용 회의록 정리 스킬을 만들어 줘’라고 시작할 수도 있어요. 처음에는 지침만으로 만들고, 실제로 반복 계산이나 파일 처리가 필요해질 때 스크립트를 추가하면 돼요.

Codex CLI와 IDE 확장에서는 /skills로 목록을 보거나 $를 입력해 스킬을 선택할 수 있어요. 직접 이름을 넣으면 어떤 스킬을 쓰려는지 분명히 전달할 수 있어요. 자동 선택은 description과 요청이 맞을 때 일어나므로 첫 확인은 직접 호출로 해 보세요.

$meeting-notes 다음 메모를 정리해 줘. - 출시 소개문은 수요일까지 민수가 수정한다. - 디자인 검토 담당자는 아직 정하지 않았다. - 다음 회의 날짜는 논의하지 않았다.

결과에 민수와 수요일은 들어가고, 디자인 검토 담당자와 다음 회의 날짜는 새로 지어내지 않았는지 확인해요. 형식만 맞았는지보다 입력의 사실을 보존했는지 살펴보는 게 중요해요. 다른 메모로도 한 번 더 실행해 보세요.

파일 경로, SKILL.md 이름, 맨 위의 name과 description을 차례로 확인해요. Codex는 스킬 변경을 자동으로 감지하지만 반영되지 않으면 재시작해 보세요. 같은 name을 가진 스킬이 여러 곳에 있으면 합쳐지지 않고 선택 목록에 함께 나타날 수 있어요.

목록에는 있는데 자동으로 선택되지 않는다면 설명의 앞부분에 실제 작업 이름을 적어 주세요. ‘업무를 돕는 스킬’보다 ‘회의 메모에서 결정 사항과 후속 작업을 정리할 때’가 범위를 전달하기 좋아요. 스킬을 많이 설치했다면 목록 생략 경고가 있는지도 확인해요.

로컬 스킬은 ~/.codex/config.toml의 [[skills.config]] 항목에서 비활성화할 수 있어요. 아래 path는 내 스킬의 실제 절대 경로로 바꿔 주세요. 기존 설정 파일이 있다면 통째로 덮어쓰지 말고 해당 항목을 추가하거나 수정해요.

[[skills.config]] path = "/Users/내계정/.agents/skills/meeting-notes/SKILL.md" enabled = false

config.toml을 바꾼 뒤에는 Codex를 재시작해요. 다시 사용할 때는 해당 항목을 활성화하고 목록을 확인하면 돼요. 플러그인에 묶인 스킬을 관리하려는 경우에는 플러그인 관리 화면의 상태도 함께 확인해 주세요.