nuxt-ai-ready 2.2.1 → 2.3.0

package/dist/chunks/agent-skills.mjs

@@ -1,8 +1,8 @@
 import { createHash } from 'node:crypto';
-import { realpath, readFile } from 'node:fs/promises';
-import { resolve, isAbsolute, relative, sep } from 'node:path';
+import { realpath, readFile, readdir } from 'node:fs/promises';
+import { resolve, isAbsolute, join, relative, sep } from 'node:path';
 import { parseDocument } from 'yaml';
-import { A as AGENT_SKILLS_SCHEMA } from '../shared/nuxt-ai-ready.BVWXwmUS.mjs';
+import { A as AGENT_SKILLS_SCHEMA } from '../shared/nuxt-ai-ready.B8hPhZL9.mjs';
 import 'node:module';
 import '@nuxt/kit';
 import 'defu';
@@ -23,9 +23,28 @@ const urlBase = "https://example.com/.well-known/agent-skills/index.json";
 function skillRoute(name) {
   return `/.well-known/agent-skills/${name}/SKILL.md`;
 }
+const ROOT_SKILL_ALIAS = "/SKILL.md";
+function aliasesOf(skill) {
+  return skill.alias === void 0 ? [] : Array.isArray(skill.alias) ? skill.alias : [skill.alias];
+}
 function skillUrl(name) {
   return `${name}/SKILL.md`;
 }
+function validateAlias(alias, index, sitemapMd) {
+  if (alias === void 0)
+    return [];
+  if (Array.isArray(alias))
+    return alias.flatMap((entry) => validateAlias(entry, index, sitemapMd));
+  if (typeof alias !== "string" || !/^\/(?:[^/?#\s]+\/)*[^/?#\s]+\.md$/.test(alias) || alias.split("/").includes(".."))
+    return [{ index, field: "alias", message: 'must be a path-absolute route ending in .md, such as "/SKILL.md"' }];
+  if (alias.startsWith("/.well-known/"))
+    return [{ index, field: "alias", message: "must not use the /.well-known/ prefix reserved for discovery routes" }];
+  if (alias === "/index.md")
+    return [{ index, field: "alias", message: 'must not use the module-owned markdown route "/index.md"' }];
+  if (sitemapMd && alias === "/sitemap.md")
+    return [{ index, field: "alias", message: 'must not use the module-owned markdown route "/sitemap.md"' }];
+  return [];
+}
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -51,7 +70,7 @@ function validateCommonFields(skill, index) {
   }
   return issues;
 }
-function validateSkill(skill, index) {
+function validateSkill(skill, index, sitemapMd) {
   if (!isRecord(skill)) {
     return [{ index, field: "source", message: "must be a local or external skill entry" }];
   }
@@ -59,6 +78,7 @@ function validateSkill(skill, index) {
   if (skill.source === "local") {
     if (typeof skill.file !== "string" || skill.file.trim().length === 0)
       issues.push({ index, field: "file", message: "must be a non-empty path relative to the Nuxt root directory" });
+    issues.push(...validateAlias(skill.alias, index, sitemapMd));
     return issues;
   }
   if (skill.source === "external") {
@@ -83,33 +103,25 @@ function resolveExternalEntry(skill) {
     digest: skill.digest
   };
 }
-function parseLocalSkillMetadata(content, skill, index) {
+function readSkillFrontmatter(content) {
   const match = content.match(/^\uFEFF?---[\t ]*\r?\n([\s\S]*?)\r?\n---[\t ]*(?:\r?\n|$)/);
-  if (!match?.[1]) {
-    return [{
-      index,
-      field: "file",
-      message: "must contain YAML frontmatter with name and description fields"
-    }];
-  }
+  if (!match?.[1])
+    return { _tag: "Err", message: "must contain YAML frontmatter with name and description fields" };
   const document = parseDocument(match[1], { prettyErrors: false });
-  if (document.errors.length > 0) {
-    return [{
-      index,
-      field: "file",
-      message: `contains invalid YAML frontmatter: ${document.errors[0]?.message || "unknown YAML error"}`
-    }];
-  }
+  if (document.errors.length > 0)
+    return { _tag: "Err", message: `contains invalid YAML frontmatter: ${document.errors[0]?.message || "unknown YAML error"}` };
   const metadata = document.toJS();
-  if (!isRecord(metadata)) {
-    return [{
-      index,
-      field: "file",
-      message: "frontmatter must be a YAML mapping with name and description fields"
-    }];
-  }
+  if (!isRecord(metadata))
+    return { _tag: "Err", message: "frontmatter must be a YAML mapping with name and description fields" };
+  return { _tag: "Ok", metadata, hasBody: content.slice(match[0].length).trim().length > 0 };
+}
+function parseLocalSkillMetadata(content, skill, index) {
+  const frontmatter = readSkillFrontmatter(content);
+  if (frontmatter._tag === "Err")
+    return [{ index, field: "file", message: frontmatter.message }];
+  const { metadata } = frontmatter;
   const issues = [];
-  if (!content.slice(match[0].length).trim()) {
+  if (!frontmatter.hasBody) {
     issues.push({
       index,
       field: "file",
@@ -174,7 +186,7 @@ async function resolveLocalEntry(skill, index, rootDir) {
           issues: metadataIssues
         };
       }
-      const route = skillRoute(skill.name);
+      const routes = [skillRoute(skill.name), ...aliasesOf(skill)];
       const digest = `sha256:${createHash("sha256").update(content).digest("hex")}`;
       return {
         _tag: "Resolved",
@@ -185,7 +197,7 @@ async function resolveLocalEntry(skill, index, rootDir) {
           url: skillUrl(skill.name),
           digest
         },
-        route,
+        routes,
         content: text
       };
     });
@@ -198,40 +210,57 @@ async function resolveLocalEntry(skill, index, rootDir) {
     }]
   }));
 }
-async function resolveAgentSkillsConfig(config, rootDir) {
+async function resolveAgentSkillsConfig(config, rootDir, options = {}) {
   if (config === false || config === void 0)
     return { _tag: "Disabled" };
-  if (!isRecord(config) || !Array.isArray(config.skills)) {
+  if (!isRecord(config) || config.skills !== void 0 && !Array.isArray(config.skills)) {
     return {
       _tag: "Invalid",
-      issues: [{ field: "agentSkills", message: "must contain a skills array" }]
+      issues: [{ field: "agentSkills", message: "skills must be an array when set" }]
     };
   }
-  const issues = config.skills.flatMap((skill, index) => validateSkill(skill, index));
+  const configuredSkills = config.skills ?? [];
+  if (configuredSkills.length === 0)
+    return { _tag: "Disabled" };
+  const sitemapMd = options.sitemapMd !== false;
+  const issues = configuredSkills.flatMap((skill, index) => validateSkill(skill, index, sitemapMd));
   const seenNames = /* @__PURE__ */ new Set();
-  for (const [index, skill] of config.skills.entries()) {
+  const seenAliases = /* @__PURE__ */ new Set();
+  for (const [index, skill] of configuredSkills.entries()) {
     if (!isRecord(skill) || typeof skill.name !== "string" || seenNames.has(skill.name)) {
       if (isRecord(skill) && typeof skill.name === "string" && seenNames.has(skill.name))
         issues.push({ index, field: "name", message: `duplicates the skill name "${skill.name}"` });
       continue;
     }
     seenNames.add(skill.name);
+    for (const alias of aliasesOf(skill)) {
+      if (seenAliases.has(alias))
+        issues.push({ index, field: "alias", message: `duplicates the alias "${alias}"` });
+      seenAliases.add(alias);
+    }
   }
   if (issues.length > 0)
     return { _tag: "Invalid", issues };
-  const skills = config.skills;
+  const skills = configuredSkills;
   const resolved = await Promise.all(skills.map((skill, index) => skill.source === "local" ? resolveLocalEntry(skill, index, rootDir) : Promise.resolve({ _tag: "Resolved", entry: resolveExternalEntry(skill) })));
   const fileIssues = resolved.flatMap((result) => result._tag === "Invalid" ? result.issues : []);
   if (fileIssues.length > 0)
     return { _tag: "Invalid", issues: fileIssues };
   const entries = [];
   const localArtifacts = {};
+  const links = [];
   for (const result of resolved) {
     if (result._tag !== "Resolved")
       continue;
     entries.push(result.entry);
-    if ("route" in result)
-      localArtifacts[result.route] = result.content;
+    if ("routes" in result) {
+      for (const route of result.routes)
+        localArtifacts[route] = result.content;
+      const [alias] = result.routes.slice(1).sort((a, b) => a.length - b.length);
+      links.push({ name: result.entry.name, description: result.entry.description, href: alias ?? result.routes[0] });
+    } else {
+      links.push({ name: result.entry.name, description: result.entry.description, href: result.entry.url });
+    }
   }
   return {
     _tag: "Enabled",
@@ -239,8 +268,88 @@ async function resolveAgentSkillsConfig(config, rootDir) {
       $schema: AGENT_SKILLS_SCHEMA,
       skills: entries
     },
-    localArtifacts
+    localArtifacts,
+    links
+  };
+}
+function toPosix(path) {
+  return path.split(sep).join("/");
+}
+async function discoverAgentSkills(options) {
+  const dir = options.dir.replace(/^\.?\/+/, "").replace(/\/+$/, "");
+  const skills = [];
+  const issues = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const scanDir of options.scanDirs) {
+    const base = resolve(scanDir, dir);
+    if (!isWithinDirectory(options.rootDir, base) && base !== options.rootDir)
+      continue;
+    const entries = await readdir(base, { withFileTypes: true }).catch(() => {
+      return [];
+    });
+    for (const entry of entries.filter((entry2) => entry2.isDirectory()).sort((a, b) => a.name.localeCompare(b.name))) {
+      if (seen.has(entry.name))
+        continue;
+      const file = join(base, entry.name, "SKILL.md");
+      const content = await readFile(file, "utf8").catch(() => {
+        return null;
+      });
+      if (content === null)
+        continue;
+      const relativeFile = toPosix(relative(options.rootDir, file));
+      const frontmatter = readSkillFrontmatter(content);
+      if (frontmatter._tag === "Err") {
+        issues.push({ field: "file", message: `${relativeFile} ${frontmatter.message}` });
+        continue;
+      }
+      const { name, description } = frontmatter.metadata;
+      if (name !== entry.name) {
+        issues.push({ field: "name", message: `${relativeFile} frontmatter name "${String(name)}" must equal its directory name "${entry.name}"` });
+        continue;
+      }
+      if (typeof description !== "string" || description.length === 0) {
+        issues.push({ field: "description", message: `${relativeFile} frontmatter must contain a description` });
+        continue;
+      }
+      seen.add(entry.name);
+      skills.push({
+        source: "local",
+        name: entry.name,
+        description,
+        file: relativeFile,
+        alias: `/${dir}/${entry.name}/SKILL.md`
+      });
+    }
+  }
+  return { skills, issues };
+}
+function mergeAgentSkills(discovered, configured) {
+  const overridden = new Set(configured.map((skill) => skill.name));
+  return [...discovered.filter((skill) => !overridden.has(skill.name)), ...configured];
+}
+function applyRootAlias(skills, root) {
+  if (root === false)
+    return { _tag: "Ok", skills: [...skills] };
+  const locals = skills.filter((skill) => skill.source === "local");
+  const target = root === void 0 ? locals.length === 1 ? locals[0] : void 0 : locals.find((skill) => skill.name === root);
+  if (root !== void 0 && !target)
+    return { _tag: "Invalid", issues: [{ field: "root", message: `names no local skill: "${root}"` }] };
+  if (!target || aliasesOf(target).includes(ROOT_SKILL_ALIAS))
+    return { _tag: "Ok", skills: [...skills] };
+  return {
+    _tag: "Ok",
+    skills: skills.map((skill) => skill === target ? { ...skill, alias: [...aliasesOf(skill), ROOT_SKILL_ALIAS] } : skill)
   };
 }
+async function prepareAgentSkills(config, options) {
+  if (config.dir !== void 0 && config.dir !== false && typeof config.dir !== "string")
+    return { _tag: "Invalid", issues: [{ field: "dir", message: "must be a string or false when set" }] };
+  if (config.skills !== void 0 && !Array.isArray(config.skills))
+    return { _tag: "Invalid", issues: [{ field: "agentSkills", message: "skills must be an array when set" }] };
+  const discovered = config.dir === false ? { skills: [], issues: [] } : await discoverAgentSkills({ rootDir: options.rootDir, scanDirs: options.scanDirs, dir: config.dir ?? "skills" });
+  if (discovered.issues.length > 0)
+    return { _tag: "Invalid", issues: discovered.issues };
+  return { _tag: "Ok", skills: mergeAgentSkills(discovered.skills, config.skills ?? []) };
+}
 
-export { AGENT_SKILLS_SCHEMA, resolveAgentSkillsConfig };
+export { AGENT_SKILLS_SCHEMA, ROOT_SKILL_ALIAS, applyRootAlias, discoverAgentSkills, mergeAgentSkills, prepareAgentSkills, readSkillFrontmatter, resolveAgentSkillsConfig };

package/dist/chunks/prerender.mjs

@@ -5,7 +5,7 @@ import { colorize } from 'consola/utils';
 import { resolveLocaleFromRoute } from 'nuxtseo-shared/i18n-runtime';
 import { collectSitemap } from 'sitemapd/parse';
 import { withLeadingSlash, joinURL, withBase } from 'ufo';
-import { l as logger, s as supportsNativeNodeSqlite, M as MARKDOWN_LINK_AVAILABILITY_FILE } from '../shared/nuxt-ai-ready.BVWXwmUS.mjs';
+import { l as logger, s as supportsNativeNodeSqlite, M as MARKDOWN_LINK_AVAILABILITY_FILE } from '../shared/nuxt-ai-ready.B8hPhZL9.mjs';
 import { normalizePagePath, toMarkdownPath } from '../../dist/runtime/markdown-path.js';
 import { toDeployedRoute, toLogicalRoute } from '../../dist/runtime/route-path.js';
 import { initSchema, computeContentHash, insertPage, queryAllPages, exportDbDump } from '../../dist/runtime/server/db/shared.js';

package/dist/module.d.mts

@@ -1,5 +1,5 @@
 import * as _nuxt_schema from '@nuxt/schema';
-import { LlmsTxtConfig, ContentNegotiationPolicy, ModuleOptions } from '../dist/runtime/types.js';
+import { LlmsTxtConfig, AgentSkillConfig, ContentNegotiationPolicy, ModuleOptions } from '../dist/runtime/types.js';
 export { AgentSkillConfig, AgentSkillsConfig, AgentSkillsIndex, AgentSkillsIndexEntry, ApiCatalogConfig, ApiCatalogEntry, ApiCatalogLinkTarget, ApiCatalogLinks, ExternalAgentSkillConfig, LocalAgentSkillConfig, McpServerCardConfig, ModuleOptions } from '../dist/runtime/types.js';
 import { RuntimeI18nConfig } from 'nuxtseo-shared/i18n-runtime';
 import { ResolvedWebMcpToolsConfig } from '../dist/runtime/site-tool-config.js';
@@ -73,11 +73,21 @@ interface ModuleHooks {
         sections: LlmsTxtConfig['sections'];
         notes: string[];
     }) => void | Promise<void>;
+    /**
+     * Hook called with every agent skill about to be published: the ones
+     * discovered under `agentSkills.dir` merged with `agentSkills.skills`.
+     * Mutate the array to add external entries, drop a skill, or change its
+     * aliases. The root alias is applied after this hook.
+     */
+    'ai-ready:agent-skills': (payload: {
+        skills: AgentSkillConfig[];
+    }) => void | Promise<void>;
 }
 declare module '@nuxt/schema' {
     interface NuxtHooks {
         'ai-ready:page:markdown': ModuleHooks['ai-ready:page:markdown'];
         'ai-ready:llms-txt': ModuleHooks['ai-ready:llms-txt'];
+        'ai-ready:agent-skills': ModuleHooks['ai-ready:agent-skills'];
     }
 }
 interface ModulePublicRuntimeConfig {

package/dist/module.json

@@ -4,7 +4,7 @@
     "nuxt": ">=4.0.0"
   },
   "configKey": "aiReady",
-  "version": "2.2.1",
+  "version": "2.3.0",
   "builder": {
     "@nuxt/module-builder": "1.0.3",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -7,7 +7,7 @@ import 'defu';
 import 'nuxt-site-config/kit';
 import 'nuxtseo-shared/kit';
 import 'pkg-types';
-export { m as default } from './shared/nuxt-ai-ready.BVWXwmUS.mjs';
+export { m as default } from './shared/nuxt-ai-ready.B8hPhZL9.mjs';
 import '../dist/runtime/markdown-path.js';
 import '../dist/runtime/server/utils/sitemap-md.js';
 import '../dist/runtime/server/utils/discovery-response.js';

package/dist/runtime/server/middleware/markdown.prerender.js

@@ -9,6 +9,7 @@ import { fetchRawWithEvent } from "../utils/fetch.js";
 import { buildFrontmatter } from "../utils/frontmatter.js";
 import { extractKeywords } from "../utils/keywords.js";
 import { getMarkdownRenderInfo } from "../utils/markdown-request.js";
+import { agentSkillArtifactPaths } from "../utils/negotiation-response.js";
 import { consumePrerenderedHtml } from "../utils/prerender-html.js";
 import { isSitemapMdRequest } from "../utils/sitemap-md.js";
 function extractHeadingsFromMarkdown(markdown) {
@@ -23,7 +24,7 @@ function extractHeadingsFromMarkdown(markdown) {
   return headings;
 }
 export default defineEventHandler(async (event) => {
-  if (event.path.startsWith("/.well-known/"))
+  if (event.path.startsWith("/.well-known/") || agentSkillArtifactPaths().has(event.path))
     return;
   if (!import.meta.prerender) {
     return;

package/dist/runtime/server/utils/negotiation-decision.d.ts

@@ -13,10 +13,15 @@ export interface NegotiationInput {
     request: MarkdownRequest;
     routeRule: NegotiationRouteRule;
     policy: ContentNegotiationPolicy;
+    /**
+     * Routes that already serve a Markdown file verbatim, such as an agent skill
+     * alias. They are answered by their own handler, never rendered.
+     */
+    artifactPaths?: ReadonlySet<string>;
 }
 export type NegotiationDecision = {
     _tag: 'skip';
-    reason: 'well-known' | 'internal' | 'not-a-page' | 'deferred';
+    reason: 'well-known' | 'internal' | 'artifact' | 'not-a-page' | 'deferred';
 } | {
     _tag: 'not-acceptable';
 } | {

package/dist/runtime/server/utils/negotiation-decision.js

@@ -6,6 +6,8 @@ export function resolveNegotiationDecision(input) {
   const path = withoutQuery(request.path);
   if (path.startsWith("/.well-known/"))
     return { _tag: "skip", reason: "well-known" };
+  if (input.artifactPaths?.has(path))
+    return { _tag: "skip", reason: "artifact" };
   if (request.headers[INTERNAL_HEADER])
     return { _tag: "skip", reason: "internal" };
   const negotiation = resolveContentNegotiation({ policy: input.policy, routeRule: input.routeRule });

package/dist/runtime/server/utils/negotiation-response.d.ts

@@ -3,6 +3,8 @@ import type { ModulePublicRuntimeConfig } from '../../../module.js';
 import type { RuntimeRouteContext } from './i18n.js';
 import type { NegotiationDecision, NegotiationStage } from './negotiation-decision.js';
 import { sendRedirect } from '#nuxtseo/h3';
+/** Routes an agent skill answers verbatim; negotiation must not render them. */
+export declare function agentSkillArtifactPaths(): ReadonlySet<string>;
 export type LinkUrlResolver = (path: string) => string;
 export interface NegotiationContext {
     config: ModulePublicRuntimeConfig;

package/dist/runtime/server/utils/negotiation-response.js

@@ -1,4 +1,5 @@
 import { createNitroRouteRuleMatcher } from "nuxtseo-shared/server";
+import { localAgentSkillArtifacts } from "#ai-ready-virtual/agent-skills.mjs";
 import { appendHeader, createError, getRequestURL, getResponseHeader, sendRedirect, setHeader } from "#nuxtseo/h3";
 import { useRuntimeConfig } from "#nuxtseo/nitro";
 import { withSiteUrl } from "#site-config/server/composables/utils";
@@ -11,6 +12,11 @@ import { buildLinkHeader } from "./link-header.js";
 import { toMarkdownRequest } from "./markdown-request.js";
 import { resolveNegotiationDecision } from "./negotiation-decision.js";
 const APPLIED_KEY = "nuxt-ai-ready:negotiation-applied";
+let artifactPaths;
+export function agentSkillArtifactPaths() {
+  artifactPaths ??= new Set(Object.keys(localAgentSkillArtifacts));
+  return artifactPaths;
+}
 export function setLinkHeader(event, ctx, variant) {
   setHeader(event, "link", buildLinkHeader(ctx.path, variant, ctx.config, ctx.resolveUrl, ctx.routeContext));
 }
@@ -74,7 +80,8 @@ export function decideNegotiation(event, stage) {
     stage,
     request: toMarkdownRequest(event),
     routeRule: getRouteRuleMatcher(runtimeConfig)(event.path),
-    policy: config.contentNegotiation
+    policy: config.contentNegotiation,
+    artifactPaths: agentSkillArtifactPaths()
   });
 }
 export async function applyNegotiation(event, decision) {

package/dist/runtime/types.d.ts

@@ -46,6 +46,13 @@ export interface LocalAgentSkillConfig {
     description: string;
     /** SKILL.md path, resolved relative to the Nuxt root directory. */
     file: string;
+    /**
+     * Also serve the same bytes at these path-absolute `.md` routes, such as
+     * `/SKILL.md`. Content negotiation leaves the routes alone, so the response
+     * is the file itself with no generated frontmatter. The discovery index
+     * keeps advertising the `.well-known` artifact URL.
+     */
+    alias?: string | string[];
 }
 export interface ExternalAgentSkillConfig {
     /** Advertise an artifact already hosted at a URL. */
@@ -63,7 +70,29 @@ export interface ExternalAgentSkillConfig {
 }
 export type AgentSkillConfig = LocalAgentSkillConfig | ExternalAgentSkillConfig;
 export interface AgentSkillsConfig {
-    skills: AgentSkillConfig[];
+    /**
+     * Explicit entries. Discovered skills are merged in first; an explicit entry
+     * with the same name replaces the discovered one.
+     */
+    skills?: AgentSkillConfig[];
+    /**
+     * Directory scanned for `<name>/SKILL.md` in the project root and in every
+     * layer inside it. Each match is published as a local skill and also served
+     * at `/<dir>/<name>/SKILL.md`, mirroring the repository path. `false` turns
+     * discovery off.
+     * @default 'skills'
+     */
+    dir?: string | false;
+    /**
+     * Name of the local skill also served at `/SKILL.md`. Defaults to the only
+     * local skill when exactly one exists. `false` publishes no root alias.
+     */
+    root?: string | false;
+    /**
+     * Add an "Agent Skills" section to llms.txt listing every published skill.
+     * @default true
+     */
+    llmsTxt?: boolean;
 }
 export interface AgentSkillsIndexEntry {
     name: string;
@@ -231,9 +260,11 @@ export interface ModuleOptions {
         exposedTo?: string[];
     };
     /**
-     * Publish an Agent Skills Discovery v0.2.0 index and optionally host local
-     * SKILL.md artifacts under `/.well-known/agent-skills/`.
-     * @default false
+     * Publish an Agent Skills Discovery v0.2.0 index and host local SKILL.md
+     * artifacts under `/.well-known/agent-skills/`. Skills in `skills/<name>/SKILL.md`
+     * are discovered and published without configuration; nothing is published
+     * when none exist. Set `false` to turn the feature off.
+     * @default {}
      */
     agentSkills?: false | AgentSkillsConfig;
     /**

package/dist/shared/{nuxt-ai-ready.BVWXwmUS.mjs → nuxt-ai-ready.B8hPhZL9.mjs}

@@ -3,7 +3,7 @@ import { readFile, mkdir, writeFile, access } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import { dirname, basename, join } from 'node:path';
 import { hasNuxtModule, useNuxt, useLogger, addTypeTemplate, addTemplate, defineNuxtModule, createResolver, addServerImports, addServerPlugin, addServerHandler, extendRouteRules, addPlugin, addImports } from '@nuxt/kit';
-import defu from 'defu';
+import defu$1, { defu } from 'defu';
 import { installNuxtSiteConfig, useSiteConfig, withSiteUrl } from 'nuxt-site-config/kit';
 import { resolveNuxtContentVersion, renderNitroTypeAugmentations, setupNitroRuntimeCompatibility } from 'nuxtseo-shared/kit';
 import { readPackageJSON, resolvePackageJSON } from 'pkg-types';
@@ -864,7 +864,7 @@ function ensureStaticHeader(contents, route, name, value) {
   return `${contents.slice(0, blockStart)}${prefix}  ${name}: ${value}${eol}${contents.slice(blockStart)}`;
 }
 const CLOUDFLARE_STATIC_HEADER_RULE_LIMIT = 100;
-const RE_EXACT_MARKDOWN_ROUTE = /^\/[^*\s]*\.md[\t ]*\r?$/;
+const RE_EXACT_MARKDOWN_ROUTE$1 = /^\/[^*\s]*\.md[\t ]*\r?$/;
 function splitHeaderBlocks(contents) {
   const blocks = [];
   let current = { route: null, text: "" };
@@ -884,7 +884,7 @@ function enforceStaticHeaderBudget(contents, limit) {
   const ruleCount = blocks.filter((block) => block.route !== null).length;
   if (ruleCount <= limit)
     return { contents, total: ruleCount, dropped: 0 };
-  const kept = blocks.filter((block) => block.route === null || !RE_EXACT_MARKDOWN_ROUTE.test(block.route));
+  const kept = blocks.filter((block) => block.route === null || !RE_EXACT_MARKDOWN_ROUTE$1.test(block.route));
   return {
     contents: kept.map((block) => block.text).join(""),
     total: kept.filter((block) => block.route !== null).length,
@@ -923,9 +923,13 @@ function pageRouteFromMarkdownTwin(fileName) {
     return "/";
   return isStaticMarkdownSourceRoute(pageRoute) ? pageRoute : null;
 }
-function prerenderedMarkdownHeaderRules(prerenderedRoutes, baseURL, describedby) {
+function prerenderedMarkdownHeaderRules(prerenderedRoutes, baseURL, describedby, artifactRoutes) {
+  const artifacts = new Set(artifactRoutes);
   const rules = /* @__PURE__ */ new Map();
   for (const entry of prerenderedRoutes) {
+    if (entry.route !== void 0 && artifacts.has(entry.route) || entry.fileName !== void 0 && artifacts.has(entry.fileName)) {
+      continue;
+    }
     const pageRoute = pageRouteFromMarkdownTwin(entry.fileName);
     if (pageRoute === null)
       continue;
@@ -942,6 +946,34 @@ function prerenderedMarkdownHeaderRules(prerenderedRoutes, baseURL, describedby)
   }
   return [...rules.values()];
 }
+const RE_EXACT_MARKDOWN_ROUTE = /^\/[^*:\s]*\.md$/;
+function isStaticHeaderRouteRule([, rule]) {
+  return Boolean(rule && "headers" in rule && rule.headers);
+}
+function planStaticMarkdownHeaderRules(routeRules, rules, limit) {
+  if (limit === null)
+    return { _tag: "apply", rules };
+  const entries = Object.entries(routeRules).filter(isStaticHeaderRouteRule);
+  const registeredMarkdown = entries.map(([route]) => route).filter((route) => RE_EXACT_MARKDOWN_ROUTE.test(route));
+  const other = entries.length - registeredMarkdown.length;
+  const markdown = /* @__PURE__ */ new Set([...registeredMarkdown, ...rules.map((rule) => rule.route)]);
+  const total = other + markdown.size;
+  if (total <= limit)
+    return { _tag: "apply", rules };
+  return { _tag: "skip", drop: registeredMarkdown, total, dropped: markdown.size };
+}
+function applyStaticMarkdownHeaderPlan(routeRules, plan) {
+  if (plan._tag === "skip") {
+    for (const route of plan.drop) {
+      const rule = routeRules[route];
+      if (rule)
+        rule.headers = void 0;
+    }
+    return;
+  }
+  for (const { route, headers } of plan.rules)
+    routeRules[route] = defu({ headers }, routeRules[route]);
+}
 
 const DEFAULT_MAX_OUTPUT_CHARS = 1500;
 const DEFAULT_LIST_LIMIT = 20;
@@ -1111,11 +1143,35 @@ const module$1 = defineNuxtModule({
       logger.debug("Module is disabled, skipping setup.");
       return;
     }
-    const agentSkillsResult = config.agentSkills === false || config.agentSkills === void 0 ? { _tag: "Disabled" } : await import('../chunks/agent-skills.mjs').then(({ resolveAgentSkillsConfig }) => resolveAgentSkillsConfig(config.agentSkills, nuxt.options.rootDir));
-    if (agentSkillsResult._tag === "Invalid") {
-      const details = agentSkillsResult.issues.map((issue) => `${issue.index === void 0 ? "agentSkills" : `agentSkills.skills[${issue.index}]`}.${issue.field}: ${issue.message}`).join("\n");
-      throw new Error(`[nuxt-ai-ready] Invalid Agent Skills configuration:
+    const agentSkillsConfig = config.agentSkills === false ? false : config.agentSkills ?? {};
+    const agentSkillsError = (issues) => {
+      const details = issues.map((issue) => `${issue.index === void 0 ? "agentSkills" : `agentSkills.skills[${issue.index}]`}.${issue.field}: ${issue.message}`).join("\n");
+      return new Error(`[nuxt-ai-ready] Invalid Agent Skills configuration:
 ${details}`);
+    };
+    let agentSkillsResult = { _tag: "Disabled" };
+    if (agentSkillsConfig !== false) {
+      const { applyRootAlias, prepareAgentSkills, resolveAgentSkillsConfig } = await import('../chunks/agent-skills.mjs');
+      const prepared = await prepareAgentSkills(agentSkillsConfig, {
+        rootDir: nuxt.options.rootDir,
+        scanDirs: nuxt.options._layers.map((layer) => layer.config.rootDir ?? layer.cwd)
+      });
+      if (prepared._tag === "Invalid")
+        throw agentSkillsError(prepared.issues);
+      const payload = { skills: prepared.skills };
+      await nuxt.callHook("ai-ready:agent-skills", payload);
+      const rooted = applyRootAlias(payload.skills, agentSkillsConfig.root);
+      if (rooted._tag === "Invalid")
+        throw agentSkillsError(rooted.issues);
+      agentSkillsResult = await resolveAgentSkillsConfig(
+        { ...agentSkillsConfig, skills: rooted.skills },
+        nuxt.options.rootDir,
+        { sitemapMd: config.sitemapMd !== false }
+      );
+      if (agentSkillsResult._tag === "Invalid")
+        throw agentSkillsError(agentSkillsResult.issues);
+      if (agentSkillsResult._tag === "Enabled")
+        logger.debug(`Publishing ${agentSkillsResult.index.skills.length} agent skill(s): ${agentSkillsResult.index.skills.map((skill) => skill.name).join(", ")}`);
     }
     const mcpServerCardResult = parseMcpServerCardConfig(config.mcpServerCard);
     if (mcpServerCardResult._tag === "Invalid")
@@ -1291,6 +1347,18 @@ ${details}`);
         }
       ]
     });
+    if (agentSkillsResult._tag === "Enabled" && agentSkillsConfig !== false && agentSkillsConfig.llmsTxt !== false) {
+      const indexUrl = withSiteUrl(AGENT_SKILLS_INDEX_ROUTE.slice(1), { withBase: true });
+      defaultLlmsTxtSections.push({
+        title: "Agent Skills",
+        description: `Skills an agent can install from this site. The index at ${indexUrl} carries a sha256 digest for each one.`,
+        links: agentSkillsResult.links.map((link) => ({
+          title: link.name,
+          href: link.href.startsWith("/") ? withSiteUrl(link.href.slice(1), { withBase: true }) : new URL(link.href, indexUrl).href,
+          description: link.description
+        }))
+      });
+    }
     const mergedLlmsTxt = config.llmsTxt ? {
       markdownLinks: config.llmsTxt.markdownLinks ?? false,
       sections: [
@@ -1658,7 +1726,7 @@ export const logger = createModuleLogger('nuxt-ai-ready', ${!!config.debug})
       mdreamOptions: config.mdreamOptions || {},
       sitemapMd: config.sitemapMd !== false,
       describedby: config.describedby !== false,
-      markdownCacheHeaders: defu(config.markdownCacheHeaders, {
+      markdownCacheHeaders: defu$1(config.markdownCacheHeaders, {
         maxAge: 3600,
         swr: true
       }),
@@ -1814,14 +1882,24 @@ export const logger = createModuleLogger('nuxt-ai-ready', ${!!config.debug})
       });
     }
     nuxt.hooks.hook("nitro:build:before", (nitro) => {
+      const isCloudflarePreset = String(nitro.options.preset || "").startsWith("cloudflare");
       nitro.hooks.hook("prerender:done", () => {
-        for (const { route, headers } of prerenderedMarkdownHeaderRules(
-          nitro._prerenderedRoutes || [],
-          staticBaseURL,
-          config.describedby !== false
-        )) {
-          nitro.options.routeRules[route] = defu({ headers }, nitro.options.routeRules[route]);
+        const plan = planStaticMarkdownHeaderRules(
+          nitro.options.routeRules,
+          prerenderedMarkdownHeaderRules(
+            nitro._prerenderedRoutes || [],
+            staticBaseURL,
+            config.describedby !== false,
+            agentSkillsResult._tag === "Enabled" ? Object.keys(agentSkillsResult.localArtifacts) : []
+          ),
+          isCloudflarePreset ? CLOUDFLARE_STATIC_HEADER_RULE_LIMIT : null
+        );
+        if (plan._tag === "skip") {
+          applyStaticMarkdownHeaderPlan(nitro.options.routeRules, plan);
+          logger.warn(`_headers would hold ${plan.total} rules and Cloudflare allows ${CLOUDFLARE_STATIC_HEADER_RULE_LIMIT}. Skipped the ${plan.dropped} per-page .md rules; the /*.md glob still sets the charset and describedby entries, but static markdown does not send a per-page canonical Link.`);
+          return;
         }
+        applyStaticMarkdownHeaderPlan(nitro.options.routeRules, plan);
       });
       nitro.hooks.hook("compiled", async () => {
         const headersPath = join(nitro.options.output.publicDir, "_headers");
@@ -1843,7 +1921,7 @@ export const logger = createModuleLogger('nuxt-ai-ready', ${!!config.debug})
               staticDescribedbyEntry(nitro.options.baseURL || "/")
             );
           }
-          if (String(nitro.options.preset || "").startsWith("cloudflare")) {
+          if (isCloudflarePreset) {
             const budget = enforceStaticHeaderBudget(mergedHeaders, CLOUDFLARE_STATIC_HEADER_RULE_LIMIT);
             if (budget.dropped > 0) {
               mergedHeaders = budget.contents;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nuxt-ai-ready",
   "type": "module",
-  "version": "2.2.1",
+  "version": "2.3.0",
   "description": "Best practice AI & LLM discoverability for Nuxt sites.",
   "author": {
     "name": "Harlan Wilton",