Write and review C# XML documentation comments for public and complex internal APIs, including summaries, remarks, examples, cref links, parameters, returns, constructors, properties, and exceptions. Use when asked for C# documentation best practices or XML comments.
Convert C# APIs into precise XML documentation comments that describe behavior, parameters, return values, examples, exceptions, and cross-references using Microsoft-style phrasing.
When to invoke
"Add XML docs to this C# API."
"Review these C# documentation comments."
"What should the <param> and <returns> text say?"
"Document exceptions and examples for this method."
API coverage
API surface
Documentation expectation
Public types and members
Document with XML comments.
Internal members
Document when complex, non-obvious, or not self-explanatory, or part of a testable/internal contract.
Overrides and interface implementations
Use <inheritdoc/> unless behavior materially changes; document differences when it does.
Exceptions
Document exceptions thrown directly and nested exceptions users are likely to encounter.
Common XML tags
Tag
Use
<summary>
Brief one-sentence description. Start with a present-tense, third-person verb.
<remarks>
Extra context, implementation notes, or usage constraints.
<see langword="null" />
language-specific keywords through <see langword> such as null, true, false, int, and bool.
<c>
Inline code snippets.
<example>
Usage examples.
<code language="csharp">
Code blocks inside <example>; the <code> tag should carry a language attribute such as language="csharp".
<see cref="TypeOrMember" />
Inline reference in a sentence.
<seealso cref="TypeOrMember" />
Standalone See also reference.
<inheritdoc/>
Inherit base or interface documentation.
<paramref name="name" />
Reference a parameter in prose.
<typeparamref name="T" />
Reference a generic type parameter in prose.
Methods and generics
Element
Wording rule
<param>
Use a noun phrase that does not specify the data type and begins with an introductory article.
Flag enum parameter
Start with "A bitwise combination of the enumeration values that specifies...".
Non-flag enum parameter
Start with "One of the enumeration values that specifies..." and treat it as a non-flag enum.
Boolean parameter
Use "<see langword="true" /> to ...; otherwise, <see langword="false" />."
out parameter
Use "When this method returns, contains ... . This parameter is treated as uninitialized."
<typeparam>
Describe generic type parameters.
<returns>
Use a noun phrase that does not specify the data type and begins with an introductory article.
Boolean return
Use "<see langword="true" /> if ...; otherwise, <see langword="false" />."
Constructors, properties, and exceptions
Member
Required phrasing
Constructor summary
"Initializes a new instance of the <Class> class." or "Initializes a new instance of the <Class> struct."
Read-write property
Start <summary> with "Gets or sets..." for a read-write property.
Read-only property
Start <summary> with "Gets..." for a read-only property.
Boolean property
Start with "Gets a value that indicates whether..." or "Gets or sets a value that indicates whether...".
<value>
Describe the property value as a noun phrase; include default in a separate sentence when known.
Boolean <value>
Use "<see langword="true" /> if ...; otherwise, <see langword="false" />. The default is ..." when a default is known.
<exception cref="...">
State the condition directly; omit "Thrown if" and initial "If". The baseline shorthand is <exception cref>.
Examples
Good
/// <summary>
/// Gets a value that indicates whether the cache contains the specified key.
/// </summary>
/// <param name="key">The key to locate.</param>
/// <returns><see langword="true" /> if the cache contains <paramref name="key" />; otherwise, <see langword="false" />.</returns>
Bad
/// <summary>Checks a string key and returns bool.</summary>
/// <param name="key">String key.</param>
/// <returns>Boolean result.</returns>
Gotchas
Do not restate the type: parameter and return descriptions should explain meaning, not string, int, or bool.
Do not use vague summaries: describe observable behavior, not "Does the thing".
Do not overuse <inheritdoc/>: document behavior differences explicitly.
Do not document impossible exceptions: list exceptions users can actually encounter.
Public APIs have XML comments; complex internal APIs are documented when needed.
<summary> starts with a present-tense, third-person verb.
Parameters, type parameters, returns, values, and exceptions use the required wording patterns.
Boolean, enum, flag enum, and out parameter wording follows the specialized rules.
Examples use <example> with <code language="csharp"> when code blocks are included in XML docs.
Cross-references use <see cref>, <seealso>, <paramref>, and <typeparamref> where appropriate.
1---2name: csharp-docs-23description: Write and review C# XML documentation comments for public and complex internal APIs, including summaries, remarks, examples, cref links, parameters, returns, constructors, properties, and exceptions. Use when asked for C# documentation best practices or XML comments.4---56# C# XML documentation78Convert C# APIs into precise XML documentation comments that describe behavior, parameters, return values, examples, exceptions, and cross-references using Microsoft-style phrasing.910## When to invoke1112- "Add XML docs to this C# API."13- "Review these C# documentation comments."14- "What should the `<param>` and `<returns>` text say?"15- "Document exceptions and examples for this method."1617## API coverage1819| API surface | Documentation expectation |20| --- | --- |21| Public types and members | Document with XML comments. |22| Internal members | Document when complex, non-obvious, or not self-explanatory, or part of a testable/internal contract. |23| Overrides and interface implementations | Use `<inheritdoc/>` unless behavior materially changes; document differences when it does. |24| Exceptions | Document exceptions thrown directly and nested exceptions users are likely to encounter. |2526## Common XML tags2728| Tag | Use |29| --- | --- |30| `<summary>` | Brief one-sentence description. Start with a present-tense, third-person verb. |31| `<remarks>` | Extra context, implementation notes, or usage constraints. |32| `<see langword="null" />` | `language-specific` keywords through `<see langword>` such as `null`, `true`, `false`, `int`, and `bool`. |33| `<c>` | Inline code snippets. |34| `<example>` | Usage examples. |35| `<code language="csharp">` | Code blocks inside `<example>`; the `<code>` tag should carry a `language` attribute such as `language="csharp"`. |36| `<see cref="TypeOrMember" />` | Inline reference in a sentence. |37| `<seealso cref="TypeOrMember" />` | Standalone See also reference. |38| `<inheritdoc/>` | Inherit base or interface documentation. |39| `<paramref name="name" />` | Reference a parameter in prose. |40| `<typeparamref name="T" />` | Reference a generic type parameter in prose. |4142## Methods and generics4344| Element | Wording rule |45| --- | --- |46| `<param>` | Use a noun phrase that does not specify the data type and begins with an introductory article. |47| Flag enum parameter | Start with "A bitwise combination of the enumeration values that specifies...". |48| Non-flag enum parameter | Start with "One of the enumeration values that specifies..." and treat it as a non-flag enum. |49| Boolean parameter | Use "`<see langword="true" />` to ...; otherwise, `<see langword="false" />`." |50| `out` parameter | Use "When this method returns, contains ... . This parameter is treated as uninitialized." |51| `<typeparam>` | Describe generic type parameters. |52| `<returns>` | Use a noun phrase that does not specify the data type and begins with an introductory article. |53| Boolean return | Use "`<see langword="true" />` if ...; otherwise, `<see langword="false" />`." |5455## Constructors, properties, and exceptions5657| Member | Required phrasing |58| --- | --- |59| Constructor summary | "Initializes a new instance of the `<Class>` class." or "Initializes a new instance of the `<Class>` struct." |60| Read-write property | Start `<summary>` with "Gets or sets..." for a read-write property. |61| Read-only property | Start `<summary>` with "Gets..." for a read-only property. |62| Boolean property | Start with "Gets a value that indicates whether..." or "Gets or sets a value that indicates whether...". |63| `<value>` | Describe the property value as a noun phrase; include default in a separate sentence when known. |64| Boolean `<value>` | Use "`<see langword="true" />` if ...; otherwise, `<see langword="false" />`. The default is ..." when a default is known. |65| `<exception cref="...">` | State the condition directly; omit "Thrown if" and initial "If". The baseline shorthand is `<exception cref>`. |6667## Examples6869### Good7071```csharp72/// <summary>73/// Gets a value that indicates whether the cache contains the specified key.74/// </summary>75/// <param name="key">The key to locate.</param>76/// <returns><see langword="true" /> if the cache contains <paramref name="key" />; otherwise, <see langword="false" />.</returns>77```7879### Bad8081```csharp82/// <summary>Checks a string key and returns bool.</summary>83/// <param name="key">String key.</param>84/// <returns>Boolean result.</returns>85```8687## Gotchas8889- **Do not restate the type**: parameter and return descriptions should explain meaning, not `string`, `int`, or `bool`.90- **Do not use vague summaries**: describe observable behavior, not "Does the thing".91- **Do not overuse `<inheritdoc/>`**: document behavior differences explicitly.92- **Do not document impossible exceptions**: list exceptions users can actually encounter.9394## Output template9596````markdown97## C# documentation result9899**Target:** `<type or member>`100101```csharp102/// <summary>103/// <present-tense third-person description>.104/// </summary>105/// <param name="<name>"><noun phrase>.</param>106/// <returns><noun phrase or Boolean wording>.</returns>107/// <exception cref="<ExceptionType>"><condition>.</exception>108```109110### Documentation notes111- `<summary>`: <why this wording fits>112- `<param>`: <parameter wording decisions>113- `<returns>`: <return wording decisions>114- `<exception>`: <exception coverage>115````116117## Quality gate118119- [ ] Public APIs have XML comments; complex internal APIs are documented when needed.120- [ ] `<summary>` starts with a present-tense, third-person verb.121- [ ] Parameters, type parameters, returns, values, and exceptions use the required wording patterns.122- [ ] Boolean, enum, flag enum, and `out` parameter wording follows the specialized rules.123- [ ] Examples use `<example>` with `<code language="csharp">` when code blocks are included in XML docs.124- [ ] Cross-references use `<see cref>`, `<seealso>`, `<paramref>`, and `<typeparamref>` where appropriate.
Run npx skillmds@latest add paulasilvatech/csharp-docs-2 in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
Write and review C# XML documentation comments for public and complex internal APIs, including summaries, remarks, examples, cref links, parameters, returns, constructors, properties, and exceptions. Use when asked for C# documentation best practices or XML comments. It is listed under Docs & Writing on SkillMD.
This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
paulasilvatech (@paulasilvatech) published this skill. Their other Agent Skills are listed on their SkillMD profile.
paulasilvatech