Guide · Agent skill
How to use the .NET upgrade agent skill (dotnet-upgrade)
Updated · written with AI from the project's own documentation and checked against our catalogue data
The dotnet-upgrade skill is a bundle of prepared prompts for planning an upgrade of older .NET projects, including .NET Framework and .NET Core or .NET Standard, to a modern version such as .NET 8. It is aimed at engineering teams, developers working on multi-project solutions, and tech leads who need planning and communication templates. After this guide you will know what the skill does, how to install it, how to ask for it in plain language, and where its limits are.
ND .NET Upgrade Promptsgithub/awesome-copilot · MIT Download the skill Quick start
- 1Download the ZIP. Get the dotnet-upgrade skill as a ZIP from the page where you found this guide.
- 2Unzip it into a skills folder. Extract it into ~/.claude/skills/ for personal use, or into .claude/skills/ inside a project for project-only use.
- 3Or upload it in the Claude apps. In the Claude apps, open Settings, go to Capabilities, then Skills, and upload the skill.
- 4Ask a specific upgrade question. Name your current framework, the target such as .NET 8, and the task, for example ordering projects or finding legacy packages.
- 5Review every suggestion. Check package versions, pipeline edits and code changes yourself, since the skill only supplies prompts and does not run upgrade tools.
- 6Run your own build and tests. Use your existing build and test suites, and tools such as the .NET Upgrade Assistant if you choose, to validate the upgraded solution.
What does the dotnet-upgrade skill make the agent do?
An agent skill is a folder containing instructions that an AI agent can load when a request matches the skill. This one contains a SKILL.md file with a long list of named prompts, grouped into areas such as project discovery, upgrade strategy, NuGet and dependency management, CI/CD pipelines, testing, breaking-change analysis, version control, documentation and tooling.
The prompts cover the planning side of a migration: classifying each project by type, checking dependency compatibility, finding legacy packages.config projects, proposing an upgrade order and incremental strategy with rollback checkpoints, suggesting CI/CD pipeline changes, and drafting test plans, PR structure, review checklists and release notes.
The skill only provides guidance and templates. It does not run any upgrade tool and does not modify your code. The prompts do name tools such as the .NET Upgrade Assistant, dotnet list package --outdated, dotnet migrate and API Analyzer, and suggest when to use them, but you run those yourself.
How do you install the dotnet-upgrade skill?
Download the ZIP of the skill from the page where you found this guide. Unzip it into one of two locations, depending on how you want to use it. A personal install goes in your home folder under ~/.claude/skills/. A project install goes in the .claude/skills/ folder inside a specific project, so it applies only to that repository.
If you use the Claude apps instead of a local folder, you can upload the skill there. Open Settings, go to Capabilities, and then Skills, and upload the skill from there.
- Personal install: unzip into ~/.claude/skills/
- Project install: unzip into .claude/skills/ inside your project folder
- Claude apps: Settings → Capabilities → Skills, then upload
~/.claude/skills/How do you trigger the skill with a natural request?
You do not need a special command. Describe what you want in ordinary language that matches the upgrade work the skill covers. Name the framework you are coming from and the target, for example .NET 8, and point the agent at your solution or projects. Good requests mention a concrete task, such as ordering projects, finding packages that lack .NET 8 support, or drafting a PR description.
Being specific helps the agent pick the right prompt area. A request that names a single task usually produces a more useful answer than a general request to upgrade everything at once.
- Classify the projects in this solution by framework and list their TargetFramework values.
- Find legacy packages.config projects and tell me what needs migrating to PackageReference.
- Propose an upgrade order for these projects, starting with the least dependent ones.
- Draft a PR title and description for upgrading this class library to .NET 8, with a test checklist.
- Which third-party libraries here lack .NET 8 support, and what are the migration paths?
What kinds of output can you expect?
Expect planning output: classifications, ordered lists, checklists, draft pipeline snippets, test scenarios and document templates. The prompts ask for suggestions such as TargetFramework values like net8.0, replacements for deprecated APIs such as WebHostBuilder to HostBuilder, and the Startup.cs to Program.cs refactoring review.
Treat every suggestion as a draft. The prompts describe their output as suggestions, so a person needs to review the recommended versions, pipeline edits and code changes, and test them before relying on them.
Who should use this skill, and who should not?
The skill fits teams planning a migration from .NET Framework or older .NET Core to .NET 8, developers who want a structured checklist for a multi-project solution, and tech leads who need draft PR, testing and stakeholder templates.
It is a poor fit for small, simple projects that Microsoft's own tooling can upgrade directly, because the prompts add planning overhead. It is also the wrong expectation if you want an agent that rewrites code or runs the upgrade automatically.
What does the skill need, and what are the safety notes?
The skill lists no requirements. It does not run scripts and does not use the network, according to its listing. Its only file is SKILL.md, which contains prompt text.
Because it only supplies prompts, it does not change your repository by itself. Any changes come from what you and your agent choose to do afterwards, so review diffs, pipeline edits and package version changes before merging, and run your own build and test suites.
- Runs scripts: no
- Uses network: no
- Files included: SKILL.md
- Requirements listed: none
Tips for getting useful results
Work one project or one area at a time instead of asking for a full migration in a single request. Ask for the upgrade order first, then the package review, then the pipeline changes. Keep the outputs in your repository as a markdown checklist so the team can track progress across projects.
- Start with classification and dependency review before asking for code-level changes.
- Ask for rollback checkpoints in the incremental strategy so each step can be reverted.
- Use the PR structure and review prompts to standardise commit and PR titles such as Upgrade to .NET 8.
- Verify every package version the agent suggests against the library's own documentation.
What people use it for
- Planning the upgrade order for a multi-project solution, starting with the least dependent class libraries.
- Finding packages.config projects that need migrating to PackageReference before moving to .NET 8.
- Drafting a PR title, description and review checklist for an upgrade to .NET 8.
- Listing third-party libraries that lack .NET 8 support and noting possible migration paths.
- Creating a markdown upgrade checklist that tracks build, test and deployment readiness per project.
Frequently asked questions
Is the dotnet-upgrade skill free to use?
The skill is published under the MIT licence on the github/awesome-copilot repository. Check the licence file in the repository for the full terms before reusing it.
What do I need installed to use dotnet-upgrade?
The skill lists no requirements and does not run scripts. You need an agent environment that supports skills, such as the Claude apps or a local setup that reads a skills folder.
Where do I put the dotnet-upgrade skill folder?
Unzip it into ~/.claude/skills/ for personal use, or into .claude/skills/ inside a project for that project only. In the Claude apps, upload it under Settings, then Capabilities, then Skills.
Does dotnet-upgrade upgrade my code automatically?
No. The skill contains only prompt text and does not run an upgrade tool. Its suggestions still need human review and testing.
Is this skill better than Microsoft's upgrade tools?
It does not replace them. The prompts recommend when to use tools such as the .NET Upgrade Assistant and dotnet list package --outdated, and they add planning, checklist and communication templates. For small, simple projects, Microsoft's tooling alone may be enough.
Why does the agent give generic answers when I use dotnet-upgrade?
Requests that cover the whole migration at once tend to produce broad output. Name one project, one framework pair such as .NET Framework to .NET 8, and one task, and share the relevant .csproj or packages.config details.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use dotnet-upgrade if you are planning a migration from .NET Framework or older .NET Core to .NET 8 and want structured prompts for ordering, package review, pipelines and PR templates. Skip it for a small project that Microsoft's own tooling can upgrade directly, or if you expect an agent to rewrite and run the upgrade for you.
Download the skill