이전 글에서 wrap 스킬로 세션 마무리를 자동화하는 구조를 만들었다. 그 기반이 되는 skill-version-manager는 스킬의 사용 -> 기록 -> 패치 -> 릴리스 사이클을 관리하는 도구인데 한 가지 문제가 있었다. 경로가 하드코딩되어 있었다.
WSL2 환경을 정리하면서 작업 디렉토리를 ~/Desktop/vibe/에서 ~/vibe/로 옮겼다. 그 순간 skill-version-manager가 동작을 멈췄다. v1.0.0에는 WORKSPACE_ROOT가 ~/Desktop/vibe/workspace-skill/로 박혀 있었기 때문이다.
개발 도구에 절대 경로를 하드코딩하면 안 된다는 건 누구나 안다. 그런데 스킬은 "그냥 프롬프트"라는 인식 때문에 별 생각 없이 넘어갔던 거다. 스킬도 소프트웨어고 소프트웨어는 환경이 바뀌면 깨진다.
해결 방향은 단순했다. 하드코딩된 경로를 지우고 실행 시점의 CWD(Current Working Directory)를 WORKSPACE_ROOT로 쓰는 것이다. 어떤 프로젝트 디렉토리에서 skill-version-manager를 실행하든 그 디렉토리가 workspace가 된다.
여기에 더해 스킬 설치 경로(SKILL_INSTALL_DIR)도 자동 감지하도록 했다. Claude Code는 스킬을 두 곳에 설치할 수 있다.
{CWD}/.claude/skills/ — 해당 프로젝트에서만 사용~/.claude/skills/ — 모든 프로젝트에서 사용감지 로직의 우선순위는 이렇다.
project-level 디렉토리에 해당 스킬이 있으면 그걸 쓴다. 없으면 user-level을 확인한다. 둘 다 있거나 둘 다 없으면(최초 설치) 사용자에게 물어본다. 명시적 설정이 암묵적 기본값보다 우선하는 fallback 체인 패턴이다.
경로 감지를 넣으면서 status 출력에도 설치 위치 컬럼을 추가했다. 어떤 스킬이 user-level이고 어떤 게 project-level인지 한눈에 보인다.
| 스킬 | 설치 위치 | 설치 버전 | 최신 버전 | 미처리 기록 | 마지막 패치 |
|--------------|----------|----------|----------|------------|-----------|
| idea-guide | user | v1.2.0 | v1.2.0 | 0 | 2026-02-10 |
| my-skill | project | v1.0.0 | v1.0.0 | 0 | - |이 정보가 있으면 "이 스킬은 이 프로젝트 전용인데 왜 다른 프로젝트에서 안 보이지?" 같은 혼란을 방지할 수 있다.
이번 작업에서 하나 더 효과를 본 건 설계 문서를 먼저 작성하는 방식이었다. docs/plans/ 디렉토리에 변경 의도와 구조를 먼저 적고 그걸 기반으로 패치노트와 구현을 진행했다. AI 코딩 도우미와 협업할 때 이 방식이 특히 잘 맞는다. 설계 문서가 곧 컨텍스트가 되기 때문이다. Claude Code에 "이 설계 문서대로 구현해줘"라고 하면 의도가 정확하게 전달된다.
패치노트에 이런 메모를 남겼다.
스킬 도구는 특정 환경에 의존하지 않고 실행 컨텍스트에서 필요한 정보를 감지해야 한다. 하드코딩된 경로는 개발자의 현재 환경에서만 동작한다.
Convention over Configuration이라는 원칙이 있다. Rails가 유명하게 만든 개념인데 핵심은 "합리적인 기본값을 제공하되 명시적 설정을 우선한다"는 것이다. CWD 기반 감지가 딱 이 패턴이다. 별도 설정 없이 실행 위치에서 컨텍스트를 유추하고 모호하면 사용자에게 묻는다.
Claude Code 스킬을 만들면서 자꾸 느끼는 건데 스킬도 결국 소프트웨어다. 버전 관리가 필요하고 환경 독립성이 필요하고 테스트가 필요하다. "프롬프트 파일"이라고 대충 관리하면 환경이 바뀌는 순간 깨진다. 이번 v1.1.0은 그 교훈을 코드로 옮긴 작업이었다.