NuGet manager
Add and remove NuGet packages in projects/solutions. through the dotnet CLI, update existing package versions only after verifying the target version exists, and immediately restore to catch compatibility failures.
When to invoke
- "Add this NuGet package to my project."
- "Remove Newtonsoft.Json from this .NET project."
- "Update a package version in Directory.Packages.props."
- "Verify that this NuGet version exists."
- "Fix package references in a .csproj."
Prerequisites and context
| Requirement |
Why |
| .NET SDK compatible with the target solution |
Provides dotnet add, dotnet remove, dotnet restore, and dotnet test if needed. |
dotnet on PATH |
All add/remove operations must use the CLI. |
jq or PowerShell |
Needed to parse dotnet package search <PACKAGE_NAME> --exact-match --format json for exact version verification. |
Use dotnet package search for version lookup. Treat .props files as package metadata files, not general edit targets.
Core rules
| Operation |
Allowed method |
Forbidden method |
| Add package |
dotnet add [<PROJECT>] package <PACKAGE_NAME> [--version <VERSION>] |
Directly editing .csproj, .props, or Directory.Packages.props; NEVER direct-edit for adds. |
| Remove package |
dotnet remove [<PROJECT>] package <PACKAGE_NAME> |
Directly deleting <PackageReference> or <PackageVersion> entries. |
| Update existing version |
Verify the version, locate the version owner, edit only the version string, run dotnet restore. |
Changing versions without checking NuGet or restoring; DIRECT EDITING is ONLY for VERSION UPDATES. |
| Central package management |
Edit <PackageVersion Include="Package.Name" Version="1.2.3" /> in Directory.Packages.props. |
Adding/removing central package entries by hand instead of using CLI-supported workflows when possible. |
| Per-project package management |
Edit the Version on an existing <PackageReference Include="Package.Name" Version="1.2.3" />. |
Moving packages between project and central management without a clear migration request. |
Procedure
- Identify the solution, project, and package operation: add, remove, or update version.
- For add/remove, run the
dotnet CLI command against the intended project or solution scope.
- For version updates, verify the exact target version exists before editing.
- Determine whether versions are centrally managed by searching for
Directory.Packages.props; otherwise inspect individual .csproj files.
- Change only the existing version string in the owning file.
- Run
dotnet restore on the project or solution immediately.
- If restore fails, revert the version change and report the compatibility blocker.
Commands and version verification
| Task |
Command |
| Add package |
dotnet add src/MyProject/MyProject.csproj package Newtonsoft.Json |
| Add specific version |
dotnet add src/MyProject/MyProject.csproj package <PACKAGE_NAME> --version <VERSION> |
| Remove package |
dotnet remove src/MyProject/MyProject.csproj package Newtonsoft.Json |
| Search exact package |
dotnet package search <PACKAGE_NAME> --exact-match --format json and parse the JSON result. |
Verify version with jq |
`dotnet package search --exact-match --format json |
| Verify version with PowerShell |
`(dotnet package search --exact-match --format json |
| Restore |
dotnet restore |
Examples
| User request |
Correct action |
| "Add Serilog to the WebApi project" |
Run dotnet add src/WebApi/WebApi.csproj package Serilog. |
| "Update Newtonsoft.Json to 13.0.3 in the whole solution" |
Verify 13.0.3, locate Directory.Packages.props or .csproj, update the version string, then run dotnet restore. |
| "Remove Newtonsoft.Json" |
Run dotnet remove [<PROJECT>] package Newtonsoft.Json for each intended project. |
Gotchas
- Never add or remove packages by editing XML: the CLI updates related restore metadata consistently.
- Direct editing is only for version changes: even then, edit the file that already owns the version.
- Central package management changes the target file:
Directory.Packages.props overrides per-project expectations.
- Restore immediately: a version that exists on NuGet can still be incompatible with the project.
Output template
## NuGet package result
**Status:** complete | reverted | blocked
**Operation:** add | remove | update-version
**Package:** `<PACKAGE_NAME>`
**Target:** `<solution or project>`
| Step | Command or file | Result |
| --- | --- | --- |
| Verify | `<dotnet package search ...>` | pass | fail | not needed |
| Change | `<dotnet add/remove ...>` or `<file>` | <summary> |
| Restore | `dotnet restore` | pass | fail |
### Notes
- <compatibility issue, central package file, or revert detail>
Quality gate
1---2name: nuget-manager-33description: Manage NuGet packages safely in .NET projects and solutions using the `dotnet` CLI. Use this skill when adding, removing, or updating package versions, verifying `PACKAGE_NAME` availability, working with `Directory.Packages.props`, or deciding when direct `.csproj` edits are allowed.4---56<!-- Generated from harness/github-copilot/plugins/dotnet-desktop-development/skills/nuget-manager/SKILL.md by harness/claude-code/scripts/convert_from_copilot.py. Edit the source, not this file. -->78# NuGet manager910Add and remove NuGet packages in projects/solutions. through the `dotnet` CLI, update existing package versions only after verifying the target version exists, and immediately restore to catch compatibility failures.1112## When to invoke1314- "Add this NuGet package to my project."15- "Remove Newtonsoft.Json from this .NET project."16- "Update a package version in Directory.Packages.props."17- "Verify that this NuGet version exists."18- "Fix package references in a .csproj."1920## Prerequisites and context2122| Requirement | Why |23| --- | --- |24| .NET SDK compatible with the target solution | Provides `dotnet add`, `dotnet remove`, `dotnet restore`, and `dotnet test` if needed. |25| `dotnet` on `PATH` | All add/remove operations must use the CLI. |26| `jq` or PowerShell | Needed to parse `dotnet package search <PACKAGE_NAME> --exact-match --format json` for exact version verification. |2728Use `dotnet package search` for version lookup. Treat `.props` files as package metadata files, not general edit targets.2930## Core rules3132| Operation | Allowed method | Forbidden method |33| --- | --- | --- |34| Add package | `dotnet add [<PROJECT>] package <PACKAGE_NAME> [--version <VERSION>]` | Directly editing `.csproj`, `.props`, or `Directory.Packages.props`; NEVER direct-edit for adds. |35| Remove package | `dotnet remove [<PROJECT>] package <PACKAGE_NAME>` | Directly deleting `<PackageReference>` or `<PackageVersion>` entries. |36| Update existing version | Verify the version, locate the version owner, edit only the version string, run `dotnet restore`. | Changing versions without checking NuGet or restoring; DIRECT EDITING is ONLY for VERSION UPDATES. |37| Central package management | Edit `<PackageVersion Include="Package.Name" Version="1.2.3" />` in `Directory.Packages.props`. | Adding/removing central package entries by hand instead of using CLI-supported workflows when possible. |38| Per-project package management | Edit the `Version` on an existing `<PackageReference Include="Package.Name" Version="1.2.3" />`. | Moving packages between project and central management without a clear migration request. |3940## Procedure41421. Identify the solution, project, and package operation: add, remove, or update version.432. For add/remove, run the `dotnet` CLI command against the intended project or solution scope.443. For version updates, verify the exact target version exists before editing.454. Determine whether versions are centrally managed by searching for `Directory.Packages.props`; otherwise inspect individual `.csproj` files.465. Change only the existing version string in the owning file.476. Run `dotnet restore` on the project or solution immediately.487. If restore fails, revert the version change and report the compatibility blocker.4950## Commands and version verification5152| Task | Command |53| --- | --- |54| Add package | `dotnet add src/MyProject/MyProject.csproj package Newtonsoft.Json` |55| Add specific version | `dotnet add src/MyProject/MyProject.csproj package <PACKAGE_NAME> --version <VERSION>` |56| Remove package | `dotnet remove src/MyProject/MyProject.csproj package Newtonsoft.Json` |57| Search exact package | `dotnet package search <PACKAGE_NAME> --exact-match --format json` and parse the JSON result. |58| Verify version with `jq` | `dotnet package search <PACKAGE_NAME> --exact-match --format json | jq -e '.searchResult[].packages[] | select(.version == "<VERSION>")'` |59| Verify version with PowerShell | `(dotnet package search <PACKAGE_NAME> --exact-match --format json | ConvertFrom-Json).searchResult.packages | Where-Object { $_.version -eq "<VERSION>" }` |60| Restore | `dotnet restore` |6162## Examples6364| User request | Correct action |65| --- | --- |66| "Add Serilog to the WebApi project" | Run `dotnet add src/WebApi/WebApi.csproj package Serilog`. |67| "Update Newtonsoft.Json to 13.0.3 in the whole solution" | Verify `13.0.3`, locate `Directory.Packages.props` or `.csproj`, update the version string, then run `dotnet restore`. |68| "Remove Newtonsoft.Json" | Run `dotnet remove [<PROJECT>] package Newtonsoft.Json` for each intended project. |6970## Gotchas7172- **Never add or remove packages by editing XML**: the CLI updates related restore metadata consistently.73- **Direct editing is only for version changes**: even then, edit the file that already owns the version.74- **Central package management changes the target file**: `Directory.Packages.props` overrides per-project expectations.75- **Restore immediately**: a version that exists on NuGet can still be incompatible with the project.7677## Output template7879```markdown80## NuGet package result8182**Status:** complete | reverted | blocked83**Operation:** add | remove | update-version84**Package:** `<PACKAGE_NAME>`85**Target:** `<solution or project>`8687| Step | Command or file | Result |88| --- | --- | --- |89| Verify | `<dotnet package search ...>` | pass | fail | not needed |90| Change | `<dotnet add/remove ...>` or `<file>` | <summary> |91| Restore | `dotnet restore` | pass | fail |9293### Notes94- <compatibility issue, central package file, or revert detail>95```9697## Quality gate9899- [ ] Add and remove operations used `dotnet add package` or `dotnet remove package`.100- [ ] Direct file editing was limited to changing an existing package version.101- [ ] Target versions were verified with `dotnet package search <PACKAGE_NAME> --exact-match --format json` before editing.102- [ ] Version ownership was resolved to `Directory.Packages.props` or the correct `.csproj`.103- [ ] `dotnet restore` ran after the change, or failure to run was reported.104- [ ] Failed restores caused the version change to be reverted or clearly marked blocked.
paulasilvatech