template-validation
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
- 最近更新
- 2026-11-14
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- template-validation
- license
- MIT
- 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).
03 SKILL.md 正文
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
typefield - For
type: "parameter":- WARNING if no
datatypespecified (defaults tostring) - SUGGESTION if no
description(improves--helpoutput) - If
datatype: "choice":- ERROR if no
choicesdefined - ERROR if
choicesis empty - ERROR if
defaultValueis not in the choices list - WARNING if optional (not
isRequired) and nodefaultValue— users get unexpected behavior
- ERROR if no
- If
datatype: "bool":- ERROR if
defaultValueis not a valid boolean
- ERROR if
- If
datatype: "int":- ERROR if
defaultValueis not a valid integer
- ERROR if
- Valid datatypes:
string,bool,choice,int,float,hex,text - ERROR if datatype is not in the valid list
- WARNING if no
- For
type: "computed":- ERROR if missing
valueexpression
- ERROR if missing
- For
type: "generated":- ERROR if missing
generatorfield - Valid generators:
casing,coalesce,constant,port,guid,now,random,regex,regexMatch,switch,join
- ERROR if missing
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",
"defaultValue": "Blue",
"choices": {
"Blue": { "displayName": "Blue" },
"Green": { "displayName": "Green" }
}
}
Parameter prefix collisions: WARNING if any parameter name is a prefix of another parameter name (e.g., Auth and AuthMode) — this creates ambiguous parsing in expression contexts.
5. Sources Validation
For source modifier conditions:
- WARNING if a condition string doesn't contain parentheses around symbol names — expected format is
(symbolName), not baresymbolName
6. Post-Action Validation
For each post-action:
- ERROR if missing
actionId - WARNING if missing
description— this text is shown to users when the action requires manual steps - SUGGESTION if missing
manualInstructions— these are shown when the action can't run automatically (e.g., in an IDE)
7. Constraint Validation
For each constraint:
- ERROR if missing
typefield - WARNING if missing
args— most constraint types require arguments - For
type: "host", missingargsis an ERROR.argsis a required array; each entry needshostname. Supported built-in identifiers includedotnetcli,vs,vs-mac,ide, anddotnetcli-preview. An optionalversionuses NuGet version/range syntax such as[10.0.100,). The engine matches argument keys case-insensitively, so the documentedhostNamespelling is also valid. Reject unrelated fields such aspatternandvalue. - For
type: "sdk-version",argsis a version string or array using the same syntax.
8. Tags Validation
- SUGGESTION if no
languagetag — addingtags.language(e.g.,"C#") improves filtering indotnet new list --language - SUGGESTION if no
typetag — addingtags.type(e.g.,"project"or"item") improves categorization
Workflow
Step 1: Locate the template.json
The file can be at:
- Direct path:
path/to/template.json - In a template directory:
path/to/.template.config/template.json - In a
.template.configdirectory:path/.template.config/template.json
Step 2: Parse and validate
Read the JSON. If it's malformed, report the JSON parse error with line and column. If an absolute-path read fails, retry the user-supplied relative path from the working directory before concluding the file is unavailable.
Only after parsing succeeds, run all 8 validation categories above. Collect errors, warnings, and suggestions separately. Verify schema-sensitive claims against the installed SDK or the current template-engine schema; do not infer a runtime failure from a field name alone.
Step 3: Report results
Lead with a one-line verdict, then a single findings table. This decisive shape is required — do not scatter findings across prose paragraphs.
Verdict header (pick one):
❌ Not ready — N error(s), M warning(s)— has errors⚠️ Publishable but N warning(s)— no errors, has warnings✅ Ready to publish — 0 errors, 0 warnings— no errors or warnings (optional suggestions may still apply)
Then one table, ordered errors → warnings → suggestions:
| Severity | Location (JSON path or line:col) |
Issue | Fix |
|---|---|---|---|
| ERROR | shortName |
"list" conflicts with a dotnet new subcommand |
Rename to a distinctive value, e.g. "my-list" |
| ERROR | symbols.maxRetries.defaultValue |
"abc" is not a valid int |
Set a numeric default, e.g. "3" |
| WARNING | sourceName |
Missing replacement token | Set it to the source project name |
Every ERROR and WARNING MUST include a concrete fix — the corrected value, JSON snippet, or a specific edit instruction (e.g. "remove the trailing comma"), not just a restatement of the problem. A finding without an actionable fix is incomplete. This is the single biggest thing that separates a useful validation from a generic lint.
Close with the total: "N error(s), M warning(s), K suggestion(s)."
For malformed JSON the output is intentionally smaller and has exactly two parts:
❌ Not ready — JSON parse error at line N, column M: <message>.
<smallest corrected fragment showing the exact edit>
Do not append a findings table or semantic totals until the corrected file parses.
Common Pitfalls
| Pitfall | Impact |
|---|---|
| ShortName = "list" or "search" | Template can never be created — conflicts with a dotnet new subcommand |
Missing sourceName |
--name MyProject doesn't rename anything in the generated files |
Choice parameter without defaultValue |
Confusing user experience on optional choice params |
Invalid datatype value |
Template engine ignores the symbol, causing silent failures |
Computed symbol without value |
Template engine throws at instantiation time |
Parameter prefix collision (Auth vs AuthMode) |
Ambiguous expression evaluation |
| Source condition without parentheses | Condition may not evaluate correctly |
| Continuing semantic validation after JSON parsing failed | Findings are speculative. Report the exact parse fix and stop. |
Host constraint uses scalar args, the invalid dotnet-cli host ID, or unrelated fields |
Use args: [{ "hostname": "dotnetcli", "version": "[10.0.100,)" }]; hostName is also accepted case-insensitively. |
More Info
- template.json reference — full schema
- Available Symbol Generators — generator types
- Post-action registry — action IDs
- Constraints — constraint types
04 同仓库更多 Skills
rust-best-practices
Guide for writing idiomatic Rust code based on Apollo GraphQL's best practices handbook. Use this skill when: (1) writing new Rust code or functions, (2) reviewing or refactoring existing Rust code, (3) deciding between borrowing vs cloning or ownership patterns, (4) implementing error handling with Result types, (5) optimizing Rust code for performance, (6) writing tests or documentation for Rust projects.
postgres-database-migration
Use this skill for planning, testing, and safely executing PostgreSQL schema migrations — especially when working with production data or shared databases. **Trigger when user asks to:** - Test a schema migration before applying it to production - Add, remove, or rename columns safely on a live table - Change a column's data type without downtime - Add or drop indexes, constraints, or foreign keys on large tables - Understand which ALTER TABLE operations lock the table - Roll back a failed migration - Plan a zero-downtime migration strategy - Fork a database to test a migration safely Covers: lock-level reference for every common DDL operation, safe migration patterns, fork-based testing, zero-downtime column changes, index creation, constraint addition, backfill strategies, pre/post-migration validation, and rollback planning.
postgres-best-practices
Best practices and guidelines for working with Postgres. Covers schema design, indexing strategies, query optimization, migrations, and common pitfalls. Use when writing SQL, designing database schemas, optimizing queries, or setting up a Postgres database.
writing-mstest-tests
ALWAYS USE when asked to fix, rewrite, update, improve, modernize, show corrected code for, or explain existing MSTest tests or MSTest-specific configuration. Use for "review" when corrected code or edits are wanted, even for one pasted assertion or passing tests with bad failure output. Covers expected/actual labels; generic Boolean, collection, string, numeric, null, identity, exception, hard-cast, and object[] checks; TestContext/lifecycle; timeout/cancellation; OS/CI conditions, retry, cleanup, parallelization, MSTest.Sdk project setup, and MSTESTxxxx. Honor the installed MSTest version. DO NOT USE to design new test cases (code-testing), perform report-only audits, create project files rather than explain MSTest setup, run tests, migrate frameworks, or handle non-MSTest/non-.NET code.
winforms-expert
Create, modify, debug, or review Windows Forms applications only when the request contains a concrete Windows Forms marker. USE FOR: WinForms, Windows Forms, System.Windows.Forms, WinForms Form or UserControl designer files (*.Designer.cs or *.Designer.vb), Visual Studio WinForms Designer, TableLayoutPanel, BindingSource, DataGridView, Control.InvokeAsync, component-tray ownership, or custom control serialization. DO NOT USE FOR: WPF or WPF XAML, including Window.InputBindings, KeyBinding, commands, or DataContext; .NET MAUI; Avalonia; or any request where none of the listed Windows Forms markers is present.
vectorization
Design, implement, optimize, and review SIMD code in .NET. USE FOR: vectorizing scalar loops with TensorPrimitives, Vector64/128/256/512, or platform hardware intrinsics; reviewing existing SIMD code, including the generic Vector type, for contract equivalence, tail handling, memory safety, portability, fallbacks, and measured performance. DO NOT USE FOR: performance work unrelated to SIMD or vectorization.