AG-UI .NET SDK — Docs Sync
sdks/dotnet/AGENTS.md (coding instructions) and sdks/dotnet/docs/architecture.md
(design overview) describe the SDK's structure, naming, and conventions. They
drift silently after refactors because nothing fails the build when prose goes
stale. This skill reconciles them against the live tree.
Typical drift this catches: a package rename, a moved/removed project, a changed
endpoint pattern, or a new sample step that the prose never caught up with. An agent
that edits these files from memory re-introduces the same kind of drift, so always
derive the truth from the tree first.
Process
- Establish ground truth from the tree, not from the doc. The authoritative
source is
sdks/dotnet/AGUI.slnx plus the folder listing — never the prose
you are about to edit.
- Projects: read
<Project Path=...> entries from AGUI.slnx.
- Folders:
Get-ChildItem src,tests,samples -Directory.
- Samples/steps: list
samples/GettingStarted/Step* to get the real range.
- Drift scan — diff each doc claim against the tree. For every concrete
claim in AGENTS.md / docs/architecture.md, confirm it against ground truth:
- Project & package names exist in
AGUI.slnx (and in src/, tests/).
- Symbols the docs name still exist:
Select-String -Path src\*\*.cs,samples\*\*.cs -Pattern "<Symbol>".
- Renamed/removed symbols are GONE everywhere: grep the repo for the old
name (e.g.
AGUI.Hosting.AspNetCore, TypedResults.ServerSentEvents); a
hit in prose-only is the drift to fix.
- Fix surgically. Edit only the stale lines. Match existing tone, tables,
and code-fence style. Do not restructure or invent conventions.
- Verify. Re-grep every symbol/name you wrote to confirm it exists in the
tree. Optionally
dotnet build from sdks/dotnet/ if you touched code-style
or build claims.
Drift checklist (the claims that rot)
| Doc claim |
Reconcile against |
| src package list / names |
AGUI.slnx /src/ folder + src/ dirs |
| Package dependency table & framework refs |
grep Microsoft.AspNetCore src\*\*.csproj (must be empty — no src project references ASP.NET) |
| Where ASP.NET glue lives |
samples/AGUI.Samples.Shared (the only FrameworkReference Microsoft.AspNetCore.App) |
| Test-project table & count |
AGUI.slnx /tests/ + tests/ dirs |
| Sample step range / count |
samples/GettingStarted/Step* listing |
| Endpoint pattern code |
actual sample Program.cs + samples/AGUI.Samples.Shared |
| Project layout bullet list |
src/, tests/, samples/ dirs |
| Code-style / naming / serialization rules |
Directory.Build.props/.targets, Directory.Packages.props, source |
| PublicAPI workflow |
presence of PublicAPI.*.txt in each src/ project |
Deriving ground truth (commands, not a snapshot)
Don't trust any embedded list (including this skill). Re-derive the current state
from the tree every time:
# from sdks/dotnet/
Select-String -Path AGUI.slnx -Pattern '<Project Path' # all projects
Get-ChildItem src,tests,samples -Directory # folders
Get-ChildItem samples/GettingStarted -Directory -Filter Step* # sample step range
Select-String -Path src\*\*.csproj -Pattern Microsoft.AspNetCore # must be empty (no ASP.NET in src/)
A couple of durable facts that are easy to get wrong: the server package is
AGUI.Server (ASP.NET hosting glue lives only in samples/AGUI.Samples.Shared),
and the integration-test project name stays AGUI.Hosting.AspNetCore.IntegrationTests
even though its types are in namespace AGUI.Server.IntegrationTests. Everything else,
derive from the commands above.
❌ Critical anti-patterns
- Never edit the docs from memory or from the doc's own current text. The
stale prose is exactly what misleads you. Derive every name from
AGUI.slnx
and the folder listing first.
- Never rename a symbol in prose without grepping the whole tree for the
old name — a lingering reference (or an unchanged code fence) is silent drift.
- Don't invent conventions or restructure the docs. Reconcile only what the
tree proves changed; keep tables, tone, and code-fence style intact.
- Don't confuse a kept project name with a moved concept. The integration
test project is still
AGUI.Hosting.AspNetCore.IntegrationTests even though
the src package was renamed to AGUI.Server.
Files to mine
sdks/dotnet/AGENTS.md, sdks/dotnet/docs/architecture.md, sdks/dotnet/AGUI.slnx,
sdks/dotnet/Directory.Build.props, Directory.Build.targets,
Directory.Packages.props, and the src/, tests/, samples/ folder trees.
Source: ag-ui-protocol/ag-ui → .github/skills/agui-dotnet-agents-sync/SKILL.md
1---2name: agui-dotnet-agents-sync3description: > Keep the AG-UI .NET SDK docs (sdks/dotnet/AGENTS.md and docs/architecture.md) in sync with the real code tree after structural changes. USE FOR: "update AGENTS.md / docs/architecture.md", "check the dotnet docs are current", verifying docs after a .NET SDK refactor (package rename, added/removed project, changed endpoint pattern, new/renamed test project, sample step added, new convention). DO NOT USE FOR: writing product code or tests (follow AGENTS.md itself), Python/TypeScript SDK docs, or generic markdown editing unrelated to the dotnet SDK structure.4---5# AG-UI .NET SDK — Docs Sync67`sdks/dotnet/AGENTS.md` (coding instructions) and `sdks/dotnet/docs/architecture.md`8(design overview) describe the SDK's structure, naming, and conventions. They9drift silently after refactors because nothing fails the build when prose goes10stale. This skill reconciles them against the live tree.1112> Typical drift this catches: a package rename, a moved/removed project, a changed13> endpoint pattern, or a new sample step that the prose never caught up with. An agent14> that edits these files from memory re-introduces the same kind of drift, so always15> derive the truth from the tree first.1617## Process18191. **Establish ground truth from the tree, not from the doc.** The authoritative20 source is `sdks/dotnet/AGUI.slnx` plus the folder listing — never the prose21 you are about to edit.22 - Projects: read `<Project Path=...>` entries from `AGUI.slnx`.23 - Folders: `Get-ChildItem src,tests,samples -Directory`.24 - Samples/steps: list `samples/GettingStarted/Step*` to get the real range.252. **Drift scan — diff each doc claim against the tree.** For every concrete26 claim in AGENTS.md / docs/architecture.md, confirm it against ground truth:27 - Project & package names exist in `AGUI.slnx` (and in `src/`, `tests/`).28 - Symbols the docs name still exist: `Select-String -Path src\*\*.cs,samples\*\*.cs -Pattern "<Symbol>"`.29 - Renamed/removed symbols are GONE everywhere: grep the repo for the old30 name (e.g. `AGUI.Hosting.AspNetCore`, `TypedResults.ServerSentEvents`); a31 hit in prose-only is the drift to fix.323. **Fix surgically.** Edit only the stale lines. Match existing tone, tables,33 and code-fence style. Do not restructure or invent conventions.344. **Verify.** Re-grep every symbol/name you wrote to confirm it exists in the35 tree. Optionally `dotnet build` from `sdks/dotnet/` if you touched code-style36 or build claims.3738## Drift checklist (the claims that rot)3940| Doc claim | Reconcile against |41|---|---|42| **src package list / names** | `AGUI.slnx` `/src/` folder + `src/` dirs |43| **Package dependency table & framework refs** | `grep Microsoft.AspNetCore src\*\*.csproj` (must be empty — no src project references ASP.NET) |44| **Where ASP.NET glue lives** | `samples/AGUI.Samples.Shared` (the only `FrameworkReference Microsoft.AspNetCore.App`) |45| **Test-project table & count** | `AGUI.slnx` `/tests/` + `tests/` dirs |46| **Sample step range / count** | `samples/GettingStarted/Step*` listing |47| **Endpoint pattern code** | actual sample `Program.cs` + `samples/AGUI.Samples.Shared` |48| **Project layout bullet list** | `src/`, `tests/`, `samples/` dirs |49| **Code-style / naming / serialization rules** | `Directory.Build.props/.targets`, `Directory.Packages.props`, source |50| **PublicAPI workflow** | presence of `PublicAPI.*.txt` in each `src/` project |5152## Deriving ground truth (commands, not a snapshot)5354Don't trust any embedded list (including this skill). Re-derive the current state55from the tree every time:5657```powershell58# from sdks/dotnet/59Select-String -Path AGUI.slnx -Pattern '<Project Path' # all projects60Get-ChildItem src,tests,samples -Directory # folders61Get-ChildItem samples/GettingStarted -Directory -Filter Step* # sample step range62Select-String -Path src\*\*.csproj -Pattern Microsoft.AspNetCore # must be empty (no ASP.NET in src/)63```6465A couple of durable facts that are easy to get wrong: the server package is66`AGUI.Server` (ASP.NET hosting glue lives only in `samples/AGUI.Samples.Shared`),67and the integration-test **project name** stays `AGUI.Hosting.AspNetCore.IntegrationTests`68even though its types are in namespace `AGUI.Server.IntegrationTests`. Everything else,69derive from the commands above.7071## ❌ Critical anti-patterns72731. **Never edit the docs from memory or from the doc's own current text.** The74 stale prose is exactly what misleads you. Derive every name from `AGUI.slnx`75 and the folder listing first.762. **Never rename a symbol in prose without grepping the whole tree** for the77 old name — a lingering reference (or an unchanged code fence) is silent drift.783. **Don't invent conventions or restructure the docs.** Reconcile only what the79 tree proves changed; keep tables, tone, and code-fence style intact.804. **Don't confuse a kept project name with a moved concept.** The integration81 test project is still `AGUI.Hosting.AspNetCore.IntegrationTests` even though82 the src package was renamed to `AGUI.Server`.8384## Files to mine8586`sdks/dotnet/AGENTS.md`, `sdks/dotnet/docs/architecture.md`, `sdks/dotnet/AGUI.slnx`,87`sdks/dotnet/Directory.Build.props`, `Directory.Build.targets`,88`Directory.Packages.props`, and the `src/`, `tests/`, `samples/` folder trees.8990---9192**Source:** [`ag-ui-protocol/ag-ui`](https://github.com/ag-ui-protocol/ag-ui) → `.github/skills/agui-dotnet-agents-sync/SKILL.md`
thedixitjain