Bundle agent skills with your npm packages to help AI assistants understand your library.

Agent Skills provide contextual documentation that AI coding assistants load automatically. When developers use your library, their AI agent reads your skill to deliver accurate guidance on your API, patterns, and best practices.

Skills follow the agentskills open format, supported by Claude Code, GitHub Copilot, Cursor, and other AI coding tools.

This package enables library authors to bundle skills with their npm packages. When users install your package, their AI agent discovers and exports the skills to the appropriate location.

npm install npm-agentskills

Add an agents field to your package.json that points to skill directories:

{
  "name": "my-awesome-library",
  "agents": {
    "skills": [
      { "name": "my-skill", "path": "./skills/my-skill" }
    ]
  }
}

Create skill directories with a SKILL.md file:

skills/my-skill/
├── SKILL.md           # Required: entry point with frontmatter
└── references/        # Optional: additional documentation files
    └── api.md

Learn how to write skills: See the agentskills.io specification for the complete guide on creating effective agent skills.

Add the module to your Nuxt config. The module automatically discovers skills from node_modules and exports them when you run nuxi prepare or nuxi dev:

export default defineNuxtConfig({
  modules: ['npm-agentskills/nuxt'],
  agents: {
    targets: ['claude', 'cursor'],
  },
})

The module scans your dependencies for packages with agents fields and exports their skills to project-local directories.

Run the CLI after installing packages that contain skills:

# Export skills to Claude Code
npx agents export --target claude

# Export to multiple agents
npx agents export --target cursor
npx agents export --target codex

# List all discovered skills
npx agents list

Add this to your postinstall script for automatic exports:

{
  "scripts": {
    "postinstall": "agents export --target claude"
  }
}

All paths are project-local, keeping skills scoped to your project rather than polluting global configuration.

Many agents read from multiple directories for compatibility:

• Goose also reads .claude/skills/ and .agents/skills/
• OpenCode also reads .claude/skills/
• Amp uses the portable .agents/skills/ convention

If you target claude, your skills will work with Goose and OpenCode automatically.

Use the core functions directly in build tools or custom integrations:

import {
  exportToTargets,
  generateManifest,
  resolveSkills,
  scanForSkillPackages,
  scanLocalPackage,
} from 'npm-agentskills'

// Scan node_modules for packages with agents field
const packageSkills = await scanForSkillPackages('./node_modules')

// Scan local package.json for skills defined in this project
const localSkills = await scanLocalPackage('./')

// Resolve and deduplicate skills
const skills = await resolveSkills(packageSkills, localSkills)

// Export to agent directories
await exportToTargets(skills, ['claude', 'cursor'], './')

// Generate manifest for debugging
const manifest = generateManifest(skills)

# List all discovered skills with their sources
agents list
agents list --json          # Output as JSON

# Export skills to agent directory
agents export --target claude
agents export --target cursor
agents export --dest ./custom-path  # Custom destination

# Options
--cwd <dir>      # Project root (default: current directory)
--dir <dir>      # Skills directory (default: node_modules/.cache/agentskills)

1. Discovery: Scans node_modules for packages with an agents field in their package.json
2. Resolution: Reads each skill's SKILL.md file and parses the frontmatter metadata
3. Export: Copies skill directories to the appropriate agent location
4. Manifest: Generates a manifest.json file listing all discovered skills

For Nuxt, the module handles this automatically during nuxi prepare. For other frameworks, you run the CLI manually or via npm scripts.

Verify the tool discovers your skills correctly:

# List discovered skills
npx agents list

# Export to agent directory
npx agents export --target claude

# Verify files exist
ls -la .claude/skills/your-skill/

MIT