AGENT SKILL

dotnet-local-tools

Managing local .NET tools with dotnet-tools.json for consistent tooling across development environments and CI/CD pipelines.

License 许可
MIT
最近更新
2026-11-13
Stars
★ 1
Forks
0

01 前言 Front Matter

name
dotnet-local-tools
description
Managing local .NET tools with dotnet-tools.json for consistent tooling across development environments and CI/CD pipelines.

03 SKILL.md 正文

.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:

  1. Global tool with different version: dotnet tool list -g
  2. Multiple tool manifests: Look for .config/dotnet-tools.json in 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

04 同仓库更多 Skills

Blind-Striker
Blind-Striker/agent-skills-and-plugins

writing-tunit-tests

Write tests in TUnit — the attributes, the async assertion model, data-driven cases, lifecycle hooks, and the parallelism rules. USE FOR writing or fixing a test in a TUnit project, translating a test idea into TUnit syntax, or reviewing TUnit test code for API mistakes. DO NOT USE FOR deciding what to test, judging whether a test is any good, or running tests.

★ 1
Blind-Striker
Blind-Striker/agent-skills-and-plugins

dotnet-walls

Walls for a .NET change in a repository without its own quality gates — pinned, ephemeral analyzer, format, clone and scanner commands for the verify step, their identity ratchet, and the build traps. Use during a walls preflight, or when a worker's verify step needs .NET quality gates.

★ 1
Blind-Striker
Blind-Striker/agent-skills-and-plugins

csharp-15

Write, review and modernize C# 15 (.NET 11) code correctly. Covers every C# 15 feature - collection expression arguments (`[with(...), ...]`), union types (`union`, `[Union]`, `IUnion`, custom unions), closed class hierarchies (`closed`), extension indexers, labeled `break`/`continue`, non-virtual static interface members on runtimes without default interface methods, and the preview memory-safety model (`unsafe(expr)`, `safe`, requires-unsafe members). Use when code targets net11.0 or LangVersion 15/preview, when the user mentions any of these features, when replacing marker interfaces, OneOf-style results, `goto`/flag loop exits or capacity/comparer boilerplate, or when the build reports CS8121, CS8509, CS8655, CS8510, CS0121/CS0411 on a `with(...)` element, CS9370, CS9380 or CS9363.

★ 1
Blind-Striker
Blind-Striker/agent-skills-and-plugins

verified-waves

Run one task as verified multi-agent waves. Plans the fan-out, sends findings to fresh skeptics, keeps a ledger, and reports N of M done; small tasks stay solo.

★ 1
Blind-Striker
Blind-Striker/agent-skills-and-plugins

harness

The bundled dispatch harness, which runs a task file on worker models through OpenCode or Codex, fences their writes, escalates their asks to the operator, settles each result from git and its verify commands, and records every step in a ledger. Its commands, task file, modes and write fence, configuration, runs and their recovery, ledger and exit codes.

★ 1
Blind-Striker
Blind-Striker/agent-skills-and-plugins

delegating-to-worker-models

Use when you hand off implementation, a plan, research a decision will rely on, or a review, and you brief the worker and check what comes back. A subagent that searches, reads in parallel, or keeps your context small is ordinary tool use. Covers what stays with you, the mechanism, assigning work by strength, the walls preflight, prompts without contradictions, the worker contract and model profiles, evidence from your own run, review, and the fix-up loop.

★ 1