Claude Code 스킬에서 zsh 백틱 평가 문제

command not found: fixed 에러를 보고 20분 동안 멍하니 있었어요. /wrap 스킬이 며칠 동안 잘 돌아가다가 갑자기 zsh가 SKILL.md 파일의 마크다운 포맷팅을 명령어라고 불평하기 시작한 거예요. 원인은 백틱이었어요 — 마크다운에서는 인라인 코드에 쓰이고, zsh에서는 명령어 치환에 쓰이는 같은 문자요.

왜 중요한가

Claude Code 스킬은 SKILL.md 파일의 내용을 읽어서 셸 환경을 통해 전달하는 방식으로 로드돼요. 스킬 파일에 백틱으로 감싼 텍스트가 있으면, zsh는 마크다운 포맷팅으로 보지 않아요. 명령어 치환 문법으로 인식하는 거예요. 셸이 백틱을 짝지어서 그 사이의 내용을 실행하려고 시도하고, 실제 코드와는 전혀 관련 없는 에러가 나와요.

특히 까다로운 건 이 에러가 치명적이지 않다는 점이에요. 스킬은 여전히 로드되고, 출력도 대부분 정상이지만, 매번 호출할 때마다 stderr 노이즈가 쌓여서 터미널이 지저분해지고 진짜 문제를 찾기 어려워져요.

문제를 일으킨 코드

제 /wrap 스킬을 깨뜨린 정확한 마크다운이에요:

entry type: `+` (added), `~` (changed),
   `-` (removed), `!` (fixed)
3. Add entry to `{PATH}/CHANGELOG.md`:

그리고 zsh가 내뱉은 에러:

(eval):1: command not found: fixed
(eval):2: command not found: 3.

(eval) 접두사가 핵심 단서예요. zsh의 eval 빌트인이 텍스트를 처리하고 있다는 뜻이지, 일반적인 명령어 실행이 아니에요.

zsh가 이걸 어떻게 해석하는지

zsh가 무엇을 보는지 단계별로 따라가 볼게요. ! 앞의 백틱을 만나면 닫는 백틱을 찾기 시작해요. (fixed) 앞의 백틱을 찾으면 이제 zsh는 (changed),\n와 주변 텍스트를 포함하는 명령어 치환을 갖게 돼요.

닫는 백틱 뒤의 (fixed)는 서브셸 명령어로 해석돼요. zsh가 fixed를 프로그램으로 실행하려 하는데 — 존재하지 않으니 command not found: fixed가 나오는 거예요.

그다음 줄의 3.도 또 다른 명령어로 처리돼요. 같은 결과예요.

핵심 포인트:

• 마크다운의 백틱 쌍이 zsh에서는 명령어 치환 구분자가 돼요
• 닫는 백틱 뒤의 (text)는 서브셸로 해석돼요
• 에러의 (eval) 접두사는 항상 zsh의 eval 빌트인이 원인이라는 뜻이에요
• 이 에러들은 치명적이지 않지만 매번 스킬 호출할 때 stderr 노이즈를 만들어요

해결 방법

셸에 민감한 문자가 포함된 텍스트에서 백틱 포맷팅을 제거하세요. 일반 텍스트나 다른 포맷팅 방식을 사용하면 돼요:

# Before (breaks)
`!` (fixed)

# After (works)
fixed = !

일반 규칙은 이래요: !, $, (, ) 같은 문자를 백틱으로 감싸면서 뒤에 셸 문법으로 해석될 수 있는 텍스트가 오는 걸 피하세요.

실전 정리

Claude Code SKILL.md 파일을 작성하다가 갑자기 (eval): command not found 에러가 나오면, 백틱 포맷팅부터 확인하세요. 해결법은 항상 포맷팅을 단순화하는 거예요 — 셸에 민감한 문자가 포함된 내용에는 인라인 코드 백틱 대신 일반 텍스트를 사용하면 돼요.

이건 SKILL.md 파일에만 해당하는 문제예요. 셸 평가를 통해 처리되기 때문이에요. 브라우저에서 렌더링되는 일반 마크다운 파일에는 영향이 없어요.