Improve AI skill discoverability in llms.json and llms.txt

- 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 <noreply@anthropic.com>

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

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"
     }
   ],