This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:

CI run failed: build logs

Review Summary

This PR introduces static MCP-facing Cloudflare Skills artifacts served from /.well-known/mcp/skills/, and updates the Agents MCP documentation to emphasize the Cloudflare API MCP server as the default choice.

What changed

• New Astro API route (src/pages/.well-known/mcp/skills/[...path].ts): SSG endpoint that exposes an SEP-style index.json, a .tree.json manifest, and direct skill file resources backed by the downloaded skills/ bundle.
• New utilities (src/util/cloudflare-skills.ts): Parses skill directories, validates frontmatter (name must match directory), computes SHA-256 digests, and assembles the publication index/tree structures. Includes a new Node test suite (cloudflare-skills.node.test.ts).
• Docs update (servers-for-cloudflare/index.mdx): Adds guidance to use the Cloudflare API MCP server by default, and positions product-specific servers as specialized options.
• Repo config updates: Adds skills/ to .gitignore (root-only), tsconfig.json exclude, eslint.config.js ignore, and sets Content-Type headers in public/_headers for the new well-known paths.

Suggested labels

agents, enhancement, documentation

Issues to address before merge

🔴 Blocking: Missing yaml dependency

src/util/cloudflare-skills.ts imports YAML from "yaml", but yaml is not declared in package.json. With pnpm's strict dependency resolution, this causes both pnpm run check and pnpm run test to fail in this branch.

src/util/cloudflare-skills.ts:12:18 - error ts(2307): Cannot find module 'yaml' or its corresponding type declarations.

Fix: Add yaml to devDependencies in package.json.

🟡 Maintainers should verify

• Documentation checklist is unchecked. The PR body leaves the style-guide checkbox unticked. The content reads well, but please confirm before merge.

Inline review comments

src/util/cloudflare-skills.ts

Lines 125–157 — readability of getMimeType
The deeply nested ternary chain is hard to scan and easy to break. Consider replacing it with a Map or plain object lookup:

const MIME_TYPES: Record<string, string> = {
  ".md": "text/markdown",
  ".mdc": "text/markdown",
  ".json": "application/json",
  // …
};

function getMimeType(path: string) {
  const mimeType = MIME_TYPES[extname(path).toLowerCase()] ?? "application/octet-stream";
  return TEXT_MIME_TYPES.has(mimeType) ? `${mimeType}; charset=utf-8` : mimeType;
}

Line 228 — skills/ directory may not exist
If prebuild hasn't run or the fetch fails, readdir(root) throws an opaque ENOENT. Consider catching that and re-throwing with a helpful message, e.g. "skills/ directory not found. Run 'pnpm run prebuild' to fetch the Cloudflare Skills bundle."

Lines 21–23 (src/pages/.well-known/mcp/skills/[...path].ts) — cacheHeaders are ignored in production
In Astro SSG, GET is only invoked at build time; the returned headers are discarded and only the body is written to disk. The _headers file correctly sets Content-Type, but if you intended to control caching, add a Cache-Control rule to public/_headers instead.

src/util/cloudflare-skills.node.test.ts

Missing edge-case coverage
The tests validate happy path and frontmatter/directory name mismatch. Consider adding coverage for:

• Nested skills rejection (the Nested skills are not supported error at line 240 of the implementation).
• Missing or malformed frontmatter (the must start with YAML frontmatter and must include name and description frontmatter errors).
• Empty skills/ directory behavior.

public/_headers

No format issues. The * wildcard in /.well-known/mcp/skills/*/SKILL.md is correct for top-level skill directories; it will match cloudflare/SKILL.md but not nested paths, which aligns with the flat skill structure enforced by the code.

Overall: The architecture is clean and the docs changes are helpful. The only hard blocker is the missing yaml dependency. Once that's added and CI passes, this looks good to merge.

github run

Hey there, we've marked this pull request as stale because there's no recent activity on it. This label helps us identify PRs that might need updates (or to be closed out by our team if no longer relevant).