From 56f950af38cc263d66b6bf1eb1cfa733d8ea7dda Mon Sep 17 00:00:00 2001
From: Marco Walz <marco.walz@dfinity.org>
Date: Tue, 31 Mar 2026 12:52:53 +0200
Subject: [PATCH] Improve skill discovery for agents

- Add url field to each skill entry in index.json so agents follow
  direct links instead of constructing URLs from templates
- Improve llms.txt with numbered steps, concrete example, and
  guardrails against wrong URL construction
- Skip dotfiles/dirs in collectFiles to exclude .score_cache from index
---
 src/data/skills.ts                         |  3 ++-
 src/pages/.well-known/skills/index.json.ts |  2 ++
 src/pages/llms.txt.ts                      | 18 ++++++++++++------
 3 files changed, 16 insertions(+), 7 deletions(-)

diff --git a/src/data/skills.ts b/src/data/skills.ts
index 95a151c..3f84045 100644
--- a/src/data/skills.ts
+++ b/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));
diff --git a/src/pages/.well-known/skills/index.json.ts b/src/pages/.well-known/skills/index.json.ts
index ee36c8e..204137d 100644
--- a/src/pages/.well-known/skills/index.json.ts
+++ b/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,
     })),
   };
diff --git a/src/pages/llms.txt.ts b/src/pages/llms.txt.ts
index 9d8999f..0735b99 100644
--- a/src/pages/llms.txt.ts
+++ b/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