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 (skills/bundle-size-analysis/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

skills/
  bundle-size-analysis/
    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 nested skills/bundle-size-analysis 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 the skills/ directory.

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 skills/bundle-size-analysis/agents/openai.yaml. The portable skill contract is skills/bundle-size-analysis/SKILL.md plus the referenced assets/, references/, and scripts/ files in that skill directory.

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 "skills/bundle-size-analysis/scripts/bundle_size_analysis.py" package [email protected] [email protected]

Fetch deeper Bundlephobia data:

python "skills/bundle-size-analysis/scripts/bundle_size_analysis.py" package [email protected] --exports --dependencies --history 10 --similar

Machine-readable output:

python "skills/bundle-size-analysis/scripts/bundle_size_analysis.py" package [email protected] --json

Common commands

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

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

# Check npm publish footprint
python "skills/bundle-size-analysis/scripts/bundle_size_analysis.py" pack --repo .

# Measure local build artifacts
python "skills/bundle-size-analysis/scripts/bundle_size_analysis.py" artifacts dist build

# Run the combined audit
python "skills/bundle-size-analysis/scripts/bundle_size_analysis.py" audit --repo .

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

For the full command surface and workflow guidance, see:

• skills/bundle-size-analysis/SKILL.md
• skills/bundle-size-analysis/references/check-selection.md
• skills/bundle-size-analysis/references/bundlephobia-helper.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.