@farming-labs/theme 0.1.38 → 0.1.41

package/dist/docs-api.d.mts

@@ -64,6 +64,7 @@ interface DocsMCPAPIOptions {
  * - **GET  ?query=…**        → full-text search
  * - **GET  ?format=llms**     → llms.txt (concise page listing)
  * - **GET  ?format=llms-full** → llms-full.txt (full page content)
+ * - **GET  ?format=skill**    → skill.md
  * - **POST**                  → AI-powered chat with RAG
  *
  * @example
@@ -82,7 +83,7 @@ interface DocsMCPAPIOptions {
  */
 declare function createDocsAPI(options?: DocsAPIOptions): {
   /**
-   * GET handler — search, llms.txt, or llms-full.txt depending on query params.
+   * GET handler — search, markdown, llms.txt, llms-full.txt, or skill.md.
    */
   GET(request: Request): Promise<Response>;
   /**

package/dist/docs-api.mjs

@@ -13,6 +13,7 @@ import { createDocsMcpHttpHandler, createFilesystemDocsMcpSource, resolveDocsMcp
 * A single route handler that serves **both** search and AI chat:
 *
 * - `GET  /api/docs?query=…` → full-text search over indexed MDX pages
+* - `GET  /api/docs?format=skill` → skill.md for agent discovery
 * - `POST /api/docs` → RAG-powered "Ask AI" (searches relevant docs,
 *   then streams an LLM response using the docs as context)
 *
@@ -43,6 +44,8 @@ const DEFAULT_LLMS_TXT_ROUTE = "/llms.txt";
 const DEFAULT_LLMS_FULL_TXT_ROUTE = "/llms-full.txt";
 const DEFAULT_LLMS_TXT_WELL_KNOWN_ROUTE = "/.well-known/llms.txt";
 const DEFAULT_LLMS_FULL_TXT_WELL_KNOWN_ROUTE = "/.well-known/llms-full.txt";
+const DEFAULT_SKILL_MD_ROUTE = "/skill.md";
+const DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE = "/.well-known/skill.md";
 const DEFAULT_AGENT_FEEDBACK_ROUTE = "/api/docs/agent/feedback";
 const DEFAULT_AGENT_FEEDBACK_PAYLOAD_SCHEMA = {
 	type: "object",
@@ -159,6 +162,11 @@ function resolveAgentSpecRequest(url) {
 	const pathname = normalizeUrlPath(url.pathname);
 	return pathname === DEFAULT_AGENT_SPEC_ROUTE || pathname === DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE || pathname === DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE;
 }
+function resolveSkillRequest(url) {
+	const pathname = normalizeUrlPath(url.pathname);
+	if (pathname === DEFAULT_SKILL_MD_ROUTE || pathname === DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE) return true;
+	return url.searchParams.get("format")?.trim() === "skill";
+}
 function isSearchEnabled(search) {
 	if (search === false) return false;
 	if (search && typeof search === "object" && search.enabled === false) return false;
@@ -237,6 +245,11 @@ function buildAgentSpec({ origin, entry, i18n, search, mcp, feedback, llms }) {
 		},
 		skills: {
 			enabled: true,
+			file: "skill.md",
+			route: DEFAULT_SKILL_MD_ROUTE,
+			wellKnown: DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE,
+			api: `${DEFAULT_DOCS_API_ROUTE}?format=skill`,
+			generatedFallback: true,
 			registry: "skills.sh",
 			install: "npx skills add farming-labs/docs",
 			recommended: [{
@@ -820,6 +833,53 @@ function renderMarkdownDocument(page) {
 	lines.push("", page.agentFallbackRawContent ?? page.rawContent ?? page.content);
 	return lines.join("\n");
 }
+function renderSkillDocument({ origin, entry, search, mcp, feedback, llms }) {
+	const normalizedEntry = normalizePathSegment(entry) || "docs";
+	const siteTitle = compactSkillText(llms.siteTitle ?? "Documentation");
+	const siteDescription = llms.siteDescription ? compactSkillText(llms.siteDescription) : void 0;
+	const searchEnabled = isSearchEnabled(search);
+	const lines = [
+		"---",
+		"name: docs",
+		`description: ${toYamlString(truncateSkillDescription(`Use ${siteTitle} through markdown routes, llms.txt, agent discovery, search, and MCP when available.`))}`,
+		"---",
+		"",
+		`# ${siteTitle} Skill`,
+		"",
+		`Base URL: ${origin}`
+	];
+	if (siteDescription) lines.push(`Description: ${siteDescription}`);
+	lines.push("", "## When To Use", "Use this skill when you need to read or implement against this documentation site.", "", "## Start Here", `- Fetch ${DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE}; fall back to ${DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE} or ${DEFAULT_AGENT_SPEC_ROUTE}.`, `- Fetch /${normalizedEntry}.md for the root docs page.`, `- Fetch /${normalizedEntry}/{slug}.md for page-specific context.`, "- You can also request text/markdown from normal page URLs.");
+	if (searchEnabled) lines.push(`- Search with ${DEFAULT_DOCS_API_ROUTE}?query={query} when you do not know the page.`);
+	if (llms.enabled) lines.push(`- Use ${DEFAULT_LLMS_TXT_ROUTE} for a compact docs index.`, `- Use ${DEFAULT_LLMS_FULL_TXT_ROUTE} for full markdown context.`);
+	if (mcp.enabled) lines.push(`- Use ${DEFAULT_MCP_WELL_KNOWN_ROUTE} or ${DEFAULT_MCP_PUBLIC_ROUTE} for MCP tools when your environment supports MCP.`);
+	if (feedback.enabled) lines.push(`- Read ${feedback.schemaRoute} before posting agent feedback to ${feedback.route}.`);
+	lines.push("", "## Routes", `- Skill document: ${DEFAULT_SKILL_MD_ROUTE}`, `- Skill well-known alias: ${DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE}`, `- Skill API format: ${DEFAULT_DOCS_API_ROUTE}?format=skill`, `- Agent discovery: ${DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE}`, `- Agent discovery fallback: ${DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE}`, `- Markdown root: /${normalizedEntry}.md`, `- Markdown pages: /${normalizedEntry}/{slug}.md`);
+	if (llms.enabled) lines.push(`- llms.txt: ${DEFAULT_LLMS_TXT_ROUTE}`, `- llms-full.txt: ${DEFAULT_LLMS_FULL_TXT_ROUTE}`, `- llms well-known aliases: ${DEFAULT_LLMS_TXT_WELL_KNOWN_ROUTE}, ${DEFAULT_LLMS_FULL_TXT_WELL_KNOWN_ROUTE}`);
+	if (mcp.enabled) lines.push(`- MCP: ${DEFAULT_MCP_PUBLIC_ROUTE}, ${DEFAULT_MCP_WELL_KNOWN_ROUTE}`);
+	lines.push("", "## Reusable Framework Skills", "For framework setup, CLI, page actions, Ask AI, or configuration work, install the reusable Farming Labs skills:", "", "```sh", "npx skills add farming-labs/docs", "```");
+	return lines.join("\n");
+}
+function readRootSkillDocument(rootDir) {
+	const candidate = path.join(rootDir, "skill.md");
+	try {
+		if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) return fs.readFileSync(candidate, "utf-8");
+	} catch {
+		return null;
+	}
+	return null;
+}
+function compactSkillText(value) {
+	return value.replace(/\s+/g, " ").trim();
+}
+function truncateSkillDescription(value) {
+	const normalized = compactSkillText(value);
+	if (normalized.length <= 1024) return normalized;
+	return `${normalized.slice(0, 1021).trimEnd()}...`;
+}
+function toYamlString(value) {
+	return JSON.stringify(value);
+}
 const DEFAULT_SYSTEM_PROMPT = `You are a helpful documentation assistant. Answer questions based on the provided documentation context. Be concise and accurate. If the answer is not in the context, say so honestly. Use markdown formatting for code examples and links.`;
 function resolveModelAndProvider(aiConfig, requestedModelId) {
 	const raw = aiConfig.model;
@@ -946,6 +1006,7 @@ function generateLlmsTxt(indexes, options) {
 * - **GET  ?query=…**        → full-text search
 * - **GET  ?format=llms**     → llms.txt (concise page listing)
 * - **GET  ?format=llms-full** → llms-full.txt (full page content)
+* - **GET  ?format=skill**    → skill.md
 * - **POST**                  → AI-powered chat with RAG
 *
 * @example
@@ -1117,6 +1178,19 @@ function createDocsAPI(options) {
 					"X-Robots-Tag": "noindex"
 				} });
 			}
+			if (resolveSkillRequest(url)) return new Response(readRootSkillDocument(root) ?? renderSkillDocument({
+				origin: url.origin,
+				entry,
+				i18n,
+				search: searchConfig,
+				mcp: mcpConfig,
+				feedback: agentFeedbackConfig,
+				llms: llmsConfig
+			}), { headers: {
+				"Content-Type": "text/markdown; charset=utf-8",
+				"Cache-Control": "public, max-age=0, s-maxage=3600",
+				"X-Robots-Tag": "noindex"
+			} });
 			const markdownRequest = resolveMarkdownRequest(entry, url, request);
 			if (markdownRequest) {
 				const document = await getMarkdownDocument(ctx, markdownRequest.requestedPath);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farming-labs/theme",
-  "version": "0.1.38",
+  "version": "0.1.41",
   "description": "Theme package for @farming-labs/docs — layout, provider, MDX components, and styles",
   "keywords": [
     "docs",
@@ -133,7 +133,7 @@
     "tsdown": "^0.20.3",
     "typescript": "^5.9.3",
     "vitest": "^3.2.4",
-    "@farming-labs/docs": "0.1.38"
+    "@farming-labs/docs": "0.1.41"
   },
   "peerDependencies": {
     "@farming-labs/docs": ">=0.0.1",