npm-agent

name	npm-agent
description	Execute NPM packages as AI agent tools - a flexible alternative to MCPs
model-only	false
allowed-tools	["Bash","Read","Write"]

NPM Agent Skill

You have access to a curated library of 289 high-quality NPM packages that can be executed as tools via bash. This provides flexible, powerful capabilities that go beyond what MCPs offer.

Quick Reference

The manifest at data/packages.json contains all available packages with execution patterns.

Package Categories

• data_processing: CSV, JSON, XML, YAML parsing (csv-parse, papaparse, js-yaml, fast-xml-parser)
• image_media: Image manipulation and PDF (sharp, pdfjs-dist, jspdf, svgo)
• http_apis: HTTP clients (axios, got, node-fetch)
• utilities: General utilities (lodash, dayjs, moment, uuid, nanoid)
• validation: Data validation (ajv, zod, joi, yup)
• file_system: File operations (glob, archiver, fs-extra)
• cloud_infrastructure: Cloud SDKs (stripe, twilio, @azure/*)
• database: Database clients (pg, knex, mongoose)
• cli_tools: CLI building (commander, yargs, inquirer, ora, chalk)
• testing: Test frameworks (jest, mocha, chai, sinon)
• web_scraping: Browser automation (puppeteer, playwright, cheerio)
• templating: Template engines (handlebars, ejs, mustache, marked)

Execution Patterns

Pattern 1: npx One-Shot (Best for CLI tools)

npx -y <package> [args]

The -y flag auto-confirms installation.

Pattern 2: Node One-Liner (Best for programmatic usage)

node -e "const pkg = require('<package>'); /* code */"

Pattern 3: Temp Script (For complex operations)

1. Write a .js file
2. Run with node script.js
3. Delete the file

Common Examples

Image Processing (sharp)

# Resize image
node -e "require('sharp')('input.png').resize(300).toFile('output.png')"

# Convert to JPEG
node -e "require('sharp')('input.png').jpeg({quality: 80}).toFile('output.jpg')"

# Get metadata
node -e "require('sharp')('image.png').metadata().then(m => console.log(JSON.stringify(m, null, 2)))"

CSV Parsing (csv-parse, papaparse)

# Parse CSV file
node -e "require('fs').createReadStream('data.csv').pipe(require('csv-parse').parse({columns:true})).on('data', r => console.log(JSON.stringify(r)))"

# Quick parse with papaparse
node -e "console.log(JSON.stringify(require('papaparse').parse(require('fs').readFileSync('data.csv','utf8'), {header:true}).data))"

HTTP Requests (axios, got, node-fetch)

# GET request
node -e "require('axios').get('https://api.example.com/data').then(r => console.log(JSON.stringify(r.data)))"

# POST request
node -e "require('axios').post('https://api.example.com/data', {key: 'value'}).then(r => console.log(r.status))"

Date Manipulation (dayjs, moment)

# Current date formatted
node -e "console.log(require('dayjs')().format('YYYY-MM-DD HH:mm:ss'))"

# Add 7 days
node -e "console.log(require('dayjs')().add(7, 'day').format('YYYY-MM-DD'))"

JSON Schema Validation (ajv, zod)

# Validate with AJV
node -e "const Ajv = require('ajv'); const v = new Ajv(); console.log(v.validate({type: 'object', required: ['name']}, {name: 'test'}))"

YAML Parsing (js-yaml)

# Parse YAML
node -e "console.log(JSON.stringify(require('js-yaml').load(require('fs').readFileSync('config.yaml', 'utf8'))))"

# Convert JSON to YAML
node -e "console.log(require('js-yaml').dump({key: 'value', nested: {a: 1}}))"

File Operations (glob, archiver)

# Find all JS files
node -e "require('glob').glob('**/*.js', {ignore: 'node_modules/**'}).then(f => console.log(f.join('\n')))"

# Create ZIP archive
node -e "const a = require('archiver')('zip'); a.pipe(require('fs').createWriteStream('archive.zip')); a.directory('src/', false); a.finalize()"

Markdown Processing (marked) - ESM Module

# Convert markdown to HTML (CLI)
npx marked -i README.md -o README.html

# Programmatic (marked is ESM-only, use import())
node -e "import('marked').then(m => console.log(m.parse('# Hello\n\nWorld')))"

Template Rendering (handlebars, ejs)

# Handlebars
node -e "console.log(require('handlebars').compile('Hello {{name}}!')({name: 'World'}))"

# EJS
node -e "console.log(require('ejs').render('Hello <%= name %>!', {name: 'World'}))"

Excel/Spreadsheet (xlsx, exceljs)

# Read Excel file
node -e "const XLSX = require('xlsx'); const wb = XLSX.readFile('file.xlsx'); console.log(JSON.stringify(XLSX.utils.sheet_to_json(wb.Sheets[wb.SheetNames[0]])))"

PDF Generation (jspdf)

node -e "const {jsPDF} = require('jspdf'); const doc = new jsPDF(); doc.text('Hello World', 10, 10); require('fs').writeFileSync('output.pdf', Buffer.from(doc.output('arraybuffer')))"

UUID/ID Generation (uuid, nanoid)

# UUID v4
node -e "console.log(require('uuid').v4())"

# NanoID (ESM-only, use import())
node -e "import('nanoid').then(m => console.log(m.nanoid()))"

Crypto (crypto-js, bcrypt)

# MD5 hash
node -e "console.log(require('crypto-js').MD5('hello').toString())"

# SHA256
node -e "console.log(require('crypto-js').SHA256('hello').toString())"

Best Practices

1. Always use -y with npx to auto-confirm package installation
2. Prefer node one-liners for simple operations to minimize context
3. Check the manifest for specific execution patterns per package
4. Handle errors gracefully - wrap in try/catch for robustness
5. Clean up temp files if creating scripts

ESM vs CommonJS Modules

Some modern packages are ESM-only and cannot use require(). Use import() instead:

CommonJS packages (most packages):

node -e "console.log(require('dayjs')().format('YYYY-MM-DD'))"

ESM-only packages (use dynamic import):

node -e "import('nanoid').then(m => console.log(m.nanoid()))"
node -e "import('marked').then(m => console.log(m.parse('# Hello')))"

Known ESM-only packages:

• nanoid (v4+)
• marked (v5+)
• chalk (v5+)
• ora (v6+)
• execa (v6+)
• got (v12+)
• node-fetch (v3+)

How to detect ESM packages:

• Error: ERR_REQUIRE_ESM or require is not defined
• Package.json contains "type": "module"

Pattern for ESM:

node -e "import('<package>').then(m => { /* use m.functionName() */ })"

When to Use NPM Packages vs MCPs

Why NPM Packages Are Often Better

Aspect	MCP	NPM Packages
Setup time	Hours per tool	Minutes
Code required	Custom server	Zero
Maintenance	You maintain it	NPM community
Updates	Manual redeploy	npm update
Tool count	Build each one	289+ ready to use

Use NPM Packages When:

• You need image/file processing capabilities
• You need data transformation (CSV, JSON, XML, Excel)
• You need flexible API interactions with official SDKs
• The task requires error handling and recovery
• You want to combine multiple tools dynamically
• Quick setup is important
• You want battle-tested, community-maintained tools

Use MCPs When:

• You need persistent connections (WebSockets, database pools)
• Real-time streaming is required
• Complex authentication flows (OAuth callbacks)
• Building proprietary tools with custom logic
• Internal systems require special protocols

Finding the Right Package

1. Check the manifest: data/packages.json
2. Search by category: Look at the category field
3. Check examples: Many packages have codeExamples in the manifest
4. Fallback: Use npx <package> --help to discover CLI options

Package Installation Note

Packages are auto-installed when first used via npx -y or when running node -e (npm will resolve them). For repeated use, you can pre-install:

npm install <package>