Codex 스킬이 $에 안 뜰 때 확인할 것: BOM, YAML, CLI 로그
최근 Codex App에서 Jira triage용 스킬을 하나 만들었습니다.
Skill Creator로 생성도 잘 되었고, SKILL.md 파일도 생겼습니다.
그런데 정작 가장 중요한 순간에 문제가 생겼습니다.
$ 입력 시 제가 만든 스킬이 보이지 않았습니다.
처음에는 App 문제라고 생각했습니다.
재실행도 해보고, 경로도 바꿔보고, 새 스킬도 하나 더 만들어봤습니다.
그런데 결론은 훨씬 더 전통적인 쪽이었습니다.
스킬이 안 보이는 게 아니라, 애초에 제대로 로드되지 못하고 있었습니다.
이번에 실제로 걸린 문제는 두 가지였습니다.
- UTF-8 BOM 때문에 frontmatter를 제대로 읽지 못한 문제
- YAML 문법 오류 때문에
description파싱이 깨진 문제
둘 다 파일은 멀쩡해 보이는데, 파서는 다르게 읽는 문제라서 더 헷갈렸습니다.
증상은 단순했습니다
제가 본 증상은 아주 단순했습니다.
- Skill Creator로 생성한 스킬이 있음
SKILL.md파일도 존재함- 그런데 Codex App에서
$입력 시 스킬이 안 뜸 - 새로 만든 다른 스킬도 마찬가지였음
이 상태에서는 App UI 문제처럼 보이기 쉽습니다.
실제로 저도 처음에는 “왜 picker에 안 뜨지?” 정도로 생각했습니다.
방향이 바뀐 건 Codex CLI에서 확인한 에러 메시지 덕분이었습니다.
핵심은 CLI 에러 메시지였습니다
Codex CLI를 실행해보니 바로 단서가 나왔습니다.
처음에는 이런 식의 메시지가 보였습니다.
Skipped loading ... invalid SKILL.md filesmissing YAML frontmatter delimited by ---
이걸 보고 나서야 문제를 다시 보게 됐습니다.
이건 “스킬이 인덱싱되지 않는다”는 뜻이 아니라,
스킬 파일을 읽는 첫 단계에서 이미 실패하고 있다는 뜻에 가까웠습니다.
즉, $에서 안 보이는 이유도 UI 문제가 아니라
로드 실패였습니다.
실제 원인은 두 가지였습니다
첫 번째는 UTF-8 BOM이었습니다.
파일은 ---로 시작하는 것처럼 보였지만, 실제로는 앞에 BOM이 붙어 있어서 Codex가 frontmatter 시작을 제대로 인식하지 못했습니다.
두 번째는 YAML 문법 오류였습니다.
description: 값 안에 default: 같은 콜론 패턴이 들어 있었는데, 따옴표 없이 작성돼 있어서 YAML 파서가 깨졌습니다.
즉, 하나는 파일 시작 바이트 문제,
다른 하나는 frontmatter 문법 문제였습니다.
둘 다 사람 눈에는 잘 안 보이는데, 파서 입장에서는 치명적이었습니다.
겪어보니 중요한 건 “안 뜨는 이유”를 먼저 보는 것이었습니다
이번 경험에서 가장 중요했던 건
App 화면만 보고 원인을 추측하는 것보다,
CLI에서 실제 로딩 에러를 먼저 확인하는 것이었습니다.
App에서는 그냥 “스킬이 안 뜬다”로 보이지만,
CLI에서는 적어도
- 스킬을 찾았는지
- 파싱을 했는지
- 어디서 실패했는지
를 바로 알 수 있었습니다.
이번에도 해결의 시작점은
picker를 계속 들여다본 게 아니라
CLI 에러 메시지를 본 것이었습니다.
비슷한 문제를 겪는다면 이렇게 보면 될 것 같습니다
저처럼 Skill Creator로 만든 스킬이 $에 안 뜬다면,
저는 다음 순서로 확인해볼 것 같습니다.
1. CLI에서 로딩 에러부터 보기
codex 실행 시
Skipped loading ... invalid SKILL.md files 같은 메시지가 나오는지 확인합니다.
이게 보이면 picker 문제가 아니라
스킬 파일 로드 자체가 실패한 상태일 가능성이 큽니다.
2. SKILL.md 맨 앞이 정말 바로 ---인지 보기
겉으로는 괜찮아 보여도,
파일 맨 앞에 BOM이나 숨은 문자가 붙어 있을 수 있습니다.
3. UTF-8 BOM 여부 확인
특히 Windows 환경에서는 먼저 의심해볼 만합니다.
BOM이 붙어 있으면 frontmatter를 못 읽을 수 있습니다.
4. YAML frontmatter 문법 확인
description처럼 긴 값을 쓸 때는
콜론, 따옴표, 줄바꿈 때문에 YAML이 쉽게 깨질 수 있습니다.
5. 수정 후 재실행
파일만 고치고 끝내지 말고,
CLI를 다시 실행해서 에러가 사라졌는지까지 확인해야 합니다.
결론
이번 문제는 겉으로 보면
“Skill Creator로 만들었는데 왜 $에 안 뜨지?” 정도로 보였습니다.
그런데 실제 원인은 훨씬 아래 레이어에 있었습니다.
- 하나는 UTF-8 BOM
- 하나는 YAML frontmatter 문법
즉, App UI 문제처럼 보였지만
실제로는 스킬 파일이 로드 단계에서 실패하고 있었던 것이었습니다.
이런 문제는 App 화면만 보고 있으면 잘 안 풀리고,
CLI 에러 메시지를 먼저 봐야 방향이 잡힌다는 점도 같이 배웠습니다.
다음에 비슷한 문제가 생긴다면
저는 가장 먼저 $ picker가 아니라
SKILL.md의 첫 바이트와 YAML frontmatter부터 확인할 것 같습니다.
보통 사람을 괴롭히는 건 거대한 AI 모델이 아니라,
보이지 않는 3바이트와 따옴표 하나입니다.
