ComeOnOliver/skillshub / skills/Aaronontheweb/dotnet-skills/local-tools
dotnet-local-tools
VerifiedManaging local .NET tools with dotnet-tools.json for consistent tooling across development environments and CI/CD pipelines.
.NET Local Tools
When to Use This Skill
Use this skill when:
- Setting up consistent tooling across a development team
- Ensuring CI/CD pipelines use the same tool versions as local development
- Managing project-specific CLI tools (docfx, incrementalist, dotnet-ef, etc.)
- Avoiding global tool version conflicts between projects
What Are Local Tools?
Local tools are .NET CLI tools that are installed and versioned per-repository rather than globally. They're defined in .config/dotnet-tools.json and restored with dotnet tool restore.
Local vs Global Tools
| Aspect | Global Tools | Local Tools |
|---|---|---|
| Installation | dotnet tool install -g | dotnet tool restore |
| Scope | Machine-wide | Per-repository |
| Version control | Manual | In .config/dotnet-tools.json |
| CI/CD | Must install each tool | Single restore command |
| Conflicts | Can have version conflicts | Isolated per project |
Setting Up Local Tools
Initialize the Manifest
# Create .config/dotnet-tools.json
dotnet new tool-manifest
This creates:
.config/
└── dotnet-tools.json
Install Tools Locally
# Install a tool locally
dotnet tool install docfx
# Install specific version
dotnet tool install docfx --version 2.78.3
# Install from a specific source
dotnet tool install MyTool --add-source https://mycompany.pkgs.visualstudio.com/_packaging/feed/nuget/v3/index.json
Restore Tools
# Restore all tools from manifest
dotnet tool restore
dotnet-tools.json Format
{
"version": 1,
"isRoot": true,
"tools": {
"docfx": {
"version": "2.78.3",
"commands": [
"docfx"
],
"rollForward": false
},
"dotnet-ef": {
"version": "9.0.0",
"commands": [
"dotnet-ef"
],
"rollForward": false
},
"incrementalist.cmd": {
"version": "1.2.0",
"commands": [
"incrementalist"
],
"rollForward": false
},
"dotnet-reportgenerator-globaltool": {
"version": "5.4.1",
"commands": [
"reportgenerator"
],
"rollForward": false
}
}
}
Fields
| Field | Description |
|---|---|
version | Manifest schema version (always 1) |
isRoot | Marks this as the root manifest (prevents searching parent directories) |
tools | Dictionary of tool configurations |
tools.<name>.version | Exact version to install |
tools.<name>.commands | CLI commands the tool provides |
tools.<name>.rollForward | Allow newer versions (usually false for reproducibility) |
Common Tools
Documentation
# DocFX - API documentation generator
dotnet tool install docfx
"docfx": {
"version": "2.78.3",
"commands": ["docfx"],
"rollForward": false
}
Usage:
dotnet docfx docfx.json
dotnet docfx serve _site
Entity Framework Core
# EF Core CLI for migrations
dotnet tool install dotnet-ef
"dotnet-ef": {
"version": "9.0.0",
"commands": ["dotnet-ef"],
"rollForward": false
}
Usage:
dotnet ef migrations add InitialCreate
dotnet ef database update
Code Coverage
# ReportGenerator for coverage reports
dotnet tool install dotnet-reportgenerator-globaltool
"dotnet-reportgenerator-globaltool": {
"version": "5.4.1",
"commands": ["reportgenerator"],
"rollForward": false
}
Usage:
dotnet reportgenerator -reports:coverage.cobertura.xml -targetdir:coveragereport -reporttypes:Html
Incremental Builds
# Incrementalist - build only changed projects
dotnet tool install incrementalist.cmd
"incrementalist.cmd": {
"version": "1.2.0",
"commands": ["incrementalist"],
"rollForward": false
}
Usage:
# Get projects affected by changes since main branch
incrementalist --branch main
Code Formatting
# CSharpier - opinionated C# formatter
dotnet tool install csharpier
"csharpier": {
"version": "0.30.3",
"commands": ["dotnet-csharpier"],
"rollForward": false
}
Usage:
dotnet csharpier .
dotnet csharpier --check . # CI mode - fails if changes needed
Code Analysis
# JB dotnet-inspect (requires license)
dotnet tool install jb
"jb": {
"version": "2024.3.4",
"commands": ["jb"],
"rollForward": false
}
CI/CD Integration
GitHub Actions
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup .NET
uses: actions/setup-dotnet@v4
with:
global-json-file: global.json
- name: Restore tools
run: dotnet tool restore
- name: Build
run: dotnet build
- name: Test with coverage
run: dotnet test --collect:"XPlat Code Coverage"
- name: Generate coverage report
run: dotnet reportgenerator -reports:**/coverage.cobertura.xml -targetdir:coveragereport
- name: Build documentation
run: dotnet docfx docs/docfx.json
Azure Pipelines
steps:
- task: UseDotNet@2
inputs:
useGlobalJson: true
- script: dotnet tool restore
displayName: 'Restore .NET tools'
- script: dotnet build -c Release
displayName: 'Build'
- script: dotnet test -c Release --collect:"XPlat Code Coverage"
displayName: 'Test'
- script: dotnet reportgenerator -reports:**/coverage.cobertura.xml -targetdir:$(Build.ArtifactStagingDirectory)/coverage
displayName: 'Generate coverage report'
Managing Tool Versions
Update a Tool
# Update to latest version
dotnet tool update docfx
# Update to specific version
dotnet tool update docfx --version 2.79.0
List Installed Tools
# List local tools
dotnet tool list
# List with outdated check
dotnet tool list --outdated
Remove a Tool
dotnet tool uninstall docfx
Best Practices
1. Always Set isRoot: true
Prevents MSBuild from searching parent directories for tool manifests:
{
"version": 1,
"isRoot": true,
...
}
2. Pin Exact Versions
Use "rollForward": false for reproducible builds:
"docfx": {
"version": "2.78.3",
"rollForward": false
}
3. Restore in CI Before Use
Always run dotnet tool restore before using any local tool:
- run: dotnet tool restore
- run: dotnet docfx docs/docfx.json
4. Document Tool Requirements
Add a comment or section in README:
## Development Setup
1. Restore tools: `dotnet tool restore`
2. Build: `dotnet build`
3. Test: `dotnet test`
5. Use Dependabot for Updates
# .github/dependabot.yml
version: 2
updates:
- package-ecosystem: "nuget"
directory: "/"
schedule:
interval: "weekly"
# Includes local tools in .config/dotnet-tools.json
Troubleshooting
Tool Not Found After Restore
Ensure you're running from the repository root:
# Wrong - running from subdirectory
cd src/MyApp
dotnet docfx # Error: tool not found
# Correct - run from solution root
cd ../..
dotnet docfx docs/docfx.json
Version Conflicts
If you see version conflicts, check for:
- Global tool with different version:
dotnet tool list -g - Multiple tool manifests: Look for
.config/dotnet-tools.jsonin parent directories
Clearing Tool Cache
# Clear NuGet tool cache
dotnet nuget locals all --clear
# Re-restore tools
dotnet tool restore
Example: Complete Development Setup
{
"version": 1,
"isRoot": true,
"tools": {
"docfx": {
"version": "2.78.3",
"commands": ["docfx"],
"rollForward": false
},
"dotnet-ef": {
"version": "9.0.0",
"commands": ["dotnet-ef"],
"rollForward": false
},
"dotnet-reportgenerator-globaltool": {
"version": "5.4.1",
"commands": ["reportgenerator"],
"rollForward": false
},
"csharpier": {
"version": "0.30.3",
"commands": ["dotnet-csharpier"],
"rollForward": false
},
"incrementalist.cmd": {
"version": "1.2.0",
"commands": ["incrementalist"],
"rollForward": false
}
}
}
Development workflow:
# Initial setup
dotnet tool restore
# Format code before commit
dotnet csharpier .
# Run tests with coverage
dotnet test --collect:"XPlat Code Coverage"
dotnet reportgenerator -reports:**/coverage.cobertura.xml -targetdir:coverage
# Build documentation
dotnet docfx docs/docfx.json
# Check which projects changed (for large repos)
incrementalist --branch main
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |