목적

본고의 목적은 .claude/skills 하위에 배치하는 스킬이 향후 3자리 규모로 증가하더라도, 분류·관리·판별이 용이하게 이루어질 수 있는 디렉터리 구성을 확립하는 것이다. 현행 구성은 모든 스킬을 단일 계층에 병치하는 방식이며, 일정 규모까지는 충분히 기능하지만, 스킬 수의 증가에 따라 가시성 및 유지보수성이 저하될 것으로 예상된다.

개요

본 방침에서는 스킬의 실체를 카테고리별 계층 디렉터리(skill-sources/)에서 관리하고, .claude/skills에는 스크립트를 통해 자동 생성된 심볼릭 링크(Symbolic Link)만을 배치한다. Claude Code의 사양상, 스킬은 .claude/skills/<skill-name>/SKILL.md라는 단일 계층 배치만 인식되지만, 본 방침은 이 제약을 공식적으로 지원되는 심볼릭 링크 이용을 통해 회피하는 것이다.

내용

전제가 되는 사양

본 방침의 전제가 되는 Claude Code의 사양에 대해, 공식 문서 조사 및 실기 검증을 실시하였다. 그 결과, .claude/skills/ 하위에 서브 디렉터리를 두는 중첩 배치는 인식되지 않음을 확인하였다. 반면, 스킬 디렉터리 단위의 심볼릭 링크는 다음과 같이 공식 문서에 명시된 지원 대상이며, 실기 검증에서도 인식됨을 확인하였다.

A
<skill-name> entry in the enterprise, personal, or project locations can be a symlink to a directory elsewhere on disk. Claude Code follows the symlink and reads SKILL.md from the target directory

디렉터리 구성

채택하는 구성을 아래에 나타낸다. 실체는 카테고리별 계층 구조를 가진 skill-sources/ 하위에서 관리하며, .claude/skills/에는 링크만을 배치한다.

skill-sources/ ← 실체 (자유로운 계층으로 관리·편집)
doc/
writer/SKILL.md
...

메커니즘

본 구성은 세 가지 요소로 이루어진다. 첫 번째 요소는 링크 생성 스크립트이다. 이는 skill-sources/를 순회하며, 계층 경로를 -로 연결한 명칭의 심볼릭 링크를 멱등(Idempotent)하게 재생성하는 것으로, 수십 줄의 셸 스크립트 규모로 구현 가능하다. 두 번째 요소는 명명 규칙의 자동 강제이다. 스킬명은 디렉터리 경로로부터 기계적으로 결정되므로, 명명 규칙이 개인의 주의력에 의존하지 않고 구조로서 강제된다. 세 번째 요소는 상대 경로에 의한 링크이다. 상대 경로로 생성된 링크는 clone 대상 위치에 의존하지 않고 동작하며, Git에 그대로 커밋할 수 있다. 물론, 커밋하지 않고 clone 할 때마다 생성해도 무방하다.

장점

본 방식의 가장 큰 장점은 실체가 항상 하나라는 점에 있다. 이를 통해 복사 방식에서 발생할 수 있는 동기화 어긋남이나 이중 편집 문제를 원리적으로 방지할 수 있다. 또한, 실체에 대한 편집은 즉시 반영되므로 동작 확인 사이클을 해치지 않으며, 스킬명이 경로로부터 기존의 명명 규칙과 동일한 형식으로 도출되기에 기존 스킬명을 전혀 변경하지 않고도 도입할 수 있다.

나아가, 링크의 생성 대상을 skill-sources/ 하위의 전체가 아닌 특정 카테고리 디렉터리로만 한정할 수 있다는 점도 장점이다. 실체의 관리와 Claude Code로의 공개가 분리되기 때문에, 실체로는 모든 스킬을 일원적으로 보유한 채 실제로 .claude/skills/에 배치할 스킬을 취사선택할 수 있다. 이를 통해 플랫(Flat)한 네임스페이스에 나열되는 스킬 수 자체를 억제할 수 있으며, 스킬 수 증가에 따라 description이 잘려 자동 발동 정밀도가 저하되는 문제를 실체를 삭제·복제하지 않고도 완화할 수 있다.

이러한 특성은 업무가 크게 여러 계통으로 나뉘고, 각 계통이 필요로 하는 스킬이 서로 겹치지 않을 때 특히 유효하다. 계통별로 링크 생성 대상 디렉터리를 전환함으로써, 해당 업무와 관련된 스킬만을 공개된 상태로 업무에 맞춰 재구성할 수 있으며, 무관한 스킬에 의한 네임스페이스 압박이나 오작동을 피할 수 있다.

과거에 검토한 사항

본 방침을 책정함에 있어 검토한 대안과 그 채택 여부 및 이유를 아래에 나타낸다.

Future works

링크 생성 대상을 한정함으로써 공개 스킬 수를 억제할 수는 있으나, 단일 계통 내에서 필요한 스킬이 3자리 규모에 달할 경우에는 여전히 플랫한 네임스페이스(Namespace)의 비대화와 그에 따른 설명(Description)의 생략이 과제로 남는다. 이 경우, 스킬 자동 발동의 정밀도가 저하될 것으로 예상되므로, 저빈도 스킬에 대한 disable-model-invocation: true 부여나, settings.json의 skillOverrides를 통한 표시 생략을 향후 검토한다.

또한, 링크 생성 스크립트가 skill-sources/를 스캔하는 로직을 유용하여, 각 SKILL.md의 프론트매터(Frontmatter)로부터 카테고리별 목록(SKILLS_CATALOG.md)을 자동 생성함으로써 가시성을 더욱 향상시킬 수 있을 것으로 기대된다.

결론

스킬의 실체는 skill-sources/ 하위의 계층적 디렉터리로 관리하고, .claude/skills에는 링크 생성 스크립트에 의해 작성된 심볼릭 링크를 배치하는 방식을 채택한다. 본 방식은 공식적으로 지원되는 메커니즘으로만 구성되며, 실체의 일원 관리, 명명 규칙의 자동 강제, 그리고 기존 스킬 명칭의 유지를 동시에 충족한다. 도입에 필요한 작업은 skill-sources/로의 실체 이동, 링크 생성 스크립트 작성, 그리고 CI 체크 추가뿐이며, 단계적인 이행도 가능하다.

Discussion