template-authoring

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

Workflow

Rules that change the answer

Use these structures exactly; do not invent fields from other template features.

Deliver the requested artifact. When the user says "show", "write", or "give me the content", put the complete JSON/XML in the final response even if you also wrote it to disk. Never edit this skill's SKILL.md or plugin documentation as a substitute for authoring the user's template. Only create or modify template files when the user requested file changes and the target template/project is present.

Step 1: Bootstrap from existing project

Analyze the source .csproj and create a .template.config/template.json:

1. Copy the source project into a dedicated template-source directory by default, preserving the original project untouched. Modify the original in place only when the user explicitly asks for that layout.
2. Create .template.config inside the template-source directory.
3. Generate template.json with identity (reverse-DNS), name, shortName, sourceName (project name for replacement), classifications, and tags
4. Preserve from source — generic dotnet new templates frequently get these wrong, so verify each is carried over from the original .csproj:
   1. SDK type — Microsoft.NET.Sdk, Microsoft.NET.Sdk.Web, Microsoft.NET.Sdk.Worker, etc.
   2. Analyzer/package reference metadata — PrivateAssets, IncludeAssets, ExcludeAssets
   3. OutputType and other key properties — TreatWarningsAsErrors, Nullable, LangVersion
   4. CPM participation — no inline Version attributes when a Directory.Packages.props is present
   5. Custom build props/targets and Directory.Build.props conventions
   6. 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.

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:

1. Add parameters with appropriate types (string, bool, choice), defaults, and descriptions

2. Add conditional content using the file type's valid syntax. In XML use template directives inside XML comments, not bare preprocessor lines:

   <!--#if (database == "SqlServer") -->
   <PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" />
   <!--#endif -->
   <!--#if (database == "Postgres") -->
   <PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" />
   <!--#endif -->

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

For a restore post-action, prefer primaryOutputs when the project path is known:

"primaryOutputs": [{ "path": "MyProject.csproj" }],
"postActions": [{
  "description": "Restore NuGet packages.",
  "manualInstructions": [{ "text": "Run 'dotnet restore'." }],
  "actionId": "210D431B-A78B-4D2F-B762-4ED3E3EA9025",
  "continueOnError": true
}]

If args.files is needed, its paths are matched against the source template before renames, for example "files": ["**/*.csproj"]. Explain that distinction.

Step 4: Test the template locally

For a create-from-existing-project request, this step is required rather than optional: install the authored template, run a dry-run, instantiate it into a temporary output folder, and build the generated project. Report each observed result; inspecting template.json alone does not prove the reusable template works.

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

When packaging is requested, include the complete pack project, not only a directory tree:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <PackageId>Contoso.ProjectTemplates</PackageId>
    <PackageType>Template</PackageType>
    <TargetFramework>net8.0</TargetFramework>
    <IncludeBuildOutput>false</IncludeBuildOutput>
    <NoWarn>$(NoWarn);NU5128</NoWarn>
  </PropertyGroup>
  <ItemGroup>
    <Compile Remove="**\*" />
    <Content Include="templates\**\*" Pack="true" PackagePath="content\" />
  </ItemGroup>
</Project>

The pack project's target framework applies only to the content-only packaging project; it does not retarget projects inside templates/. Prefer a broadly available supported framework unless the packaging project itself uses newer build features.

For a self-contained CPM template, the packaged Directory.Packages.props must include <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally> and every versionless PackageReference must have a matching PackageVersion. Keep the props file at the intended generated repository root; do not place a duplicate nearer the project where it changes lookup.

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
• XML template directives are wrapped in XML comments and the generated project parses
• Host constraints use args[].hostname; restore actions use primaryOutputs or args.files

Common Pitfalls

More Info

• Custom templates for dotnet new — official authoring guide
• template.json reference — full schema reference
• Template Engine Wiki — template engine internals