RFC: Standardize npm/JavaScript Package Distribution #81

Context & Problem

The current Agent Skills specification defines the format of SKILL.md files but does not standardize how these skills are distributed to developers.

Currently, there is no standard way to:

1. Bundle skills alongside the code they document.
2. Auto-discover skills installed via package managers.
3. Ensure skills stay version-locked with the library code.

Related: #27, #63, #9

Proposal

Add an optional agentskills field to package.json. This allows library authors to declare the skills contained within their npm packages.

Schema Definition

{
  "name": "my-library",
  "agentskills": {
    "skills": [
      { "name": "my-skill", "path": "./skills/my-skill" }
    ]
  },
  "files": ["dist", "skills"]
}

• name: Lowercase, hyphenated unique identifier for the skill.
• path: Relative path from package root to directory containing SKILL.md.

Benefits

1. Version Locking: Skills are versioned with the code. Install v2.0.0 of a library, get v2.0.0 skills.
2. Single Install: npm install my-library installs both the code and the agent instructions.
3. Infrastructure: Leverages existing npm caching, distribution, and security scanning.
4. Auto-Discovery: Agents can scan node_modules to find all available capabilities.

Reference Implementation

I have built a working implementation: npm-agentskills.

Features:

• Scans node_modules for the agentskills field
• Exports skills to agent-specific directories
• CLI: agentskills list and agentskills export --target <agent>
• Nuxt module for automatic export on nuxi prepare
• Programmatic API for custom integrations

Real-world Example:
onmax/nuxt-better-auth#58

Related

• https://github.com/antfu/skills-npm

Supported Targets

Ecosystem & Compatibility

• Nuxt RFC: Adoption plan for Nuxt at nuxt/nuxt#34059
• PRPM (PRPM: Open Source Cross-format distribution and conversion for Agent Skills #9): Compatible with Package Repository Package Manager concepts
• Filesystem (RFC: Standardize skill installation/discovery paths #63): Complements filesystem proposals by handling delivery to user's machine

Future Scope

While this proposal focuses on npm/package.json, the pattern is applicable to other ecosystems:

• Rust: Cargo.toml metadata
• Python: pyproject.toml metadata
• Deno/Bun: Compatible with package.json usage