TL;DR

skills-npm은 npm 패키지에 포함된 에이전트 스킬을 자동으로 찾아 프로젝트의 에이전트 폴더에 심볼릭 링크로 연결하는 CLI 도구입니다. npx skills-npm setup으로 package.json의 prepare 훅에 등록하면 이후 의존성 설치 시 스킬이 자동으로 재연결되며 .gitignore 자동 수정과 dry-run, include/exclude 같은 세부 설정을 제공합니다. 에이전트 감지는 홈 디렉터리 존재와 CLI 설치 여부를 결합해 수행하므로 대다수 코딩 에이전트 환경에서 무손실로 동작할 수 있습니다. 에이전트 스킬을 npm으로 배포하거나 팀원마다 별도 클론 없이 스킬을 공유하려는 경우 빠르게 도입해볼 만합니다.

핵심 포인트

• 이 레포지토리는 Node.js/TypeScript 환경에서 동작하는 독립형 CLI 도구로, npm 패키지 내부에 들어있는 에이전트 스킬을 찾아 프로젝트 내에 심볼릭 링크로 연결합니다. 설치 후 prepare 훅에 등록해 의존성 설치 시 자동으로 스킬을 재연결하도록 동작하므로 수동으로 깃을 클론하거나 별도 스크립트를 유지할 필요가 줄어듭니다. 에이전트 생태계(예: cursor, claude, codex 등)를 로컬 설정 디렉터리와 PATH에 있는 CLI로 감지해 대상 에이전트를 자동으로 선택하거나 명시적으로 지정할 수 있습니다.
• 설치는 개발 의존성으로 추가한 뒤 npx skills-npm setup 명령 한 번으로 준비를 끝낼 수 있으며, setup은 package.json의 prepare 스크립트에 skills-npm을 병합하고 .gitignore에 **/skills/npm-* 패턴을 추가한 뒤 첫 동기화를 수행합니다. 런타임에는 node_modules에서 발견한 skills 디렉터리를 skills/npm-<package-name>-<skill-name> 형식으로 에이전트 폴더로 심볼릭 링크합니다. 이 방식은 스킬과 툴의 버전 불일치 및 팀별 복제 관리 부담을 줄이는 것을 목표로 합니다.
• 구성은 프로젝트 루트에 skills-npm.config.ts 파일을 두어 제어하며 source(source: 'node_modules' | 'package.json'), agents, recursive, gitignore, yes, dryRun, include/exclude 같은 옵션을 제공합니다. include와 exclude는 @some/* 같은 와일드카드 패턴과 패키지별 특정 스킬 지정이 가능해 대규모 모노레포나 선택적 패키지 처리에 대응합니다. 기본 동작은 workspace 루트를 자동 탐지(pnpm-workspace.yaml, lerna.json, 또는 workspaces 필드가 있는 package.json)로 설정되며 필요시 cwd로 오버라이드할 수 있습니다.
• 패키지 작성자는 패키지 안에 skills/디렉터리를 포함해 SKILL.md 같은 메타를 제공하면 사용자가 npm으로 설치할 때 스킬을 함께 배포할 수 있습니다. README는 @slidev/cli, @vitejs/devtools-kit, @vueuse/skills 등 실제 스킬을 번들한 패키지 사례를 제시해 실무 적용 가능성을 보여줍니다. 이 도구는 Git 전용 소스 방식을 대체하려는 워크플로우에 적합하며, 스킬을 패키지화해 배포하는 프로젝트에서 특히 유용합니다.