dotnet-research

Purpose

A fast way for the user to onboard themselves onto an unfamiliar .NET/C# concept, library, or technology — new enough to be useful in a real conversation or PR within minutes, thorough enough to serve as a reference doc later.

Intent — a catalyst, not a substitute for learning. This skill lowers the activation energy to start learning a topic and gives the user a grounded reference to build on; it does not replace actually learning the thing. It compresses the cold-start ("what is this, why does it exist, where do we already use it") and points at authoritative sources — but real fluency still comes from the user writing the code, hitting the edge cases, and reading the primary docs it links to. Treat the output as a map that orients and points at the territory, current as of when it was generated, not as the territory itself. Write it so it accelerates understanding and directs the user to the sources, rather than posing as a complete substitute for them.

Trigger

/dotnet-research <topic>, or equivalent phrasing naming a topic ("get me up to speed on minimal APIs", "what is Source Generators in C#", "explain the difference between Span<T> and Memory<T>").

If no topic is given, ask what they want researched — don't guess a topic.

Gather

.NET and C# move fast (LTS/STS release cadence, evolving language versions) — always search, never answer from memory alone for anything version- or currency-sensitive.

1. Search for the topic against official sources first: Microsoft Learn (learn.microsoft.com), the .NET blog (devblogs.microsoft.com/dotnet), and the relevant GitHub repo (dotnet/runtime, dotnet/aspnetcore, etc.) if the topic is open-source.
2. Identify which .NET version(s) / C# language version introduced or changed this, and whether it's current, preview, or superseded.
3. Search for at least one real-world comparison or "gotchas" discussion (practical write-ups, not just API reference) so the deeper dive has more than restated docs.
4. If the topic has a common alternative or predecessor the user would naturally compare it to (e.g. Span<T> vs arrays, minimal APIs vs controllers, records vs classes), search that too so the comparison section is grounded rather than assumed.
5. Scan the local repos for existing, working usage of the topic. The launch directory is typically a parent holding many sibling repos, so this is a broad fan-out — delegate it to an Explore subagent rather than grepping inline, so only the concrete hits land back in context instead of the raw search output. Tell the subagent: search the on-disk repos (Grep/Glob only — never call az, hit Azure Portal, or reach any cloud/remote resource), first narrowing to the repos plausibly relevant to the topic rather than sweeping all of them, and return concrete repo/path/file.cs:line hits that show the topic actually being used, not just referenced in passing. If nothing turns up, that's a valid result — skip the "In your codebase" subsection rather than forcing an example.

Scale search depth to topic breadth — a narrow API question might need 2-3 searches, a broad topic ("what's new in .NET 9") needs more to cover properly.

Scope the output to the ask

Match the deliverable to the question. A broad or genuinely unfamiliar topic ("what's new in .NET 9", "explain Source Generators") warrants the full doc-and-artifact treatment below. A narrow, self-contained question ("Span<T> vs ReadOnlySpan<T>", "does record struct support with") is better answered inline — a tight primer in the reply, no file, no artifact. When /dotnet-research is invoked explicitly, or the user asks for a reference doc / shareable link, always produce the full artifact regardless of topic size. If unsure which side a topic falls on, ask rather than defaulting to a full doc for a one-line question.

Write

Save the file to a dotnet-research/ folder at the root of the directory the claude command was launched from (create the folder if it doesn't exist yet — don't nest it under .claude/). Name the file after the topic in kebab-case, e.g. dotnet-research/minimal-apis.md. Then publish that same file with the Artifact tool so the user gets a shareable link — do not use a scratchpad path.

Before writing the file, load the artifact-design skill — it's required before authoring any artifact and calibrates how much design the page warrants. When you publish, pass the required favicon (an emoji, e.g. ⚙️), a short noun-phrase title (the topic name), and a one-sentence description. Default to a plain .md artifact; if the user later asks for a Word version, handle that as a separate request. Follow copyright rules: paraphrase throughout, quotes only when exact wording matters, under 15 words, one per source.

Structure, top to bottom:

1. Title — the topic as a heading.
2. Quick primer (first, right under the title) — 3-6 sentences: what it is, why it exists / what problem it solves, and a minimal code example if the topic is code-shaped. Someone should be able to read only this and hold their own in a conversation about it five minutes later.
3. Deeper dive — everything else, in whatever subsections fit the topic, typically:
   • How it works — mechanics, not just the pitch. If the mechanics are inherently visual (pipelines, lifetimes, state machines, request/data flow), include a diagram — load the artifact-diagramming skill for how to build one that stays legible in both light and dark themes.
   • In your codebase — real usage found while scanning local repos, cited as repo/path/file.cs:line with a one-line note on what it's doing there. Omit this subsection entirely if scanning turned up nothing — don't manufacture an example to fill it.
   • Comparison — vs. the natural alternative(s), with a short table or list of tradeoffs where that's clearer than prose.
   • Gotchas / pitfalls — things that trip people up in practice.
   • Best practices — how it's actually used well in production code.
   • Version notes — which .NET/C# version, current status (stable/preview/deprecated).
   • Further reading — links to the official docs and any standout sources found, as a short list.

Code examples use C# and follow current idiomatic style (e.g. file-scoped namespaces, nullable reference types where relevant) unless the topic specifically concerns an older pattern.

Voice

Direct and technical — the user is a working .NET/C# developer, not a beginner. Skip "let's start with the basics of programming" framing; assume general programming fluency and go straight to what's specific and non-obvious about this topic. No padding, no motivational framing.

Ground rules

• This skill only researches and writes a reference doc into dotnet-research/ — it never edits the user's actual code or project files unless they separately ask for that in the same conversation.
• Follow standard citation/copyright rules: paraphrase source material, quotes under 15 words and one per source, link out rather than reproduce.