# npm-package

A skill that walks the agent through building an npm library on Bun: scaffolding, strict TypeScript, tests, bundling and publishing.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 331 installs · ★ 176
- Author: jwynia
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/jwynia/agent-skills/tree/HEAD/skills/tech/development/tooling/npm-package/SKILL.md
- Updated: 2026-02-24
- HTML: https://affpapa.org/en/nevibecode/skills/npm-package

## What it does

The skill covers the whole life of an npm package, from an empty folder to `npm publish`. It ships a `scaffold.ts` script that lays out the project, a set of configuration rules, and reference docs on the `exports` map, strict TypeScript and the publishing workflow. The agent leans on those when it edits `package.json`, `tsconfig.json` or `bunup.config.ts`.

The toolchain is fixed: Bun for runtime and packages, Bunup for bundling and `.d.ts` generation, Biome for formatting, ESLint with typescript-eslint for type-aware rules, Vitest for tests, Changesets for versions. The skill bans `any`, bans `main` in place of `exports`, and bans `paths` in a published package — tsc does not rewrite aliases, so consumers cannot resolve them.

Scope is narrow. It targets a single-package repo, not a monorepo, and it is not meant for an `npx` CLI or an application. Bundling goes through Bunup, so without Bun in the project the steps will not run.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add jwynia/agent-skills --skill npm-package -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/npm-package/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/npm-package/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add jwynia/agent-skills --skill npm-package -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/npm-package/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add jwynia/agent-skills --skill npm-package -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/npm-package/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install jwynia/agent-skills npm-package
```

2. **Manually: put the files in place**
- File: `.github/skills/npm-package/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add jwynia/agent-skills --skill npm-package -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/jwynia/agent-skills --path skills/tech/development/tooling/npm-package
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/npm-package/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add jwynia/agent-skills --skill npm-package -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/jwynia/agent-skills/tree/HEAD/skills/tech/development/tooling/npm-package/SKILL.md

## When to use it
- scaffold a fresh npm package layout
- set up a strict tsconfig for a published library
- fix the `exports` map and CJS/ESM interop
- produce dual ESM and CJS output with type declarations
- prepare a release with Changesets and publish with provenance

## Example prompts
- Create a new npm package my-lib using the npm-package skill
- Check the `exports` map in package.json and fix the CJS/ESM interop
- Set up Vitest with coverage thresholds and bundle the package with Bunup

## Similar
- [updating-npm-package](https://affpapa.org/en/nevibecode/skills/updating-npm-package.md) — skill · 398 installs
- [aube-package-manager](https://affpapa.org/en/nevibecode/skills/aube-package-manager.md) — skill · 392 installs
- [check-npm](https://affpapa.org/en/nevibecode/skills/check-npm.md) — skill · 2800 installs
- [npm-security-best-practices](https://affpapa.org/en/nevibecode/skills/npm-security-best-practices.md) — skill · 919 installs
- [link-workspace-packages](https://affpapa.org/en/nevibecode/skills/link-workspace-packages.md) — skill · 3100 installs
- [tsdown](https://affpapa.org/en/nevibecode/skills/tsdown.md) — skill · 1500 installs

From the same set: [jwynia/agent-skills](https://affpapa.org/en/nevibecode/by/jwynia/agent-skills.md) — 81 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md