package-publishing — скилл для Claude Code: публикация npm-пакетов
Скилл package-publishing помогает настроить package.json, сборку ESM и CJS и публикацию TypeScript-библиотеки в npm. Пригодится при настройке точек входа и проверок перед релизом.
MIT 119 установок ★ 29 обновлён 2026-08-17
npx skills add oakoss/agent-skills --skill package-publishing -a claude-codeЧто делает package-publishing
Скилл разбирает настройки exports, main, module и types, условные экспорты для ESM и CJS, объявления типов и список файлов для публикации. Он также помогает настроить проверку сборки через prepublishOnly, просмотреть состав пакета командой npm pack --dry-run и включить provenance.
Для новой библиотеки exports задаёт публичные точки входа, а main может служить запасным вариантом для старых потребителей. В блоках экспортов types нужно ставить первым: иначе выбор объявления типов может работать неправильно. Скилл посвящён публикации npm-пакетов, а не настройке сборки приложения или частного реестра.
Какие задачи решает
- настроить публичные точки входа в
package.json - собрать библиотеку в форматах ESM и CJS
- описать TypeScript-типы для условий экспорта
- проверить содержимое пакета перед публикацией
- добавить сборку и provenance в процесс публикации
Примеры запросов агенту
- Настрой
exportsвpackage.jsonдля моей TypeScript-библиотеки с ESM и CJS. - Проверь, какие файлы попадут в пакет при публикации в npm.
- Подскажи, как добавить
prepublishOnlyи provenance для публикации.
Как установить package-publishing
1Через Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill package-publishing -a claude-code2Вручную: положить файлы
~/.claude/skills/package-publishing/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/package-publishing/
1Через Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill package-publishing -a codex2Вручную: положить файлы
.agents/skills/package-publishing/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill package-publishing -a cursor2Вручную: положить файлы
.cursor/skills/package-publishing/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install oakoss/agent-skills skills/package-publishing2Вручную: положить файлы
.github/skills/package-publishing/SKILL.md1Через Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill package-publishing -a gemini-cli2Командой платформы
gemini skills install https://github.com/oakoss/agent-skills --path skills/package-publishingВручную: положить файлы
.devin/skills/package-publishing/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill package-publishing -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы о package-publishing
Как установить package-publishing в Claude Code?
Выполните npx skills add oakoss/agent-skills --skill package-publishing -a claude-code. Файл скилла появится по пути ~/.claude/skills/package-publishing/SKILL.md.
Что делает package-publishing?
Скилл помогает настроить метаданные npm-пакета, сборки ESM и CJS, объявления TypeScript-типов и шаги публикации. В том числе разбирает предварительную проверку через npm pack --dry-run.
В каком порядке указывать условия экспорта для типов?
Условие types должно идти первым в каждом блоке экспорта. Это помогает инструментам найти подходящие объявления типов.
Исходный текст
SKILL.md · MIT
---
name: package-publishing
description: 'npm package publishing patterns for modern TypeScript libraries. Use when configuring package.json exports, setting up dual ESM/CJS builds, or publishing to npm. Use for npm-publish, package-json, exports, main, module, types, dual-package, provenance, prepublishOnly.'
license: MIT
metadata:
author: oakoss
version: '1.0'
source: 'https://docs.npmjs.com/cli/v10/configuring-npm/package-json'
user-invocable: false
---
# Package Publishing
## Overview
Covers modern npm package authoring: `package.json` configuration with the `exports` field, dual ESM/CJS builds, TypeScript type declarations, and secure publishing workflows with provenance.
**When to use:** Configuring package entry points, setting up conditional exports, building dual-format packages, publishing scoped packages, or troubleshooting module resolution.
**When NOT to use:** Application-level bundling (Vite/webpack app configs), monorepo workspace orchestration (Turborepo/Nx), private registry setup (Verdaccio/Artifactory).
## Quick Reference
| Pattern | Field / Command | Key Points |
| ------------------- | ----------------------------------------- | ------------------------------------------------ |
| Entry point | `exports` in package.json | Replaces `main`/`module`; encapsulates internals |
| CJS fallback | `main` | Legacy consumers without `exports` support |
| ESM entry | `module` | Bundler convention; not used by Node.js |
| Type declarations | `types` condition in `exports` | Must be listed first in each condition block |
| Subpath exports | `"./utils": { ... }` | Clean public API; blocks deep imports |
| Conditional exports | `import`/`require` conditions | Toggle ESM vs CJS per consumer |
| Package type | `"type": "module"` | Makes `.js` files ESM; use `.cjs` for CommonJS |
| Side effects | `"sideEffects": false` | Enables tree-shaking in bundlers |
| Peer deps | `peerDependencies` | Shared runtime deps (React, Vue, etc.) |
| Engine constraints | `"engines": { "node": ">=18" }` | Document minimum Node.js version |
| Files allowlist | `"files": ["dist"]` | Controls what gets published to npm |
| Prepublish check | `"prepublishOnly": "npm run build"` | Ensure build runs before publish |
| Dry run | `npm pack --dry-run` | Preview package contents before publishing |
| Provenance | `--provenance` flag or trusted publishers | Cryptographic build attestation |
| Scoped publish | `--access public` | Required for first publish of scoped packages |
## Common Mistakes
| Mistake | Correct Pattern |
| -------------------------------------------------------- | ---------------------------------------------------------------------- |
| Putting `types` after `default` in exports | `types` must be the first condition in every export block |
| Missing `"./package.json"` in exports | Include `"./package.json": "./package.json"` for tooling compatibility |
| Different APIs for `import` vs `require` | Same API surface; write ESM source, transpile to CJS |
| Using `main` without `exports` for new packages | Use `exports` as the primary entry point definition |
| Forgetting `"type": "module"` with `.js` ESM output | Set `"type": "module"` or use `.mjs` extension explicitly |
| Publishing `src/` or `node_modules/` | Use `"files"` allowlist to include only `dist/` |
| No `prepublishOnly` script | Add build step to prevent publishing stale artifacts |
| Using `default` export for libraries | Prefer named exports for consistent cross-tooling behavior |
| Not testing with `npm pack` before publish | Always dry-run to verify package contents and size |
| Omitting `peerDependencies` for framework plugins | Declare shared runtime dependencies as peers |
| Publishing without provenance | Enable provenance for supply-chain transparency |
| Using `.d.ts` for CJS when package is `"type": "module"` | Use `.d.cts` for CJS type declarations, `.d.ts` or `.d.mts` for ESM |
## Delegation
- **Build tooling setup**: Use `Explore` agent to examine tsup/unbuild/rollup configs
- **Type resolution debugging**: Use `Task` agent with "Are the Types Wrong?" (`attw`)
- **Publish pipeline review**: Delegate to `code-reviewer` agent
## References
- [Package.json configuration: exports, main, types, files, engines, peerDependencies](references/package-json-config.md)
- [Build scripts, prepublishOnly, npm pack, provenance, scoped packages](references/build-and-publish.md)
- [Dual ESM/CJS builds, conditional exports, type declarations](references/dual-format.md)
© oakoss · MIT · oakoss/agent-skills