@@ -0,0 +1,215 @@
+import { existsSync } from 'node:fs'
+import { readdir, readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { addServerHandler, createResolver, defineNuxtModule, useLogger } from '@nuxt/kit'
+import { parse as parseYaml } from 'yaml'
+
+/**
+ * Skills module — exposes Anthropic Agent Skills via `.well-known/skills`.
+ *
+ * Ported from upstream docus:
+ * - `2f7861bd` feat(skills): add agent skills discovery via `.well-known`
+ * - `764329f5` feat(skills): make directory configurable via module options
+ *
+ * Skills live under `<rootDir>/<dir>/<name>/SKILL.md`, each with YAML
+ * frontmatter `{ name, description }`. Both fields are required; `name`
+ * must satisfy the Anthropic Agent Skills spec
+ * (`/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/`, max 64 chars) and `description`
+ * is capped at 200 chars.
+ */
+
+export interface ModuleOptions {
+  /**
+   * Directory (relative to project rootDir) that contains skill folders.
+   * Each subfolder is treated as a skill and must contain a `SKILL.md` file.
+   * @default 'skills'
+   */
+  dir?: string
+}
+
+interface SkillEntry {
+  name: string
+  description: string
+  files: string[]
+}
+
+const SKILL_NAME_REGEX = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/
+const MAX_NAME_LENGTH = 64
+const MAX_DESCRIPTION_LENGTH = 200
+
+export default defineNuxtModule<ModuleOptions>({
+  meta: {
+    name: 'skills',
+    configKey: 'skills',
+  },
+  defaults: {
+    dir: 'skills',
+  },
+  async setup(options, nuxt) {
+    const log = useLogger('docs-skills')
+    const dir = options.dir ?? 'skills'
+    const skillsDir = join(nuxt.options.rootDir, dir)
+
+    if (!existsSync(skillsDir)) {
+      return
+    }
+
+    const catalog = await scanSkills(skillsDir, log)
+    if (!catalog.length) {
+      return
+    }
+
+    log.info(
+      `Found ${catalog.length} agent skill${catalog.length > 1 ? 's' : ''}: ${catalog.map(s => s.name).join(', ')}`,
+    )
+
+    // Expose the catalog at runtime so the index route doesn't need to re-scan
+    // the source tree (which may be unavailable in serverless deployments).
+    nuxt.options.runtimeConfig.skills = { catalog }
+
+    const { resolve } = createResolver(import.meta.url)
+
+    nuxt.hook('nitro:config', (nitroConfig) => {
+      // Ship the skill files as Nitro server assets so they are readable
+      // from runtime handlers via `useStorage('assets:skills')`.
+      nitroConfig.serverAssets ||= []
+      nitroConfig.serverAssets.push({ baseName: 'skills', dir: skillsDir })
+
+      // Register every skill file path so static builds prerender them.
+      nitroConfig.prerender ||= {}
+      nitroConfig.prerender.routes ||= []
+      nitroConfig.prerender.routes.push('/.well-known/skills/index.json')
+      for (const skill of catalog) {
+        for (const file of skill.files) {
+          nitroConfig.prerender.routes.push(`/.well-known/skills/${skill.name}/${file}`)
+        }
+      }
+    })
+
+    addServerHandler({
+      route: '/.well-known/skills/index.json',
+      handler: resolve('./runtime/server/routes/.well-known/skills/index.get'),
+    })
+
+    addServerHandler({
+      route: '/.well-known/skills/**',
+      handler: resolve('./runtime/server/routes/.well-known/skills/[...path].get'),
+    })
+  },
+})
+
+function parseFrontmatter(content: string): { name?: string, description?: string } | null {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/)
+  if (!match?.[1]) {
+    return null
+  }
+  try {
+    const parsed: unknown = parseYaml(match[1])
+    if (!parsed || typeof parsed !== 'object') {
+      return null
+    }
+    const obj = parsed as Record<string, unknown>
+    return {
+      name: typeof obj.name === 'string' ? obj.name : undefined,
+      description: typeof obj.description === 'string' ? obj.description : undefined,
+    }
+  }
+  catch {
+    return null
+  }
+}
+
+function validateSkillName(name: string, dirName: string, log: ReturnType<typeof useLogger>): boolean {
+  if (name.length > MAX_NAME_LENGTH) {
+    log.warn(`Skill "${name}" exceeds ${MAX_NAME_LENGTH} character limit`)
+    return false
+  }
+  if (!SKILL_NAME_REGEX.test(name) || name.includes('--')) {
+    log.warn(`Skill name "${name}" does not match the Agent Skills naming spec`)
+    return false
+  }
+  if (name !== dirName) {
+    log.warn(`Skill name "${name}" does not match directory name "${dirName}"`)
+    return false
+  }
+  return true
+}
+
+async function listFilesRecursively(dir: string, base: string = ''): Promise<string[]> {
+  const files: string[] = []
+  const entries = await readdir(dir, { withFileTypes: true })
+  for (const entry of entries) {
+    const relPath = base ? `${base}/${entry.name}` : entry.name
+    if (entry.isDirectory()) {
+      files.push(...await listFilesRecursively(join(dir, entry.name), relPath))
+    }
+    else {
+      files.push(relPath)
+    }
+  }
+  return files
+}
+
+async function scanSkills(skillsDir: string, log: ReturnType<typeof useLogger>): Promise<SkillEntry[]> {
+  const catalog: SkillEntry[] = []
+  const entries = await readdir(skillsDir, { withFileTypes: true })
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) {
+      continue
+    }
+
+    const skillDir = join(skillsDir, entry.name)
+    const skillMdPath = join(skillDir, 'SKILL.md')
+
+    if (!existsSync(skillMdPath)) {
+      continue
+    }
+
+    const content = await readFile(skillMdPath, 'utf-8')
+    const frontmatter = parseFrontmatter(content)
+
+    if (!frontmatter?.name) {
+      log.warn(`Skipping skill "${entry.name}": missing name in SKILL.md frontmatter`)
+      continue
+    }
+
+    if (!frontmatter.description) {
+      log.warn(`Skipping skill "${entry.name}": missing description in SKILL.md frontmatter`)
+      continue
+    }
+
+    if (frontmatter.description.length > MAX_DESCRIPTION_LENGTH) {
+      log.warn(
+        `Skipping skill "${entry.name}": description exceeds ${MAX_DESCRIPTION_LENGTH} character limit`,
+      )
+      continue
+    }
+
+    const name = frontmatter.name
+    if (!validateSkillName(name, entry.name, log)) {
+      continue
+    }
+
+    const allFiles = await listFilesRecursively(skillDir)
+    // Drop dot-prefixed paths (e.g. .DS_Store, .git directories).
+    const files = allFiles.filter(f => !f.split('/').some(s => s.startsWith('.')))
+    const sortedFiles = ['SKILL.md', ...files.filter(f => f !== 'SKILL.md')]
+
+    catalog.push({
+      name,
+      description: frontmatter.description,
+      files: sortedFiles,
+    })
+  }
+
+  return catalog
+}
+
+declare module 'nuxt/schema' {
+  interface RuntimeConfig {
+    skills: {
+      catalog: SkillEntry[]
+    }
+  }
+}
@@ -0,0 +1,90 @@
+const CONTENT_TYPES: Record<string, string> = {
+  '.md': 'text/markdown; charset=utf-8',
+  '.markdown': 'text/markdown; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.yaml': 'application/yaml; charset=utf-8',
+  '.yml': 'application/yaml; charset=utf-8',
+  '.txt': 'text/plain; charset=utf-8',
+  '.py': 'text/plain; charset=utf-8',
+  '.sh': 'text/plain; charset=utf-8',
+  '.bash': 'text/plain; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.cjs': 'text/javascript; charset=utf-8',
+  '.ts': 'text/plain; charset=utf-8',
+  '.tsx': 'text/plain; charset=utf-8',
+  '.jsx': 'text/plain; charset=utf-8',
+  '.html': 'text/html; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.toml': 'text/plain; charset=utf-8',
+  '.xml': 'application/xml; charset=utf-8',
+}
+
+function getContentType(path: string): string {
+  // Only consider the basename so a path like `dir.x/file` doesn't pick up
+  // an extension from a parent directory.
+  const slash = path.lastIndexOf('/')
+  const basename = slash === -1 ? path : path.slice(slash + 1)
+  const dot = basename.lastIndexOf('.')
+  if (dot === -1) return 'application/octet-stream'
+  const ext = basename.slice(dot).toLowerCase()
+  return CONTENT_TYPES[ext] || 'application/octet-stream'
+}
+
+export default defineEventHandler(async (event) => {
+  const url = getRequestURL(event)
+  const prefix = '/.well-known/skills/'
+  const idx = url.pathname.indexOf(prefix)
+
+  if (idx === -1) {
+    throw createError({ statusCode: 404, statusMessage: 'Not Found' })
+  }
+
+  let filePath: string
+  try {
+    filePath = decodeURIComponent(url.pathname.slice(idx + prefix.length))
+  }
+  catch {
+    throw createError({ statusCode: 400, statusMessage: 'Bad Request' })
+  }
+
+  // The index.json route is served by a dedicated handler — this one should
+  // never see it, but guard anyway.
+  if (!filePath || filePath === 'index.json') {
+    throw createError({ statusCode: 404, statusMessage: 'Not Found' })
+  }
+
+  // Block path traversal and dotfile access.
+  const segments = filePath.split('/')
+  if (segments.some(seg => seg === '' || seg === '..' || seg === '.' || seg.startsWith('.'))) {
+    throw createError({ statusCode: 400, statusMessage: 'Bad Request' })
+  }
+
+  const storage = useStorage('assets:skills')
+
+  // Use getItemRaw so JSON/YAML files are returned as their raw bytes/string
+  // instead of being deserialized by destr.
+  const raw = await storage.getItemRaw<unknown>(filePath)
+
+  if (raw === null || raw === undefined) {
+    throw createError({ statusCode: 404, statusMessage: 'Not Found' })
+  }
+
+  setResponseHeader(event, 'content-type', getContentType(filePath))
+  setResponseHeader(event, 'cache-control', 'public, max-age=3600')
+
+  // Return raw bytes for non-string payloads so binary files (images,
+  // archives, etc.) are served untouched. UTF-8 decoding would corrupt
+  // them and produces unnecessary overhead for text payloads.
+  if (typeof raw === 'string') {
+    return raw
+  }
+  if (raw instanceof Uint8Array) {
+    return raw
+  }
+  if (typeof Buffer !== 'undefined' && Buffer.isBuffer(raw)) {
+    return raw
+  }
+
+  throw createError({ statusCode: 404, statusMessage: 'Not Found' })
+})
@@ -0,0 +1,20 @@
+/**
+ * Returns the agent skills catalog from `runtimeConfig.skills.catalog`,
+ * which the module builds at startup. This avoids re-scanning storage and
+ * re-parsing YAML frontmatter on every request.
+ */
+export default defineEventHandler((event) => {
+  const config = useRuntimeConfig(event)
+  const catalog = (config.skills?.catalog ?? [])
+    .map(skill => ({
+      name: skill.name,
+      description: skill.description,
+      path: `/.well-known/skills/${skill.name}/SKILL.md`,
+    }))
+    .sort((a, b) => a.name.localeCompare(b.name))
+
+  setResponseHeader(event, 'content-type', 'application/json; charset=utf-8')
+  setResponseHeader(event, 'cache-control', 'public, max-age=3600')
+
+  return { skills: { catalog } }
+})
@@ -8,6 +8,7 @@ export default defineNuxtConfig({
     resolve('./modules/config'),
     resolve('./modules/css'),
     resolve('./modules/shadcn'),
+    resolve('./modules/skills'),
     '@nuxtjs/color-mode',
     '@nuxt/content',
     '@nuxt/image',
 
@@ -73,6 +73,7 @@
     "ufo": "^1.6.1",
     "unified": "^11.0.5",
     "unist-util-visit": "^5.0.0",
+    "yaml": "^2.8.2",
     "zod": "^4.2.1",
     "zod-to-json-schema": "^3.25.0"
   },