스킬 4개에서 17개로: 패키지 관리자가 없는 세계에서 살아남기

스킬 4개일 때는 관리 같은 게 필요 없었다. 17개가 되자 "이 스킬 어디에 깔았더라?"가 일상이 됐다.

idea-guide, python-guide, skill-version-manager, typst-guide — 처음에는 이 4개뿐이었다. 그런데 AI 에이전트와 함께 일하는 시간이 늘면서 스킬이 빠르게 늘어났다. 범용 스킬(cjk-ascii-art, english-humanizer, korean-humanizer, claude-code-headless 등)과 museck.com 전용 스킬(blog-miner, museck-bi, museck-blog, museck-seo 등)을 대량으로 추가했다. 스킬이 10개를 넘어가면서 관리 체계를 본격적으로 구축해야 했다.

폭발적 성장: 범용 스킬 11개 + 브랜드 스킬 6개

추가된 스킬을 분류해보면 크게 두 종류다.

범용 스킬은 어떤 프로젝트에서든 쓸 수 있다. korean-humanizer는 AI가 쓴 한국어를 자연스럽게 다듬어주고, claude-code-headless는 헤드리스 환경에서 Claude Code를 자동화하는 가이드다. 브랜드 스킬은 museck.com에서만 쓴다. blog-miner는 git 커밋에서 블로그 글감을 추출하고, museck-bi는 사이트 성과 분석을 자동화한다.

첫 번째 문제: 어디에 뭐가 깔려 있는지 모른다

스킬 설치 경로가 세 곳이나 된다.

• ~/.claude/skills/ — 전역 설치, 모든 프로젝트에서 접근 가능
• {project}/.claude/skills/ — 프로젝트 레벨, 해당 프로젝트에서만 사용
• ~/.agents/skills/ — 서브에이전트 전용 경로

korean-humanizer를 글로벌에 깔았는데 프로젝트에도 옛 버전이 있으면 어느 쪽이 로드되는지 헷갈린다. npm의 global vs local 같은 문제다. install-registry.md로 이 혼란을 해결했다.

| 아이템 | 타입 | 버전 | Claude 경로 | workspace |
|--------|------|------|-------------|-----------|
| forge | skill | v1.2.0 | ~/.claude/skills/forge/ | skills/forge/ |
| korean-humanizer | skill | v1.0.0 | ~/.claude/skills/korean-humanizer/ | skills/korean-humanizer/ |
| blog-miner | skill | v1.0.0 | - | museck-brand/blog-miner/ |

이 테이블 하나로 전체 스킬 현황을 볼 수 있다. workspace 열은 소스 저장소 내 경로, Claude 경로는 실제 설치 위치다. 새 스킬을 추가하거나 업데이트할 때마다 이 테이블을 갱신한다.

두 번째 문제: 범용과 브랜드 전용의 경계

museck-blog 스킬에는 두 가지 지식이 섞여 있었다. "블로그를 어떻게 쓰는가"라는 범용 지식과 "museck.com의 PayloadCMS에 어떻게 발행하는가"라는 프로젝트 전용 지식이다. 이걸 한 파일에 담으면 다른 프로젝트에서 재사용할 수 없다.

museck-brand/ 디렉토리를 만들어 브랜드 전용 스킬을 분리했다. 범용 로직과 브랜드 특화 로직을 명확히 나누면, 범용 부분은 다른 프로젝트에도 설치할 수 있다. npm의 @scope/package 네임스페이스와 비슷한 발상이다.

세 번째 문제: 에이전트와 스킬의 구분

스킬과 서브에이전트는 다르다. 스킬은 사용자가 호출하는 가이드/프레임워크이고, 서브에이전트는 자율적으로 행동하는 주체다. 이 구분을 명명 규칙으로 강제했다.

• 에이전트: -er/-or 접미사 (content-spotter, analytics-advisor)
• 스킬: -er/-or 불가 (blog-engine, seo-engine, web-analytics)

이름만 봐도 "이건 자동으로 돌아가는 에이전트구나" vs "이건 내가 호출해야 하는 도구구나"를 알 수 있다. skill-version-manager도 이 규칙에 맞춰 v1.2.0에서 에이전트 지원을 추가했다. 서브에이전트도 스킬과 동일한 디렉토리 구조로 관리된다.

배운 것

소프트웨어 패키지 관리에서 배운 교훈이 AI 스킬 관리에도 그대로 적용된다. 스코프 분리, 중앙 레지스트리, 명명 규칙 — 이런 것들이 규모가 커질 때 혼란을 막아준다. 다만 차이점도 있다. 스킬 파일은 의존성 트리가 없고, 빌드 과정이 없고, 바이너리 호환성 문제도 없다. 그래서 npm이나 pip 같은 무거운 인프라 없이 마크다운 테이블 하나로 관리가 가능했다.

가장 중요한 교훈은 "범용과 전용을 일찍 분리하라"는 것이다. 나중에 분리하면 기존 설치 경로를 모두 업데이트해야 하는 비용이 발생한다. 처음부터 이 스킬이 특정 프로젝트에만 쓰이는지, 범용으로 쓸 수 있는지 한 번 더 생각하는 습관이 필요하다.

자주 묻는 질문

install-registry가 마크다운 테이블인데, 자동화는 안 하나요?

현재는 수동으로 관리한다. 스킬 수가 아직 20개 미만이라 자동화의 이점보다 마크다운의 가독성이 더 크다. 50개를 넘어가면 YAML이나 JSON 기반 레지스트리로 전환하고 CLI 도구를 만들 계획이다.

브랜드 스킬을 다른 사람이 쓸 수 있나요?

브랜드 스킬은 museck.com의 인프라(PayloadCMS, K8s 배포 등)에 종속되어 있어서 그대로는 쓸 수 없다. 하지만 범용 스킬로 추출한 blog-engine이나 seo-engine은 어떤 프로젝트에서든 사용 가능하다. 이 분리가 브랜드 그룹의 핵심 가치다.

에이전트 명명 규칙이 왜 중요한가요?

스킬과 에이전트는 실행 방식이 다르다. 스킬은 사용자가 호출하고, 에이전트는 자율적으로 동작한다. 이름에서 이 차이를 바로 알 수 있으면 다른 사람이 저장소를 봤을 때 각 아이템의 성격을 즉시 파악할 수 있다. 코드 컨벤션과 같은 원리다.