# How to Use the .NET Template Engine for Project Scaffolding

> Master the .NET template engine for efficient project scaffolding. Discover, create, and validate templates with this guide to the dotnet skills repository.

- Repository: [.NET Platform/skills](https://github.com/dotnet/skills)
- Tags: how-to-guide
- Published: 2026-07-07

---

**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`](https://github.com/dotnet/skills/blob/main/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`](https://github.com/dotnet/skills/blob/main/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`](https://github.com/dotnet/skills/blob/main/plugins/dotnet-template-engine/skills/template-discovery/SKILL.md) |
| **template-authoring** | Bootstraps reusable templates from existing projects and validates [`template.json`](https://github.com/dotnet/skills/blob/main/template.json) configuration. | [`plugins/dotnet-template-engine/skills/template-authoring/SKILL.md`](https://github.com/dotnet/skills/blob/main/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`](https://github.com/dotnet/skills/blob/main/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`](https://github.com/dotnet/skills/blob/main/plugins/dotnet-template-engine/plugin.json). This file groups the skill set and optional agent definitions, making them discoverable to the Skills runtime:

```json
{
  "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:

```bash

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

```bash
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:

```bash
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:

```bash

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

```bash

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

```bash

# 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`](https://github.com/dotnet/skills/blob/main/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`](https://github.com/dotnet/skills/blob/main/plugins/dotnet-template-engine/skills/template-authoring/SKILL.md) bootstraps reusable templates from existing projects. It generates the required [`.template.config/template.json`](https://github.com/dotnet/skills/blob/main/.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`](https://github.com/dotnet/skills/blob/main/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.