SKILL.md 파일 하나가 20개가 되는 순간, 더 이상 "그냥 텍스트 파일"이 아니게 된다. 어떤 버전을 어디에 설치했는지 모르겠고, 수정 이력을 추적할 방법이 없다.
Claude Code의 스킬과 서브에이전트는 마크다운 파일이다. 프롬프트 엔지니어링의 결과물이지만, 프로젝트가 커지면서 소프트웨어와 같은 문제가 생겼다. 여러 프로젝트에 같은 스킬을 설치하는데, A 프로젝트에서 수정한 내용이 B 프로젝트에는 반영되지 않는다. 어떤 버전이 최신인지, 어디서 뭘 고쳤는지 알 수 없다. git 기반의 가벼운 버전 관리 시스템을 직접 설계했다.
Claude Code 스킬은 ~/.claude/skills/이나 프로젝트의 .claude/skills/에 설치된다. 처음에는 4개뿐이었다. idea-guide, python-guide, skill-version-manager, typst-guide. 이 정도면 머릿속에 다 들어온다. 그런데 스킬이 10개를 넘어가면서 상황이 달라졌다.
npm이나 pip 같은 패키지 매니저가 해결하는 문제와 본질적으로 같았다. 다만 대상이 코드가 아니라 프롬프트 마크다운 파일일 뿐.
무거운 도구를 만들고 싶지 않았다. git과 파일 시스템만으로 충분히 관리할 수 있는 규칙을 설계했다.
{skill-name}/
├── CLAUDE.md # 아이템별 프로젝트 규칙
├── skill-versions/
│ ├── v1.0.0/SKILL.md # 버전별 스냅샷
│ └── v1.1.0/SKILL.md
├── docs/
│ ├── notes/ # 세션별 사용 기록
│ ├── patch_notes/ # 버전별 패치노트
│ └── plans/ # 설계 문서핵심은 skill-versions/ 디렉토리다. 버전별로 SKILL.md 전체를 스냅샷으로 보관한다. git diff로 버전 간 차이를 바로 볼 수 있고, 특정 버전으로 롤백도 가능하다. 세션 노트는 session-{version}-{YYYY-MM-DD}.md 형식으로 저장하여, 어떤 버전을 쓸 때 어떤 문제가 있었는지 기록한다.
스킬을 사용하면서 개선점을 발견하면 세션 노트에 기록한다. 기록이 쌓이면 SKILL.md에 반영하고, 변경이 의미 있는 단위가 되면 새 버전을 릴리스한다. 세션 종료 시 자동으로 변경사항을 정리하고 커밋하는 wrap 스킬도 만들었다. 세션이 끝날 때마다 수동으로 정리하는 건 사람이 절대 꾸준히 하지 못하기 때문이다.
스킬을 여러 곳에 설치하다 보면 "어디에 어떤 버전이 깔려 있는지" 파악이 안 된다. install-registry.md로 설치 경로를 중앙 관리하기 시작했다.
| 아이템 | 타입 | 버전 | 경로 |
|--------|------|------|------|
| forge | skill | v1.2.0 | ~/.claude/skills/forge/ |
| korean-humanize | skill | v1.0.0 | ~/.claude/skills/korean-humanize/ |이 파일 하나를 보면 전체 스킬 현황이 파악된다. 새 프로젝트에 스킬을 설치할 때도 최신 버전을 바로 확인할 수 있다.
의외로 가장 많이 겪은 문제는 빈 디렉토리 관리였다. 새 스킬을 추가하면 docs/notes/, docs/patch_notes/, docs/plans/ 디렉토리가 비어 있다. git은 빈 디렉토리를 추적하지 않으므로, clone 하면 구조가 무너진다. .gitkeep을 넣는 건 기본인데, 스킬이 늘어날수록 자꾸 빠뜨렸다. 결국 스킬 생성 시 자동으로 디렉토리 구조와 .gitkeep을 만드는 로직을 skill-version-manager에 추가했다.
AI 에이전트의 프롬프트도 소프트웨어다. 반복적으로 사용하고, 점진적으로 개선하고, 여러 환경에 배포한다면 — 그건 코드와 같은 관리가 필요하다는 뜻이다. 다만 무거운 도구가 필요한 건 아니었다. git + 디렉토리 규칙 + 마크다운 레지스트리면 충분했다.
skill-version-manager 자체도 v1.0.0에서 v1.1.0으로 발전했다. CWD 기반 경로 해석과 project-level 스킬 지원을 추가했다. 버전 관리 도구가 자기 자신을 버전 관리하는 상황이 재밌었다. 중요한 건 이 시스템이 복잡해지지 않았다는 점이다. 파일 시스템과 git만 쓰기 때문에 별도의 CLI나 데이터베이스 없이도 동작한다. "가장 좋은 도구는 이미 있는 도구를 잘 쓰는 것"이라는 걸 다시 한번 확인했다.
Claude Code가 특정 작업을 수행할 때 참조하는 마크다운 파일이다. 작업 가이드, 체크리스트, 도메인 지식 등을 담고 있다. 사용자가 슬래시 커맨드로 호출하면 Claude Code가 해당 스킬의 내용을 컨텍스트에 로드해서 작업에 활용한다.
경험상 5개를 넘어가면 필요하다. 특히 같은 스킬을 여러 프로젝트에서 쓰기 시작하면 버전 불일치 문제가 바로 생긴다. 혼자 쓰더라도 "3개월 전 버전으로 돌아가고 싶다"는 순간이 온다.
npm이나 pip은 코드 패키지를 위한 도구다. 스킬 파일은 의존성 해석이나 빌드 과정이 필요 없고, 단순히 마크다운 파일의 버전과 설치 위치만 추적하면 된다. 이런 단순한 요구사항에는 디렉토리 규칙 + git이 가장 가볍고 실용적인 해법이었다.