How to use the ASP.NET Minimal API with OpenAPI agent skill

What does the skill make the agent do?

Once the skill is installed, the agent follows a set of best-practice rules whenever you ask it to create Minimal API endpoints. The guidance covers three areas: how endpoints are organised, how request and response types are written, and how the API is documented.

The skill is guidance only. It does not run anything itself, so the agent writes or edits code based on these rules and you still build and test the project yourself.

• Organise endpoints with the MapGroup() extension and, for larger APIs, separate endpoint classes or a feature-based folder structure.
• Define explicit request and response DTOs or record types with validation attributes such as [Required].
• Return TypedResults and Results<T1, T2> so each endpoint has clear, strongly typed responses.
• Document the API with the built-in OpenAPI support in .NET 9, including summaries, descriptions, operation IDs set with WithName, and document or schema transformers.
• Use [Description()] on properties and parameters and set proper content types.

Who should use it, and who should not?

The skill suits C# developers building small or medium web APIs on .NET 9 or later, and teams that want consistent, well-documented Minimal API code. It also fits developers who want OpenAPI documentation added to existing Minimal API endpoints.

It is not a good match for projects that use MVC controllers or older .NET versions. The guidance targets Minimal APIs and .NET 9 OpenAPI features, so the agent may need to adapt the advice. Non-developers without a .NET project will not get much value, because the skill assumes an existing C# codebase to write into.

What do you need before installing?

You need the .NET 9 SDK or later and an ASP.NET Core project that uses Minimal APIs. The skill assumes there is already a C# codebase for the agent to write into.

• .NET 9 SDK or later
• An ASP.NET Core project using Minimal APIs
• The skill package includes one file, SKILL.md

How do you install the skill?

Download the ZIP from this page and unzip it. You can install the skill in one of two ways.

For a personal install that works across your projects, unzip it into ~/.claude/skills/. To limit it to one project, unzip it into that project's .claude/skills/ folder.

In the Claude apps you can instead upload the skill under Settings → Capabilities → Skills.

• Personal: unzip into ~/.claude/skills/
• Project only: unzip into the project's .claude/skills/ folder
• Claude apps: Settings → Capabilities → Skills, then upload

How do you trigger the skill with natural requests?

You do not need a special command. Ask the agent in plain language to build or document Minimal API endpoints in your C# project, and the skill guidance applies. Mention OpenAPI, Swagger, typed results or endpoint grouping if you want the agent to lean into those areas.

Give the agent the context it needs: the resource, the operations and the fields. The more specific the request, the more useful the output.

• Create a Minimal API endpoint group for orders with GET, POST and DELETE, and document it with OpenAPI.
• Add OpenAPI summaries, descriptions and operation IDs to my existing Minimal API endpoints.
• Refactor my Minimal API routes to use MapGroup and return TypedResults.
• Add validation attributes to my request models and show the 400 responses in the OpenAPI document.

What does good output look like?

Expect the agent to group related routes with MapGroup(), define request and response types as records or classes with validation attributes, return TypedResults, and add WithName and summary metadata to each endpoint. Check that the code compiles against your .NET 9 project and that the generated OpenAPI document shows the summaries and operation IDs you expect.

Because the skill covers error responses through ProblemDetailsService and StatusCodePages, review how errors are returned and confirm they match what your clients expect.

• Check the project builds on the .NET 9 SDK or later.
• Confirm operation IDs and summaries appear in the OpenAPI document.
• Review validation rules against your real business requirements.

Is it safe to use?

The skill does not run scripts and does not use the network. It is a SKILL.md guidance file. Because it only shapes how the agent writes code, the main risk is the code the agent produces, so review changes as you would any pull request.

• Runs scripts: no
• Uses network: no

Tips for better results

Keep your project's existing conventions in mind and tell the agent about them, since the skill gives general best practice rather than your house style. Ask for one feature at a time so the diff stays reviewable.

• State whether you use a feature-based folder structure or separate endpoint classes.
• Ask for document transformers if you need servers, tags or security schemes in the output.
• Ask for schema transformers when you need to customise individual OpenAPI schemas.