skills.rest
peterblazejewicz
peterblazejewiczCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

documentation-and-adrs

Writes ADRs, XML doc comments, OpenAPI metadata, and READMEs for .NET projects.

7|Updated Jan 11, 2026
Search Tags:#documentation#openapi#adr#readme#dotnet#architecture-decisions#xml-doc-comments
One-click install
npx skills add https://github.com/peterblazejewicz/claude-plugins --skill documentation-and-adrs-peterblazejewicz
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: documentation-and-adrs
Source: https://github.com/peterblazejewicz/claude-plugins/tree/main/plugins/dotnet-skills/skills/documentation-and-adrs
Command: npx skills add https://github.com/peterblazejewicz/claude-plugins --skill documentation-and-adrs-peterblazejewicz

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Architectural decisions and their rationale are often lost, forcing teams and AI agents to re-debate settled choices and leaving public APIs undocumented. This Skill captures the why behind .NET technical decisions in durable, structured documentation. ## Core Features & Use Cases - Architecture Decision Records (ADRs): Provides a numbered ADR template (Context, Decision, Alternatives Considered, Consequences) stored in docs/adr/, with a PROPOSED → ACCEPTED → SUPERSEDED lifecycle. - API Documentation: Covers XML doc comments with <summary>, <remarks>, and <exception> tags, plus OpenAPI/Swagger metadata for ASP.NET Core Minimal APIs. - README & Changelog Templates: Supplies README structures with dotnet CLI commands, global.json notes, and changelog guidance tied to NuGet versioning (MinVer, Nerdbank.GitVersioning). - Use Case: After choosing PostgreSQL with EF Core over Dapper and MongoDB, use this Skill to write ADR-001 documenting the alternatives considered and consequences, so future engineers never re-litigate the decision. ## Quick Start Ask the agent to write an ADR documenting your recent architectural decision, such as choosing EF Core over Dapper for your data layer.

Frequently Asked Questions about documentation-and-adrs

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write an architecture decision record for a .NET project?▼

Create a numbered Markdown file in docs/adr/ with sections for Status, Date, Context, Decision, Alternatives Considered, and Consequences. Document each rejected option with pros, cons, and the rejection reason, then mark the ADR as Accepted.

When should I write an ADR instead of a code comment?▼

Write an ADR for decisions that are expensive to reverse, such as choosing EF Core vs Dapper, REST vs gRPC, or a hosting platform. Use inline comments only to explain non-obvious intent in code, and reference the ADR for full rationale.

How do I add OpenAPI documentation to ASP.NET Core Minimal APIs?▼

Chain metadata methods on the endpoint: WithName, WithSummary, WithDescription, Produces, and WithOpenApi. Commit the generated swagger.json when it forms part of your contract with external consumers.

Should old ADRs be deleted when a decision changes?▼

No, old ADRs capture historical context and should be kept. When a decision changes, write a new ADR that references and supersedes the previous one, following the PROPOSED to ACCEPTED to SUPERSEDED lifecycle.

When should I not write documentation or comments?▼

Skip comments that restate what self-explanatory code already does, avoid TODO comments for work you should do now, and never leave commented-out code. Do not document throwaway prototypes or obvious implementations.

Related Skills

Explore More Software Engineering Skills→
emaarcoemaarco
3

create-adr

Create MADR-format Architectural Decision Records in the docs/adr/ directory.

Community
Intermediate
23prime23prime

writing-markdown

Create and edit Markdown files conforming to markdownlint and editorconfig rules.

Community
Basic
DataDogDataDog
417

write-comment

Enforces comment-writing conventions for Ruby code in the dd-trace-rb repository.

Official
Intermediate
Busboom-FooBusboom-Foo

oop

Apply small code changes directly to master with a deterministic test workflow.

Official
Intermediate