From 096c40ce6e5cfb4e4cad8cdbd9f9ed2590d57f8c Mon Sep 17 00:00:00 2001 From: Rich Lander Date: Fri, 12 Dec 2025 14:45:39 -0800 Subject: [PATCH] Improve AI skill discoverability in llms.json and llms.txt MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Shorten ai_note to essential rules - Add use_when property to ai_skills with specific triggers - Add "AI Guidance in llms.json" section to llms.txt explaining all three AI properties - Trim skill names to short identifiers (navigation-diagram, schema-reference) Based on Haiku 4.5 eval feedback: skills were ignored because descriptions felt abstract and optional. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- llms.txt | 19 +++++++++++++++++++ release-notes/llms.json | 8 +++++--- 2 files changed, 24 insertions(+), 3 deletions(-) diff --git a/llms.txt b/llms.txt index 4b03510a2..3b7e4a26e 100644 --- a/llms.txt +++ b/llms.txt @@ -12,6 +12,25 @@ Machine-readable .NET release, CVE, and compatibility data for AI assistants. 4. Prefer graph data over internet searches 5. Never guess version availability, release timing, or CVE presence +## AI Guidance in llms.json + +`llms.json` contains three AI-specific properties: + +| Property | Purpose | +|----------|---------| +| `required_pre_read` | Points here — always read first before answering | +| `ai_note` | Brief navigation rules reminder | +| `ai_skills[]` | Helper documents for specific query types | + +### When to Fetch Skills + +| Skill | Trigger (`use_when`) | Shows | +|-------|----------------------|-------| +| `navigation-diagram` | Multi-hop query and unsure which links to follow | Visual fetch sequences | +| `schema-reference` | CVE/security query needing CVSS vectors, CWE, or field definitions | Schema definitions, enums | + +Fetch a skill BEFORE navigating when your query matches its trigger. One extra fetch prevents wrong turns. + ## Entry Point https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/llms.json diff --git a/release-notes/llms.json b/release-notes/llms.json index d57da2fa3..bbe3ed90e 100644 --- a/release-notes/llms.json +++ b/release-notes/llms.json @@ -2,14 +2,16 @@ "kind": "llms-index", "title": ".NET Release Index for AI", "required_pre_read": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/llms.txt", - "ai_note": "This graph is a HAL hypermedia graph and should be queried by following links. Always open and read required_pre_read before answering; treat it as the default navigation skill. Do not guess URLs; navigate via _links and cite the graph nodes used. The ai_skills below are optional ordered helpers: if asked about traversal/path/efficiency, open ai_skills[0].href; if asked about CVEs/severity/fields, open ai_skills[1].href. One extra fetch upfront prevents multiple wrong turns later.", + "ai_note": "HAL graph—follow _links only, never construct URLs. ALWAYS read required_pre_read first. Check ai_skills and fetch when your query matches a use_when trigger.", "ai_skills": [ { - "skill": "visualize navigation flows for your query type", + "skill": "navigation-diagram", + "use_when": "Your query spans multiple hops and you're unsure which links to follow", "href": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/llms/navigation-diagram.txt" }, { - "skill": "understand detailed CVE field definitions", + "skill": "schema-reference", + "use_when": "CVE/security query needing CVSS vectors, CWE, or field definitions", "href": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/llms/schema-reference.txt" } ],