Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
실행 인터프리터 — 전역 python3 는 이 스킬의 인터프리터가 아니다
Owns: Why the project venv is the only interpreter (no global
python3, no NumPy fallback) · Index: docs/README.md
SKILL.md 허브에서 옮겨온 전문(2026-09-09, 허브 슬림화). 규칙 자체(venv 절대경로 · 폴백 금지 · NumPy 게이트)는 허브가 요약으로 유지하고, 근거와 세부는 여기가 소유한다.
이 스킬의 모든 명령은 레포 루트의 venv 인터프리터로 실행한다:
export SPRITE_GEN_ROOT=/path/to/sprite-gen
$SPRITE_GEN_ROOT/.venv/bin/python <script.py> ...
부트스트랩은 README quickstart·CI 와 같은 한 줄이다 —
python3 -m venv .venv && .venv/bin/pip install -e ...venv가 없으면 만든 뒤 실행한다. 다른 경로에 만들었다면 그 인터프리터의 절대경로로 바꿔 쓴다 — 바뀌면 안 되는 것은 경로가 아니라 "전역python3를 쓰지 않는다" 는 규칙이다.이유: 의존(Pillow, NumPy)의 SSoT 는
pyproject.toml이고, 그것을 실물로 만드는 곳은 이 venv 하나다. 전역python3는$PATH가 그날 가리키는 아무 인터프리터이고(macOS 에서는 보통 homebrew CPython, PEP 668EXTERNALLY-MANAGED), 거기 든 패키지는 손으로 넣은 것이라 선언과 실물이 갈린다. 실제로 그렇게 갈렸다: homebrew python3 에는 Pillow 만 있고 NumPy 가 없어서, 한 개가 깔려 있다는 이유로 다 깔린 것처럼 보이는 상태였다.폴백 금지: "
.venv있으면 그거, 없으면python3" 같은 해석은 두지 않는다 (원칙 6). 없으면 만들거나 요란하게 실패한다 — 조용히 다른 인터프리터로 도는 경로는 없다.NumPy 가 없는 인터프리터에서는 아무것도 시작하지 않는다: 진입점은 패키지 import 시점에 멈추고, 실행한 인터프리터 경로와 위 부트스트랩 명령을 그대로 찍는다. 추출 경로는 바이트 동일 계약을 지고 있어서 순수 파이썬 폴백은 없다 — 느리게라도 도는 두 번째 구현을 두면 같은 질문에 답이 둘이 된다. (게이트
sprite_gen/_deps.py, 잠금tests/test_numpy_dependency_gate.py)자식 프로세스는 상속한다:
heal_run과 큐레이션 서버는 자식을sys.executable로 띄운다. 즉 부모를 옳은 인터프리터로 띄우면 그 아래는 자동으로 옳고, 반대로 큐레이션 서버를 전역python3로 띄우면 그 서버가 부르는 재추출·compose 가 전부 같이 틀린다. 고칠 곳은 띄우는 순간 한 곳이다.sprite-gen <tool>은 실재하는 콘솔 스크립트다 (anchor,cutout,curation,recolor,recolor-palette,migrate-breathe,migrate-request…).pip install이 venv 의bin/에 써 넣고 그 shebang 이 바로 그 venv 의 인터프리터를 가리키므로, 이 형식은 인터프리터를 고르는 문제 자체가 없다:$SPRITE_GEN_ROOT/.venv/bin/sprite-gen <tool> ...- 여기서도 절대경로다 — 맨
sprite-gen이 PATH 에 있는 건 venv 를 활성화했거나 그 환경에 설치한 셸 안에서뿐이다.SKILL.md·docs/*.md는 활성화 없는 셸에서 읽히므로 맨python3와 같은 이유로 맨sprite-gen도 쓰지 않는다 (README quickstart 는 활성화가 앞에 있어 예외). - 이 변경 이전에 만든
.venv에는 없다 —[project.scripts]가 없던 시절 설치본이라bin/sprite-gen이 안 만들어졌다.pip install -e .를 한 번 다시 돌리면 생긴다. $SPRITE_GEN_ROOT/.venv/bin/python -m sprite_gen.cli <tool> ...는 같은cli:main을 부르는 동치 형식이다 — 콘솔 스크립트가 아직 없는 venv 에서 쓴다.
- 여기서도 절대경로다 — 맨
레지스터는 파일로 갈린다: 상대경로
python3 scripts/...형식이 같은 인터프리터를 가리키는 건source .venv/bin/activate가 바로 앞에 적혀 있는 README quickstart 안에서만이다.SKILL.md와docs/*.md는 활성화 단계가 없는 셸에서 읽히므로, 절대경로든 상대경로든 여기서는 상대형을 쓰지 않는다 — 위 venv 절대경로 형식 하나만 쓴다. (tests/test_entrypoint_interpreter.py가 이 두 파일군에 대해 잠근다.)
Related
- docs/README.md — documentation index