list-npm-package-content

list-npm-package-content 스킬 개요

list-npm-package-content가 실제로 하는 일

list-npm-package-content 스킬은 npm 패키지를 publish하기 전에, 실제 npm 패키지 tarball에 어떤 파일이 들어가 배포될지를 정확히 점검할 수 있게 도와줍니다. 하는 일은 실무적으로 단순합니다. 패키지를 빌드하고, tarball을 만들고, 그 안의 파일 목록을 확인한 뒤, 임시 아카이브를 삭제해서 사용자가 실제로 설치하게 될 결과물을 검증합니다.

이 스킬이 특히 잘 맞는 경우

이 스킬은 아래 같은 질문에 답해야 하는 패키지 유지보수자, 릴리스 엔지니어, 라이브러리 작성자에게 특히 유용합니다.

• “빌드 결과물이 실제 publish 패키지에 들어갔나?”
• “왜 npm이 소스 파일, 테스트 fixture, 또는 비밀 정보를 같이 실어 보내고 있지?”
• “왜 설치 후 필요한 파일이 빠져 있지?”
• “이 패키지는 publish된 아티팩트만 보이는 배포 환경에서도 제대로 동작할까?”

특히 monorepo를 운영하거나 subpackage 기준으로 publish하는 경우라면 더 직접적으로 관련 있습니다.

이 스킬의 진짜 해결 과제

list-npm-package-content의 핵심 가치는 단순히 파일 목록을 출력하는 데 있지 않습니다. npm 소비자가 실제로 받게 되는 패키징 결과를 publish 전에 보여 줌으로써 릴리스 리스크를 낮춰 준다는 점이 중요합니다. 이 결과는 종종 저장소의 디렉터리 트리와 다릅니다. 그래서 패키지 크기 문제, 누락된 빌드 산출물, 의도치 않은 파일 유출, 불완전한 publish 결과로 인한 배포 실패를 디버깅할 때 특히 의미가 큽니다.

일반적인 프롬프트와 다른 점

일반적인 AI 프롬프트는 “files, .npmignore, .gitignore를 확인해 보세요” 정도로 안내할 수 있습니다. 하지만 이 스킬은 설정 규칙 자체보다 실제 tarball 결과를 중심에 둔다는 점에서 더 강합니다. 실무에서는 tarball이 곧 진실입니다. 포함된 helper script도 build → pack → inspect → clean up이라는 구체적인 워크플로를 제공합니다.

설치 전에 알아둘 핵심 제약

현재 list-npm-package-content 스킬은 의도적으로 범위를 좁혀 두었습니다.

• npm 패키지 내용물 확인에 초점이 있으며, 전체 릴리스 검증을 다루지는 않습니다.
• helper script는 pnpm 기반 워크플로를 전제로 합니다.
• 점검하려는 패키지 디렉터리에서 실행한다고 가정합니다.
• npm 패키징의 모든 예외 케이스를 자동으로 설명해 주지는 않으므로, 출력 결과는 직접 해석해야 합니다.

패키징 전반을 넓게 설명하는 튜토리얼이 필요하다면 이 스킬은 너무 집중형일 수 있습니다. 반대로 publish 전 빠른 검증이 목적이라면 잘 맞습니다.

list-npm-package-content 스킬 사용 방법

list-npm-package-content 설치/사용 전제

list-npm-package-content는 대상 패키지가 이미 정상적으로 build 가능한 환경에서 사용하는 것이 좋습니다. 저장소 기준으로 보면 패키징 워크플로는 다음 shell script를 중심으로 동작합니다.

bash scripts/list-package-files.sh

이 스크립트는 아래 작업을 수행합니다.

• pnpm build
• pnpm pack
• 생성된 tarball에 대해 tar -tzf 실행
• tarball 정리(cleanup)

따라서 list-npm-package-content를 쓰기 전에, 현재 환경에 pnpm, tar, 그리고 프로젝트 의존성이 준비되어 있는지 먼저 확인해야 합니다.

먼저 읽어야 할 파일

이 스킬을 파악할 때 가장 빠르고 실용적인 읽기 순서는 다음과 같습니다.

1. skills/list-npm-package-content/SKILL.md
2. skills/list-npm-package-content/scripts/list-package-files.sh
3. 대상 패키지의 package.json
4. 대상 패키지의 .npmignore가 있다면 그 파일
5. .npmignore가 없다면 대상 패키지의 .gitignore

이 순서는 추상적인 가이드에서 시작해, 실제 출력 결과를 좌우하는 정확한 패키징 규칙으로 내려가는 흐름과 맞닿아 있습니다.

이 스킬이 사용자에게 필요한 입력

list-npm-package-content를 제대로 활용하려면 에이전트에게 아래 정보를 주는 것이 좋습니다.

• 패키지 경로, 예: packages/ai
• 사용 중인 package manager
• pack 전에 build가 필요한 패키지인지 여부
• 무엇을 검증하려는지
• 의심되는 파일이나 누락 여부를 확인하고 싶은 파일

좋은 입력은 구체적입니다. “내 패키지 좀 확인해줘”는 약합니다. “dist/, README.md, 생성된 type 파일이 포함되는지 보여주고, test fixture는 제외되는지 확인해줘”가 훨씬 낫습니다.

실전 호출 워크플로

list-npm-package-content usage를 실무적으로 쓰는 흐름은 다음과 같습니다.

1. 패키지 디렉터리로 이동합니다.
2. 저장소 구조가 이 스킬과 맞으면 helper script를 실행합니다.
3. tarball 파일 목록을 검토합니다.
4. 결과를 아래 항목과 비교합니다.
   • package.json의 files
   • .npmignore
   • 예상한 build output
5. 패키징 설정을 수정하고 다시 실행합니다.

이 스킬은 한 번 실행하고 끝내기보다 반복 루프로 쓸 때 가장 효과적입니다.

스킬을 잘 발동시키는 예시 프롬프트

에이전트에 아래처럼 요청하면 더 좋은 결과를 얻을 수 있습니다.

“packages/my-lib에 list-npm-package-content를 사용해줘. 패키지를 빌드하고 tarball 내용을 나열한 다음, dist/, type declarations, README.md가 포함되는지 알려줘. 그리고 source files, tests, env files, 또는 불필요하게 커 보이는 아티팩트가 ship되면 표시해줘.”

왜 효과적인지:

• 패키지 경로가 명확합니다.
• 무엇을 중점적으로 검사할지 지정합니다.
• 포함 여부와 제외 검토를 함께 요청합니다.
• 단순 설명이 아니라 판단 가능한 결과를 요구합니다.

배포 점검용으로 더 강한 프롬프트

list-npm-package-content for Deployment처럼 배포 관점으로 쓰려면, 런타임 요구사항에 맞춰 프롬프트를 조정하는 것이 좋습니다.

“packages/sdk에 list-npm-package-content를 사용하고, publish된 tarball에 CI와 serverless 배포 환경에서 production install에 필요한 파일이 모두 들어 있는지 검증해줘. 컴파일된 출력물이 존재하는지, entry point가 정상적으로 resolve되는지, 런타임에 로컬 전용 파일이 필요한 구조는 아닌지 확인해줘.”

이렇게 하면 결과가 더 좋아집니다. 실제 배포 실패는 대개 눈에 띄는 패키징 실수보다, build된 자산이 빠진 문제에서 발생하는 경우가 많기 때문입니다.

helper script가 실제로 검증하는 것

번들된 shell script는 선언된 의도만이 아니라, 실제 패키징 결과를 검증합니다. 사실상 아래 질문을 던지는 셈입니다.

• build가 예상한 산출물을 만들었는가?
• pnpm pack이 그것들을 실제로 포함했는가?
• tarball이 최종 사용자가 다운로드하는 내용과 일치하는가?

이 때문에 저장소 내용과 publish 내용이 어긋나는 상황에서 특히 유용합니다.

npm이 tarball 포함 파일을 결정하는 방식

이 스킬은 확인해야 할 핵심 패키징 규칙을 드러내 줍니다.

1. package.json의 files
2. .npmignore
3. .npmignore가 없을 때의 .gitignore
4. package.json, README, LICENSE, CHANGELOG처럼 npm이 항상 포함하는 파일
5. .git, node_modules, .npmrc처럼 npm이 항상 제외하는 경로

이 우선순위는 중요합니다. 많은 패키징 버그는 저장소 트리가 자동으로 publish 패키지와 같을 것이라고 가정해서 생깁니다.

package.json만 읽는 것보다 이 스킬을 써야 하는 때

설정만 훑어보는 것으로 충분하지 않을 때 list-npm-package-content를 쓰는 것이 맞습니다. package.json을 읽으면 의도는 파악할 수 있지만, build 도구, ignore 규칙, 생성 파일이 서로 상호작용한 뒤 최종 tarball에 실제로 무엇이 들어갔는지는 알 수 없습니다. 릴리스 검증 관점에서는 설정 자체보다 tarball 결과가 더 신뢰할 만합니다.

실제 저장소에서 자주 필요한 적응 작업

다음과 같은 경우에는 스크립트를 약간 조정해야 할 수 있습니다.

• 저장소가 pnpm이 아니라 npm 또는 yarn을 사용하는 경우
• build 명령이 pnpm build와 다른 경우
• rebuild 없이 특정 패키지만 확인하고 싶은 경우
• monorepo의 특정 패키지 경로에서 publish하는 경우
• 환경에 GNU 호환 shell 도구가 없는 경우

그렇다고 이 스킬의 가치가 떨어지는 것은 아닙니다. 다만 list-npm-package-content install은 바로 꽂아 쓰는 도구라기보다, 워크플로를 도입하는 성격이 더 강하다는 뜻입니다.

list-npm-package-content 스킬 FAQ

list-npm-package-content는 초보자도 쓰기 쉬운가

네, 기본적인 패키지 publish 개념을 이미 알고 있다면 충분히 접근 가능합니다. 이 스킬은 범위가 좁고 구체적이라서, 초보자가 추상적인 npm 문서를 헤매지 않게 도와줍니다. 가장 큰 진입 장벽은 환경 설정입니다. 패키지 디렉터리가 어디인지, pack 전에 build 단계가 필요한지 정도는 알고 있어야 합니다.

이 스킬이 일반 프롬프트보다 더 잘 푸는 문제는 무엇인가

실행 중심의 답이 필요할 때 list-npm-package-content가 일반 프롬프트보다 낫습니다. npm 규칙을 설명하는 데서 그치지 않고, 실제 tarball 내용을 기준으로 재현 가능한 점검 절차를 제공합니다. 그래서 publish 전 QA나 누락 파일 디버깅에 더 유용합니다.

이 스킬이 npm pack이나 npm publish dry run을 대체하나

정확히 그렇지는 않습니다. 이 스킬도 같은 패키징 현실을 바탕으로 하지만, 핵심 가치는 안내된 워크플로와 포함된 스크립트 패턴에 있습니다. 별도의 패키징 시스템이라기보다, packing 과정을 둘러싼 신뢰도 높은 점검 루틴으로 이해하는 편이 맞습니다.

list-npm-package-content는 monorepo 전용인가

아닙니다. 단일 패키지 저장소에서도 잘 동작합니다. 다만 monorepo에서는 패키지 경계, build 산출물, publish 루트를 더 쉽게 잘못 잡기 때문에 가치가 더 커집니다.

언제 list-npm-package-content를 쓰지 말아야 하나

질문이 npm 버전 관리, changelog 생성, registry 인증, 릴리스 자동화에만 관한 것이라면 이 스킬은 건너뛰는 편이 낫습니다. 실제 패키지를 점검하지 않고 files나 ignore 규칙의 개념 설명만 필요할 때도 마찬가지입니다.

배포 디버깅에도 사용할 수 있나

네. list-npm-package-content for Deployment는 publish된 패키지에 컴파일된 파일, 런타임 자산, declaration 파일이 빠져서 production install이 실패하는 경우에 매우 좋은 사용 사례입니다. 다운스트림 환경이 실제로 무엇을 받는지 검증할 수 있게 해 줍니다.

list-npm-package-content 스킬 개선 방법

결정에 도움이 되는 프롬프트로 시작하기

list-npm-package-content에서 더 좋은 결과를 얻으려면, 판단으로 이어질 질문을 해야 합니다. 예를 들면 다음과 같습니다.

• 런타임에 필요한 파일이 있는지 검증
• 의도치 않게 ship되는 파일 탐지
• ship된 내용과 저장소 구조 비교
• 특정 파일이 왜 빠졌는지 설명 요청

이렇게 물어야 단순히 파일 목록만 받는 것보다 결과가 훨씬 좋아집니다.

정확한 패키지 경로와 기대 산출물을 명시하기

가장 가치가 큰 개선은 아래 항목을 분명히 적는 것입니다.

• 패키지 디렉터리
• 기대하는 build output
• 패키지 entry point
• tarball에 반드시 있어야 하는 파일
• tarball에 있으면 안 되는 파일

예시:

“packages/ui에 대해 list-npm-package-content를 실행하고 dist/index.js, dist/index.d.ts, README.md가 포함되는지 확인해줘. 반대로 src/, tests, .env 파일은 제외되는지도 검증해줘.”

이렇게 해야 막연한 점검이 아니라 publish 검증으로 바뀝니다.

tarball 결과를 패키지 entry point와 대조하기

흔한 실패 패턴 중 하나는 tarball에 파일은 들어 있지만, main, module, exports, types가 가리키는 파일은 정작 없거나 맞지 않는 경우입니다. 아래처럼 비교를 명시적으로 요청하면 list-npm-package-content 결과의 품질이 높아집니다.

“패키징된 파일 목록을 보여주고, package.json의 exports와 types 필드가 참조하는 경로를 실제로 충족하는지 검증해줘.”

이렇게 하면 깨진 publish를 초기에 많이 걸러낼 수 있습니다.

설정 변경 후 반복적으로 사용하기

가장 좋은 워크플로는 반복형입니다.

1. tarball 점검
2. files 또는 ignore 규칙 수정
3. rebuild 및 repack
4. 다시 비교

list-npm-package-content guide의 품질은 첫 결과를 최종 답으로 보지 않고, 진단용 기준선으로 취급할 때 더 좋아집니다.

build 성공에 과신하지 않기

build가 성공했다고 해서 publish도 올바르다는 뜻은 아닙니다. dist/가 생성되더라도 tarball에서는 여전히 제외될 수 있습니다. list-npm-package-content를 사용할 때는 에이전트에게 “build 성공”과 “publish된 패키지가 완전함”을 분리해서 판단해 달라고 요청하세요. 바로 그 구분이 이 스킬의 실제 가치를 만드는 지점입니다.

도구 체인이 다르면 이식성을 개선하기

저장소가 pnpm을 쓰지 않는다면, 목적을 바꾸지 말고 helper script 로직만 환경에 맞게 조정하는 것이 좋습니다.

• pnpm build를 현재 build 명령으로 교체
• pnpm pack을 해당 환경의 pack 명령으로 교체
• tarball 목록 확인과 cleanup 단계는 유지

이렇게 하면 list-npm-package-content usage의 핵심은 유지하면서도 현재 환경에 맞출 수 있습니다.

먼저 확인할 만한 대표 실패 패턴

우선적으로 점검할 가치가 큰 문제는 아래와 같습니다.

• tarball에 dist/가 없음
• source files가 의도치 않게 포함됨
• test data 또는 fixture가 함께 ship됨
• ignore 파일이 필요한 자산까지 제외함
• README 또는 license 파일이 예상과 다르게 누락됨
• entry point가 tarball에 없는 파일을 참조함

이 항목들을 명시적으로 확인해 달라고 요청하면 결과가 훨씬 실무적으로 바뀝니다.

나열만 하지 말고 이유까지 설명하게 하기

출력 품질을 높이려면 파일 목록뿐 아니라, 왜 포함되거나 제외되었는지도 함께 요청하는 것이 좋습니다. 예를 들면:

“tarball 내용을 나열하고, 예상과 다르게 포함되거나 누락된 파일이 있다면 어떤 규칙 때문에 그렇게 되었는지 설명해줘.”

이렇게 해야 단순 점검을 넘어 디버깅 지원 도구로 발전합니다.

모든 릴리스 후보 전에 list-npm-package-content 사용하기

가장 실용적인 개선은 프로세스 측면입니다. 깨진 publish 이후가 아니라, release candidate를 만들기 전에 list-npm-package-content를 실행하세요. 가벼운 preflight check이지만, 불필요한 지원 이슈, 롤백, 배포 장애를 미리 막는 데 큰 도움이 됩니다.