@pratikpsl/agent-skills 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (26) hide show
  1. package/LICENSE +201 -201
  2. package/package.json +2 -2
  3. package/src/templates/dotnet/AgentSkills/README.md +40 -40
  4. package/src/templates/dotnet/AgentSkills/agents/README.md +11 -11
  5. package/src/templates/dotnet/AgentSkills/agents/architect.agent.md +59 -59
  6. package/src/templates/dotnet/AgentSkills/agents/developer.agent.md +88 -88
  7. package/src/templates/dotnet/AgentSkills/memory/index.md +21 -21
  8. package/src/templates/dotnet/AgentSkills/memory/lessons/api.md +3 -3
  9. package/src/templates/dotnet/AgentSkills/memory/lessons/auth.md +3 -3
  10. package/src/templates/dotnet/AgentSkills/memory/lessons/csharp.md +3 -3
  11. package/src/templates/dotnet/AgentSkills/memory/lessons/db.md +3 -3
  12. package/src/templates/dotnet/AgentSkills/memory/lessons/design.md +3 -3
  13. package/src/templates/dotnet/AgentSkills/memory/lessons/infra.md +2 -2
  14. package/src/templates/dotnet/AgentSkills/memory/lessons/mcp.md +3 -3
  15. package/src/templates/dotnet/AgentSkills/memory/lessons/testing.md +3 -3
  16. package/src/templates/dotnet/AgentSkills/memory/schema.md +26 -26
  17. package/src/templates/dotnet/AgentSkills/skills/INDEX.md +8 -8
  18. package/src/templates/dotnet/AgentSkills/skills/code-standards/SKILL.md +122 -122
  19. package/src/templates/dotnet/AgentSkills/skills/core/SKILL.md +23 -23
  20. package/src/templates/dotnet/AgentSkills/skills/csharp-xunit/SKILL.md +67 -67
  21. package/src/templates/dotnet/AgentSkills/skills/design/SKILL.md +108 -108
  22. package/src/templates/dotnet/AgentSkills/skills/dotnet-api/SKILL.md +303 -303
  23. package/src/templates/dotnet/AgentSkills/skills/dotnet-best-practices/SKILL.md +170 -170
  24. package/src/templates/dotnet/AgentSkills/skills/harness/SKILL.md +62 -62
  25. package/src/templates/dotnet/AgentSkills/skills/mcp_dotnet/SKILL.md +54 -54
  26. package/src/templates/dotnet/manifest.json +2 -2
@@ -1,170 +1,170 @@
1
- ---
2
- name: dotnet-best-practices
3
- description: >
4
- Load when writing, reviewing, refactoring, or optimizing .NET/C# code.
5
- Covers project conventions, CQRS, EF Core, async, testing, performance,
6
- logging, security, and maintainability.
7
- ---
8
-
9
- # .NET/C# Best Practices
10
-
11
- Use this skill to keep .NET/C# changes simple, maintainable, testable, and aligned with this repository.
12
-
13
- ## Repository Defaults
14
-
15
- - Follow the target framework and language version declared in `Directory.Build.props`.
16
- - Current defaults are `net10.0` and `LangVersion` set to `latest`.
17
- - Use modern C# features only when they improve readability or correctness.
18
- - Prefer clear, boring code over clever code.
19
- - Keep changes scoped to the current feature or bug.
20
-
21
- ## Documentation and Structure
22
-
23
- - Add XML documentation comments for public APIs when they are part of the external or shared surface.
24
- - Include meaningful parameter and return descriptions when they add information beyond the name.
25
- - Organize code by feature/domain when the project already follows that structure.
26
- - Keep controllers, endpoints, handlers, validators, repositories, and DTOs in predictable folders.
27
- - Use namespaces that match the project and feature structure.
28
-
29
- ## CQRS and Architecture
30
-
31
- - Commands mutate state and should return nothing, an ID, or a small result.
32
- - Queries read state and must not mutate data.
33
- - Keep controllers and minimal API endpoints thin; they should validate transport concerns and dispatch through MediatR.
34
- - Put business rules in domain/application services or entities, not controllers.
35
- - Use one handler per command or query.
36
- - Prefer records for commands, queries, and DTOs when immutability is appropriate.
37
- - Mark classes `sealed` unless inheritance is intentionally supported.
38
- - Use interfaces for boundaries that need substitution, testing, or multiple implementations.
39
-
40
- ## Dependency Injection and Services
41
-
42
- - Use constructor injection or primary constructors for required dependencies.
43
- - Validate required dependencies when nullable flow does not already prove safety.
44
- - Register services with the narrowest correct lifetime:
45
- - `Singleton` for stateless, thread-safe services.
46
- - `Scoped` for request-bound services and EF Core `DbContext`.
47
- - `Transient` for lightweight stateless services.
48
- - Do not resolve services manually from `IServiceProvider` unless there is a clear framework boundary.
49
- - Avoid hidden global state.
50
-
51
- ## Async/Await
52
-
53
- - Use async/await for I/O, database, network, and long-running operations.
54
- - Do not block async work with `.Result`, `.Wait()`, or `.GetAwaiter().GetResult()`.
55
- - Prefer async all the way through the call chain.
56
- - Accept and pass `CancellationToken` on request, handler, EF Core, and HTTP calls.
57
- - Use `ConfigureAwait(false)` in reusable library code when appropriate; it is usually unnecessary in ASP.NET Core request code.
58
- - Avoid `async void` except for event handlers.
59
-
60
- ## EF Core and Database Performance
61
-
62
- - Avoid N+1 queries. Use projections, `Include`, explicit joins, or separate optimized queries.
63
- - Use `.AsNoTracking()` for read-only queries.
64
- - Select only required columns into DTOs instead of loading full entities.
65
- - Add pagination for list endpoints; avoid returning unbounded result sets.
66
- - Filter in the database, not in memory.
67
- - Use indexes for frequent filters, joins, and ordering paths.
68
- - Prefer `AnyAsync` over `CountAsync` when checking existence.
69
- - Avoid lazy loading in APIs unless there is a specific measured reason.
70
- - Use `SplitQuery` only when it avoids cartesian explosion from large includes.
71
- - Batch writes where possible and call `SaveChangesAsync` once per unit of work.
72
- - Consider `ExecuteUpdateAsync` and `ExecuteDeleteAsync` for bulk updates/deletes.
73
- - Consider compiled queries only for measured hot paths.
74
- - Always parameterize raw SQL if raw SQL is truly needed.
75
-
76
- ## Memory and Allocation Performance
77
-
78
- - Avoid unnecessary object creation in hot paths.
79
- - Use `StringBuilder` for repeated string concatenation in loops or large text generation.
80
- - Be careful with LINQ in hot paths; simple loops can reduce allocations and improve clarity.
81
- - Avoid exceptions for normal control flow.
82
- - Prefer `Array.Empty<T>()` over new empty arrays.
83
- - Reuse static readonly immutable data when safe.
84
- - Use pooling, `Span<T>`, `Memory<T>`, or `ValueTask` only when measurement shows a real benefit.
85
-
86
- ## Caching
87
-
88
- - Cache frequently used, slow-changing data to reduce database and network load.
89
- - Use in-memory caching for single-instance or per-node data.
90
- - Use distributed caching such as Redis for multi-instance deployments or shared cache state.
91
- - Define clear cache keys, expiration, invalidation, and size limits.
92
- - Avoid caching sensitive user data unless encryption, isolation, and expiry are correct.
93
- - Prevent cache stampedes for expensive entries with locking or single-flight behavior.
94
- - Do not cache data that must be strongly consistent unless the domain explicitly allows staleness.
95
-
96
- ## API Payload and Response Performance
97
-
98
- - Return DTOs that contain only the fields the caller needs.
99
- - Use pagination, filtering, and sorting parameters for collection endpoints.
100
- - Avoid sending large object graphs.
101
- - Enable response compression for compressible text responses such as JSON, HTML, CSS, and JavaScript.
102
- - Do not compress already compressed content such as images, videos, zip files, or PDFs.
103
- - Use ETags, `Last-Modified`, or cache headers where HTTP caching is safe.
104
- - Prefer streaming for large downloads instead of buffering the full payload in memory.
105
-
106
- ## Logging and Observability
107
-
108
- - Use structured logging with message templates and named properties.
109
- - Avoid excessive logging in hot paths, especially per-item logs in loops.
110
- - Do not use string interpolation for expensive log messages unless guarded by `logger.IsEnabled(...)`.
111
- - Log enough context to diagnose failures without logging secrets or personal data.
112
- - Use correlation IDs, request IDs, or tracing context across request boundaries.
113
- - Use metrics/tracing for performance-critical paths instead of relying only on logs.
114
-
115
- ## Efficient Data Structures
116
-
117
- - Use `Dictionary<TKey, TValue>` for fast key lookups.
118
- - Use `HashSet<T>` for uniqueness checks and membership tests.
119
- - Avoid repeated linear searches over large collections.
120
- - Use `List<T>` when order matters and append/read operations dominate.
121
- - Choose immutable or read-only collections when shared state should not change.
122
-
123
- ## HTTP and External Calls
124
-
125
- - Use `IHttpClientFactory` for outbound HTTP calls.
126
- - Set timeouts and pass cancellation tokens.
127
- - Avoid retry storms; use bounded retries with backoff for transient failures.
128
- - Do not make external calls inside tight loops when batching is possible.
129
- - Prefer resilient integration patterns for unreliable dependencies.
130
-
131
- ## Security
132
-
133
- - Validate and sanitize external input.
134
- - Use FluentValidation or existing validation patterns for request validation.
135
- - Never concatenate user input into SQL, file paths, shell commands, or logs.
136
- - Do not log secrets, tokens, passwords, connection strings, or sensitive personal data.
137
- - Use least-privilege configuration for database and external services.
138
-
139
- ## Testing Standards
140
-
141
- - Use xUnit for unit tests.
142
- - Use FluentAssertions where it improves readability.
143
- - Use Moq or the existing repository mocking style for dependencies.
144
- - Follow Arrange, Act, Assert.
145
- - Test success, failure, validation, null/empty input, and cancellation paths when relevant.
146
- - Keep tests deterministic and independent.
147
-
148
- ## Performance Workflow
149
-
150
- - Measure before optimizing unless the issue is obvious and local.
151
- - Prefer simple fixes before complex optimizations.
152
- - Use realistic data sizes when validating performance.
153
- - Consider tools such as logs, metrics, traces, `dotnet-counters`, `dotnet-trace`, BenchmarkDotNet, or database query plans.
154
- - Document any non-obvious optimization with the measured reason.
155
- - Do not trade correctness, security, or maintainability for small unmeasured gains.
156
-
157
- ## Review Checklist
158
-
159
- - [ ] No avoidable N+1 queries.
160
- - [ ] Read-only EF Core queries use `.AsNoTracking()`.
161
- - [ ] Queries project only required columns.
162
- - [ ] Async code does not block on tasks.
163
- - [ ] Cancellation tokens flow through I/O boundaries.
164
- - [ ] No excessive allocations in hot paths.
165
- - [ ] Caching has clear expiration and invalidation.
166
- - [ ] Logs are structured and not excessive.
167
- - [ ] API responses avoid unnecessary payload size.
168
- - [ ] Compression and HTTP caching are used only where appropriate.
169
- - [ ] Data structures match access patterns.
170
- - [ ] Tests cover the changed behavior.
1
+ ---
2
+ name: dotnet-best-practices
3
+ description: >
4
+ Load when writing, reviewing, refactoring, or optimizing .NET/C# code.
5
+ Covers project conventions, CQRS, EF Core, async, testing, performance,
6
+ logging, security, and maintainability.
7
+ ---
8
+
9
+ # .NET/C# Best Practices
10
+
11
+ Use this skill to keep .NET/C# changes simple, maintainable, testable, and aligned with this repository.
12
+
13
+ ## Repository Defaults
14
+
15
+ - Follow the target framework and language version declared in `Directory.Build.props`.
16
+ - Current defaults are `net10.0` and `LangVersion` set to `latest`.
17
+ - Use modern C# features only when they improve readability or correctness.
18
+ - Prefer clear, boring code over clever code.
19
+ - Keep changes scoped to the current feature or bug.
20
+
21
+ ## Documentation and Structure
22
+
23
+ - Add XML documentation comments for public APIs when they are part of the external or shared surface.
24
+ - Include meaningful parameter and return descriptions when they add information beyond the name.
25
+ - Organize code by feature/domain when the project already follows that structure.
26
+ - Keep controllers, endpoints, handlers, validators, repositories, and DTOs in predictable folders.
27
+ - Use namespaces that match the project and feature structure.
28
+
29
+ ## CQRS and Architecture
30
+
31
+ - Commands mutate state and should return nothing, an ID, or a small result.
32
+ - Queries read state and must not mutate data.
33
+ - Keep controllers and minimal API endpoints thin; they should validate transport concerns and dispatch through MediatR.
34
+ - Put business rules in domain/application services or entities, not controllers.
35
+ - Use one handler per command or query.
36
+ - Prefer records for commands, queries, and DTOs when immutability is appropriate.
37
+ - Mark classes `sealed` unless inheritance is intentionally supported.
38
+ - Use interfaces for boundaries that need substitution, testing, or multiple implementations.
39
+
40
+ ## Dependency Injection and Services
41
+
42
+ - Use constructor injection or primary constructors for required dependencies.
43
+ - Validate required dependencies when nullable flow does not already prove safety.
44
+ - Register services with the narrowest correct lifetime:
45
+ - `Singleton` for stateless, thread-safe services.
46
+ - `Scoped` for request-bound services and EF Core `DbContext`.
47
+ - `Transient` for lightweight stateless services.
48
+ - Do not resolve services manually from `IServiceProvider` unless there is a clear framework boundary.
49
+ - Avoid hidden global state.
50
+
51
+ ## Async/Await
52
+
53
+ - Use async/await for I/O, database, network, and long-running operations.
54
+ - Do not block async work with `.Result`, `.Wait()`, or `.GetAwaiter().GetResult()`.
55
+ - Prefer async all the way through the call chain.
56
+ - Accept and pass `CancellationToken` on request, handler, EF Core, and HTTP calls.
57
+ - Use `ConfigureAwait(false)` in reusable library code when appropriate; it is usually unnecessary in ASP.NET Core request code.
58
+ - Avoid `async void` except for event handlers.
59
+
60
+ ## EF Core and Database Performance
61
+
62
+ - Avoid N+1 queries. Use projections, `Include`, explicit joins, or separate optimized queries.
63
+ - Use `.AsNoTracking()` for read-only queries.
64
+ - Select only required columns into DTOs instead of loading full entities.
65
+ - Add pagination for list endpoints; avoid returning unbounded result sets.
66
+ - Filter in the database, not in memory.
67
+ - Use indexes for frequent filters, joins, and ordering paths.
68
+ - Prefer `AnyAsync` over `CountAsync` when checking existence.
69
+ - Avoid lazy loading in APIs unless there is a specific measured reason.
70
+ - Use `SplitQuery` only when it avoids cartesian explosion from large includes.
71
+ - Batch writes where possible and call `SaveChangesAsync` once per unit of work.
72
+ - Consider `ExecuteUpdateAsync` and `ExecuteDeleteAsync` for bulk updates/deletes.
73
+ - Consider compiled queries only for measured hot paths.
74
+ - Always parameterize raw SQL if raw SQL is truly needed.
75
+
76
+ ## Memory and Allocation Performance
77
+
78
+ - Avoid unnecessary object creation in hot paths.
79
+ - Use `StringBuilder` for repeated string concatenation in loops or large text generation.
80
+ - Be careful with LINQ in hot paths; simple loops can reduce allocations and improve clarity.
81
+ - Avoid exceptions for normal control flow.
82
+ - Prefer `Array.Empty<T>()` over new empty arrays.
83
+ - Reuse static readonly immutable data when safe.
84
+ - Use pooling, `Span<T>`, `Memory<T>`, or `ValueTask` only when measurement shows a real benefit.
85
+
86
+ ## Caching
87
+
88
+ - Cache frequently used, slow-changing data to reduce database and network load.
89
+ - Use in-memory caching for single-instance or per-node data.
90
+ - Use distributed caching such as Redis for multi-instance deployments or shared cache state.
91
+ - Define clear cache keys, expiration, invalidation, and size limits.
92
+ - Avoid caching sensitive user data unless encryption, isolation, and expiry are correct.
93
+ - Prevent cache stampedes for expensive entries with locking or single-flight behavior.
94
+ - Do not cache data that must be strongly consistent unless the domain explicitly allows staleness.
95
+
96
+ ## API Payload and Response Performance
97
+
98
+ - Return DTOs that contain only the fields the caller needs.
99
+ - Use pagination, filtering, and sorting parameters for collection endpoints.
100
+ - Avoid sending large object graphs.
101
+ - Enable response compression for compressible text responses such as JSON, HTML, CSS, and JavaScript.
102
+ - Do not compress already compressed content such as images, videos, zip files, or PDFs.
103
+ - Use ETags, `Last-Modified`, or cache headers where HTTP caching is safe.
104
+ - Prefer streaming for large downloads instead of buffering the full payload in memory.
105
+
106
+ ## Logging and Observability
107
+
108
+ - Use structured logging with message templates and named properties.
109
+ - Avoid excessive logging in hot paths, especially per-item logs in loops.
110
+ - Do not use string interpolation for expensive log messages unless guarded by `logger.IsEnabled(...)`.
111
+ - Log enough context to diagnose failures without logging secrets or personal data.
112
+ - Use correlation IDs, request IDs, or tracing context across request boundaries.
113
+ - Use metrics/tracing for performance-critical paths instead of relying only on logs.
114
+
115
+ ## Efficient Data Structures
116
+
117
+ - Use `Dictionary<TKey, TValue>` for fast key lookups.
118
+ - Use `HashSet<T>` for uniqueness checks and membership tests.
119
+ - Avoid repeated linear searches over large collections.
120
+ - Use `List<T>` when order matters and append/read operations dominate.
121
+ - Choose immutable or read-only collections when shared state should not change.
122
+
123
+ ## HTTP and External Calls
124
+
125
+ - Use `IHttpClientFactory` for outbound HTTP calls.
126
+ - Set timeouts and pass cancellation tokens.
127
+ - Avoid retry storms; use bounded retries with backoff for transient failures.
128
+ - Do not make external calls inside tight loops when batching is possible.
129
+ - Prefer resilient integration patterns for unreliable dependencies.
130
+
131
+ ## Security
132
+
133
+ - Validate and sanitize external input.
134
+ - Use FluentValidation or existing validation patterns for request validation.
135
+ - Never concatenate user input into SQL, file paths, shell commands, or logs.
136
+ - Do not log secrets, tokens, passwords, connection strings, or sensitive personal data.
137
+ - Use least-privilege configuration for database and external services.
138
+
139
+ ## Testing Standards
140
+
141
+ - Use xUnit for unit tests.
142
+ - Use FluentAssertions where it improves readability.
143
+ - Use Moq or the existing repository mocking style for dependencies.
144
+ - Follow Arrange, Act, Assert.
145
+ - Test success, failure, validation, null/empty input, and cancellation paths when relevant.
146
+ - Keep tests deterministic and independent.
147
+
148
+ ## Performance Workflow
149
+
150
+ - Measure before optimizing unless the issue is obvious and local.
151
+ - Prefer simple fixes before complex optimizations.
152
+ - Use realistic data sizes when validating performance.
153
+ - Consider tools such as logs, metrics, traces, `dotnet-counters`, `dotnet-trace`, BenchmarkDotNet, or database query plans.
154
+ - Document any non-obvious optimization with the measured reason.
155
+ - Do not trade correctness, security, or maintainability for small unmeasured gains.
156
+
157
+ ## Review Checklist
158
+
159
+ - [ ] No avoidable N+1 queries.
160
+ - [ ] Read-only EF Core queries use `.AsNoTracking()`.
161
+ - [ ] Queries project only required columns.
162
+ - [ ] Async code does not block on tasks.
163
+ - [ ] Cancellation tokens flow through I/O boundaries.
164
+ - [ ] No excessive allocations in hot paths.
165
+ - [ ] Caching has clear expiration and invalidation.
166
+ - [ ] Logs are structured and not excessive.
167
+ - [ ] API responses avoid unnecessary payload size.
168
+ - [ ] Compression and HTTP caching are used only where appropriate.
169
+ - [ ] Data structures match access patterns.
170
+ - [ ] Tests cover the changed behavior.
@@ -1,62 +1,62 @@
1
- ---
2
- name: harness
3
- description: >
4
- Load when changing agent instructions, validation scripts, CI workflows,
5
- hooks, or repository operational guardrails.
6
- ---
7
-
8
- # Harness Engineering
9
-
10
- Harness engineering is the operational layer around the model:
11
-
12
- ```text
13
- Agent = Model + Harness
14
- ```
15
-
16
- Use this skill when adding or changing guide rails, validation, recovery, or feedback loops.
17
-
18
- ## Controls
19
-
20
- | Control | Purpose | Repo examples |
21
- |---|---|---|
22
- | Guides | Feedforward controls that steer work before action | `AGENTS.md`, `AgentSkills/skills/INDEX.md`, `AgentSkills/agents/` |
23
- | Sensors | Feedback controls that observe output after action | `tools/Harness/validate.ps1`, `.github/workflows/dotnet.yml`, `.editorconfig` |
24
-
25
- ## Rules
26
-
27
- - Keep `AgentSkills/` as the canonical source of truth.
28
- - Tool-specific folders may contain lightweight entry points only.
29
- - Prefer one shared validation command over duplicated CI, hook, and README commands.
30
- - Sensors must be deterministic first: restore, build, test, format.
31
- - Use inferential review only after computational checks pass.
32
- - Keep harness changes small, readable, and easy to remove.
33
-
34
- ## Agent and IDE Entry Point Contract
35
-
36
- All coding agents and AI-enabled IDEs must start from
37
- `AgentSkills/OPERATING.md`.
38
-
39
- Tool-specific entry points must be short router files that:
40
-
41
- - Identify themselves as lightweight entry points.
42
- - Point to `AgentSkills/OPERATING.md`.
43
- - Point to `AgentSkills/skills/INDEX.md` for skill routing.
44
- - Point to `AgentSkills/agents/` for optional role definitions.
45
- - Avoid duplicating project rules, checklists, memory instructions, or skill content.
46
-
47
- When a new agent or IDE integration is added, create only the smallest entry
48
- point required by that tool and route it back to `AgentSkills/`.
49
-
50
- ## Validation
51
-
52
- Run the shared sensor before finishing changes:
53
-
54
- ```powershell
55
- pwsh ./tools/Harness/validate.ps1
56
- ```
57
-
58
- For quick local loops:
59
-
60
- ```powershell
61
- pwsh ./tools/Harness/validate.ps1 -Configuration Debug -SkipFormat
62
- ```
1
+ ---
2
+ name: harness
3
+ description: >
4
+ Load when changing agent instructions, validation scripts, CI workflows,
5
+ hooks, or repository operational guardrails.
6
+ ---
7
+
8
+ # Harness Engineering
9
+
10
+ Harness engineering is the operational layer around the model:
11
+
12
+ ```text
13
+ Agent = Model + Harness
14
+ ```
15
+
16
+ Use this skill when adding or changing guide rails, validation, recovery, or feedback loops.
17
+
18
+ ## Controls
19
+
20
+ | Control | Purpose | Repo examples |
21
+ |---|---|---|
22
+ | Guides | Feedforward controls that steer work before action | `AGENTS.md`, `AgentSkills/skills/INDEX.md`, `AgentSkills/agents/` |
23
+ | Sensors | Feedback controls that observe output after action | `tools/Harness/validate.ps1`, `.github/workflows/dotnet.yml`, `.editorconfig` |
24
+
25
+ ## Rules
26
+
27
+ - Keep `AgentSkills/` as the canonical source of truth.
28
+ - Tool-specific folders may contain lightweight entry points only.
29
+ - Prefer one shared validation command over duplicated CI, hook, and README commands.
30
+ - Sensors must be deterministic first: restore, build, test, format.
31
+ - Use inferential review only after computational checks pass.
32
+ - Keep harness changes small, readable, and easy to remove.
33
+
34
+ ## Agent and IDE Entry Point Contract
35
+
36
+ All coding agents and AI-enabled IDEs must start from
37
+ `AgentSkills/OPERATING.md`.
38
+
39
+ Tool-specific entry points must be short router files that:
40
+
41
+ - Identify themselves as lightweight entry points.
42
+ - Point to `AgentSkills/OPERATING.md`.
43
+ - Point to `AgentSkills/skills/INDEX.md` for skill routing.
44
+ - Point to `AgentSkills/agents/` for optional role definitions.
45
+ - Avoid duplicating project rules, checklists, memory instructions, or skill content.
46
+
47
+ When a new agent or IDE integration is added, create only the smallest entry
48
+ point required by that tool and route it back to `AgentSkills/`.
49
+
50
+ ## Validation
51
+
52
+ Run the shared sensor before finishing changes:
53
+
54
+ ```powershell
55
+ pwsh ./tools/Harness/validate.ps1
56
+ ```
57
+
58
+ For quick local loops:
59
+
60
+ ```powershell
61
+ pwsh ./tools/Harness/validate.ps1 -Configuration Debug -SkipFormat
62
+ ```
@@ -1,54 +1,54 @@
1
- ---
2
- name: mcp_dotnet
3
- description: >
4
- Load when building, reviewing, or extending .NET MCP server tools,
5
- transports, contracts, and IDE/client integration.
6
- ---
7
-
8
- # MCP .NET Skill
9
-
10
- Use this skill for Model Context Protocol work in this repository.
11
-
12
- ## Project Rules
13
-
14
- - Keep MCP tools thin; route behavior through the same MediatR commands and queries used by REST endpoints.
15
- - Do not duplicate business logic in MCP tool methods.
16
- - Treat MCP tool contracts as public API: use stable names, clear descriptions, explicit input types, and small output DTOs.
17
- - Pass `CancellationToken` through all tool, mediator, EF Core, and HTTP boundaries.
18
- - Keep stdout reserved for MCP protocol messages when using stdio transport; send logs to stderr.
19
- - Validate tool inputs before dispatching commands or queries.
20
- - Avoid exposing raw entities, stack traces, connection strings, secrets, or internal schema details.
21
- - Add or update tests for tool behavior and contract mapping when MCP behavior changes.
22
-
23
- ## Tool Design Checklist
24
-
25
- - [ ] Tool name is action-oriented and stable, for example `get_employee_by_id`.
26
- - [ ] Description tells the model when to use the tool.
27
- - [ ] Inputs are minimal and strongly typed.
28
- - [ ] Output is a DTO or result object, not an EF entity.
29
- - [ ] Tool delegates to MediatR or an existing application service.
30
- - [ ] Errors are structured and safe to show to an AI client.
31
- - [ ] Cancellation token is accepted and passed through.
32
- - [ ] New tools are documented in the relevant MCP docs when public usage changes.
33
-
34
- ## Implementation Shape
35
-
36
- ```csharp
37
- [McpTool("get_employee_by_id", "Gets one employee by id.")]
38
- public static async Task<EmployeeDto?> GetEmployeeByIdAsync(
39
- Guid employeeId,
40
- IMediator mediator,
41
- CancellationToken cancellationToken)
42
- {
43
- return await mediator.Send(
44
- new GetEmployeeByIdQuery(employeeId),
45
- cancellationToken);
46
- }
47
- ```
48
-
49
- ## Transport Notes
50
-
51
- - HTTP transport can share ASP.NET Core middleware for auth, validation, logging, and error handling.
52
- - Stdio transport must not write normal logs to stdout.
53
- - Keep `mcp.json` entries simple and point to built server artifacts or stable commands.
54
- - If a client cannot discover tools, verify the server builds, starts, and returns valid MCP initialize/list-tools responses.
1
+ ---
2
+ name: mcp_dotnet
3
+ description: >
4
+ Load when building, reviewing, or extending .NET MCP server tools,
5
+ transports, contracts, and IDE/client integration.
6
+ ---
7
+
8
+ # MCP .NET Skill
9
+
10
+ Use this skill for Model Context Protocol work in this repository.
11
+
12
+ ## Project Rules
13
+
14
+ - Keep MCP tools thin; route behavior through the same MediatR commands and queries used by REST endpoints.
15
+ - Do not duplicate business logic in MCP tool methods.
16
+ - Treat MCP tool contracts as public API: use stable names, clear descriptions, explicit input types, and small output DTOs.
17
+ - Pass `CancellationToken` through all tool, mediator, EF Core, and HTTP boundaries.
18
+ - Keep stdout reserved for MCP protocol messages when using stdio transport; send logs to stderr.
19
+ - Validate tool inputs before dispatching commands or queries.
20
+ - Avoid exposing raw entities, stack traces, connection strings, secrets, or internal schema details.
21
+ - Add or update tests for tool behavior and contract mapping when MCP behavior changes.
22
+
23
+ ## Tool Design Checklist
24
+
25
+ - [ ] Tool name is action-oriented and stable, for example `get_employee_by_id`.
26
+ - [ ] Description tells the model when to use the tool.
27
+ - [ ] Inputs are minimal and strongly typed.
28
+ - [ ] Output is a DTO or result object, not an EF entity.
29
+ - [ ] Tool delegates to MediatR or an existing application service.
30
+ - [ ] Errors are structured and safe to show to an AI client.
31
+ - [ ] Cancellation token is accepted and passed through.
32
+ - [ ] New tools are documented in the relevant MCP docs when public usage changes.
33
+
34
+ ## Implementation Shape
35
+
36
+ ```csharp
37
+ [McpTool("get_employee_by_id", "Gets one employee by id.")]
38
+ public static async Task<EmployeeDto?> GetEmployeeByIdAsync(
39
+ Guid employeeId,
40
+ IMediator mediator,
41
+ CancellationToken cancellationToken)
42
+ {
43
+ return await mediator.Send(
44
+ new GetEmployeeByIdQuery(employeeId),
45
+ cancellationToken);
46
+ }
47
+ ```
48
+
49
+ ## Transport Notes
50
+
51
+ - HTTP transport can share ASP.NET Core middleware for auth, validation, logging, and error handling.
52
+ - Stdio transport must not write normal logs to stdout.
53
+ - Keep `mcp.json` entries simple and point to built server artifacts or stable commands.
54
+ - If a client cannot discover tools, verify the server builds, starts, and returns valid MCP initialize/list-tools responses.
@@ -1,6 +1,6 @@
1
- {
1
+ {
2
2
  "name": "@pratikpsl/agent-skills-dotnet",
3
- "version": "0.1.0",
3
+ "version": "0.3.0",
4
4
  "description": "AI agent skill definitions for .NET/C# projects (CQRS, MediatR, EF Core, xUnit, ASP.NET Core).",
5
5
  "skills": [
6
6
  {