feat(skills): add .well-known/skills module

[amondnet]

Summary

Ports the agent skills discovery module from upstream docus (survey item #7 in docs/docus-upstream-changes.md). Adds a Nitro module that scans <rootDir>/skills/ for Anthropic Agent Skills and exposes them under .well-known/skills/.

Continues the porting work started in #27.

Upstream commits

• 2f7861bd feat(skills): add agent skills discovery via .well-known
• 764329f5 feat(skills): make directory configurable via module options

What's new

packages/layer/modules/skills/index.ts

A defineNuxtModule with options { dir?: string } (default 'skills', configurable via skills.dir). At setup time the module:

1. Resolves <rootDir>/<dir> and bails out if it doesn't exist.
2. Scans every subdirectory for a SKILL.md file with YAML frontmatter { name, description }.
3. Validates names against the Anthropic Agent Skills spec — /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/, max 64 chars, no --, must match the directory name. Invalid entries are skipped with a warning.
4. Registers the skills directory as a Nitro serverAsset (assets:skills) so files are accessible at runtime via storage even when the source tree is unavailable (serverless, etc.).
5. Registers every skill file path in nitro.prerender.routes for static builds.
6. Adds two server handlers via addServerHandler.

runtime/server/routes/.well-known/skills/index.get.ts

Scans the asset storage for top-level SKILL.md files, re-parses frontmatter, and returns:

{
  "skills": {
    "catalog": [
      { "name": "...", "description": "...", "path": "/.well-known/skills/.../SKILL.md" }
    ]
  }
}

Sets Cache-Control: public, max-age=3600.

runtime/server/routes/.well-known/skills/[...path].get.ts

Serves any file under a skill folder with content-type detection (.md → text/markdown, .json → application/json, .yaml/.yml → application/yaml, code files → text/plain, etc.). Blocks path traversal (.., .) and dotfile access. 404s when the file doesn't exist. Cache 1h.

Both routes use getItemRaw to avoid destr auto-parsing JSON payloads.

Configuration changes

• packages/layer/nuxt.config.ts — registers the new module after ./modules/shadcn.
• packages/layer/package.json — adds yaml as a direct dependency (matches docus' approach and keeps the module independent of @nuxt/content).

Verification

Local e2e against apps/docs:

mkdir -p apps/docs/skills/test-skill
cat > apps/docs/skills/test-skill/SKILL.md <<'SKILL'
---
name: test-skill
description: hello
---
Sample skill body.
SKILL
bun dev  # in one shell
curl -s http://localhost:3000/.well-known/skills/index.json | jq .
curl -s http://localhost:3000/.well-known/skills/test-skill/SKILL.md

Both endpoints return the expected payloads, including correct content-type headers and 404 for unknown paths. Tested .json files round-trip correctly (initial draft used getItem which would have JSON-parsed them; switched to getItemRaw).

• bun lint — clean.
• cd packages/layer && bun typecheck — no new errors (pre-existing baseline errors unchanged).

The sample skill was removed before committing.

References

• Survey: docs/docus-upstream-changes.md item fix(layer): add proper code block styling with Tailwind import #7
• Anthropic Agent Skills spec naming rules
• Previous bundle: feat(layer): port first docus upstream bundle #27

---

Summary by cubic

Adds a Nuxt module that discovers Anthropic Agent Skills in skills/ and exposes them under /.well-known/skills for discovery and static builds. The index is served from a prebuilt catalog for faster responses.

• New Features

  • Scans <rootDir>/<dir> (default skills) for SKILL.md with YAML frontmatter; requires name and description (200-char cap), validates names per the Anthropic spec, and skips invalid entries with warnings.
  • Builds a catalog at startup and serves /.well-known/skills/index.json from runtime config with { name, description, path } (cached 1h).
  • /.well-known/skills/<name>/<file> serves any skill file with content-type detection, traversal/dotfile protection, and binary-safe responses (cached 1h).
  • Registers skills as Nitro serverAssets and prerenders all skill file routes for static builds.
  • Configurable via skills.dir in nuxt.config.

• Dependencies

  • Added yaml.

^{Written for commit 207f398. Summary will update on new commits.}

[cloudflare-workers-and-pages]

Deploying docs-please with    Cloudflare Pages

Latest commit:	207f398
Status:	⚡️  Build in progress...

View logs

[gemini-code-assist]

Code Review

This pull request introduces a new skills module to expose Anthropic Agent Skills via .well-known/skills by scanning directories, parsing YAML frontmatter, and registering routes. The review feedback highlights two critical issues: first, the server handler file [...path].get.ts registered in the module is missing from the changes, which will cause runtime errors; second, the index.get.ts handler redundantly re-scans and re-parses files on every request instead of utilizing the pre-built catalog from the runtime configuration.

[cubic-dev-ai]

4 issues found across 6 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/layer/modules/skills/runtime/server/routes/.well-known/skills/[...path].get.ts">

<violation number="1" location="packages/layer/modules/skills/runtime/server/routes/.well-known/skills/[...path].get.ts:39">
P2: Guard the decode. A malformed `%` sequence here can throw a `URIError` and turn a bad request into a 500 instead of a clean 400/404.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant Build as Nuxt Build
    participant Module as Skills Module
    participant FS as File System (skills/)
    participant AssetStore as Nitro Asset Store (assets:skills)
    participant Runtime as Nuxt Runtime
    participant Client as HTTP Client

    Note over Build,Client: Build-Time: Skill Discovery & Registration

    Build->>Module: setup() with options { dir: 'skills' }
    Module->>FS: Scan subdirectories for SKILL.md
    FS-->>Module: List of skill directories

    loop For each skill subdirectory
        Module->>FS: Read SKILL.md
        FS-->>Module: Raw content with YAML frontmatter
        Module->>Module: Parse frontmatter (name, description)
        alt Invalid name (spec violation, max 64 chars, dir mismatch)
            Module->>Module: Log warning, skip skill
        else Valid skill
            Module->>FS: Recursively list skill files
            FS-->>Module: File list (filtered, dotfiles excluded)
            Module->>Module: Build catalog entry { name, description, files }
        end
    end

    alt No skills directory or empty catalog
        Module->>Build: Return early, no routes registered
    else Skills found
        Module->>Build: Set runtimeConfig.skills.catalog
        Module->>Build: Register serverAsset 'skills' -> skillsDir
        Module->>Build: Add prerender routes (index.json + all skill files)

        Module->>Build: addServerHandler('/.well-known/skills/index.json')
        Module->>Build: addServerHandler('/.well-known/skills/**')
        Build-->>Module: Handlers registered
    end

    Note over Build,Client: Runtime: Request Handling

    Client->>Runtime: GET /.well-known/skills/index.json
    Runtime->>AssetStore: getKeys() via assets:skills
    AssetStore-->>Runtime: All storage keys (skill:SKILL.md pairs)
    Runtime->>Runtime: Filter top-level SKILL.md keys
    loop For each top-level skill
        Runtime->>AssetStore: getItemRaw('skill:SKILL.md')
        AssetStore-->>Runtime: Raw file content
        Runtime->>Runtime: Parse YAML frontmatter, validate name
        alt Invalid (missing description, bad name)
            Runtime->>Runtime: Log warning, skip entry
        else Valid
            Runtime->>Runtime: Add to catalog { name, description, path }
        end
    end
    Runtime-->>Client: 200 JSON { skills: { catalog: [...] } }
    Note over Runtime: Cache-Control: public, max-age=3600

    Client->>Runtime: GET /.well-known/skills/<name>/<file>
    Runtime->>Runtime: Extract path from URL
    alt Path traversal detected (.., ., dotfiles) or empty/index.json
        Runtime-->>Client: 400 Bad Request
    else Valid path
        Runtime->>AssetStore: getItemRaw('<name>:<file>')
        alt File not found (null/undefined)
            AssetStore-->>Runtime: null
            Runtime-->>Client: 404 Not Found
        else File found
            AssetStore-->>Runtime: Raw bytes or string
            Runtime->>Runtime: Convert to string, detect content-type
            Runtime-->>Client: 200 with file content + content-type header
            Note over Runtime: Cache-Control: public, max-age=3600
        end
    end

Loading

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud