mirror of
https://github.com/dotnet/skills.git
synced 2026-09-20 09:49:54 +08:00
Add dotnet-template-engine plugin (#341)
* Add dotnet-template-engine plugin Add template-engine skills for .NET project scaffolding powered by the DotnetTemplateMCP MCP server (v1.1.0). Includes three skills and one agent: Skills: - template-discovery: find, inspect, and compare templates with intent resolution (70+ keyword mappings) - template-instantiation: create projects with CPM adaptation, latest NuGet versions, parameter validation, and multi-template composition - template-authoring: create templates from existing projects and validate template.json for authoring issues Agent: - template-engine: expert agent that routes to the appropriate skill based on user intent Also adds CODEOWNERS entries, marketplace.json registration, eval tests, and .mcp.json for DotnetTemplateMCP server configuration. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Address review feedback: mcpServers in plugin.json, expect_tools, path fix - Move MCP server config into plugin.json under mcpServers so SkillValidator discovers the template_* tools during evaluation runs - Add expect_tools constraints to all eval scenarios to verify actual MCP tool invocation instead of relying on rubric text alone - Fix frontmatter path: template.config → .template.config (leading dot) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Update DotnetTemplateMCP to v1.2.0 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Include 'dotnet new' in agent description for discoverability Address review feedback from danmoseley: the frontmatter description is how the caller decides whether to load the agent tokens, so it needs to mention 'dotnet new' as a trigger keyword. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Remove MCP server configuration and references - Delete .mcp.json MCP server config file - Remove mcpServers section from plugin.json - Remove MCP/DotnetTemplateMCP references from agent, skills, and marketplace descriptions - Skills and eval files remain unchanged Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Remove ghost tool references and add CLI fallback guidance - Remove references to 4 non-existent tools: template_compose, template_suggest_parameters, template_validate, solution_analyze - Replace with real alternatives (template_inspect, manual review, sequential template_instantiate, direct file inspection) - Add CLI fallback guidance so LLMs degrade gracefully when template tools are unavailable - Fix authoring eval to not expect template_validate tool Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Address review feedback: CODEOWNERS naming, claude marketplace, README - Rename CODEOWNERS header to dotnet-template-engine for consistency - Mirror plugin entry in .claude-plugin/marketplace.json - Add plugin to README What's Included table Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fix PR review comments: align eval rubric with expect_tools and sync marketplace.json - Updated template-discovery eval.yaml rubric to match expect_tools (removed 'or template_search' since expect_tools enforces template_from_intent) - Made .claude-plugin/marketplace.json byte-for-byte identical to .github/plugin/marketplace.json (removed extra trailing newline) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Address review comments: strengthen eval assertions and fix rubrics - Add exit_success assertions to all eval scenarios - Add file_exists and file_contains assertions for template-instantiation - Add output_contains for shortName and datatype in template-authoring - Fix rubrics to reference actual tools (skill + dotnet new CLI) instead of non-existent MCP tools (template_from_intent, template_inspect, template_instantiate) which caused the judge to penalize quality scores - Update expect_tools from non-existent MCP tools to 'skill' - Change plugin version from 1.2.0 to 0.1.0 for consistency with other plugins - Remove extra blank line in README.md after plugin table Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Rewrite skills and agent to use dotnet new CLI instead of phantom MCP tools The SKILL.md files and agent.md referenced MCP tools (template_from_intent, template_inspect, template_instantiate, template_dry_run, etc.) that are not available at runtime since no MCP server is declared in plugin.json. This caused the agent to waste tokens attempting to find these tools before falling back to dotnet new CLI commands. Changes: - template-discovery/SKILL.md: Replace MCP tool calls with dotnet new search, dotnet new list, dotnet new --help, and dotnet new --dry-run. Add intent-to-template keyword mapping table. - template-instantiation/SKILL.md: Replace template_instantiate with dotnet new CLI commands. Add explicit CPM adaptation steps and multi-project composition with dotnet sln/dotnet add reference. - template-authoring/SKILL.md: Replace template_create_from_existing with manual template.json creation guidance including example JSON. Replace template_dry_run/template_instantiate with CLI equivalents. - template-engine.agent.md: Replace Available Tools table with CLI Commands Reference. Update all workflow steps to use CLI commands. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fix file assertion paths: remove ./ prefix for glob matcher compatibility Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Dan Moseley <danmose@microsoft.com>
This commit is contained in:
YuliiaKovalova
@@ -0,0 +1,112 @@
|
||||
---
|
||||
name: template-engine
|
||||
description: "Expert agent for .NET Template Engine and dotnet new operations — template discovery, project scaffolding, and template authoring. Routes to specialized skills for search, instantiation, and authoring tasks. Verifies template-engine domain relevance before deep-diving."
|
||||
user-invokable: true
|
||||
disable-model-invocation: false
|
||||
---
|
||||
|
||||
# Template Engine Expert Agent
|
||||
|
||||
You are an expert in the .NET Template Engine (`dotnet new`). You help developers find the right template, create projects with correct parameters, and author custom templates.
|
||||
|
||||
## Core Competencies
|
||||
|
||||
- Searching and discovering templates (local and NuGet.org)
|
||||
- Resolving natural-language descriptions to template + parameters
|
||||
- Inspecting template parameters, constraints, and post-actions
|
||||
- Creating projects with validated parameters, CPM adaptation, and latest NuGet versions
|
||||
- Composing multi-project solutions in a single workflow
|
||||
- Authoring and validating custom templates
|
||||
|
||||
## Domain Relevance Check
|
||||
|
||||
Before deep-diving into template operations, verify the context is template-related:
|
||||
|
||||
1. **Quick check**: Is the user asking about creating a new project, finding templates, or authoring templates? Are they using `dotnet new` commands?
|
||||
2. **If yes**: Proceed with template expertise
|
||||
3. **If unclear**: Ask if they need help with project creation or template management
|
||||
4. **If no**: Politely explain that this agent specializes in .NET templates and suggest the appropriate agent (e.g., MSBuild agent for build issues)
|
||||
|
||||
## Triage and Routing
|
||||
|
||||
Classify the user's request and invoke the appropriate skill:
|
||||
|
||||
| User Intent | Skill / Action |
|
||||
|------------|----------------|
|
||||
| "Create a new project/app/service" | `template-instantiation` skill |
|
||||
| "What templates are available for X?" | `template-discovery` skill |
|
||||
| "Show me template details/parameters" | `template-discovery` skill (inspect via `dotnet new <template> --help`) |
|
||||
| "Create a template from my project" | `template-authoring` skill |
|
||||
| "Validate my custom template" | `template-authoring` skill |
|
||||
| "Add a parameter to my template" | `template-authoring` skill |
|
||||
| "Install a template package" | `template-instantiation` skill (install via `dotnet new install`) |
|
||||
| "Create solution + API + tests" | `template-instantiation` skill (sequential creation) |
|
||||
| "Show me the solution structure" | Inspect `.sln` and `.csproj` files directly |
|
||||
|
||||
## Workflow: Creating a Project
|
||||
|
||||
When a user asks to create a new project, follow this workflow:
|
||||
|
||||
### 1. Understand the Intent
|
||||
Ask clarifying questions if needed:
|
||||
- What type of project? (web API, console, library, test, MAUI, etc.)
|
||||
- What framework version? (net10.0, net9.0, etc.)
|
||||
- Any specific features? (auth, AOT, Docker, etc.)
|
||||
- Where should it be created?
|
||||
|
||||
### 2. Find the Template
|
||||
Map the user's description to a template short name (see template-discovery skill for keyword mappings), or use `dotnet new search` for keyword-based search. Present options if multiple matches exist.
|
||||
|
||||
### 3. Inspect Parameters
|
||||
Use `dotnet new <template> --help` to show available parameters and their defaults, types, and choices.
|
||||
|
||||
### 4. Analyze Workspace
|
||||
Inspect the existing project structure: check for `Directory.Packages.props` (CPM), `global.json`, and existing `.csproj` files to determine framework conventions.
|
||||
|
||||
### 5. Preview
|
||||
Use `dotnet new <template> --dry-run` to show what files would be created. Confirm with the user.
|
||||
|
||||
### 6. Create
|
||||
Use `dotnet new <template> --name <name> --output <path>` with all parameters. After creation, adapt to CPM if needed (move package versions to `Directory.Packages.props`).
|
||||
|
||||
### 7. Post-Creation
|
||||
- Add to solution if applicable
|
||||
- Verify the project builds
|
||||
- Suggest next steps (add packages, configure services, add tests)
|
||||
|
||||
## Workflow: Creating a Template
|
||||
|
||||
When a user asks to create a custom template:
|
||||
|
||||
### 1. Analyze the Source Project
|
||||
Read the `.csproj` and create a `.template.config/template.json` that preserves the project's conventions (SDK type, packages, properties). Review the generated template.json.
|
||||
|
||||
### 2. Validate
|
||||
Review the generated `template.json` for required fields (`identity`, `name`, `shortName`), valid parameter datatypes, shortName conflicts with CLI commands, and complete post-action configuration. Use `dotnet new <template> --help` on the installed template to verify metadata.
|
||||
|
||||
### 3. Refine
|
||||
Help the user add parameters, conditional content, post-actions, and constraints.
|
||||
|
||||
### 4. Test
|
||||
Install the template locally with `dotnet new install`, run a dry-run with `dotnet new <template> --dry-run`, then create a test project and verify it builds.
|
||||
|
||||
### 5. Package
|
||||
Guide the user through creating a NuGet package for distribution.
|
||||
|
||||
## CLI Commands Reference
|
||||
|
||||
| Command | Use For |
|
||||
|---------|---------|
|
||||
| `dotnet new search <keyword>` | Finding templates by keyword (local + NuGet.org) |
|
||||
| `dotnet new list [keyword]` | Listing installed templates with optional filters |
|
||||
| `dotnet new <template> --help` | Getting full template parameter details |
|
||||
| `dotnet new <template> --name <name> --output <path>` | Creating projects |
|
||||
| `dotnet new <template> --dry-run` | Previewing creation without writing files |
|
||||
| `dotnet new install <package>` | Installing template packages |
|
||||
| `dotnet new uninstall <package>` | Removing template packages |
|
||||
|
||||
## Cross-Reference
|
||||
|
||||
- **Build failures after project creation** → Route to MSBuild agent (`dotnet-msbuild` plugin)
|
||||
- **NuGet package issues** → Route to MSBuild agent
|
||||
- **Test project setup** → Create with `dotnet new`, match test framework to repo conventions
|
||||
@@ -0,0 +1,7 @@
|
||||
{
|
||||
"name": "dotnet-template-engine",
|
||||
"version": "0.1.0",
|
||||
"description": ".NET Template Engine skills: template discovery, project scaffolding, and template authoring.",
|
||||
"skills": "./skills/",
|
||||
"agents": "./agents/"
|
||||
}
|
||||
@@ -0,0 +1,162 @@
|
||||
---
|
||||
name: template-authoring
|
||||
description: >
|
||||
Guides creation and validation of custom dotnet new templates. Generates templates
|
||||
from existing projects and validates template.json for authoring issues.
|
||||
USE FOR: creating a reusable dotnet new template from an existing project, validating
|
||||
template.json files for schema compliance and parameter issues, bootstrapping
|
||||
.template.config/template.json with correct identity, shortName, parameters, and
|
||||
post-actions, packaging templates as NuGet packages for distribution.
|
||||
DO NOT USE FOR: finding or using existing templates (use template-discovery and
|
||||
template-instantiation), MSBuild project file issues unrelated to template authoring,
|
||||
NuGet package publishing (only template packaging structure).
|
||||
---
|
||||
|
||||
# Template Authoring
|
||||
|
||||
This skill helps an agent create and validate custom `dotnet new` templates. It guides bootstrapping templates from existing projects and validates `template.json` files for authoring issues before publishing.
|
||||
|
||||
## When to Use
|
||||
|
||||
- User wants to create a reusable template from an existing .csproj
|
||||
- User wants to validate a template.json for correctness
|
||||
- User is setting up `.template.config/template.json` from scratch
|
||||
- User wants to package a template for NuGet distribution
|
||||
|
||||
## When Not to Use
|
||||
|
||||
- User wants to find or use existing templates — route to `template-discovery` or `template-instantiation`
|
||||
- User has MSBuild issues unrelated to template authoring — route to `dotnet-msbuild` plugin
|
||||
|
||||
## Inputs
|
||||
|
||||
| Input | Required | Description |
|
||||
|-------|----------|-------------|
|
||||
| Source project path | For creation | Path to the .csproj to use as template source |
|
||||
| template.json path | For validation | Path to an existing template.json to validate |
|
||||
| Template name | For creation | Human-readable name for the template |
|
||||
| Short name | Recommended | Short name for `dotnet new <shortname>` usage |
|
||||
|
||||
## Workflow
|
||||
|
||||
### Step 1: Bootstrap from existing project
|
||||
|
||||
Analyze the source `.csproj` and create a `.template.config/template.json` that preserves the project's conventions:
|
||||
|
||||
1. Create the `.template.config` directory next to the project
|
||||
2. Generate `template.json` with:
|
||||
- `identity` in reverse-DNS format (e.g., `MyOrg.Templates.MyLib`)
|
||||
- `name` as the human-readable template name
|
||||
- `shortName` for `dotnet new <shortname>` usage
|
||||
- `sourceName` set to the project name (enables name replacement)
|
||||
- `classifications` for discoverability (e.g., `["Library"]`)
|
||||
- `tags` with language and type
|
||||
|
||||
Example generated `template.json`:
|
||||
```json
|
||||
{
|
||||
"$schema": "http://json.schemastore.org/template",
|
||||
"author": "MyOrg",
|
||||
"classifications": ["Library"],
|
||||
"identity": "MyOrg.Templates.MyLib",
|
||||
"name": "My Library Template",
|
||||
"shortName": "mylib",
|
||||
"sourceName": "MyLib",
|
||||
"tags": {
|
||||
"language": "C#",
|
||||
"type": "project"
|
||||
},
|
||||
"symbols": {
|
||||
"Framework": {
|
||||
"type": "parameter",
|
||||
"datatype": "choice",
|
||||
"defaultValue": "net9.0",
|
||||
"choices": [
|
||||
{ "choice": "net9.0" },
|
||||
{ "choice": "net10.0" }
|
||||
],
|
||||
"replaces": "net9.0"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Preserve from the source project:
|
||||
- SDK type, package references with metadata (PrivateAssets, IncludeAssets)
|
||||
- Properties (OutputType, TreatWarningsAsErrors)
|
||||
- Central Package Management and shared compile patterns
|
||||
|
||||
### Step 2: Validate template.json
|
||||
|
||||
Read and review the `template.json` for common authoring issues:
|
||||
|
||||
Validation checks to perform:
|
||||
- **Required fields** — verify `identity`, `name`, and `shortName` are present
|
||||
- **Identity format** — use reverse-DNS format (e.g., `MyOrg.Templates.WebApi`)
|
||||
- **Parameter issues** — check datatypes are valid (`string`, `bool`, `choice`, `int`, `float`), choices have defaults, descriptions are present
|
||||
- **ShortName conflicts** — avoid names that collide with built-in CLI commands (`build`, `run`, `test`, `publish`). Check with `dotnet new list` to see if the name is already taken
|
||||
- **Post-action completeness** — verify post-actions have all required configuration
|
||||
- **Tags** — ensure language, type, and classification tags are set for discoverability
|
||||
|
||||
### Step 3: Refine the template
|
||||
|
||||
Based on validation results and user requirements:
|
||||
|
||||
1. **Add parameters** with appropriate types (string, bool, choice), defaults, and descriptions
|
||||
2. **Add conditional content** using `#if` preprocessor directives for optional features
|
||||
3. **Configure post-actions** for solution add, restore, or custom scripts
|
||||
4. **Set constraints** to restrict which SDKs or workloads the template supports
|
||||
5. **Add classifications** and tags for discoverability
|
||||
|
||||
### Step 4: Test the template locally
|
||||
|
||||
1. Install the template from the local directory:
|
||||
```bash
|
||||
dotnet new install ./path/to/template/root
|
||||
```
|
||||
2. Run a dry-run to verify the output:
|
||||
```bash
|
||||
dotnet new mylib --name TestProject --dry-run
|
||||
```
|
||||
3. Create a test project and verify it builds:
|
||||
```bash
|
||||
dotnet new mylib --name TestProject --output ./test-output
|
||||
dotnet build ./test-output/TestProject
|
||||
```
|
||||
4. Verify all parameters produce the expected output
|
||||
|
||||
### Step 5: Package for distribution
|
||||
|
||||
1. Create a `.nuspec` or use `<PackAsTool>` in a packaging `.csproj`
|
||||
2. Include the template directory with `.template.config/template.json`
|
||||
3. Run `dotnet pack` to create the `.nupkg`
|
||||
4. Test installation from the `.nupkg`:
|
||||
```bash
|
||||
dotnet new install ./path/to/package.nupkg
|
||||
```
|
||||
|
||||
## Validation
|
||||
|
||||
- [ ] `template.json` passes manual validation with zero errors
|
||||
- [ ] Template identity and shortName are unique and meaningful
|
||||
- [ ] All parameters have descriptions and appropriate defaults
|
||||
- [ ] Template can be installed, dry-run, and instantiated successfully
|
||||
- [ ] Created projects build cleanly with `dotnet build`
|
||||
- [ ] Conditional content produces correct output for all parameter combinations
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
| Pitfall | Solution |
|
||||
|---------|----------|
|
||||
| Identity format issues | Use reverse-DNS format (e.g., `MyOrg.Templates.WebApi`). Avoid spaces or special characters. |
|
||||
| ShortName conflicts with CLI commands | Avoid names like `build`, `run`, `test`, `publish`. Check by running `dotnet new list` to see if the name is already taken. |
|
||||
| Missing parameter descriptions | Every parameter should have a `description` and `displayName` for discoverability. |
|
||||
| Not testing all parameter combinations | Use `dotnet new <template> --dry-run` with different parameter values to verify conditional content works correctly. |
|
||||
| Hardcoded versions in template | Use `sourceName` replacement for project names and consider parameterizing framework versions. |
|
||||
| Not setting classifications | Add appropriate `classifications` (e.g., `["Web", "API"]`) for template discovery. |
|
||||
|
||||
## More Info
|
||||
|
||||
- [Custom templates for dotnet new](https://learn.microsoft.com/dotnet/core/tools/custom-templates) — official authoring guide
|
||||
- [template.json reference](https://github.com/dotnet/templating/wiki/Reference-for-template.json) — full schema reference
|
||||
- [Template Engine Wiki](https://github.com/dotnet/templating/wiki) — template engine internals
|
||||
@@ -0,0 +1,115 @@
|
||||
---
|
||||
name: template-discovery
|
||||
description: >
|
||||
Helps find, inspect, and compare .NET project templates.
|
||||
Resolves natural-language project descriptions to ranked template matches
|
||||
with pre-filled parameters.
|
||||
USE FOR: finding the right dotnet new template for a task, comparing templates side by
|
||||
side, inspecting template parameters and constraints, understanding what a template
|
||||
produces before creating a project, resolving intent like "web API with auth" to
|
||||
concrete template + parameters.
|
||||
DO NOT USE FOR: actually creating projects (use template-instantiation), authoring
|
||||
custom templates (use template-authoring), MSBuild or build issues (use dotnet-msbuild
|
||||
plugin), NuGet package management unrelated to template packages.
|
||||
---
|
||||
|
||||
# Template Discovery
|
||||
|
||||
This skill helps an agent find, inspect, and select the right `dotnet new` template for a given task using `dotnet new` CLI commands for search, listing, and parameter inspection.
|
||||
|
||||
## When to Use
|
||||
|
||||
- User asks "What templates are available for X?"
|
||||
- User describes a project in natural language ("I need a web API with authentication")
|
||||
- User wants to compare templates or understand parameters before creating a project
|
||||
- User needs to know what a template produces (files, structure) before committing
|
||||
|
||||
## When Not to Use
|
||||
|
||||
- User wants to create a project — route to `template-instantiation` skill
|
||||
- User wants to author or validate a custom template — route to `template-authoring` skill
|
||||
- User is troubleshooting build issues — route to `dotnet-msbuild` plugin
|
||||
|
||||
## Inputs
|
||||
|
||||
| Input | Required | Description |
|
||||
|-------|----------|-------------|
|
||||
| User intent or keywords | Yes | Natural-language description or keywords (e.g., "web API", "console app", "MAUI") |
|
||||
| Language preference | No | C#, F#, or VB — defaults to C# |
|
||||
| Framework preference | No | Target framework (e.g., net10.0, net9.0) |
|
||||
|
||||
## Workflow
|
||||
|
||||
### Step 1: Resolve intent to template candidates
|
||||
|
||||
Map the user's natural-language description to template short names using these common keyword mappings:
|
||||
|
||||
| User Intent | Template | Suggested Parameters |
|
||||
|-------------|----------|---------------------|
|
||||
| web API, REST API | `webapi` | `--auth Individual --use-controllers` if auth requested |
|
||||
| web app, website | `webapp` | |
|
||||
| Blazor, interactive web | `blazor` | |
|
||||
| console app, CLI tool | `console` | |
|
||||
| class library, shared code | `classlib` | |
|
||||
| worker service, background job | `worker` | |
|
||||
| gRPC service | `grpc` | |
|
||||
| MAUI app, mobile app | `maui` | |
|
||||
| test project, unit tests | `xunit`, `mstest`, or `nunit` | |
|
||||
|
||||
### Step 2: Search for templates
|
||||
|
||||
Use `dotnet new search` to find templates by keyword across both locally installed templates and NuGet.org:
|
||||
|
||||
```bash
|
||||
dotnet new search blazor
|
||||
```
|
||||
|
||||
Use `dotnet new list` to show only installed templates, with optional filters:
|
||||
|
||||
```bash
|
||||
dotnet new list --language C# --type project
|
||||
dotnet new list web
|
||||
```
|
||||
|
||||
### Step 3: Inspect template details
|
||||
|
||||
Use `dotnet new <template> --help` to get full parameter details for a specific template — parameter names, types, defaults, and allowed values:
|
||||
|
||||
```bash
|
||||
dotnet new webapi --help
|
||||
```
|
||||
|
||||
### Step 4: Preview output
|
||||
|
||||
Use `dotnet new <template> --dry-run` to show what files and directories a template would create without writing anything to disk:
|
||||
|
||||
```bash
|
||||
dotnet new webapi --name MyApi --auth Individual --dry-run
|
||||
```
|
||||
|
||||
### Step 5: Present findings
|
||||
|
||||
Summarize the best template match with:
|
||||
- Template name and short description
|
||||
- Key parameters and recommended values
|
||||
- What the user should expect (files created, project structure)
|
||||
- Any constraints or prerequisites
|
||||
|
||||
## Validation
|
||||
|
||||
- [ ] At least one template match was found for the user's intent
|
||||
- [ ] Template parameters are explained with types and defaults
|
||||
- [ ] User understands what the template produces before proceeding to creation
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
| Pitfall | Solution |
|
||||
|---------|----------|
|
||||
| Not searching NuGet for templates | If `dotnet new list` shows no matches, use `dotnet new search <keyword>` to find installable templates on NuGet.org. |
|
||||
| Not checking template constraints | Some templates require specific SDKs or workloads. Use `dotnet new <template> --help` to surface constraints before recommending. |
|
||||
| Recommending a template without previewing output | Always use `dotnet new <template> --dry-run` to confirm the template produces what the user expects. |
|
||||
|
||||
## More Info
|
||||
|
||||
- [dotnet new templates](https://learn.microsoft.com/dotnet/core/tools/dotnet-new-sdk-templates) — built-in template reference
|
||||
- [Template Engine Wiki](https://github.com/dotnet/templating/wiki) — template engine internals
|
||||
@@ -0,0 +1,125 @@
|
||||
---
|
||||
name: template-instantiation
|
||||
description: >
|
||||
Creates .NET projects from templates with validated parameters, smart defaults,
|
||||
Central Package Management adaptation, and latest NuGet version resolution.
|
||||
USE FOR: creating new dotnet projects, scaffolding solutions with multiple projects,
|
||||
installing or uninstalling template packages, creating projects that respect
|
||||
Directory.Packages.props (CPM), composing multi-project solutions (API + tests + library),
|
||||
getting latest NuGet package versions in newly created projects.
|
||||
DO NOT USE FOR: finding or comparing templates (use template-discovery), authoring
|
||||
custom templates (use template-authoring), modifying existing projects or adding
|
||||
NuGet packages to existing projects.
|
||||
---
|
||||
|
||||
# Template Instantiation
|
||||
|
||||
This skill creates .NET projects from templates using `dotnet new` CLI commands, with guidance for parameter validation, Central Package Management adaptation, and multi-project composition.
|
||||
|
||||
## When to Use
|
||||
|
||||
- User asks to create a new .NET project, app, or service
|
||||
- User needs a solution with multiple projects (API + tests + library)
|
||||
- User wants to create a project that respects existing `Directory.Packages.props`
|
||||
- User needs to install or manage template packages
|
||||
|
||||
## When Not to Use
|
||||
|
||||
- User is searching for or comparing templates — route to `template-discovery` skill
|
||||
- User wants to author a custom template — route to `template-authoring` skill
|
||||
- User wants to add packages to an existing project — use `dotnet add package` directly
|
||||
|
||||
## Inputs
|
||||
|
||||
| Input | Required | Description |
|
||||
|-------|----------|-------------|
|
||||
| Template name or intent | Yes | Template short name (e.g., `webapi`) or natural-language description |
|
||||
| Project name | Yes | Name for the created project |
|
||||
| Output path | Recommended | Directory where the project should be created |
|
||||
| Parameters | No | Template-specific parameters (e.g., `--framework`, `--auth`, `--aot`) |
|
||||
|
||||
## Workflow
|
||||
|
||||
### Step 1: Resolve template and parameters
|
||||
|
||||
If the user provides a natural-language description, map it to a template short name (see the keyword table in the `template-discovery` skill). If they provide a template name, proceed directly.
|
||||
|
||||
Use `dotnet new <template> --help` to review available parameters, defaults, and types for any parameters the user did not specify.
|
||||
|
||||
### Step 2: Analyze the workspace
|
||||
|
||||
Check the existing solution structure before creating:
|
||||
- Is Central Package Management (CPM) enabled? Look for `Directory.Packages.props`
|
||||
- What target frameworks are in use? Check existing `.csproj` files
|
||||
- Is there a `global.json` pinning the SDK?
|
||||
|
||||
This ensures the new project is consistent with the workspace.
|
||||
|
||||
### Step 3: Preview the creation
|
||||
|
||||
Use `dotnet new <template> --dry-run` to show the user what files would be created. Confirm before proceeding.
|
||||
|
||||
```bash
|
||||
dotnet new webapi --name MyApi --framework net10.0 --dry-run
|
||||
```
|
||||
|
||||
### Step 4: Create the project
|
||||
|
||||
Use `dotnet new` with the template name and all parameters:
|
||||
|
||||
```bash
|
||||
dotnet new webapi --name MyApi --output ./src/MyApi --framework net10.0 --auth Individual
|
||||
```
|
||||
|
||||
After creation, if the workspace uses CPM:
|
||||
1. Check `.csproj` for inline `<PackageReference>` versions
|
||||
2. Move version attributes to `Directory.Packages.props` as `<PackageVersion>` entries
|
||||
3. Remove `Version` attributes from the `.csproj`
|
||||
|
||||
### Step 5: Multi-project composition (optional)
|
||||
|
||||
For complex structures, create each project sequentially and wire them together:
|
||||
|
||||
```bash
|
||||
dotnet new webapi --name MyApi --output ./src/MyApi
|
||||
dotnet new xunit --name MyApi.Tests --output ./tests/MyApi.Tests
|
||||
dotnet add ./tests/MyApi.Tests reference ./src/MyApi
|
||||
dotnet sln add ./src/MyApi ./tests/MyApi.Tests
|
||||
```
|
||||
|
||||
### Step 6: Template package management
|
||||
|
||||
Install or uninstall template packages:
|
||||
|
||||
```bash
|
||||
dotnet new install Microsoft.DotNet.Web.ProjectTemplates.10.0
|
||||
dotnet new uninstall Microsoft.DotNet.Web.ProjectTemplates.10.0
|
||||
```
|
||||
|
||||
### Step 7: Post-creation verification
|
||||
|
||||
1. Verify the project builds: `dotnet build`
|
||||
2. If added to a solution, verify `dotnet build` at the solution level
|
||||
3. If CPM was adapted, verify `Directory.Packages.props` has the new entries
|
||||
|
||||
## Validation
|
||||
|
||||
- [ ] Project was created successfully with the expected files
|
||||
- [ ] Project builds cleanly with `dotnet build`
|
||||
- [ ] If CPM is active, `.csproj` has no version attributes and `Directory.Packages.props` has matching entries
|
||||
- [ ] Package versions in the project are current (not stale template defaults)
|
||||
- [ ] If multi-project, all projects build and reference each other correctly
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
| Pitfall | Solution |
|
||||
|---------|----------|
|
||||
| Not checking for CPM before creating a project | If `Directory.Packages.props` exists, `dotnet new` creates projects with inline versions that conflict. After creation, move versions to `Directory.Packages.props` and remove them from `.csproj`. |
|
||||
| Creating projects without specifying the framework | Always specify `--framework` when the template supports multiple TFMs to avoid defaulting to an older version. |
|
||||
| Not adding the project to the solution | After creation, run `dotnet sln add` to include the project in the solution. |
|
||||
| Not verifying the project builds | Always run `dotnet build` after creation to catch missing dependencies or parameter issues early. |
|
||||
|
||||
## More Info
|
||||
|
||||
- [Central Package Management](https://learn.microsoft.com/nuget/consume-packages/central-package-management) — CPM documentation
|
||||
- [dotnet new](https://learn.microsoft.com/dotnet/core/tools/dotnet-new) — CLI reference
|
||||
Reference in New Issue
Block a user