/template-validation

name: template-validation
description: >
  Validates custom dotnet new templates for correctness before publishing.
  Catches missing fields, parameter bugs, shortName conflicts, constraint issues,
  and common authoring mistakes that cause templates to fail silently.
  USE FOR: checking template.json files for errors before publishing or testing,
  diagnosing why a template doesn't appear after installation, reviewing template
  parameter definitions for type mismatches and missing defaults, finding shortName
  conflicts with dotnet CLI commands, validating post-action and constraint configuration.
  DO NOT USE FOR: finding or using existing templates (use template-discovery),
  creating projects from templates (use template-instantiation), creating templates
  from existing projects (use template-authoring).
license: MIT

Template Validation

This skill helps validate custom `dotnet new` templates for correctness before publishing. It encodes the validation rules that catch common authoring mistakes — issues that cause templates to silently fail, produce broken projects, or not appear in `dotnet new list`.

When to Use

• User asks to check or validate a template.json file
• User reports "my template doesn't show up after installing"
• User wants to review a template before packaging and publishing to NuGet
• User encounters unexpected behavior from a custom template

When Not to Use

• User wants to find or use existing templates — route to `template-discovery`
• User wants to create a project — route to `template-instantiation`
• User wants to create a template from an existing project — route to `template-authoring`

Inputs

| Input | Required | Description | |-------|----------|-------------| | template.json path | Yes | Path to the template.json file or the template directory containing `.template.config/template.json` |

Validation Rules

When reviewing a template.json, check ALL of the following categories systematically. Report every finding as an error, warning, or suggestion.

> **Parse gate — stop on syntax errors.** Parse JSON before applying any semantic rule. If > parsing fails, report the parser's line and column, show only the smallest concrete syntax > correction, and stop. Do not invent required-field, symbol, post-action, or discoverability > findings from a document that did not parse. Re-parse after the correction before making any > semantic claim. > > The malformed-JSON final response has exactly two parts: the one-line parse verdict and a > corrected snippet showing the exact edit. Do not append semantic recommendations, optional > metadata, or a full replacement manifest.

1. Required Fields

| Field | Severity | Rule | |-------|----------|------| | `identity` | ERROR | Must be present and non-empty | | `name` | ERROR | Must be present and non-empty | | `shortName` | ERROR | Must be present and non-empty | | `sourceName` | WARNING | Without it, `--name` won't customize the generated project name | | `author` | WARNING | Improves template discoverability | | `description` | SUGGESTION | Helps users understand what the template creates | | `classifications` | SUGGESTION | Improves search and categorization (e.g., `["Web", "API"]`) | | `defaultName` | SUGGESTION | Provides a fallback project name when `--name` is not specified |

2. Identity Format

• ERROR if identity contains spaces — use dots or dashes (e.g., `MyCompany.WebApi.CSharp`)
• WARNING if identity has no namespace separator (`.` or `-`) — use reverse-DNS format

3. ShortName Conflicts

A shortName that matches a `dotnet new` subcommand conflicts, because `dotnet new <name>` is then parsed as that subcommand instead of instantiating the template. Read the reserved set for the installed SDK from the `Commands:` section of `dotnet new --help` — that is the authoritative source and avoids this rule going stale.

As of current SDKs the subcommands include (illustrative only — version-dependent, do not hardcode this list; the live `dotnet new --help` output is canonical): `install`, `uninstall`, `update`, `list`, `search`, `details`, `create`. Note that top-level `dotnet` verbs like `build`, `run`, `test`, and `publish` do NOT conflict — `dotnet new test` does not collide with `dotnet test`.

• ERROR if shortName matches any subcommand reported by `dotnet new --help` (case-insensitive)
• WARNING if shortName is only 1 character — too short for discoverability
• Note: shortName can be a string or an array of strings; check all values

4. Symbol Validation

For each symbol in the `symbols` object:

• ERROR if a symbol is missing the `type` field
• For `type: "parameter"`:
• WARNING if no `datatype` specified (defaults to `string`)
• SUGGESTION if no `description` (improves `--help` output)
• If `datatype: "choice"`:
• ERROR if no `choices` defined
• ERROR if `choices` is empty
• ERROR if `defaultValue` is not in the choices list
• WARNING if optional (not `isRequired`) and no `defaultValue` — users get unexpected behavior
• If `datatype: "bool"`:
• ERROR if `defaultValue` is not a valid boolean
• If `datatype: "int"`:
• ERROR if `defaultValue` is not a valid integer
• Valid datatypes: `string`, `bool`, `choice`, `int`, `float`, `hex`, `text`
• ERROR if datatype is not in the valid list
• For `type: "computed"`:
• ERROR if missing `value` expression
• For `type: "generated"`:
• ERROR if missing `generator` field
• Valid generators: `casing`, `coalesce`, `constant`, `port`, `guid`, `now`, `random`, `regex`, `regexMatch`, `switch`, `join`

Custom parameter help is template-specific: it appears under `dotnet new <shortName> --help`, not the global `dotnet new --help`. Correct that premise when necessary, then explain which invalid symbol definitions prevent the parameters from appearing reliably.

A valid choice parameter uses a non-empty choices object, for example:

"Color": {
  "type": "parameter",
  "datatype": "choice",