여러 저장소가 쓰는 스킬은 도메인 중립 코어와 저장소별 오버레이로 나눈다

같은 스킬을 여러 저장소에 복사해 두면 스킬을 고칠 때마다 저장소 수만큼 손으로 옮겨야 한다. 시간이 지나면 저장소마다 조금씩 갈라져서 유지 비용이 계속 쌓인다. 이 글은 스킬을 하나의 코어와 저장소별 오버레이로 나눠, 개선을 한 곳에서만 하고 모든 저장소가 받게 하는 구조를 정리한다. 오버레이를 찾는 순서, 배포할 때의 우선순위 함정, 코어로 옮길 때 깨지는 결합점을 함께 다룬다.

스킬 문서 한 편 안의 구조는 스킬 문서는 반복 실행을 스크립트로 내리고 같은 지시를 한 곳에서만 소유하게 쓴다에서 다룬다. 이 글은 그 위의 단계, 즉 여러 저장소에 걸친 스킬 공유를 다룬다.

사례는 공개 저장소 fos-skills에서 가져왔다.

복제본이 갈라지는 문제

planning 같은 스킬을 여러 저장소에 복사해 쓴다고 하자. 스킬 하나를 개선하면 나머지 저장소에도 같은 변경을 손으로 이식해야 한다. 이식하다 보면 저장소마다 조금씩 다른 버전이 남는다. 여러 프로젝트에 같은 하네스를 퍼뜨릴수록 이 비용이 커진다.

구조: 코어가 뼈대를, 오버레이가 저장소 특화를

코어는 시작할 때 현재 저장소의 오버레이를 읽어 뼈대를 채운다. 오버레이가 없으면 코어의 기본값, 즉 도메인 중립 동작으로 돌아간다.

오버레이는 코어를 덮어쓰지 않고 채운다. 코어가 뼈대이고 오버레이가 거기에 저장소 특화 내용을 붙이는 방식이다.

효과는 두 가지다.

• 워크플로를 개선할 때 코어 한 곳만 고치면 모든 저장소에 반영된다. 손으로 옮기는 일이 사라진다.
• 저장소마다 있던 큰 스킬 파일이 작은 오버레이 파일로 줄어든다.

오버레이를 찾는 순서

fos-skills 의 planning/references/monorepo.md 는 단일 저장소에서 설정을 찾는 순서를 정한다.

1. <저장소 루트>/.claude/<스킬 이름>-overlay.md
2. 그 저장소의 하네스 지침 파일, 즉 AGENTS.md 와 CLAUDE.md
3. 어디에도 없으면 사용자에게 확인한다

모노레포는 루트 바로 아래 디렉터리에 오버레이가 하나라도 있으면 모노레포로 본다. 이 경우 작업 대상 하위 프로젝트를 정한 뒤 그 하위 프로젝트의 오버레이를 루트 오버레이보다 먼저 읽는다. 변경이 두 하위 프로젝트에 걸치면 하나로 정하지 않고, 경로에 딸린 값은 각 하위 프로젝트의 오버레이에서 읽는다.

판정과 탐색 순서는 문서에 적혀 있고 scripts/overlay_paths.py 가 그대로 실행한다.

함정: 개인 전역에 둔 스킬이 프로젝트 스킬을 가린다

코어를 전용 저장소에 두고 ~/.claude/skills/<이름> 로 symlink 해서 모든 프로젝트에서 쓰게 할 수 있다. Claude Code 는 symlink 된 스킬 디렉터리를 지원한다.

그런데 같은 이름의 스킬이 여러 곳에 있으면 우선순위가 정해져 있다. Claude Code 스킬 문서는 같은 이름이 enterprise, personal, project 에 모두 있을 때 enterprise, personal, project 순으로 실행된다고 설명한다. 개인 전역은 프로젝트보다 우선한다.

그러면 자체 저장소 안에 같은 이름의 스킬을 가진 다른 저장소가 있을 때, 그 머신에서는 개인 전역 스킬이 이긴다. 저장소의 스킬이 가려지는 것이다. 개인 혼자 쓰는 저장소 묶음에는 문제가 없지만, 팀 공용 저장소처럼 자체 스킬을 유지하는 곳에는 맞지 않다.

fos-skills 는 현재 플러그인으로 스킬을 싣는 방식을 기준으로 설명한다. 같은 문서에 따르면 플러그인 스킬은 /플러그인이름:스킬이름 으로 네임스페이스가 붙어서 개인, 프로젝트 스킬과 우선순위가 충돌하지 않는다.

코어로 옮길 때의 주의

저장소마다 복사된 스킬을 코어로 모을 때는 두 가지를 조심한다.

• 통째로 복사하지 않는다. 저장소마다 특화된 부분을 오버레이로 추출해야 한다. 통짜로 이식하면 각 저장소의 특화가 사라진다.
• 삭제하기 전에 참조를 전부 찾는다. 스킬을 코어로 옮기면 의존하는 다른 스킬의 하드코딩된 경로나, 삭제 대상 아래에 있던 공유 자원이 함께 깨질 수 있다. 삭제 전에 참조를 전수 grep 하고, 공유 자원을 중립 위치로 먼저 옮긴다. 과거 기록(ADR 이나 완료된 작업 문서)의 언급은 그대로 둔다.

정리