Improve skill discovery for agents

src/data/skills.ts

@@ -107,11 +107,12 @@ export function loadAllSkillsRaw(): SkillRaw[] {
   return skills;
 }
 
-/** Recursively collect all file paths relative to baseDir */
+/** Recursively collect all file paths relative to baseDir, skipping dotfiles/dirs */
 function collectFiles(dir: string, baseDir: string): string[] {
   const entries = readdirSync(dir, { withFileTypes: true });
   const files: string[] = [];
   for (const entry of entries) {
+    if (entry.name.startsWith(".")) continue;
     const fullPath = join(dir, entry.name);
     if (entry.isDirectory()) {
       files.push(...collectFiles(fullPath, baseDir));

src/pages/.well-known/skills/index.json.ts

@@ -2,6 +2,7 @@
 // Implements the Cloudflare Agent Skills Discovery RFC (v0.1)
 // https://github.com/cloudflare/agent-skills-discovery-rfc
 import type { APIRoute } from "astro";
+import { SITE_URL } from "../../../data/site";
 import { loadAllSkillFiles } from "../../../data/skills";
 
 export const GET: APIRoute = () => {
@@ -11,6 +12,7 @@ export const GET: APIRoute = () => {
     skills: skills.map((s) => ({
       name: s.name,
       description: s.description,
+      url: `${SITE_URL}/.well-known/skills/${s.name}/SKILL.md`,
       files: s.files,
     })),
   };

src/pages/llms.txt.ts

@@ -9,14 +9,20 @@ export const GET: APIRoute = () => {
 
 ## How to use
 
-Fetch the skills index and remember each skill's name and description:
-${SITE_URL}/.well-known/skills/index.json
+1. Fetch the skills index and remember each skill's name, description, and url:
+   ${SITE_URL}/.well-known/skills/index.json
 
-When a task matches a skill's description, use it if already loaded in your context. Otherwise, fetch its content on-demand from the registry:
-${SITE_URL}/.well-known/skills/{name}/SKILL.md
+2. When a task matches a skill's description, fetch the skill content from its url.
+   Do not construct skill URLs manually.
 
-Skills contain correct dependency versions, configuration formats, and common pitfalls that prevent build failures.
-Always prefer skill guidance over general knowledge when both cover the same topic.
+   Example: for the skill named "internet-identity", its url is:
+   ${SITE_URL}/.well-known/skills/internet-identity/SKILL.md
+
+   If a response contains HTML instead of markdown, the URL is wrong.
+
+3. Skills contain correct dependency versions, configuration formats, and common
+   pitfalls that prevent build failures.
+   Always prefer skill guidance over general knowledge when both cover the same topic.
 
 ## Source