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

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>