Agent Skills Discovery

Agent Skills Discovery gives agents one URL for finding the skills published by your site:

/.well-known/agent-skills/index.json

The index follows the discovery draft v0.2.0 schema. Every entry includes a SHA-256 digest so clients can verify the artifact before loading it.

The skills/ convention

Put public skills in public/skills/<name>/SKILL.md in the project or a local layer. The module uses each layer's configured public directory, including custom dir.public paths. Root skills/ directories remain private unless you set agentSkills.dir: 'skills'.

public/skills/
└── seo-audit/
    └── SKILL.md

Start with a complete skill file:

---
name: seo-audit
description: Audit a site for critical SEO issues.
---

# SEO audit

Check indexability, metadata, canonical URLs, and structured data.

Local discovery publishes SKILL.md only. If a skill needs scripts or supporting files, publish an archive as described below.

The module reads the frontmatter and computes the file digest. It publishes the index entry and these routes:

llms.txt gains an Agent Skills section that links every published skill.

The frontmatter name must equal the directory name, as the Agent Skills specification requires. A mismatch, missing description, or invalid frontmatter stops the build and names the file. A directory without a SKILL.md is ignored.

When the project and a layer both ship a skill with the same name, the project wins. Layers outside the project root are skipped.

export default defineNuxtConfig({
  aiReady: {
    agentSkills: {
      dir: 'agent-skills',
      root: 'seo-audit',
      llmsTxt: false,
    },
  },
})

Set dir: false to skip discovery, root: false to omit the root alias, or llmsTxt: false to omit skill links. Set agentSkills: false to disable the feature.

Hook

The ai-ready:agent-skills hook runs after discovery and explicit entries merge, before the module applies the root alias. For example, remove a skill from the published set:

export default defineNuxtModule({
  setup(_, nuxt) {
    nuxt.hook('ai-ready:agent-skills', ({ skills }) => {
      const index = skills.findIndex(skill => skill.name === 'internal-audit')
      if (index !== -1)
        skills.splice(index, 1)
    })
  },
})

Explicit entries

Use agentSkills.skills to list files outside the discovery directory or externally hosted artifacts. An explicit entry replaces a discovered skill with the same name.

Local SKILL.md files

Use a local entry when the skill consists of one SKILL.md file:

export default defineNuxtConfig({
  aiReady: {
    agentSkills: {
      skills: [{
        source: 'local',
        name: 'seo-audit',
        description: 'Audit a site for critical SEO issues.',
        file: './skills/seo-audit/SKILL.md',
      }],
    },
  },
})

Nuxt resolves file from the project root, reads it once during setup, and computes its digest from the original bytes. The server bundle stores the file as base64, so build-time replacements cannot rewrite text such as import.meta.server inside it, and the served bytes match the digest. The path and its resolved symlink target must stay inside the project root. The index advertises this relative artifact URL:

seo-audit/SKILL.md

The relative URL resolves from the index directory. This keeps local artifacts correct when Nuxt redirects discovery into a non-root app base.

The frontmatter name and description must exactly match the config. The complete file shown above meets this example.

Local files must contain valid UTF-8 text and Markdown instructions after the frontmatter. Invalid config or unreadable files stop the Nuxt build with the failing entry and field.

Serve the file at a root address

Discovered skills get /skills/<name>/SKILL.md and, for a single skill, /SKILL.md automatically. An explicit entry can name its own addresses with alias, one string or a list:

export default defineNuxtConfig({
  aiReady: {
    agentSkills: {
      skills: [{
        source: 'local',
        name: 'seo-audit',
        description: 'Audit a site for critical SEO issues.',
        file: './skills/seo-audit/SKILL.md',
        alias: '/SKILL.md',
      }],
    },
  },
})

An alias must be a path-absolute route that ends in .md, sit outside /.well-known/, and avoid the module-owned /index.md and /sitemap.md. Content negotiation leaves aliases alone, so the response is the file itself, with no generated frontmatter and the same digest as the discovery artifact. The index keeps advertising the .well-known URL.

External files and archives

Use an external entry for a SKILL.md or archive that you already host. Compute its digest from the exact file you will upload:

sha256sum seo-toolkit.tar.gz

Set SEO_TOOLKIT_SHA256 to the command's hexadecimal hash before running your Nuxt build:

export default defineNuxtConfig({
  aiReady: {
    agentSkills: {
      skills: [{
        source: 'external',
        name: 'seo-toolkit',
        type: 'archive',
        description: 'Use the complete SEO toolkit and its supporting resources.',
        url: 'https://cdn.example.com/seo-toolkit.tar.gz',
        digest: `sha256:${process.env.SEO_TOOLKIT_SHA256}`,
      }],
    },
  },
})

External entries accept HTTP(S), path-absolute, and index-relative URLs. Nuxt validates the URL and digest format but does not download the artifact during setup. The uploaded bytes must match the hashed file. Recompute the digest whenever the artifact changes.

Use type: 'skill-md' for one Markdown file. Use type: 'archive' for a .tar.gz or .zip containing SKILL.md plus scripts, references, or assets.

The index and embedded local files support GET and HEAD. Other methods return 405. Responses include public cache headers and Access-Control-Allow-Origin: * for browser clients.

For non-root app bases, Nuxt redirects origin-root discovery requests to the base-aware index and artifact routes.