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-docs3description: 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<!-- Generated from harness/github-copilot/skills/csharp-docs/SKILL.md by harness/claude-code/scripts/convert_from_copilot.py. Edit the source, not this file. -->78# C# XML documentation910Convert C# APIs into precise XML documentation comments that describe behavior, parameters, return values, examples, exceptions, and cross-references using Microsoft-style phrasing.1112## When to invoke1314- "Add XML docs to this C# API."15- "Review these C# documentation comments."16- "What should the `<param>` and `<returns>` text say?"17- "Document exceptions and examples for this method."1819## API coverage2021| API surface | Documentation expectation |22| --- | --- |23| Public types and members | Document with XML comments. |24| Internal members | Document when complex, non-obvious, or not self-explanatory, or part of a testable/internal contract. |25| Overrides and interface implementations | Use `<inheritdoc/>` unless behavior materially changes; document differences when it does. |26| Exceptions | Document exceptions thrown directly and nested exceptions users are likely to encounter. |2728## Common XML tags2930| Tag | Use |31| --- | --- |32| `<summary>` | Brief one-sentence description. Start with a present-tense, third-person verb. |33| `<remarks>` | Extra context, implementation notes, or usage constraints. |34| `<see langword="null" />` | `language-specific` keywords through `<see langword>` such as `null`, `true`, `false`, `int`, and `bool`. |35| `<c>` | Inline code snippets. |36| `<example>` | Usage examples. |37| `<code language="csharp">` | Code blocks inside `<example>`; the `<code>` tag should carry a `language` attribute such as `language="csharp"`. |38| `<see cref="TypeOrMember" />` | Inline reference in a sentence. |39| `<seealso cref="TypeOrMember" />` | Standalone See also reference. |40| `<inheritdoc/>` | Inherit base or interface documentation. |41| `<paramref name="name" />` | Reference a parameter in prose. |42| `<typeparamref name="T" />` | Reference a generic type parameter in prose. |4344## Methods and generics4546| Element | Wording rule |47| --- | --- |48| `<param>` | Use a noun phrase that does not specify the data type and begins with an introductory article. |49| Flag enum parameter | Start with "A bitwise combination of the enumeration values that specifies...". |50| Non-flag enum parameter | Start with "One of the enumeration values that specifies..." and treat it as a non-flag enum. |51| Boolean parameter | Use "`<see langword="true" />` to ...; otherwise, `<see langword="false" />`." |52| `out` parameter | Use "When this method returns, contains ... . This parameter is treated as uninitialized." |53| `<typeparam>` | Describe generic type parameters. |54| `<returns>` | Use a noun phrase that does not specify the data type and begins with an introductory article. |55| Boolean return | Use "`<see langword="true" />` if ...; otherwise, `<see langword="false" />`." |5657## Constructors, properties, and exceptions5859| Member | Required phrasing |60| --- | --- |61| Constructor summary | "Initializes a new instance of the `<Class>` class." or "Initializes a new instance of the `<Class>` struct." |62| Read-write property | Start `<summary>` with "Gets or sets..." for a read-write property. |63| Read-only property | Start `<summary>` with "Gets..." for a read-only property. |64| Boolean property | Start with "Gets a value that indicates whether..." or "Gets or sets a value that indicates whether...". |65| `<value>` | Describe the property value as a noun phrase; include default in a separate sentence when known. |66| Boolean `<value>` | Use "`<see langword="true" />` if ...; otherwise, `<see langword="false" />`. The default is ..." when a default is known. |67| `<exception cref="...">` | State the condition directly; omit "Thrown if" and initial "If". The baseline shorthand is `<exception cref>`. |6869## Examples7071### Good7273```csharp74/// <summary>75/// Gets a value that indicates whether the cache contains the specified key.76/// </summary>77/// <param name="key">The key to locate.</param>78/// <returns><see langword="true" /> if the cache contains <paramref name="key" />; otherwise, <see langword="false" />.</returns>79```8081### Bad8283```csharp84/// <summary>Checks a string key and returns bool.</summary>85/// <param name="key">String key.</param>86/// <returns>Boolean result.</returns>87```8889## Gotchas9091- **Do not restate the type**: parameter and return descriptions should explain meaning, not `string`, `int`, or `bool`.92- **Do not use vague summaries**: describe observable behavior, not "Does the thing".93- **Do not overuse `<inheritdoc/>`**: document behavior differences explicitly.94- **Do not document impossible exceptions**: list exceptions users can actually encounter.9596## Output template9798````markdown99## C# documentation result100101**Target:** `<type or member>`102103```csharp104/// <summary>105/// <present-tense third-person description>.106/// </summary>107/// <param name="<name>"><noun phrase>.</param>108/// <returns><noun phrase or Boolean wording>.</returns>109/// <exception cref="<ExceptionType>"><condition>.</exception>110```111112### Documentation notes113- `<summary>`: <why this wording fits>114- `<param>`: <parameter wording decisions>115- `<returns>`: <return wording decisions>116- `<exception>`: <exception coverage>117````118119## Quality gate120121- [ ] Public APIs have XML comments; complex internal APIs are documented when needed.122- [ ] `<summary>` starts with a present-tense, third-person verb.123- [ ] Parameters, type parameters, returns, values, and exceptions use the required wording patterns.124- [ ] Boolean, enum, flag enum, and `out` parameter wording follows the specialized rules.125- [ ] Examples use `<example>` with `<code language="csharp">` when code blocks are included in XML docs.126- [ ] Cross-references use `<see cref>`, `<seealso>`, `<paramref>`, and `<typeparamref>` where appropriate.
Run npx skillmds@latest add paulasilvatech/csharp-docs 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