Skip to content

Commit 59bb38f

Browse files
richlanderclaude
richlander
and
claude
committed
Add Anthropic skill format for .NET release graph navigation
New release-notes/skills/ directory with task-specific skills: - SKILL.md: TOC with graph basics and skill triggers - navigation.md: ASCII flow diagrams, link relations, fetch counts - cve.md: CVE queries, severity levels, history traversal - breaking-changes.md: Compatibility, migration guidance - version-eol.md: Support lifecycle, EOL version queries - os-support.md: Distros, packages, glibc requirements llms.json changes: - required_pre_read now points to skills/SKILL.md - Removed ai_skills (skills now documented in SKILL.md) - ai_note leads with required_pre_read instruction This enables testing two flows: - llms.txt -> llms.json (existing) - llms.json -> SKILL.md -> task skills (new) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
1 parent a61d513 commit 59bb38f

File tree

7 files changed

+564
-16
lines changed

7 files changed

+564
-16
lines changed

‎release-notes/llms.json‎

Lines changed: 2 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,8 @@
11
{
22
"kind": "llms-index",
33
"title": ".NET Release Index for AI",
4-
"required_pre_read": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/llms.txt",
5-
"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.",
6-
"ai_skills": [
7-
{
8-
"skill": "navigation-diagram",
9-
"use_when": "Your query spans multiple hops and you're unsure which links to follow",
10-
"shows": "Visual fetch sequences for every query type, link relations, fetch counts",
11-
"href": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/llms/navigation-diagram.txt"
12-
},
13-
{
14-
"skill": "schema-reference",
15-
"use_when": "CVE/security query needing CVSS vectors, CWE, or field definitions",
16-
"shows": "Severity levels, affected package ranges, field enums, file type schemas",
17-
"href": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/llms/schema-reference.txt"
18-
}
19-
],
4+
"required_pre_read": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/skills/SKILL.md",
5+
"ai_note": "ALWAYS read required_pre_read first. HAL graph—follow _links only, never construct URLs.",
206
"latest": "10.0",
217
"latest_lts": "10.0",
228
"latest_year": "2025",

‎release-notes/skills/SKILL.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
name: dotnet-releases
3+
description: Query .NET release data, CVEs, breaking changes, EOL dates, and OS support. Use when answering questions about .NET versions, security vulnerabilities, compatibility, or support status.
4+
---
5+
6+
# .NET Release Graph
7+
8+
Machine-readable .NET release, CVE, and compatibility data via HAL hypermedia.
9+
10+
## Entry Point
11+
12+
https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/llms.json
13+
14+
## Core Rules
15+
16+
1. **Follow `_links["..."].href` exactly** — never construct URLs
17+
2. **Use `_embedded` data first** — it answers most queries without extra fetches
18+
3. **If data is missing, don't fabricate** — report the gap
19+
20+
## What's in llms.json
21+
22+
| Property | Contains |
23+
|----------|----------|
24+
| `_embedded.latest_patches[]` | Current patch for each supported version (8.0, 9.0, 10.0) with EOL dates, support status |
25+
| `_embedded.latest_security_month[]` | CVE counts and IDs (severity requires fetching month index) |
26+
| `_links` | Navigation to version indexes, timeline, releases |
27+
28+
## Skills for Specific Tasks
29+
30+
Fetch these when your query matches:
31+
32+
| Skill | Fetch When | URL |
33+
|-------|------------|-----|
34+
| navigation.md | Multi-hop query and unsure which links to follow | https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/skills/navigation.md |
35+
| cve.md | CVE queries needing severity, CVSS, or history | https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/skills/cve.md |
36+
| breaking-changes.md | Compatibility or migration questions | https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/skills/breaking-changes.md |
37+
| version-eol.md | EOL versions, support lifecycle, or version history | https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/skills/version-eol.md |
38+
| os-support.md | OS packages, distro support, or glibc requirements | https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/skills/os-support.md |
39+
40+
## Quick Answers (1 fetch)
41+
42+
These are answered directly from `llms.json`:
43+
44+
- Latest patch for .NET X → `_embedded.latest_patches[]` filter by `release`
45+
- Is .NET X supported? → `_embedded.latest_patches[]` → `supported`, `eol_date`
46+
- CVE count this month → `_embedded.latest_security_month[]` → `cve_count`
47+
48+
## Navigation Shortcuts
49+
50+
Each `_embedded.latest_patches[]` entry has `_links` for 2-fetch navigation:
51+
52+
- `release-major` → version index (breaking changes, TFMs, OS support)
53+
- `latest-sdk` → SDK index (feature bands, downloads)
54+
- `latest-security` → last security patch for that version

‎release-notes/skills/breaking-changes.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
# Breaking Changes Queries
2+
3+
## Navigation Flow (2 fetches)
4+
5+
```
6+
llms.json
7+
│
8+
└─► _embedded.latest_patches[] ─► find version (e.g., "10.0")
9+
│
10+
└─► _links["release-major"]
11+
│
12+
▼
13+
X.0/index.json
14+
│
15+
├─► _links["compatibility-json"] ─► breaking changes
16+
│
17+
└─► _links["target-frameworks-json"] ─► TFMs
18+
```
19+
20+
## Common Queries
21+
22+
### Breaking changes for .NET X (2 fetches)
23+
24+
1. Fetch `llms.json`
25+
2. Find `_embedded.latest_patches[]` where `release == "X.0"`
26+
3. Follow `_links["release-major"]` → version index
27+
4. Follow `_links["compatibility-json"]` → compatibility.json
28+
29+
### TFMs for .NET X (2 fetches)
30+
31+
Same path, but follow `_links["target-frameworks-json"]`
32+
33+
## compatibility.json Structure
34+
35+
```json
36+
{
37+
"breaking_changes": [
38+
{
39+
"id": "category-version-short-name",
40+
"title": "Human-readable title",
41+
"category": "core-libraries | sdk | aspnet-core | ...",
42+
"type": "behavioral | source-incompatible | binary-source-incompatible",
43+
"version_introduced": "10.0",
44+
"impact": "low | medium | high",
45+
"references": [
46+
{
47+
"type": "documentation-source",
48+
"url": "https://learn.microsoft.com/..."
49+
}
50+
]
51+
}
52+
]
53+
}
54+
```
55+
56+
## Breaking Change Types
57+
58+
| Type | Meaning |
59+
|------|---------|
60+
| `behavioral` | Runtime behavior changed, source compiles |
61+
| `source-incompatible` | Source won't compile without changes |
62+
| `binary-source-incompatible` | Binary and source compatibility broken |
63+
64+
## Impact Levels
65+
66+
| Impact | Description |
67+
|--------|-------------|
68+
| `low` | Unlikely to affect most apps |
69+
| `medium` | May require code changes |
70+
| `high` | Likely requires migration effort |
71+
72+
## Categories
73+
74+
Common categories in `compatibility.json`:
75+
76+
- `core-libraries` — BCL changes
77+
- `sdk` — dotnet CLI, MSBuild, NuGet
78+
- `aspnet-core` — ASP.NET Core
79+
- `windows-forms` — WinForms
80+
- `wpf` — WPF
81+
- `cryptography` — Security/crypto APIs
82+
- `extensions` — Microsoft.Extensions.*
83+
- `networking` — HTTP, sockets
84+
- `serialization` — JSON, XML serialization
85+
86+
## Tips
87+
88+
- Group by `category` for migration planning
89+
- Filter by `impact == "high"` for critical review
90+
- Follow `references[].url` for detailed migration guidance

‎release-notes/skills/cve.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# CVE Queries
2+
3+
## Quick Rule
4+
5+
`_embedded.latest_security_month[]` in llms.json has **counts and IDs only** — fetch the month index for CVSS scores and severity.
6+
7+
## Navigation Flow
8+
9+
```
10+
llms.json
11+
│
12+
├─► _embedded.latest_security_month[] ─► CVE counts, IDs (no severity)
13+
│
14+
└─► _links["latest-security-month"]
15+
│
16+
▼
17+
month/index.json
18+
│
19+
├─► _embedded.disclosures[] ─► severity, titles, fix commits
20+
│
21+
├─► _links["cve-json"] ─► full CVSS vectors, CWE, packages
22+
│
23+
└─► _links["prev-security"] ─► previous security month
24+
```
25+
26+
## Common Queries
27+
28+
### Critical CVEs this month (2 fetches)
29+
30+
1. Fetch `llms.json`
31+
2. Follow `_links["latest-security-month"]` → month index
32+
3. Filter `_embedded.disclosures[]` where `cvss_severity == "CRITICAL"`
33+
34+
### CVE history for .NET X (1 + N fetches)
35+
36+
1. Fetch `llms.json`
37+
2. Follow `_links["latest-security-month"]`
38+
3. Walk `_links["prev-security"]` until target date
39+
4. Filter `_embedded.disclosures[]` by `affected_releases`
40+
41+
### Deep CVE analysis (3 fetches)
42+
43+
1. Fetch month index
44+
2. Follow `_links["cve-json"]` for full details:
45+
- `cvss_vector` — full CVSS string
46+
- `cwe` — weakness classification
47+
- `packages[]` — affected NuGet packages with version ranges
48+
49+
## Disclosure Fields
50+
51+
Each `_embedded.disclosures[]` entry contains:
52+
53+
| Field | Description |
54+
|-------|-------------|
55+
| `id` | CVE identifier (e.g., CVE-2025-55315) |
56+
| `title` | Vulnerability title |
57+
| `cvss_score` | Numeric score (0-10) |
58+
| `cvss_severity` | NONE, LOW, MEDIUM, HIGH, CRITICAL |
59+
| `affected_releases` | Array of .NET versions (e.g., ["8.0", "9.0"]) |
60+
| `fixes[]` | Commit diff URLs per release branch |
61+
62+
## Severity Levels
63+
64+
| Severity | CVSS Range |
65+
|----------|------------|
66+
| CRITICAL | 9.0 - 10.0 |
67+
| HIGH | 7.0 - 8.9 |
68+
| MEDIUM | 4.0 - 6.9 |
69+
| LOW | 0.1 - 3.9 |
70+
| NONE | 0.0 |
71+
72+
## Tips
73+
74+
- `prev-security` links skip non-security months automatically
75+
- Fix commit URLs end in `.diff` — fetch immediately if needed (may be blocked later)
76+
- `cve-json` is only needed for CVSS vectors, CWE, or package version ranges

‎release-notes/skills/navigation.md‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
# Navigation Flows
2+
3+
Visual map of navigation patterns through the .NET release graph. Use this when planning multi-hop queries.
4+
5+
## Entry Points
6+
7+
```
8+
llms.json (AI-optimized) index.json (all versions) timeline/index.json (by date)
9+
│ │ │
10+
├─► latest_patches[] ├─► _embedded.releases[] ├─► _embedded.years[]
11+
│ (supported versions) │ (all versions incl EOL) │ └─► _embedded.months[]
12+
│ │ │
13+
└─► latest_security_month[] └─► _links.timeline-index └─► _links.prev-security
14+
(current CVE summary) (walk security history)
15+
```
16+
17+
## Flow 1: Supported Version Queries (1-2 fetches)
18+
19+
```
20+
llms.json
21+
│
22+
└─► _embedded.latest_patches[] ─────────────────────────► DONE (patch version, EOL date, support status)
23+
│
24+
├─► _links.release-major ─► X.0/index.json ─► compatibility-json ─► DONE (breaking changes)
25+
│ └─► target-frameworks-json ─► DONE (TFMs)
26+
│
27+
└─► _links.latest-sdk ─► sdk/index.json ─► DONE (feature bands, downloads)
28+
```
29+
30+
## Flow 2: CVE Queries (1-N fetches)
31+
32+
```
33+
llms.json
34+
│
35+
├─► _embedded.latest_security_month[] ─► DONE (CVE IDs and counts only)
36+
│
37+
└─► _links.latest-security-month
38+
│
39+
▼
40+
month/index.json ◄──────────────────┐
41+
│ │
42+
├─► _embedded.disclosures[] ────│─► DONE (severity, titles, fixes)
43+
│ │
44+
├─► _links.cve-json ───────────►│ cve.json ─► DONE (CVSS vectors, CWE, packages)
45+
│ │
46+
└─► _links.prev-security ───────┘ (repeat for history)
47+
```
48+
49+
## Flow 3: EOL Version Queries (3-5 fetches)
50+
51+
```
52+
llms.json
53+
│
54+
└─► _links.releases-index
55+
│
56+
▼
57+
index.json
58+
│
59+
└─► _embedded.releases[] ─► find EOL version (e.g., 6.0)
60+
│
61+
└─► _links.self
62+
│
63+
▼
64+
6.0/index.json ─► eol_date, latest patch
65+
│
66+
└─► _links.latest-security
67+
│
68+
▼
69+
6.0.35/index.json ─► _embedded.disclosures[] ─► DONE
70+
```
71+
72+
## Flow 4: Linux/OS Queries (3 fetches)
73+
74+
```
75+
llms.json
76+
│
77+
└─► _embedded.latest_patches[] ─► _links.release-major
78+
│
79+
▼
80+
X.0/index.json
81+
│
82+
└─► _links.release-manifest
83+
│
84+
▼
85+
manifest.json
86+
│
87+
├─► _links.supported-os-json ─► DONE (distros, glibc versions)
88+
│
89+
└─► _links.os-packages-json ─► DONE (apt/dnf packages per distro)
90+
```
91+
92+
## Key Link Relations
93+
94+
```
95+
From llms.json:
96+
latest-security-month ──► timeline month (CVE details)
97+
releases-index ──────────► full version list (including EOL)
98+
99+
From latest_patches[]:
100+
release-major ───────────► X.0/index.json (version resources)
101+
latest-sdk ──────────────► sdk/index.json (SDK bands)
102+
latest-security ─────────► last security patch
103+
104+
From month index:
105+
prev-security ───────────► previous security month (auto-skips non-security)
106+
cve-json ────────────────► full CVE details
107+
108+
From version index:
109+
release-manifest ────────► manifest.json (OS support, packages)
110+
compatibility-json ──────► breaking changes
111+
target-frameworks-json ──► TFMs
112+
```
113+
114+
## Fetch Count Summary
115+
116+
| Pattern | Fetches | Notes |
117+
|---------|---------|-------|
118+
| Embedded data | 1 | patch versions, support status, CVE counts |
119+
| Version resources | 2 | breaking changes, TFMs, SDK bands |
120+
| OS/Linux queries | 3 | requires manifest hop |
121+
| EOL version info | 3-5 | must traverse releases-index |
122+
| CVE history | 1+N | N = security months to traverse |

0 commit comments

Comments
 (0)