roslyn-analyzers

Stars6

Forks1

UpdatedJuly 10, 2026 at 05:41

Design, build, validate, and ship a Roslyn analyzer (and optional code fix) in a dedicated analyzer project. Use when asked to "write an analyzer", "create a Roslyn/diagnostic analyzer", "add an analyzer rule", "add a code fix", "enforce a convention at build time", or "flag a pattern in code". ALWAYS starts by checking whether an existing analyzer suite (the .NET SDK CA/IDE rules, BannedApiAnalyzers, an EditorConfig rule, Roslynator, StyleCop, Meziantou, etc.) already covers the request before authoring anything new. Covers the netstandard2.0 project layout, packing the analyzer into your library's NuGet package, the statelessness/concurrency and IOperation-vs-syntax design rules, the Microsoft.CodeAnalysis.Testing validation harness, and the in-IDE performance discipline. For BenchmarkDotNet runtime microbenchmarks see `performance-testing`; for auditing untrusted-input handling see `security-review`.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Source

JeremyKuhne

JeremyKuhne/touki

View GitHub Repository View Creator Repositories

Download

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

File Explorer

6 files

SKILL.md

readonly

compatibility	Requires the .NET SDK, Roslyn packages, and a test project capable of running Microsoft.CodeAnalysis.Testing fixtures.
description	Design, build, validate, and ship a Roslyn analyzer (and optional code fix) in a dedicated analyzer project. Use when asked to "write an analyzer", "create a Roslyn/diagnostic analyzer", "add an analyzer rule", "add a code fix", "enforce a convention at build time", or "flag a pattern in code". ALWAYS starts by checking whether an existing analyzer suite (the .NET SDK CA/IDE rules, BannedApiAnalyzers, an EditorConfig rule, Roslynator, StyleCop, Meziantou, etc.) already covers the request before authoring anything new. Covers the netstandard2.0 project layout, packing the analyzer into your library's NuGet package, the statelessness/concurrency and IOperation-vs-syntax design rules, the Microsoft.CodeAnalysis.Testing validation harness, and the in-IDE performance discipline. For BenchmarkDotNet runtime microbenchmarks see `performance-testing`; for auditing untrusted-input handling see `security-review`.
license	MIT
metadata	{"applicability":"dotnet-project-gated","binding":"optional-overlay","github-path":"skills/roslyn-analyzers","github-pinned":"v0.10.0","github-ref":"refs/tags/v0.10.0","github-repo":"https://github.com/JeremyKuhne/agent-skills","github-tree-sha":"0456189352ca224c2a9323e44eb883da455027dd","maturity":"canary","portability":"portable","related":"performance-testing, security-review, pre-pr-self-review, il-copy-inspection","requires":"none","risk":"local-write"}
name	roslyn-analyzers

Roslyn analyzers

If overlay.md exists beside this file, read it before acting; it contains repository-specific bindings. This core remains usable without it.

Author a Roslyn diagnostic analyzer (and optional code fix) the right way: confirm nothing already does the job, build it to the analyzer-authoring rules, validate it with real positive/negative cases, and keep it fast enough to run on every keystroke in the IDE.

If your repo already has a working analyzer, read it first and copy its shape - a real in-repo example is the best template. Otherwise the patterns below are distilled from working analyzers and the official Roslyn SDK guidance.

Step 0 - the prime directive: is it already covered?

Do not write a new analyzer until you have ruled out the existing ones. A hand-rolled analyzer is code you own, test, and pay for on every build and keystroke forever. Most "I want to flag X" requests are already solved by a rule that ships in the box and only needs a severity bump in .editorconfig, or by a configuration-only analyzer (banned APIs, naming rules). The full survey and the decision checklist are in existing-analyzers.md.

The short version, in priority order:

An existing rule + .editorconfig severity (the .NET SDK CA*/IDE* analyzers are on by default). Cheapest possible answer.
A configuration-only analyzer - BannedApiAnalyzers (ban a type/member), an EditorConfig naming rule, PublicApiAnalyzers (lock public surface). No custom code.
A third-party suite already in the graph or worth adding - Roslynator, StyleCop, Meziantou, SonarAnalyzer.
Only if none fit - author a custom analyzer. Continue below.

Where analyzers live (the project layout)

By convention the analyzer ships as a small cluster of projects alongside the library it guards (<root> is the library project name):

<root>.analyzers - the analyzer assembly. netstandard2.0, EnforceExtendedAnalyzerRules=true, IsPackable=false, IncludeBuildOutput=false, signed. Needs both AnalyzerReleases.Shipped.md and AnalyzerReleases.Unshipped.md or RS2008 fails the build.
<root>.analyzers.tests - a modern .NET test project (MSTest / xUnit). If your repo enforces XML-doc comments or treats warnings as errors, it may need a local .editorconfig relaxing rules like CS1591 on the test snippets.
<root>.analyzers.codefixes - the CodeFixProviders. A separate assembly because a code fix references the Roslyn Workspaces layer, which RS1022 forbids in the analyzer assembly. Only needed when you ship fixes; see the code-fix section in design.md.
Ship the analyzer inside your library's NuGet package, not as its own package. A pack target adds the analyzer and code-fix assemblies to analyzers/dotnet/cs/ in the library's .nupkg, and an OutputItemType="Analyzer" project reference from the library project dogfoods the analyzers against its own sources.

Workflow

Run step 0. Rule out existing analyzers (existing-analyzers.md). If one fits, configure it and stop - no new code.
Pick the diagnostic ID and descriptor. A stable <PREFIX>#### ID (a short uppercase prefix unique to your project, e.g. ABCD0001), category, default severity, helpLinkUri. Add the row to AnalyzerReleases.Unshipped.md in the same change or RS2000 fails.
Design the analyzer to the statelessness, registration, and IOperation-vs-syntax rules in design.md. Copy the shape of a known-good analyzer.
Validate with positive, negative, and boundary cases per validation.md. Run in Debug and Release.
Check performance against the in-IDE budget in performance.md: cheap syntactic filter first, semantic model only after, symbols cached once per compilation, EnableConcurrentExecution().
Decide whether to dogfood it on your own source. If yes, the analyzer must be clean against the existing tree or scoped off where it shouldn't apply - e.g. a directory-level .editorconfig that disables the rule for generated or ported code that should be exempt.
Self-review and ship. Run the pre-pr-self-review skill; new public diagnostic surface needs tests, and a perf claim needs a measurement.

Deep dives

existing-analyzers.md - the find-first survey: SDK CA/IDE rules, BannedApiAnalyzers, EditorConfig naming, PublicApiAnalyzers, Roslynator/StyleCop/Meziantou/Sonar, and how to tell what is already active.
design.md - authoring rules: stateless and thread-safe, narrowest registration, IOperation over raw syntax, descriptors, release tracking, and a note on code-fix providers.
validation.md - testing: the Microsoft.CodeAnalysis.Testing markup harness, a lightweight in-memory harness, the coverage checklist, and the dogfood probe.
performance.md - the in-IDE performance budget, the cheap-first rule, per-compilation symbol caching, concurrency, allocation hygiene, and how to measure with ReportAnalyzer.

Cross-skill

Validate library runtime perf (not analyzer perf) with performance-testing.
Run pre-pr-self-review before opening a PR; create-pr to publish.
If the analyzer parses or reinterprets untrusted input, run security-review.
For a rule about struct copies (defensive-copy / [NonCopyable] analyzers), il-copy-inspection is the post-build, ground-truth counterpart: it reads emitted IL to confirm a prediction and to find the compiler-synthesized copies an IOperation-based analyzer cannot see.
A consuming repository wires the concrete analyzer-project names, the example analyzer to copy from, the diagnostic-ID prefix, and these cross-references in its overlay.

Disambiguation

"Performance" means two different things here. Tuning how fast the analyzer runs inside the IDE is this skill (performance.md). Measuring how fast the library code runs at execution time with BenchmarkDotNet is performance-testing. They do not share a harness or a budget.

More from this repository

same repository

filtrace

JeremyKuhne/touki

Analyze .NET CPU, allocation, exception, GC, JIT, and wall-clock (thread-time) data in .nettrace, .etl, and speedscope files with the filtrace CLI or MCP server. Use when a user asks where time or allocation volume goes in a trace or benchmark, which method or source line is hot, why a run regressed against a baseline, what a captured .nettrace / .etl contains, or to rank / drill / diff / export a profile - including profiling .NET Framework (net481) via ETW, where an EventPipe ranking would mislead. Also covers capturing the trace first - choosing EventPipe vs ETW, elevation, and the recording tool (dotnet-trace, BenchmarkDotNet, PerfView, wpr).

2026-07-166

performance-testing

JeremyKuhne/touki

Author and run BenchmarkDotNet performance tests in a multi-targeted .NET library's perf project, and translate a user's outcome-shaped performance question into a measurement. Use when adding new benchmarks, running existing ones, comparing implementations, profiling to find which method or source line dominates, evaluating allocations / memory usage, reading the generated code (sharplab / DisassemblyDiagnoser / HardwareCounters), or when a user asks how long something takes, how much memory it uses, where time is spent, or to help make a method faster - which this skill turns into a scenario, a benchmark, and a drill-down.

2026-07-166

agent-files-review

JeremyKuhne/touki

Review changes to AI-agent customization files (AGENTS.md, .github/copilot-instructions.md, *.instructions.md, *.prompt.md, *.agent.md, SKILL.md, the validator, the CI workflow). Use when asked to review or validate agent-file changes, fix CI failures from the agent-files workflow, or audit a draft of any of these files.

2026-07-156

address-pr-feedback

JeremyKuhne/touki

Address feedback on an existing pull request - review comments, requested changes, CI failures, or any post-PR follow-up work. Use when the user says "address the review", "fix the comments", "address Copilot's feedback", "fix the CI failure", or any similar phrasing. Distinct from `create-pr`, which covers opening the *initial* PR.

2026-07-106

create-pr

JeremyKuhne/touki

Create a pull request for the current changes. Use when asked to "make a PR", "open a pull request", "push and PR", or otherwise publish in-progress work for review. Ensures changes are on a non-`main` branch, commits are made and pushed, and the PR targets `upstream/main` when an `upstream` remote exists, otherwise `origin/main`.

2026-07-106

code-comprehension

JeremyKuhne/touki

Evidence-based readability and cognitive-load review of code. Use when asked to "review this for readability", "is this too complex", "reduce nesting or cognitive load", "what is a reasonable method length / parameter count / nesting depth", or when judging whether code will be hard to understand. Screens code against research-backed thresholds and prioritizes the factors that actually drive comprehension - naming first, then structure that loads working memory.

2026-07-106

compatibility	Requires the .NET SDK, Roslyn packages, and a test project capable of running Microsoft.CodeAnalysis.Testing fixtures.
description	Design, build, validate, and ship a Roslyn analyzer (and optional code fix) in a dedicated analyzer project. Use when asked to "write an analyzer", "create a Roslyn/diagnostic analyzer", "add an analyzer rule", "add a code fix", "enforce a convention at build time", or "flag a pattern in code". ALWAYS starts by checking whether an existing analyzer suite (the .NET SDK CA/IDE rules, BannedApiAnalyzers, an EditorConfig rule, Roslynator, StyleCop, Meziantou, etc.) already covers the request before authoring anything new. Covers the netstandard2.0 project layout, packing the analyzer into your library's NuGet package, the statelessness/concurrency and IOperation-vs-syntax design rules, the Microsoft.CodeAnalysis.Testing validation harness, and the in-IDE performance discipline. For BenchmarkDotNet runtime microbenchmarks see `performance-testing`; for auditing untrusted-input handling see `security-review`.
license	MIT
metadata	{"applicability":"dotnet-project-gated","binding":"optional-overlay","github-path":"skills/roslyn-analyzers","github-pinned":"v0.10.0","github-ref":"refs/tags/v0.10.0","github-repo":"https://github.com/JeremyKuhne/agent-skills","github-tree-sha":"0456189352ca224c2a9323e44eb883da455027dd","maturity":"canary","portability":"portable","related":"performance-testing, security-review, pre-pr-self-review, il-copy-inspection","requires":"none","risk":"local-write"}
name	roslyn-analyzers

Roslyn analyzers

If overlay.md exists beside this file, read it before acting; it contains repository-specific bindings. This core remains usable without it.

Step 0 - the prime directive: is it already covered?

The short version, in priority order:

An existing rule + .editorconfig severity (the .NET SDK CA*/IDE* analyzers are on by default). Cheapest possible answer.
A configuration-only analyzer - BannedApiAnalyzers (ban a type/member), an EditorConfig naming rule, PublicApiAnalyzers (lock public surface). No custom code.
A third-party suite already in the graph or worth adding - Roslynator, StyleCop, Meziantou, SonarAnalyzer.
Only if none fit - author a custom analyzer. Continue below.

Where analyzers live (the project layout)

By convention the analyzer ships as a small cluster of projects alongside the library it guards (<root> is the library project name):

<root>.analyzers - the analyzer assembly. netstandard2.0, EnforceExtendedAnalyzerRules=true, IsPackable=false, IncludeBuildOutput=false, signed. Needs both AnalyzerReleases.Shipped.md and AnalyzerReleases.Unshipped.md or RS2008 fails the build.
<root>.analyzers.tests - a modern .NET test project (MSTest / xUnit). If your repo enforces XML-doc comments or treats warnings as errors, it may need a local .editorconfig relaxing rules like CS1591 on the test snippets.
<root>.analyzers.codefixes - the CodeFixProviders. A separate assembly because a code fix references the Roslyn Workspaces layer, which RS1022 forbids in the analyzer assembly. Only needed when you ship fixes; see the code-fix section in design.md.
Ship the analyzer inside your library's NuGet package, not as its own package. A pack target adds the analyzer and code-fix assemblies to analyzers/dotnet/cs/ in the library's .nupkg, and an OutputItemType="Analyzer" project reference from the library project dogfoods the analyzers against its own sources.

Workflow

Run step 0. Rule out existing analyzers (existing-analyzers.md). If one fits, configure it and stop - no new code.
Pick the diagnostic ID and descriptor. A stable <PREFIX>#### ID (a short uppercase prefix unique to your project, e.g. ABCD0001), category, default severity, helpLinkUri. Add the row to AnalyzerReleases.Unshipped.md in the same change or RS2000 fails.
Design the analyzer to the statelessness, registration, and IOperation-vs-syntax rules in design.md. Copy the shape of a known-good analyzer.
Validate with positive, negative, and boundary cases per validation.md. Run in Debug and Release.
Check performance against the in-IDE budget in performance.md: cheap syntactic filter first, semantic model only after, symbols cached once per compilation, EnableConcurrentExecution().
Decide whether to dogfood it on your own source. If yes, the analyzer must be clean against the existing tree or scoped off where it shouldn't apply - e.g. a directory-level .editorconfig that disables the rule for generated or ported code that should be exempt.
Self-review and ship. Run the pre-pr-self-review skill; new public diagnostic surface needs tests, and a perf claim needs a measurement.

Deep dives

existing-analyzers.md - the find-first survey: SDK CA/IDE rules, BannedApiAnalyzers, EditorConfig naming, PublicApiAnalyzers, Roslynator/StyleCop/Meziantou/Sonar, and how to tell what is already active.
design.md - authoring rules: stateless and thread-safe, narrowest registration, IOperation over raw syntax, descriptors, release tracking, and a note on code-fix providers.
validation.md - testing: the Microsoft.CodeAnalysis.Testing markup harness, a lightweight in-memory harness, the coverage checklist, and the dogfood probe.
performance.md - the in-IDE performance budget, the cheap-first rule, per-compilation symbol caching, concurrency, allocation hygiene, and how to measure with ReportAnalyzer.

Cross-skill

Validate library runtime perf (not analyzer perf) with performance-testing.
Run pre-pr-self-review before opening a PR; create-pr to publish.
If the analyzer parses or reinterprets untrusted input, run security-review.
For a rule about struct copies (defensive-copy / [NonCopyable] analyzers), il-copy-inspection is the post-build, ground-truth counterpart: it reads emitted IL to confirm a prediction and to find the compiler-synthesized copies an IOperation-based analyzer cannot see.
A consuming repository wires the concrete analyzer-project names, the example analyzer to copy from, the diagnostic-ID prefix, and these cross-references in its overlay.