스킬 84개 중 46개는 설명이 잘린 채 전달되고 있었다

Codex에서 스킬을 쓰면, 모델은 매 대화의 시작에 스킬 목록을 받습니다. 목록에는 스킬마다 이름과 설명이 한 줄씩 들어 있습니다. 모델은 이 설명을 보고 “지금 이 스킬을 쓸 때인가”를 판단합니다. 설명이 스킬을 부르는 방아쇠인 셈입니다.

이 목록에는 자리가 정해져 있습니다. Codex는 스킬 목록에 컨텍스트의 2%만 내줍니다. 스킬이 적을 때는 문제가 없지만, 많아지면 자리가 모자랍니다. 그러면 각 설명의 뒷부분을 잘라서 넣습니다.

잘리면 무엇이 문제인가

스킬 설명은 보통 “무엇을 하는 스킬인지”로 시작해서 “언제 쓰고, 언제 쓰지 말아야 하는지”로 끝납니다. 잘리는 건 뒷부분입니다. 즉 언제 써야 하는지가 가장 먼저 사라집니다.

그러면 모델은 스킬이 있다는 건 알지만, 지금이 그 스킬을 쓸 때인지 판단할 근거를 잃습니다. 필요한 순간에 스킬을 부르지 않거나, 엉뚱한 순간에 부르게 됩니다.

내 컴퓨터에서는 이게 실제로 일어나고 있었습니다.

실제로 재 보니

Astra Xray는 Codex가 GPT-6 Astra에게 넘기는 스킬 목록과 지침을 계산해 보여주는 스킬입니다. 목록을 만드는 규칙은 Codex 0.154.0 소스의 해당 부분을 한 줄씩 옮겼습니다. 계산 결과를 실제 세션 로그에 기록된 스킬 목록과 비교하니 84줄 중 84줄이 일치했습니다. 짐작이 아니라 Codex가 실제로 넘기는 것과 같은 결과라는 뜻입니다.

• Mac: 설치된 스킬 84개 중 46개가 설명이 중간에 잘린 채 넘어가고 있었습니다. 정리하고 남은 64개는 모두 설명 전체가 전달됩니다.
• Windows: 개인 스킬 9개의 설명을 절반 길이로 다듬었습니다. 2,939자가 1,452자가 됐습니다. 다른 사람이 만든 인기 스킬은 건드리지 않았습니다.
• 토큰: 호출 한 번마다 약 300토큰이 줄었습니다.

돈을 아끼는 도구가 아니다

300토큰은 GPT-6 Astra API 요금으로 한 달 치를 계산해도 4달러 정도입니다. 스킬 목록이 처음부터 컨텍스트의 2%뿐이니, 어떤 도구도 여기서 그 이상을 아낄 수는 없습니다.

이 도구의 목적은 비용이 아니라 모델이 스킬 설명을 끝까지 읽게 하는 것입니다. 토큰이 정말 많이 나가는 곳은 따로 있습니다. 도구가 돌려준 결과와 스킬 본문입니다. 그쪽은 Codex Token Xray로 잽니다.

정리하는 순서

실행하면 네 단계로 진행합니다.

1. 지금 무엇이 넘어가는지 보여준다. 잘린 설명, 서로 겹치는 스킬, 예전 모델에 맞춰 쓴 지침을 찾습니다.
2. 무엇을 왜 바꿀지 먼저 보여주고 승인을 받는다.
3. 바꿀 파일을 zip으로 백업한다. 마음에 들지 않으면 언제든 되돌립니다.
4. 고친 뒤 다시 검사해 전후를 비교한다.

설명을 줄일 때의 기준

설명을 고치는 데는 몇 가지 원칙을 정해 두었습니다.

• 짧아졌다고 성공이 아니다. 스킬을 부르는 조건과 쓰지 말아야 할 경우(“읽기 전용일 때만”, “이 파일 형식만” 같은)는 남깁니다. 본문에 이미 있는 반복 설명, 긴 예시 목록, “꼭 이 스킬을 쓰세요” 같은 설득 문구를 덜어냅니다.
• 정해진 글자 수 목표는 없다. 자리가 남아도 장황한 설명은 검토하고, 잘리지 않았어도 길면 다시 봅니다.
• 도구가 대체 문장을 자동으로 만들지 않는다. 바꿀 문장은 계획 파일에 이유와 함께 적어 검토하고, 도구는 파일의 설명 부분만 정확히 바꿉니다. 바꾸기 전 원래 바이트를 백업하고, 쓴 결과를 다시 확인합니다.
• 모든 후보를 기록한다. 바꿨는지, 이유가 있어 그대로 뒀는지, 남의 스킬이라 제외했는지, 판단을 보류했는지 하나씩 남깁니다.

건드리지 않는 것

정리 도구가 가장 조심해야 할 부분은 “무엇을 고치지 않는가”입니다.

• Codex 기본 스킬과 플러그인(computer-use, sites 등)은 고치지 않습니다.
• 다른 사람이 만든 스킬은 내 폴더에 복사돼 있어도 고치지 않습니다. 업데이트되면 수정이 사라지고, 원작자의 의도와 달라질 수 있습니다. 누가 만들었는지 확실하지 않으면 기본적으로 고치지 않고 확인을 기다립니다.
• 모델, 승인, 샌드박스, MCP 설정은 정리 범위가 아닙니다.
• 운영 환경, 비밀번호, 배포, 비용, 되돌릴 수 없는 작업에 관한 규칙은 지우지 않습니다. 문장을 다듬을 수는 있어도, 그 규칙이 지키는 행동은 계속 지켜져야 합니다. “never”라는 단어가 들어 있다고 오래된 규칙으로 보고 지우지도 않습니다. 실제 사고 뒤에 생긴 규칙인 경우가 많기 때문입니다.

써 보려면

npx skills add Seokwoooo/astra-xray

Codex 입력창에 $astra-xray를 입력하면 먼저 검사만 합니다. 정리는 따로 요청했을 때만 합니다. Python 3.9 이상이 필요하고, 검사 결과와 백업은 ~/.astra-xray 아래에만 둡니다.

스킬이 열 개 남짓이라면 이 문제는 거의 생기지 않습니다. 여러 도구를 설치하다 보니 스킬이 수십 개로 늘었다면, 한 번쯤 무엇이 잘리고 있는지 확인해 볼 만합니다.