@pratikpsl/agent-skills 0.1.0

package/src/templates/dotnet/AgentSkills/skills/design/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: design
+description: >
+  Load when designing, architecting, or implementing patterns in C#.
+  Covers project folder structure (vertical slice), SOLID, KISS, YAGNI,
+  DRY, composition, Singleton, and Factory.
+---
+
+# Design Principles and Patterns
+
+## Project Structure
+
+Organise by **feature (vertical slice)**, not by technical layer.
+Each feature folder owns everything needed for its use case: command, handler, DTO, validator, and endpoint.
+This keeps changes local, avoids cross-cutting layers, and scales without requiring global refactors.
+
+```text
+src/
+├── Features/
+│   ├── Products/
+│   │   ├── CreateProductCommand.cs
+│   │   ├── CreateProductHandler.cs
+│   │   ├── ProductDto.cs
+│   │   ├── ProductValidator.cs
+│   │   └── ProductEndpoints.cs
+│   ├── Orders/
+│   │   ├── CreateOrderCommand.cs
+│   │   ├── CreateOrderHandler.cs
+│   │   ├── OrderDto.cs
+│   │   ├── OrderValidator.cs
+│   │   └── OrderEndpoints.cs
+│   └── ...
+├── Shared/
+│   ├── Middleware/
+│   └── Utilities/
+└── Program.cs
+```
+
+**Rules:**
+- One folder per feature — never split a feature across `Commands/`, `Queries/`, `Controllers/` top-level layers.
+- When a feature grows, split it into sub-features within the same `Features/<Feature>/` directory before creating a new top-level folder.
+- Shared cross-cutting code (middleware, utilities, base types) lives in `Shared/`, not duplicated per feature.
+- `Program.cs` wires up DI, middleware, and endpoint registration only — no business logic.
+
+## SOLID
+
+| | Principle | In Practice |
+|---|---|---|
+| S | Single Responsibility | One class, one reason to change |
+| O | Open / Closed | Open to extension, closed to modification |
+| L | Liskov Substitution | Subtypes must work wherever the base type works |
+| I | Interface Segregation | Small, focused interfaces over large, general ones |
+| D | Dependency Inversion | Depend on abstractions, not concrete implementations |
+
+## KISS
+
+Prefer the obvious solution. If a junior engineer cannot understand it in 5 minutes, simplify it.
+
+## YAGNI
+
+Do not build something until it is needed. Solve today's requirement, not tomorrow's guess.
+
+```csharp
+// Bad: built "just in case" when only one format exists.
+public interface IExporter { }
+public class ExporterFactory { }
+
+// Good: solve what exists now.
+public string ExportToCsv(Report report) { }
+```
+
+## DRY
+
+Keep one source of truth per piece of knowledge: logic, configuration, and data schemas.
+
+## Composition Over Inheritance
+
+Use inheritance only for true "is-a" relationships. Prefer interfaces and delegation.
+
+## Pattern: Singleton
+
+Use when exactly one instance must coordinate shared state. Avoid when it creates hidden global state.
+
+```csharp
+public sealed class AppConfig
+{
+    private static readonly Lazy<AppConfig> InstanceHolder =
+        new(() => new AppConfig());
+
+    public static AppConfig Instance => InstanceHolder.Value;
+
+    private AppConfig()
+    {
+    }
+}
+```
+
+## Pattern: Factory
+
+Use when creation is complex, varies by type, or must be decoupled from consumers.
+
+```csharp
+// Bad
+var handler = type == "email" ? new EmailHandler() : new SmsHandler();
+
+// Good
+var handler = NotificationFactory.Create(type);
+```

package/src/templates/dotnet/AgentSkills/skills/dotnet-api/SKILL.md

@@ -0,0 +1,303 @@
+---
+name: dotnet-api
+description: >
+  Load when creating, structuring, or reviewing .NET 10 Web API projects with Swagger/OpenAPI, CORS, compression, auth, versioning, and error handling.
+---
+
+# SKILL: .NET 10 RESTful API — Best Practices
+
+## 1. URL & RESOURCE NAMING
+
+- **Nouns only**, plural: `/api/v1/articles`, `/api/v1/users`
+- HTTP verb = action; path = resource
+- Nest max 2 levels: `GET /articles/123/comments`
+- Beyond 2 levels → return URI in JSON body: `"author": "/users/3"`
+
+| ❌ Bad | ✅ Good |
+|---|---|
+| `GET /getArticles` | `GET /articles` |
+| `POST /createUser` | `POST /users` |
+
+---
+
+## 2. HTTP METHODS
+
+| Method | Use | Idempotent |
+|---|---|---|
+| GET | Retrieve | ✅ |
+| POST | Create | ❌ |
+| PUT | Full replace | ✅ |
+| PATCH | Partial update | ✅ |
+| DELETE | Remove | ✅ |
+
+---
+
+## 3. RESPONSE FORMAT & HEADERS
+
+- Always return `application/json`
+- Use `camelCase` for JSON keys (default in .NET)
+- No outer wrappers — return resource directly
+
+```csharp
+builder.Services.AddControllers()
+    .AddJsonOptions(o => o.JsonSerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase);
+```
+
+---
+
+## 4. HTTP STATUS CODES
+
+| Code | When |
+|---|---|
+| 200 | Success (GET, PUT, PATCH) |
+| 201 | Created (POST) — include `Location` header |
+| 204 | No content (DELETE) |
+| 400 | Bad request / validation failed |
+| 401 | Not authenticated |
+| 403 | Authenticated but forbidden |
+| 404 | Resource not found |
+| 500 | Unhandled server error |
+
+---
+
+## 5. GLOBAL ERROR HANDLING
+
+Use `IExceptionHandler` (dotnet 8+) — no stack traces in production.
+
+```csharp
+// GlobalExceptionHandler.cs
+public class GlobalExceptionHandler : IExceptionHandler
+{
+    public async ValueTask<bool> TryHandleAsync(HttpContext ctx, Exception ex, CancellationToken ct)
+    {
+        ctx.Response.StatusCode = StatusCodes.Status500InternalServerError;
+        await ctx.Response.WriteAsJsonAsync(new { error = "An unexpected error occurred." }, ct);
+        return true;
+    }
+}
+
+// Program.cs
+builder.Services.AddExceptionHandler<GlobalExceptionHandler>();
+builder.Services.AddProblemDetails();
+app.UseExceptionHandler();
+```
+
+Structured error shape — never raw exceptions:
+```json
+{ "status": 400, "error": "Validation failed", "code": "INVALID_EMAIL" }
+```
+
+---
+
+## 6. FILTERING, SORTING & PAGINATION
+
+Query params only — never in the body for GET.
+
+```
+GET /products?category=electronics&sort=-price&page=2&limit=20
+```
+
+```csharp
+[HttpGet]
+public IActionResult GetProducts([FromQuery] string? category, [FromQuery] string? sort,
+    [FromQuery] int page = 1, [FromQuery] int limit = 20) { ... }
+```
+
+- `sort=price` → ascending, `sort=-price` → descending
+- Always return pagination metadata: `{ total, page, limit, data: [] }`
+
+---
+
+## 7. VERSIONING
+
+```csharp
+// Program.cs
+builder.Services.AddApiVersioning(o => {
+    o.DefaultApiVersion = new ApiVersion(1);
+    o.AssumeDefaultVersionWhenUnspecified = true;
+    o.ReportApiVersions = true;
+}).AddApiExplorer(o => {
+    o.GroupNameFormat = "'v'V";
+    o.SubstituteApiVersionInUrl = true;
+});
+```
+
+```csharp
+[ApiVersion(1)]
+[Route("api/v{v:apiVersion}/articles")]
+public class ArticlesController : ControllerBase { }
+```
+
+Package: `Asp.Versioning.Mvc` + `Asp.Versioning.Mvc.ApiExplorer`
+
+---
+
+## 8. SWAGGER / OPENAPI
+
+Add to `.csproj`:
+```xml
+<GenerateDocumentationFile>true</GenerateDocumentationFile>
+```
+
+Setup: `AddEndpointsApiExplorer()` + `AddSwaggerGen()` with:
+- `SwaggerDoc` per version
+- `AddSecurityDefinition("Bearer", ...)` + matching `AddSecurityRequirement`
+- `IncludeXmlComments(...)` for XML doc file
+
+Controller annotation:
+```csharp
+/// <summary>Get all articles</summary>
+/// <response code="200">Returns list of articles</response>
+[HttpGet]
+[ProducesResponseType(typeof(List<ArticleDto>), 200)]
+[ProducesResponseType(404)]
+public IActionResult GetAll([FromQuery] int page = 1) { ... }
+```
+
+Expose only in Development:
+```csharp
+if (app.Environment.IsDevelopment()) { app.UseSwagger(); app.UseSwaggerUI(); }
+```
+
+---
+
+## 9. RESPONSE COMPRESSION
+
+```csharp
+builder.Services.AddResponseCompression(o => {
+    o.EnableForHttps = true;
+    o.Providers.Add<BrotliCompressionProvider>();
+    o.Providers.Add<GzipCompressionProvider>();
+});
+builder.Services.Configure<BrotliCompressionProviderOptions>(o => o.Level = CompressionLevel.Fastest);
+
+app.UseResponseCompression(); // must be first in pipeline
+```
+
+Package: `Microsoft.AspNetCore.ResponseCompression` (built-in)
+
+---
+
+## 10. CORS (No Wildcard in Production)
+
+```csharp
+builder.Services.AddCors(o => o.AddPolicy("ApiPolicy", p => p
+    .WithOrigins("https://myfrontend.com")   // ❌ never .AllowAnyOrigin() in prod
+    .WithMethods("GET", "POST", "PUT", "DELETE", "PATCH")
+    .WithHeaders("Authorization", "Content-Type")
+    .AllowCredentials()));
+
+app.UseCors("ApiPolicy"); // before UseAuthentication
+```
+
+Dev-only: use a separate named policy with `AllowAnyOrigin()`.
+
+---
+
+## 11. SECURITY
+
+```csharp
+builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
+    .AddJwtBearer(o => {
+        o.TokenValidationParameters = new TokenValidationParameters {
+            ValidateIssuer = true, ValidIssuer = config["Jwt:Issuer"],
+            ValidateAudience = true, ValidAudience = config["Jwt:Audience"],
+            ValidateLifetime = true,
+            IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(config["Jwt:Key"]!))
+        };
+    });
+```
+
+- `app.UseHttpsRedirection()` — mandatory
+- Never expose DB schema in endpoint design
+- Use `[Authorize]` / `[AllowAnonymous]` explicitly on controllers
+
+---
+
+## 12. CACHING
+
+Options in order of complexity:
+
+| Strategy | Use when |
+|---|---|
+| `[OutputCache(Duration = 60)]` | Single-server, simple GET caching |
+| `IDistributedCache` + Redis | Multi-instance / shared cache |
+| `Cache-Control` header | Client/CDN-side caching |
+
+```csharp
+// Distributed Redis
+builder.Services.AddStackExchangeRedisCache(o => o.Configuration = "localhost:6379");
+
+// Client hint
+Response.Headers.CacheControl = "public, max-age=60";
+```
+
+Register `AddOutputCache()` + `app.UseOutputCache()` for attribute-based caching.
+
+---
+
+## 13. RATE LIMITING (dotnet 7+ built-in)
+
+```csharp
+builder.Services.AddRateLimiter(o => o.AddFixedWindowLimiter("fixed", opt => {
+    opt.PermitLimit = 100;
+    opt.Window = TimeSpan.FromMinutes(1);
+    opt.QueueProcessingOrder = QueueProcessingOrder.OldestFirst;
+    opt.QueueLimit = 5;
+}));
+
+app.UseRateLimiter();
+
+[HttpGet, EnableRateLimiting("fixed")]
+public IActionResult Get() { ... }
+```
+
+---
+
+## 14. INPUT VALIDATION
+
+```csharp
+builder.Services.AddControllers()
+    .ConfigureApiBehaviorOptions(o => o.InvalidModelStateResponseFactory = ctx =>
+        new BadRequestObjectResult(new {
+            status = 400,
+            errors = ctx.ModelState.Values
+                .SelectMany(v => v.Errors)
+                .Select(e => e.ErrorMessage)
+        }));
+```
+
+Use `FluentValidation` for complex rules; Data Annotations for simple constraints.
+
+---
+
+## 15. PIPELINE ORDER (Critical)
+
+```csharp
+app.UseResponseCompression();
+app.UseHttpsRedirection();
+app.UseCors("ApiPolicy");
+app.UseRateLimiter();
+app.UseAuthentication();
+app.UseAuthorization();
+app.UseOutputCache();
+app.UseExceptionHandler();
+app.MapControllers();
+```
+
+---
+
+## QUICK CHECKLIST
+
+- [ ] Routes: plural nouns, no verbs, max 2 nesting levels
+- [ ] `201 Created` returns `Location` header; `204` for DELETE
+- [ ] `IExceptionHandler` registered — structured JSON errors, no stack traces
+- [ ] Collections: filtering + sorting + pagination with metadata envelope
+- [ ] Versioning: `Asp.Versioning.Mvc`, `ReportApiVersions = true`
+- [ ] Swagger: XML docs + `ProducesResponseType` on every action + JWT security scheme
+- [ ] Compression: Brotli + Gzip, `EnableForHttps = true`, first in pipeline
+- [ ] CORS: explicit `WithOrigins` — `AllowAnyOrigin` dev policy only
+- [ ] JWT: all 3 validate flags on (`Issuer`, `Audience`, `Lifetime`)
+- [ ] Rate limiting: `AddFixedWindowLimiter` + `EnableRateLimiting` per controller/action
+- [ ] `InvalidModelStateResponseFactory` returns structured 400 with field errors
+- [ ] DTOs only in responses — no raw EF entities exposed

package/src/templates/dotnet/AgentSkills/skills/dotnet-best-practices/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: dotnet-best-practices
+description: >
+  Load when writing, reviewing, refactoring, or optimizing .NET/C# code.
+  Covers project conventions, CQRS, EF Core, async, testing, performance,
+  logging, security, and maintainability.
+---
+
+# .NET/C# Best Practices
+
+Use this skill to keep .NET/C# changes simple, maintainable, testable, and aligned with this repository.
+
+## Repository Defaults
+
+- Follow the target framework and language version declared in `Directory.Build.props`.
+- Current defaults are `net10.0` and `LangVersion` set to `latest`.
+- Use modern C# features only when they improve readability or correctness.
+- Prefer clear, boring code over clever code.
+- Keep changes scoped to the current feature or bug.
+
+## Documentation and Structure
+
+- Add XML documentation comments for public APIs when they are part of the external or shared surface.
+- Include meaningful parameter and return descriptions when they add information beyond the name.
+- Organize code by feature/domain when the project already follows that structure.
+- Keep controllers, endpoints, handlers, validators, repositories, and DTOs in predictable folders.
+- Use namespaces that match the project and feature structure.
+
+## CQRS and Architecture
+
+- Commands mutate state and should return nothing, an ID, or a small result.
+- Queries read state and must not mutate data.
+- Keep controllers and minimal API endpoints thin; they should validate transport concerns and dispatch through MediatR.
+- Put business rules in domain/application services or entities, not controllers.
+- Use one handler per command or query.
+- Prefer records for commands, queries, and DTOs when immutability is appropriate.
+- Mark classes `sealed` unless inheritance is intentionally supported.
+- Use interfaces for boundaries that need substitution, testing, or multiple implementations.
+
+## Dependency Injection and Services
+
+- Use constructor injection or primary constructors for required dependencies.
+- Validate required dependencies when nullable flow does not already prove safety.
+- Register services with the narrowest correct lifetime:
+  - `Singleton` for stateless, thread-safe services.
+  - `Scoped` for request-bound services and EF Core `DbContext`.
+  - `Transient` for lightweight stateless services.
+- Do not resolve services manually from `IServiceProvider` unless there is a clear framework boundary.
+- Avoid hidden global state.
+
+## Async/Await
+
+- Use async/await for I/O, database, network, and long-running operations.
+- Do not block async work with `.Result`, `.Wait()`, or `.GetAwaiter().GetResult()`.
+- Prefer async all the way through the call chain.
+- Accept and pass `CancellationToken` on request, handler, EF Core, and HTTP calls.
+- Use `ConfigureAwait(false)` in reusable library code when appropriate; it is usually unnecessary in ASP.NET Core request code.
+- Avoid `async void` except for event handlers.
+
+## EF Core and Database Performance
+
+- Avoid N+1 queries. Use projections, `Include`, explicit joins, or separate optimized queries.
+- Use `.AsNoTracking()` for read-only queries.
+- Select only required columns into DTOs instead of loading full entities.
+- Add pagination for list endpoints; avoid returning unbounded result sets.
+- Filter in the database, not in memory.
+- Use indexes for frequent filters, joins, and ordering paths.
+- Prefer `AnyAsync` over `CountAsync` when checking existence.
+- Avoid lazy loading in APIs unless there is a specific measured reason.
+- Use `SplitQuery` only when it avoids cartesian explosion from large includes.
+- Batch writes where possible and call `SaveChangesAsync` once per unit of work.
+- Consider `ExecuteUpdateAsync` and `ExecuteDeleteAsync` for bulk updates/deletes.
+- Consider compiled queries only for measured hot paths.
+- Always parameterize raw SQL if raw SQL is truly needed.
+
+## Memory and Allocation Performance
+
+- Avoid unnecessary object creation in hot paths.
+- Use `StringBuilder` for repeated string concatenation in loops or large text generation.
+- Be careful with LINQ in hot paths; simple loops can reduce allocations and improve clarity.
+- Avoid exceptions for normal control flow.
+- Prefer `Array.Empty<T>()` over new empty arrays.
+- Reuse static readonly immutable data when safe.
+- Use pooling, `Span<T>`, `Memory<T>`, or `ValueTask` only when measurement shows a real benefit.
+
+## Caching
+
+- Cache frequently used, slow-changing data to reduce database and network load.
+- Use in-memory caching for single-instance or per-node data.
+- Use distributed caching such as Redis for multi-instance deployments or shared cache state.
+- Define clear cache keys, expiration, invalidation, and size limits.
+- Avoid caching sensitive user data unless encryption, isolation, and expiry are correct.
+- Prevent cache stampedes for expensive entries with locking or single-flight behavior.
+- Do not cache data that must be strongly consistent unless the domain explicitly allows staleness.
+
+## API Payload and Response Performance
+
+- Return DTOs that contain only the fields the caller needs.
+- Use pagination, filtering, and sorting parameters for collection endpoints.
+- Avoid sending large object graphs.
+- Enable response compression for compressible text responses such as JSON, HTML, CSS, and JavaScript.
+- Do not compress already compressed content such as images, videos, zip files, or PDFs.
+- Use ETags, `Last-Modified`, or cache headers where HTTP caching is safe.
+- Prefer streaming for large downloads instead of buffering the full payload in memory.
+
+## Logging and Observability
+
+- Use structured logging with message templates and named properties.
+- Avoid excessive logging in hot paths, especially per-item logs in loops.
+- Do not use string interpolation for expensive log messages unless guarded by `logger.IsEnabled(...)`.
+- Log enough context to diagnose failures without logging secrets or personal data.
+- Use correlation IDs, request IDs, or tracing context across request boundaries.
+- Use metrics/tracing for performance-critical paths instead of relying only on logs.
+
+## Efficient Data Structures
+
+- Use `Dictionary<TKey, TValue>` for fast key lookups.
+- Use `HashSet<T>` for uniqueness checks and membership tests.
+- Avoid repeated linear searches over large collections.
+- Use `List<T>` when order matters and append/read operations dominate.
+- Choose immutable or read-only collections when shared state should not change.
+
+## HTTP and External Calls
+
+- Use `IHttpClientFactory` for outbound HTTP calls.
+- Set timeouts and pass cancellation tokens.
+- Avoid retry storms; use bounded retries with backoff for transient failures.
+- Do not make external calls inside tight loops when batching is possible.
+- Prefer resilient integration patterns for unreliable dependencies.
+
+## Security
+
+- Validate and sanitize external input.
+- Use FluentValidation or existing validation patterns for request validation.
+- Never concatenate user input into SQL, file paths, shell commands, or logs.
+- Do not log secrets, tokens, passwords, connection strings, or sensitive personal data.
+- Use least-privilege configuration for database and external services.
+
+## Testing Standards
+
+- Use xUnit for unit tests.
+- Use FluentAssertions where it improves readability.
+- Use Moq or the existing repository mocking style for dependencies.
+- Follow Arrange, Act, Assert.
+- Test success, failure, validation, null/empty input, and cancellation paths when relevant.
+- Keep tests deterministic and independent.
+
+## Performance Workflow
+
+- Measure before optimizing unless the issue is obvious and local.
+- Prefer simple fixes before complex optimizations.
+- Use realistic data sizes when validating performance.
+- Consider tools such as logs, metrics, traces, `dotnet-counters`, `dotnet-trace`, BenchmarkDotNet, or database query plans.
+- Document any non-obvious optimization with the measured reason.
+- Do not trade correctness, security, or maintainability for small unmeasured gains.
+
+## Review Checklist
+
+- [ ] No avoidable N+1 queries.
+- [ ] Read-only EF Core queries use `.AsNoTracking()`.
+- [ ] Queries project only required columns.
+- [ ] Async code does not block on tasks.
+- [ ] Cancellation tokens flow through I/O boundaries.
+- [ ] No excessive allocations in hot paths.
+- [ ] Caching has clear expiration and invalidation.
+- [ ] Logs are structured and not excessive.
+- [ ] API responses avoid unnecessary payload size.
+- [ ] Compression and HTTP caching are used only where appropriate.
+- [ ] Data structures match access patterns.
+- [ ] Tests cover the changed behavior.

package/src/templates/dotnet/AgentSkills/skills/harness/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: harness
+description: >
+  Load when changing agent instructions, validation scripts, CI workflows,
+  hooks, or repository operational guardrails.
+---
+
+# Harness Engineering
+
+Harness engineering is the operational layer around the model:
+
+```text
+Agent = Model + Harness
+```
+
+Use this skill when adding or changing guide rails, validation, recovery, or feedback loops.
+
+## Controls
+
+| Control | Purpose | Repo examples |
+|---|---|---|
+| Guides | Feedforward controls that steer work before action | `AGENTS.md`, `AgentSkills/skills/INDEX.md`, `AgentSkills/agents/` |
+| Sensors | Feedback controls that observe output after action | `tools/Harness/validate.ps1`, `.github/workflows/dotnet.yml`, `.editorconfig` |
+
+## Rules
+
+- Keep `AgentSkills/` as the canonical source of truth.
+- Tool-specific folders may contain lightweight entry points only.
+- Prefer one shared validation command over duplicated CI, hook, and README commands.
+- Sensors must be deterministic first: restore, build, test, format.
+- Use inferential review only after computational checks pass.
+- Keep harness changes small, readable, and easy to remove.
+
+## Agent and IDE Entry Point Contract
+
+All coding agents and AI-enabled IDEs must start from
+`AgentSkills/OPERATING.md`.
+
+Tool-specific entry points must be short router files that:
+
+- Identify themselves as lightweight entry points.
+- Point to `AgentSkills/OPERATING.md`.
+- Point to `AgentSkills/skills/INDEX.md` for skill routing.
+- Point to `AgentSkills/agents/` for optional role definitions.
+- Avoid duplicating project rules, checklists, memory instructions, or skill content.
+
+When a new agent or IDE integration is added, create only the smallest entry
+point required by that tool and route it back to `AgentSkills/`.
+
+## Validation
+
+Run the shared sensor before finishing changes:
+
+```powershell
+pwsh ./tools/Harness/validate.ps1
+```
+
+For quick local loops:
+
+```powershell
+pwsh ./tools/Harness/validate.ps1 -Configuration Debug -SkipFormat
+```

package/src/templates/dotnet/AgentSkills/skills/mcp_dotnet/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: mcp_dotnet
+description: >
+  Load when building, reviewing, or extending .NET MCP server tools,
+  transports, contracts, and IDE/client integration.
+---
+
+# MCP .NET Skill
+
+Use this skill for Model Context Protocol work in this repository.
+
+## Project Rules
+
+- Keep MCP tools thin; route behavior through the same MediatR commands and queries used by REST endpoints.
+- Do not duplicate business logic in MCP tool methods.
+- Treat MCP tool contracts as public API: use stable names, clear descriptions, explicit input types, and small output DTOs.
+- Pass `CancellationToken` through all tool, mediator, EF Core, and HTTP boundaries.
+- Keep stdout reserved for MCP protocol messages when using stdio transport; send logs to stderr.
+- Validate tool inputs before dispatching commands or queries.
+- Avoid exposing raw entities, stack traces, connection strings, secrets, or internal schema details.
+- Add or update tests for tool behavior and contract mapping when MCP behavior changes.
+
+## Tool Design Checklist
+
+- [ ] Tool name is action-oriented and stable, for example `get_employee_by_id`.
+- [ ] Description tells the model when to use the tool.
+- [ ] Inputs are minimal and strongly typed.
+- [ ] Output is a DTO or result object, not an EF entity.
+- [ ] Tool delegates to MediatR or an existing application service.
+- [ ] Errors are structured and safe to show to an AI client.
+- [ ] Cancellation token is accepted and passed through.
+- [ ] New tools are documented in the relevant MCP docs when public usage changes.
+
+## Implementation Shape
+
+```csharp
+[McpTool("get_employee_by_id", "Gets one employee by id.")]
+public static async Task<EmployeeDto?> GetEmployeeByIdAsync(
+    Guid employeeId,
+    IMediator mediator,
+    CancellationToken cancellationToken)
+{
+    return await mediator.Send(
+        new GetEmployeeByIdQuery(employeeId),
+        cancellationToken);
+}
+```
+
+## Transport Notes
+
+- HTTP transport can share ASP.NET Core middleware for auth, validation, logging, and error handling.
+- Stdio transport must not write normal logs to stdout.
+- Keep `mcp.json` entries simple and point to built server artifacts or stable commands.
+- If a client cannot discover tools, verify the server builds, starts, and returns valid MCP initialize/list-tools responses.