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 they are authoring before publishing
- 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:
- Create
.template.config directory next to the project
- Generate
template.json with identity (reverse-DNS), name, shortName, sourceName (project name for replacement), classifications, and tags
- Preserve from source — generic
dotnet new templates frequently get these wrong, so verify each is carried over from the original .csproj:
- SDK type —
Microsoft.NET.Sdk, Microsoft.NET.Sdk.Web, Microsoft.NET.Sdk.Worker, etc.
- Analyzer/package reference metadata —
PrivateAssets, IncludeAssets, ExcludeAssets
OutputType and other key properties — TreatWarningsAsErrors, Nullable, LangVersion
- CPM participation — no inline
Version attributes when a Directory.Packages.props is present
- Custom build props/targets and
Directory.Build.props conventions
- Repo conventions — folder layout, naming,
global.json SDK pin
Minimal example:
{
"$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" }
}
Required output — do not stop at a minimal stub. Write the complete .template.config/template.json for the actual source project, then emit a short conventions-preserved confirmation so the user can see nothing was silently dropped. This carry-over is the whole value of the skill; a generic dotnet new template that loses these is why authoring ties with a hand-written stub.
Source .csproj setting |
Carried over? |
How |
SDK (Microsoft.NET.Sdk.*) |
✅ |
template content .csproj uses same SDK |
TreatWarningsAsErrors / Nullable / LangVersion |
✅ |
preserved verbatim in template .csproj |
PackageReference PrivateAssets / IncludeAssets / ExcludeAssets |
✅ |
metadata kept on each reference |
CPM (Directory.Packages.props present) |
✅ |
no inline Version attributes emitted |
Mark any row you intentionally omitted as ⚠️ with a reason — never leave it implicit.
Step 2: Validate template.json
Validate the generated template.json using the template-validation skill (it owns the full rule set — required fields, identity format, reserved shortName conflicts, parameter datatypes, post-actions, constraints, and tags).
Quick summary of what gets checked:
- Required fields —
identity, name, and shortName must be present.
- ShortName conflicts — avoid names that collide with
dotnet new subcommands. Read the authoritative set from the Commands: section of dotnet new --help for the installed SDK and do not hardcode it (it can change between versions); illustrative examples from current SDKs are install, uninstall, update, list, search, details, create. A conflict happens because dotnet new <name> would be parsed as the subcommand of the same name. Top-level dotnet verbs like build, run, test, and publish do NOT conflict. Run dotnet new list to confirm the name is not already taken.
- Parameters, post-actions, tags — see template-validation for the complete rules, including the valid datatype list.
Step 3: Refine the template
Based on validation results and user requirements:
- Add parameters with appropriate types (string, bool, choice), defaults, and descriptions
- Add conditional content using
#if preprocessor directives for optional features
- Configure post-actions for solution add, restore, or custom scripts
- Set constraints to restrict which SDKs or workloads the template supports
- Add classifications and tags for discoverability
Step 4: Test the template locally
dotnet new install ./path/to/template/root
dotnet new mylib --name TestProject --dry-run
dotnet new mylib --name TestProject --output ./test-output
dotnet build ./test-output/TestProject
Validation
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 that match a dotnet new subcommand; read the live set from dotnet new --help and don't hardcode it (illustrative examples: install, uninstall, update, list, search, details, create). Top-level verbs like build/run/test/publish are fine. Run 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
1---2name: template-authoring3description: >4 Guides creation and validation of custom dotnet new templates from existing projects.5 Generates a .template.config/template.json that preserves the source project's conventions.6 USE FOR: creating a reusable dotnet new template from an existing project, bootstrapping7 .template.config/template.json with correct identity, shortName, parameters, and8 post-actions, adding parameters or conditional content to a template you are authoring,9 validating the template.json you are authoring before publishing,10 packaging templates as NuGet packages for distribution.11 DO NOT USE FOR: validating an existing template.json as a standalone task (use12 template-validation), finding or using existing templates (use template-discovery and13 template-instantiation), MSBuild project file issues unrelated to template authoring,14 NuGet package publishing (only template packaging structure).15license: MIT16metadata:17 source: https://skillmd.com/skills/stanfish06/template-authoring18---1920# Template Authoring2122This 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.2324## When to Use2526- User wants to create a reusable template from an existing .csproj27- User wants to validate a template.json they are authoring before publishing28- User is setting up `.template.config/template.json` from scratch29- User wants to package a template for NuGet distribution3031## When Not to Use3233- User wants to find or use existing templates — route to `template-discovery` or `template-instantiation`34- User has MSBuild issues unrelated to template authoring — route to `dotnet-msbuild` plugin3536## Inputs3738| Input | Required | Description |39|-------|----------|-------------|40| Source project path | For creation | Path to the .csproj to use as template source |41| template.json path | For validation | Path to an existing template.json to validate |42| Template name | For creation | Human-readable name for the template |43| Short name | Recommended | Short name for `dotnet new <shortname>` usage |4445## Workflow4647### Step 1: Bootstrap from existing project4849Analyze the source `.csproj` and create a `.template.config/template.json`:50511. Create `.template.config` directory next to the project522. Generate `template.json` with `identity` (reverse-DNS), `name`, `shortName`, `sourceName` (project name for replacement), `classifications`, and `tags`533. Preserve from source — generic `dotnet new` templates frequently get these wrong, so verify each is carried over from the original `.csproj`:54 1. **SDK type** — `Microsoft.NET.Sdk`, `Microsoft.NET.Sdk.Web`, `Microsoft.NET.Sdk.Worker`, etc.55 2. **Analyzer/package reference metadata** — `PrivateAssets`, `IncludeAssets`, `ExcludeAssets`56 3. **`OutputType` and other key properties** — `TreatWarningsAsErrors`, `Nullable`, `LangVersion`57 4. **CPM participation** — no inline `Version` attributes when a `Directory.Packages.props` is present58 5. **Custom build props/targets** and `Directory.Build.props` conventions59 6. **Repo conventions** — folder layout, naming, `global.json` SDK pin6061Minimal example:62```json63{64 "$schema": "http://json.schemastore.org/template",65 "author": "MyOrg",66 "classifications": ["Library"],67 "identity": "MyOrg.Templates.MyLib",68 "name": "My Library Template",69 "shortName": "mylib",70 "sourceName": "MyLib",71 "tags": { "language": "C#", "type": "project" }72}73```7475**Required output — do not stop at a minimal stub.** Write the *complete* `.template.config/template.json` for the actual source project, then emit a short **conventions-preserved** confirmation so the user can see nothing was silently dropped. This carry-over is the whole value of the skill; a generic `dotnet new` template that loses these is why authoring ties with a hand-written stub.7677| Source `.csproj` setting | Carried over? | How |78|--------------------------|---------------|-----|79| SDK (`Microsoft.NET.Sdk.*`) | ✅ | template content `.csproj` uses same SDK |80| `TreatWarningsAsErrors` / `Nullable` / `LangVersion` | ✅ | preserved verbatim in template `.csproj` |81| PackageReference `PrivateAssets` / `IncludeAssets` / `ExcludeAssets` | ✅ | metadata kept on each reference |82| CPM (`Directory.Packages.props` present) | ✅ | no inline `Version` attributes emitted |8384Mark any row you intentionally omitted as ⚠️ with a reason — never leave it implicit.8586### Step 2: Validate template.json8788Validate the generated `template.json` using the **template-validation** skill (it owns the full rule set — required fields, identity format, reserved shortName conflicts, parameter datatypes, post-actions, constraints, and tags).8990Quick summary of what gets checked:91- **Required fields** — `identity`, `name`, and `shortName` must be present.92- **ShortName conflicts** — avoid names that collide with `dotnet new` subcommands. Read the authoritative set from the `Commands:` section of `dotnet new --help` for the installed SDK and do not hardcode it (it can change between versions); illustrative examples from current SDKs are `install`, `uninstall`, `update`, `list`, `search`, `details`, `create`. A conflict happens because `dotnet new <name>` would be parsed as the subcommand of the same name. Top-level `dotnet` verbs like `build`, `run`, `test`, and `publish` do NOT conflict. Run `dotnet new list` to confirm the name is not already taken.93- **Parameters, post-actions, tags** — see template-validation for the complete rules, including the valid datatype list.9495### Step 3: Refine the template9697Based on validation results and user requirements:98991. **Add parameters** with appropriate types (string, bool, choice), defaults, and descriptions1002. **Add conditional content** using `#if` preprocessor directives for optional features1013. **Configure post-actions** for solution add, restore, or custom scripts1024. **Set constraints** to restrict which SDKs or workloads the template supports1035. **Add classifications** and tags for discoverability104105### Step 4: Test the template locally106107```bash108dotnet new install ./path/to/template/root109dotnet new mylib --name TestProject --dry-run110dotnet new mylib --name TestProject --output ./test-output111dotnet build ./test-output/TestProject112```113114## Validation115116- [ ] `template.json` passes manual validation with zero errors117- [ ] Template identity and shortName are unique and meaningful118- [ ] All parameters have descriptions and appropriate defaults119- [ ] Template can be installed, dry-run, and instantiated successfully120- [ ] Created projects build cleanly with `dotnet build`121- [ ] Conditional content produces correct output for all parameter combinations122123## Common Pitfalls124125| Pitfall | Solution |126|---------|----------|127| Identity format issues | Use reverse-DNS format (e.g., `MyOrg.Templates.WebApi`). Avoid spaces or special characters. |128| ShortName conflicts with CLI commands | Avoid names that match a `dotnet new` subcommand; read the live set from `dotnet new --help` and don't hardcode it (illustrative examples: `install`, `uninstall`, `update`, `list`, `search`, `details`, `create`). Top-level verbs like `build`/`run`/`test`/`publish` are fine. Run `dotnet new list` to see if the name is already taken. |129| Missing parameter descriptions | Every parameter should have a `description` and `displayName` for discoverability. |130| Not testing all parameter combinations | Use `dotnet new <template> --dry-run` with different parameter values to verify conditional content works correctly. |131| Hardcoded versions in template | Use `sourceName` replacement for project names and consider parameterizing framework versions. |132| Not setting classifications | Add appropriate `classifications` (e.g., `["Web", "API"]`) for template discovery. |133134## More Info135136- [Custom templates for dotnet new](https://learn.microsoft.com/dotnet/core/tools/custom-templates) — official authoring guide137- [template.json reference](https://github.com/dotnet/templating/wiki/Reference-for-template.json) — full schema reference138- [Template Engine Wiki](https://github.com/dotnet/templating/wiki) — template engine internals