[WIP] Add diagnosing-dotnet-aot skill — Native AOT diagnostics and fixes

[artl93]

Summary

Adds a skill for diagnosing and fixing .NET Native AOT and trimming compatibility issues. Resolves #8.

What This Skill Adds Beyond Base LLM Knowledge

Base models already know general AOT concepts. This skill targets 7 specific knowledge gaps where LLMs consistently give wrong answers:

What LLMs Get Wrong	Correct Answer (from this skill)
Suggests #pragma warning disable for trim warnings	#pragma is not preserved in IL — must use [UnconditionalSuppressMessage]
Flags ALL MakeGenericType as dangerous	Safe for reference types (shared canonical code); only value types need pre-generated code
Misses Expression.Compile() perf cliff	Falls back to 10-100x slower interpreter in AOT — no warning emitted
Suggests fixing EventSource WriteEvent IL2026	False positive for >3 params with primitive types — safe to suppress
Does not know IsAotCompatible=true cascades	Automatically enables IsTrimmable + 3 analyzers
Gives incomplete annotation workflow	Must propagate [DynamicallyAccessedMembers] through entire call chain
Inconsistent on EF Core AOT status	Experimental: compiled models + precompiled queries required

Structure

skills/diagnosing-dotnet-aot/
├── SKILL.md                              # Main skill (131 lines)
└── references/
    ├── critical-patterns.md              # 13 hard-failure patterns (always loaded)
    ├── serialization-and-config.md       # STJ source gen, config binding, logging
    ├── reflection-and-di.md             # Annotation workflow, DI patterns
    ├── generics-and-types.md            # MakeGenericType safety, Expression.Compile
    ├── library-compatibility.md         # Library AOT status matrix
    └── project-setup.md                 # MSBuild, warning codes, CI patterns

agents/dotnet-aot-optimizer.agent.md      # Agent definition

tests/diagnosing-dotnet-aot/
├── EVALUATION.md                         # 6 test cases with pass/fail criteria
└── assets/                               # Code samples for each test
    ├── pragma-warning-suppress.cs        # Test 1: #pragma vs [UnconditionalSuppressMessage]
    ├── make-generic-type-mixed.cs        # Test 2: ref type vs value type distinction
    ├── expression-compile-hotpath.cs     # Test 3: silent 10-100x perf cliff
    ├── eventsource-false-positive.cs     # Test 4: known IL2026 false positive
    ├── annotation-chain-incomplete.cs    # Test 5: multi-hop annotation propagation
    └── isaotcompatible-cascade.cs        # Test 6: property cascade knowledge

Design Decisions

• Signal-based progressive loading: SKILL.md detects code signals and loads only relevant reference files (not all 6)
• Tiered severity: 🔴 Critical (will crash) / 🟡 Warning (IL warning) / ℹ️ Info (suboptimal but functional)
• All .NET ecosystem: Never recommends rewriting outside .NET
• Gerund naming: diagnosing-dotnet-aot per Claude agent skills best practices
• TOC on all reference files: All >100 lines, each has table of contents

Best Practices Applied

Following Claude agent skills best practices:

• Conciseness: removed explanations Claude already knows
• Gerund naming convention
• Third-person description with trigger terms
• Progressive disclosure (one level deep references)
• Table of contents on long reference files
• No time-sensitive language
• Consistent terminology throughout
• Evaluation test cases with concrete success criteria

[jeffschwMSFT]

this skill needs to be rebased into the new org structure and run through the skill validator

[artl93]

@jeffschwMSFT - I'm closing mine out - this is out of date and needs more attention.