bundle-size-analysis-skill

Bundlephobia Skill

An open-agent skill for inspecting npm package bundle cost with Bundlephobia and related package-size checks.

This repository provides:

• a reusable bundle-size-analysis skill (SKILL.md)
• a Python CLI helper for Bundlephobia package queries, package.json scans, npm publish footprint checks, and local artifact gzip checks
• GitHub automation for packaging the skill bundle

---

What this skill can do

Using live package-size services and local package data, you can:

• submit npm packages to Bundlephobia's API and collect minified/gzipped cost
• scan a package.json dependency list the same way Bundlephobia's site scan works
• inspect Bundlephobia exports, dependency composition, history, and similar packages
• check local publish footprint with npm pack --json --dry-run
• measure built JS/CSS artifact sizes and gzip sizes
• run threshold checks for package, pack, and artifact budgets
• choose the right evidence source for bundle size, install footprint, publish footprint, or actual app bundle analysis

---

Repository layout

SKILL.md
agents/
  openai.yaml
assets/
  bundle-size-analysis-small.svg
  bundle-size-analysis.png
references/
  check-selection.md
scripts/
  bundle_size_analysis.py
README.md
CONTRIBUTING.md
SECURITY.md
CHANGELOG.md

---

Agent compatibility

This is a root SKILL.md package. npx skills can install it directly from GitHub, and npx skills experimental_sync can discover it from node_modules because the npm package ships SKILL.md at the package root.

Use --agent universal for agents that consume the shared .agents/skills layout. Use --agent "*" only when you intentionally want to install to every supported agent directory.

npx skills add Nick2bad4u/Bundlephobia-Skill -g --agent universal -y
npx skills add Nick2bad4u/Bundlephobia-Skill -g --agent "*" -y
npm install --save-dev bundle-size-analysis-skill
npx skills experimental_sync --agent universal -y

OpenAI-specific display metadata lives in agents/openai.yaml. The portable skill contract is SKILL.md plus the referenced assets/, references/, and scripts/ files.

---

Publishing

The skill is packaged for GitHub releases and npm as bundle-size-analysis-skill.

Verify the package locally before publishing:

npm run release:verify
npm publish --access public --provenance

GitHub Actions publishes with npm OIDC trusted publishing using npm publish --access public --provenance. Configure the npm package trusted publisher for repository Nick2bad4u/Bundlephobia-Skill and workflow .github/workflows/release-skill.yml. The workflow intentionally does not use npm stage commands.

---

Quick start

1. Prerequisites

• Python 3.10+
• Node.js/npm when using pack or local package checks
• Network access when querying Bundlephobia

2. Query package sizes

From repository root:

python "scripts/bundle_size_analysis.py" package react@18.2.0 lodash@4.17.21

Fetch deeper Bundlephobia data:

python "scripts/bundle_size_analysis.py" package react@18.2.0 --exports --dependencies --history 10 --similar

Machine-readable output:

python "scripts/bundle_size_analysis.py" package react@18.2.0 --json

---

Common commands

# Scan runtime dependencies from package.json
python "scripts/bundle_size_analysis.py" scan --package-json package.json

# Include dev and optional dependencies in a package.json scan
python "scripts/bundle_size_analysis.py" scan --package-json package.json --include-dev --include-optional

# Check npm publish footprint
python "scripts/bundle_size_analysis.py" pack --repo .

# Measure local build artifacts
python "scripts/bundle_size_analysis.py" artifacts dist build

# Run the combined audit
python "scripts/bundle_size_analysis.py" audit --repo .

# Fail when any queried package exceeds a gzip budget
python "scripts/bundle_size_analysis.py" scan --package-json package.json --max-gzip-kb 50

For the full command surface and workflow guidance, see:

• SKILL.md

---

Security notes

• Do not commit private package metadata, registry tokens, or generated output that exposes secrets.
• The helper does not require Bundlephobia credentials.
• npm pack --dry-run is read-only, but review output before sharing it publicly for private packages.

More details: SECURITY.md

---

Contributing

Contributions are welcome. Please read:

• CONTRIBUTING.md
• CHANGELOG.md

---

Releases and downloads

This repository includes a release workflow that creates a downloadable zip bundle:

• Workflow: .github/workflows/release-skill.yml
• Trigger:
  • push a tag like v0.1.0
  • run manually via workflow_dispatch with:
    • release_type: patch / minor / major
    • version: optional explicit x.y.z (overrides release_type)
    • ref: branch to release from (default main)
• Asset: bundlephobia-skill-<tag>.zip

Examples:

# Manual patch bump from main
gh workflow run "Release Skill Bundle" -f release_type=patch -f ref=main

# Manual explicit release version
gh workflow run "Release Skill Bundle" -f release_type=patch -f version=0.2.0 -f ref=main

---

License

Released under The Unlicense.