Repository navigation
documentation for dotnet-package-skills tool - #3
kartheekp-ms wants to merge 2 commits into
Conversation
Added documentation for the 'dotnet-package-skills' command, detailing its usage, commands, options, and examples.
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
The documentation incorrectly guarantees that packages are never downloaded despite describing implicit restore behavior.
Review effort: Balanced
Findings: 1
What changed in this PR
Documents the proposed dotnet-package-skills tool and its package-supplied skill management workflow.
Changes:
- Documents installation, commands, options, and examples.
- Explains manifests, interactive selection, stale skills, and troubleshooting.
| File | Description |
|---|---|
designs/dotnet-package-skills.md |
Adds comprehensive command documentation. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| > [!IMPORTANT] | ||
| > Skills are instructions that your coding agent follows. Review them before you rely on them. | ||
|
|
||
| The command reads only the direct package references of your solution or project, not the packages that they depend on. It doesn't download packages or change your project files. |
| | If you've... | `install`... | | ||
| | --- | --- | | ||
| | Added a package that ships skills | Copies its skills. | | ||
| | Upgraded or downgraded a package | Replaces its skills with those of the new version, and removes the ones that the new version no longer ships. | |
There was a problem hiding this comment.
Below, it says uninstall --stale is required to remove them. Does updating just do that directly or does it also require the explicit option?
I would imagine there's a dependency management concern here, right? If 2 packages rely on the same dependent SKILL (let's call it Skill_A), and I upgrade the 1st of those packages...
If that 1st package no longer uses the dependent Skill_A,, do we accidentally delete Skill_A from disk and break the 2nd package (which still depends on it)?
There was a problem hiding this comment.
Good questions.
Upgrades don't need --stale. When a package moves to a new version, a plain install refreshes its skills and removes the ones that the new version no longer ships, in the same run. uninstall --stale is only for packages that were removed from the project: install keeps their skills and lists them, and removing them is a separate, explicit step.
Shared skills: skills aren't resolved like package dependencies. Each package ships its own skills, the tool reads only the project's direct package references, and each installed skill folder belongs to exactly one package in .dotnet-package-skills.json. On a version change, install only removes skills recorded under that package, so upgrading package 1 can't delete a skill that belongs to package 2.
Where this could bite is two packages shipping a skill with the same folder name. Only one copy can be installed, so one package owns it and the other package's copy is skipped with a warning. If the owner's new version drops that skill, install doesn't delete it or quietly hand it to the other package. It stops without changing anything:
error: Cannot install skills because Alpha 2.0.0 no longer ships the installed skill 'shared', and Beta 2.0.0 ships a skill with that name. The tool doesn't hand an installed skill to another package, and the manifest records one version per package, so it can't keep the older copy either. Run 'dotnet-package-skills uninstall --package Alpha' first, and then try again. No skills were changed.
After that uninstall, install copies Alpha 2.0.0's skills and Beta's shared.
I updated the table and the paragraph on skill names to spell out both points in 05ad656.
There was a problem hiding this comment.
Thanks for addressing this!
My first impression is the Warning is a little long. What do you think about having install provide the same "stale" shortcut as uninstall, where when running the install command with --stale (or perhaps --uninstall-stale) bypasses the warning and just performs the necessary removals?
This way if customers don't care about changing existing dependent skills, they don't have to respond to a warning by uninstalling those dependencies manually.
Address review feedback. Say that install removes the skills that a package's new version no longer ships, without uninstall --stale, which is only for packages removed from the project. Also say that each tracked skill belongs to one package, so changing one package's version never removes another package's skills, and that install stops without changing anything when a package's new version drops a skill whose name another package ships. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: f17ba583-22d3-4855-8e8b-f2a338b3390b
Added documentation for the 'dotnet-package-skills' command, detailing its usage, commands, options, and examples.
I have created this PR to get feedback on the new .NET tool, it's options and subcommands and its functionality.