How to Use the .NET Template Engine for Project Scaffolding

The .NET template engine exposes a deterministic, skill-based workflow for project scaffolding through four specialized capabilities—template discovery, instantiation, authoring, and validation—implemented as markdown-driven skills in the dotnet/skills repository.

The .NET template engine powers the familiar dotnet new command and is exposed through reusable scaffolding skills in the dotnet/skills repository. These declarative skills handle everything from natural-language intent resolution to Central Package Management (CPM) adaptation, providing a deterministic approach to project generation that works across single-project and multi-project solutions.

Core Skills and Architecture

The template engine functionality is organized into four discrete skills defined in markdown-based SKILL files. Each skill handles a specific phase of the scaffolding lifecycle according to the plugin descriptor at plugins/dotnet-template-engine/plugin.json.

The Four Primary Skills

Skill	Purpose	Source Path
template-instantiation	Creates projects from templates, handles CPM adaptation, fetches NuGet versions, and composes multi-project solutions.	plugins/dotnet-template-engine/skills/template-instantiation/SKILL.md
template-discovery	Resolves natural-language intent to concrete templates, lists installed templates, and previews output.	plugins/dotnet-template-engine/skills/template-discovery/SKILL.md
template-authoring	Bootstraps reusable templates from existing projects and validates template.json configuration.	plugins/dotnet-template-engine/skills/template-authoring/SKILL.md
template-validation	Enforces schema compliance, detects short-name conflicts, and verifies parameter correctness.	plugins/dotnet-template-engine/skills/template-validation/SKILL.md

Plugin Configuration

The skills are aggregated through the plugin descriptor located at plugins/dotnet-template-engine/plugin.json. This file groups the skill set and optional agent definitions, making them discoverable to the Skills runtime:

{
  "name": "dotnet-template-engine",
  "version": "0.1.0",
  "description": ".NET Template Engine skills for dotnet new: create projects …",
  "skills": ["./skills/"],
  "agents": ["./agents/template-engine.agent.md"]
}

The Project Scaffolding Workflow

According to the source code in the dotnet/skills repository, the template engine implements a six-step deterministic workflow:

1. Intent → Discovery – Natural-language requests (e.g., "web API with auth") are mapped to short template names via template-discovery.
2. Parameter Resolution – The discovery skill executes dotnet new <template> --help sequentially (with mutex retry logic) to obtain authoritative parameter lists.
3. Preview – The engine runs dotnet new <template> --dry-run to display files and folders that would be generated without writing to disk.
4. Creation – template-instantiation executes the real dotnet new command with resolved parameters.
5. Post-creation Adaptation – If Directory.Packages.props is detected, the skill strips inline package versions from .csproj files and migrates them to the central file for CPM compliance.
6. Verification – The skill runs dotnet build and optionally dotnet sln add to ensure scaffolded code compiles out-of-the-box.

Practical Implementation Examples

Discover Available Templates

To resolve natural-language intent to a concrete template, use the discovery commands:

# Search for web API templates

dotnet new search webapi

# List installed templates

dotnet new list | grep webapi

# View specific template parameters

dotnet new webapi --help

Preview Generation

Before creating files, preview the scaffold output using the dry-run flag:

dotnet new webapi \
  --name MyApi \
  --auth Individual \
  --framework net10.0 \
  --dry-run

Create a Single Project

Execute the full instantiation with parameters resolved from the discovery phase:

dotnet new webapi \
  --name MyApi \
  --output ./src/MyApi \
  --auth Individual \
  --framework net10.0

Adapt to Central Package Management

When working in repositories using CPM, the template-instantiation skill automatically adapts newly generated projects. Manual adaptation follows this pattern:

# Detect CPM configuration

if [ -f "$(git rev-parse --show-toplevel)/Directory.Packages.props" ]; then
  # Remove inline versions from PackageReference elements

  find ./src/MyApi -name "*.csproj" -exec sed -i '' -E 's/ Version="[^"]+"//g' {} +
  # Add versions to Directory.Packages.props (manual or scripted)

fi

Multi-Project Solution Scaffolding

Create interconnected projects and wire them together:

# Create API project

dotnet new webapi -n MyApi -o ./src/MyApi --framework net10.0

# Create test project

dotnet new xunit -n MyApi.Tests -o ./tests/MyApi.Tests

# Add project reference

dotnet add ./tests/MyApi.Tests reference ./src/MyApi/MyApi.csproj

# Add to solution

dotnet sln add ./src/MyApi/MyApi.csproj ./tests/MyApi.Tests/MyApi.Tests.csproj

# Verify build

dotnet build

Install Custom Template Packages

Extend the engine with additional templates:

# Install template package

dotnet new install Microsoft.DotNet.Web.ProjectTemplates.10.0

# Remove template package

dotnet new uninstall Microsoft.DotNet.Web.ProjectTemplates.10.0

Summary

• The dotnet/skills repository implements the .NET template engine as four specialized skills: template-instantiation, template-discovery, template-authoring, and template-validation.
• Each skill is defined in markdown-based SKILL files located under plugins/dotnet-template-engine/skills/.
• The scaffolding workflow is deterministic: discovery → parameter resolution → preview → creation → CPM adaptation → verification.
• The engine automatically handles Central Package Management by stripping inline versions from .csproj files when Directory.Packages.props is detected.
• All skills are aggregated through plugins/dotnet-template-engine/plugin.json, making them discoverable to the Skills runtime.

Frequently Asked Questions

How does the .NET template engine handle Central Package Management?

When the template-instantiation skill detects a Directory.Packages.props file in the repository root, it automatically strips inline Version attributes from PackageReference elements in newly generated .csproj files. This migration ensures version consistency across the solution by centralizing package versions in the properties file, then runs dotnet build to verify the adapted project compiles correctly.

Can I create custom templates using the template engine skills?

Yes. The template-authoring skill defined in plugins/dotnet-template-engine/skills/template-authoring/SKILL.md bootstraps reusable templates from existing projects. It generates the required .template.config/template.json configuration file and validates the schema, allowing you to package custom templates for distribution via dotnet new install.

What is the difference between template discovery and template instantiation?

Template-discovery handles the resolution phase: mapping natural-language intent (like "web API") to concrete short names (webapi), listing installed templates, and executing --dry-run previews. Template-instantiation performs the actual project creation, including file generation, CPM adaptation, NuGet version resolution, and post-creation verification via dotnet build.

How does the engine prevent parameter errors during scaffolding?

The template-validation skill enforces schema compliance against template.json definitions, detects short-name conflicts between installed templates, and verifies parameter correctness before execution. This validation occurs declaratively through the skill's markdown definition, ensuring deterministic behavior across different template packages.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}