RFC: Bundling Agent Skills in Nuxt Modules

Abstract

We propose a standard method for Nuxt modules to distribute "Agent Skills" (AI coding assistant instructions) alongside their source code. By adding an agents field to package.json, modules can define skills that are automatically discovered, version-locked, and exported to the user's AI agent configuration (Claude, Cursor, Copilot, etc.).

The Problem

Currently, agent skills for Nuxt are distributed separately from the modules they support (e.g., in a centralized nuxt-skills repository). This causes several issues:

• Manual Installation: Developers must manually find and install skills separately from the package.
• Version Drift: The skill definition might not match the installed version of the module.
• Double Maintenance: Module authors must maintain code in one repo and skills in another.

The Solution

We propose bundling skills directly inside the npm package. When a user installs a Nuxt module, they get the corresponding skills automatically.

1. The package.json Convention

Module authors define skills in their package.json using the agents property. This namespace allows for defining skills now and other agent capabilities later.

{
  "name": "@nuxthub/core",
  "version": "0.10.4",
  "agents": {
    "skills": [
      { "name": "nuxthub", "path": "./skills/nuxthub" }
    ]
  },
  "files": ["dist", "skills"]
}

2. Directory Structure

Skills follow the agentskills.io format:

skills/nuxthub/
├── SKILL.md              # Frontmatter + overview
└── references/
    ├── database.md
    ├── kv.md
    └── blob.md

Implementation

We have created a reference implementation: npm-agentskills.

Usage in Nuxt (Automatic)

Add the module to your config. Skills are discovered and exported on nuxi prepare or nuxi dev. We use the agents key to configure the module:

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

Usage via CLI (Non-Nuxt)

The CLI binary has been renamed to agents for brevity:

npx agents export --target claude
npx agents list

Future Extensibility

Following feedback from atinux (Nuxt creator), we have renamed the configuration key from agentskills to agents. This ensures the ecosystem remains open to future AI implementations, such as the Model Context Protocol (MCP) or llms.txt standards.

While this RFC focuses on skills, the agents namespace allows the configuration to evolve without breaking changes. A future configuration might look like this:

// Future vision for nuxt.config.ts
export default defineNuxtConfig({
  agents: {
    // Current functionality
    skills: {
      targets: ['claude', 'cursor']
    },
    // Future possibilities
    mcp: 'https://nuxt.com/mcp',
    llms: 'https://nuxt.com/llms.txt'
  }
})

Supported Agents

All exports are project-local:

Real-World Example

See the implementation in @onmax/nuxt-better-auth:

• PR: onmax/nuxt-better-auth#58
• PR: onmax/nuxt-better-auth#58

Next Steps

1. Gather community feedback on this updated RFC.
2. Pilot with official modules (@nuxthub/core, @nuxt/content).
3. Formalize in the upstream agentskills specification.

References

• npm-agentskills - Reference implementation
• agentskills/agentskills#81 - Ecosystem RFC
• nuxt-skills - Current skill repository