From 4b01e295285232715dcab049419889eea8c5c879 Mon Sep 17 00:00:00 2001 From: yasmoradi Date: Tue, 1 Sep 2026 23:23:00 +0200 Subject: [PATCH 1/4] imrove coding agents instructions (#13110) --- .github/copilot-instructions.md | 6 +- .github/workflows/wiki.sh | 45 ----- .github/workflows/wiki.yml | 76 --------- .vscode/mcp.json | 8 +- .../skills/ai-dlc/SKILL.md} | 10 +- .../skills/bitify-ui/SKILL.md} | 4 +- .../skills/code-reviewer/SKILL.md} | 7 +- .../skills/localize-strings/SKILL.md} | 4 +- .../skills/scaffold-entity/SKILL.md} | 6 +- .../.claude/skills/ai-dlc/SKILL.md | 11 ++ .../.claude/skills/bitify-ui/SKILL.md | 11 ++ .../.claude/skills/code-reviewer/SKILL.md | 12 ++ .../.claude/skills/localize-strings/SKILL.md | 11 ++ .../.claude/skills/scaffold-entity/SKILL.md | 11 ++ .../Bit.Boilerplate/.cursor/mcp.json | 25 +++ .../Bit.Boilerplate/.cursor/rules/agents.mdc | 10 -- .../Bit.Boilerplate/.docs/00- Wiki.md | 8 +- .../.docs/01- Entity Framework Core.md | 4 +- .../.docs/02- DTOs, Mappers, and Mapperly.md | 6 + .../.docs/03- API Controllers and OData.md | 6 + ...d Jobs and CancellationToken Management.md | 4 +- ...Localization and Multi-language Support.md | 6 + ...Exception Handling and Error Management.md | 2 +- ...entity - Authentication & Authorization.md | 4 +- ...Pages, Components, Styling & Navigation.md | 16 +- ...ndency Injection & Service Registration.md | 2 +- .../10- Configuration (appsettings.json).md | 8 +- ...ipt, Build Process & JavaScript Interop.md | 6 + .../12- Blazor Modes, PreRendering & PWA.md | 6 + .../.docs/13- Force Update System.md | 8 +- .../.docs/14- Response Caching System.md | 2 +- ...ogging, OpenTelemetry and Health Checks.md | 6 + .../16- CI-CD Pipeline and Environments.md | 6 + ... Automated Testing (Unitigration Tests).md | 8 +- .../.docs/18- Available Agent Skills.md | 155 ++++++++++++++++++ .../18- Other Available Prompt Templates.md | 81 --------- .../.docs/19- Project Miscellaneous Files.md | 25 ++- .../Bit.Boilerplate/.docs/20- .NET Aspire.md | 6 + .../.docs/21- .NET MAUI - Blazor Hybrid.md | 8 + .../Bit.Boilerplate/.docs/22- Messaging.md | 4 +- .../.docs/23- Diagnostic Modal.md | 8 +- ... Passwordless Authentication (Advanced).md | 6 + ...earch with Vector Embeddings (Advanced).md | 7 + .../.gemini/commands/ai-dlc.toml | 11 ++ .../.gemini/commands/bitify-ui.toml | 11 ++ .../.gemini/commands/code-reviewer.toml | 11 ++ .../.gemini/commands/localize-strings.toml | 11 ++ .../.gemini/commands/scaffold-entity.toml | 11 ++ .../Bit.Boilerplate/.gemini/settings.json | 25 +++ .../.github/copilot-instructions.md | 4 +- .../Bit.Boilerplate/.junie/guidelines.md | 5 - .../Bit.Boilerplate/.junie/mcp/mcp.json | 26 +++ .../Boilerplate/Bit.Boilerplate/AGENTS.md | 15 +- .../Bit.Boilerplate/Boilerplate.sln | 22 ++- .../Bit.Boilerplate/Boilerplate.slnx | 19 +-- .../Boilerplate/Bit.Boilerplate/CLAUDE.md | 8 +- .../Boilerplate/Bit.Boilerplate/GEMINI.md | 8 +- .../Documentation/DocumentationTruthTests.cs | 48 ++++-- .../Pages/AskPage.razor | 18 ++ .../Pages/Templates/Templates06Wiki.razor | 26 +-- .../Services/PubSubMessages.cs | 1 + .../Shared/AppAiChatPanel.razor.cs | 17 ++ .../Shared/SiteMapUrls.cs | 1 + .../Shared/Urls.cs | 1 + 64 files changed, 637 insertions(+), 327 deletions(-) delete mode 100644 .github/workflows/wiki.sh delete mode 100644 .github/workflows/wiki.yml rename src/Templates/Boilerplate/Bit.Boilerplate/{.github/agents/ai-dlc.agent.md => .agents/skills/ai-dlc/SKILL.md} (55%) rename src/Templates/Boilerplate/Bit.Boilerplate/{.github/prompts/bitify.prompt.md => .agents/skills/bitify-ui/SKILL.md} (96%) rename src/Templates/Boilerplate/Bit.Boilerplate/{.github/agents/code-reviewer.agent.md => .agents/skills/code-reviewer/SKILL.md} (81%) rename src/Templates/Boilerplate/Bit.Boilerplate/{.github/prompts/resx.prompt.md => .agents/skills/localize-strings/SKILL.md} (88%) rename src/Templates/Boilerplate/Bit.Boilerplate/{.github/prompts/scaffold.prompt.md => .agents/skills/scaffold-entity/SKILL.md} (93%) create mode 100644 src/Templates/Boilerplate/Bit.Boilerplate/.claude/skills/ai-dlc/SKILL.md create mode 100644 src/Templates/Boilerplate/Bit.Boilerplate/.claude/skills/bitify-ui/SKILL.md create mode 100644 src/Templates/Boilerplate/Bit.Boilerplate/.claude/skills/code-reviewer/SKILL.md create mode 100644 src/Templates/Boilerplate/Bit.Boilerplate/.claude/skills/localize-strings/SKILL.md create mode 100644 src/Templates/Boilerplate/Bit.Boilerplate/.claude/skills/scaffold-entity/SKILL.md create mode 100644 src/Templates/Boilerplate/Bit.Boilerplate/.cursor/mcp.json delete mode 100644 src/Templates/Boilerplate/Bit.Boilerplate/.cursor/rules/agents.mdc create mode 100644 src/Templates/Boilerplate/Bit.Boilerplate/.docs/18- Available Agent Skills.md delete mode 100644 src/Templates/Boilerplate/Bit.Boilerplate/.docs/18- Other Available Prompt Templates.md create mode 100644 src/Templates/Boilerplate/Bit.Boilerplate/.gemini/commands/ai-dlc.toml create mode 100644 src/Templates/Boilerplate/Bit.Boilerplate/.gemini/commands/bitify-ui.toml create mode 100644 src/Templates/Boilerplate/Bit.Boilerplate/.gemini/commands/code-reviewer.toml create mode 100644 src/Templates/Boilerplate/Bit.Boilerplate/.gemini/commands/localize-strings.toml create mode 100644 src/Templates/Boilerplate/Bit.Boilerplate/.gemini/commands/scaffold-entity.toml create mode 100644 src/Templates/Boilerplate/Bit.Boilerplate/.gemini/settings.json delete mode 100644 src/Templates/Boilerplate/Bit.Boilerplate/.junie/guidelines.md create mode 100644 src/Templates/Boilerplate/Bit.Boilerplate/.junie/mcp/mcp.json create mode 100644 src/Websites/Platform/src/Bit.Websites.Platform.Client/Pages/AskPage.razor diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 8fd7df2a95d..07d0b3f8317 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -46,13 +46,13 @@ ## Rules **RULE 1:** If a task (question, code modification or review) involves the use of bit BlazorUI components (e.g., `BitButton`, `BitTooltip`, `BitTextField`), -or refers to `bitplatform`, `bit Bswup`, `bit Butil`, `bit Besql`, or `bit Boilerplate`, or involves UI components without explicitly specifying their UI toolkit, -you **MUST** use the deepwiki's `ask_question` mcp tool to find the correct implementation and usage patterns of `bitfoundation/bitplatform` deep wiki before writing or changing any code. +or refers to `bitplatform`, `bit Bswup`, `bit Butil`, `bit Bmotion`, `bit Brouter`, or `bit Boilerplate`, or involves UI components without explicitly specifying their UI toolkit, +you **MUST** use the `bitplatform` MCP server's tools - start with the matching `Search` tool (e.g. `SearchBitBlazorUI`, `SearchBswup`, `SearchButil`, `SearchBmotion`, `SearchBrouter`) and follow the calls it names - to find the correct implementation and usage patterns before writing or changing any code. **End of RULE 1** **RULE 2:** If a task (question, code modification, or review) involves Microsoft technologies such as C#, F#, ASP.NET Core, Microsoft.Extensions, NuGet, Entity Framework, Blazor or the `dotnet` runtime, -you **MUST** use the `microsoft.docs.mcp` server to search Microsoft's latest official documentation for detailed and up-to-date information before responding to specific or narrowly defined questions. +you **MUST** use the `microsoft_docs_search`, `microsoft_docs_fetch` and `microsoft_code_sample_search` tools of the `bitplatform` MCP server to search Microsoft's latest official documentation for detailed and up-to-date information before responding to specific or narrowly defined questions. **End of RULE 2** diff --git a/.github/workflows/wiki.sh b/.github/workflows/wiki.sh deleted file mode 100644 index ade68c0a9cc..00000000000 --- a/.github/workflows/wiki.sh +++ /dev/null @@ -1,45 +0,0 @@ -#!/bin/bash - -# This script performs the full MCP query and prints the final URL as its output. - -set -euo pipefail - -# Combine issue title and body from environment variables provided by the workflow. -QUESTION="Title: $ISSUE_TITLE. Body: $ISSUE_BODY" - -# The URL of the MCP tool endpoint. -url="https://mcp.deepwiki.com/mcp" - -# The server runs in stateless mode, so no initialize/initialized handshake is needed. -# Use jq to safely construct the JSON payload, passing the question as an argument -# to avoid shell interpretation issues. -JSON_PAYLOAD=$(jq -n \ - --arg question "$QUESTION" \ - '{ - "jsonrpc": "2.0", - "id": 2, - "method": "tools/call", - "params": { - "name": "ask_question", - "arguments": { - "repoName": "bitfoundation/bitplatform", - "question": $question - } - } - }') - -# Send the query. A transport level failure here fails the whole step. -RESPONSE=$(curl -s --fail-with-body -X POST \ - -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \ - -d "$JSON_PAYLOAD" \ - "$url") - -# Extract the first URL and replace the domain. -# The URL is embedded in a JSON string, so stop at the first quote or backslash -# (the response terminates the URL with an escaped newline). -# An empty result is not an error, it just means no comment gets posted. -# The trailing `|| true` keeps a no-match grep from tripping `pipefail`. -echo "$RESPONSE" \ - | { grep -o 'https://deepwiki\.com/search/[^"\\]*' || true; } \ - | head -n 1 \ - | sed 's|https://deepwiki.com|https://wiki.bitplatform.dev|' diff --git a/.github/workflows/wiki.yml b/.github/workflows/wiki.yml deleted file mode 100644 index c9f479c4c1a..00000000000 --- a/.github/workflows/wiki.yml +++ /dev/null @@ -1,76 +0,0 @@ -name: 'bitplatform wiki' - -on: - issues: - types: [opened] - discussion: - types: [created] - -jobs: - build-and-comment: - runs-on: ubuntu-24.04 - permissions: - issues: write - discussions: write - - steps: - - name: Checkout repository - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - persist-credentials: false - - - name: Install jq - run: sudo apt-get update && sudo apt-get install -y jq - - - name: Run wiki query script - id: run-mcp-query - run: | - chmod +x ./.github/workflows/wiki.sh - # Assign first so a failing script fails this step instead of silently - # producing an empty output and skipping the comment. - wiki_url=$(./.github/workflows/wiki.sh) - echo "wiki_url=$wiki_url" >> $GITHUB_OUTPUT - env: - ISSUE_TITLE: ${{ github.event.issue.title || github.event.discussion.title }} - ISSUE_BODY: ${{ github.event.issue.body || github.event.discussion.body }} - - - name: Write comment - if: steps.run-mcp-query.outputs.wiki_url - uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 - with: - github-token: ${{ secrets.GITHUB_TOKEN }} - script: | - const commentBody = ` - Hello there! I'm a wiki πŸ€–. - - Based on the content of this thread, I've found a potentially relevant wiki page for you! - - **✨ [View Wiki Page](${{ steps.run-mcp-query.outputs.wiki_url }})** - - I hope this helps! - `; - - if (context.eventName === 'issues') { - await github.rest.issues.createComment({ - issue_number: context.issue.number, - owner: context.repo.owner, - repo: context.repo.repo, - body: commentBody - }); - } else if (context.eventName === 'discussion') { - const discussionId = context.payload.discussion.node_id; - - await github.graphql( - `mutation($discussionId: ID!, $body: String!) { - addDiscussionComment(input: {discussionId: $discussionId, body: $body}) { - comment { - id - } - } - }`, - { - discussionId: discussionId, - body: commentBody - } - ); - } diff --git a/.vscode/mcp.json b/.vscode/mcp.json index 3f0fe488029..83823e38c8c 100644 --- a/.vscode/mcp.json +++ b/.vscode/mcp.json @@ -1,12 +1,8 @@ { "servers": { - "DeepWiki": { - "type": "sse", - "url": "https://mcp.deepwiki.com/mcp" - }, - "microsoft.docs.mcp": { + "bitplatform": { "type": "http", - "url": "https://learn.microsoft.com/api/mcp" + "url": "https://bitplatform.dev/mcp" }, "github": { "type": "http", diff --git a/src/Templates/Boilerplate/Bit.Boilerplate/.github/agents/ai-dlc.agent.md b/src/Templates/Boilerplate/Bit.Boilerplate/.agents/skills/ai-dlc/SKILL.md similarity index 55% rename from src/Templates/Boilerplate/Bit.Boilerplate/.github/agents/ai-dlc.agent.md rename to src/Templates/Boilerplate/Bit.Boilerplate/.agents/skills/ai-dlc/SKILL.md index a68645ce61b..8b7970dd907 100644 --- a/src/Templates/Boilerplate/Bit.Boilerplate/.github/agents/ai-dlc.agent.md +++ b/src/Templates/Boilerplate/Bit.Boilerplate/.agents/skills/ai-dlc/SKILL.md @@ -1,6 +1,6 @@ --- name: ai-dlc -description: Guides development using the AI-Driven Development Lifecycle (AI-DLC) method. Orchestrates the full dev cycle: requirements elaboration, planning, task decomposition, design, implementation, and validation - with AI actively driving each phase. +description: Drives a feature end-to-end using the AI-Driven Development Lifecycle - requirements elaboration, planning and task decomposition, design, implementation, then validation - with explicit user approval before any code is written. Use when the user asks to build a feature properly/end-to-end, wants a structured dev cycle, asks for requirements-then-plan-then-implement, or says "run ai-dlc". --- # AI-Driven Development Lifecycle (AI-DLC) @@ -13,8 +13,8 @@ description: Guides development using the AI-Driven Development Lifecycle (AI-DL - Do NOT proceed until requirements are unambiguous ### 2. Planning & Task Decomposition -- If the built-in **Plan** agent is available, invoke it to assist with decomposing work into tasks -- **If the design involves CRUD operations**, consult the **scaffold** prompt (.github/prompts/scaffold.prompt.md) for guidance on structure and conventions +- If a built-in **Plan** agent or plan mode is available, use it to help decompose the work into tasks +- **If the design involves CRUD operations**, invoke the **scaffold-entity** skill (`.agents/skills/scaffold-entity/SKILL.md`) for structure and conventions - Break the work into small, verifiable, independently completable tasks - Order tasks by dependency - Present the plan to the user for approval before starting @@ -27,15 +27,17 @@ description: Guides development using the AI-Driven Development Lifecycle (AI-DL ### 4. Implementation - Execute tasks one at a time in the planned order - Follow all project conventions (see AGENTS.md) +- Use the **bitify-ui** skill (`.agents/skills/bitify-ui/SKILL.md`) when building UI, so new markup starts from Bit.BlazorUI components rather than raw HTML - After each task: verify correctness, run relevant checks ### 5. Validation - Run build and tests after completing all tasks +- Invoke the **code-reviewer** skill (`.agents/skills/code-reviewer/SKILL.md`) on the resulting changes - Confirm acceptance criteria are met - Surface any issues found and resolve them before handing back ## Rules -- Always complete phases 1–2 before writing any code +- Always complete phases 1-2 before writing any code - Keep the user informed of phase transitions - If blocked, explain why and propose alternatives - never silently skip work - Limit each task to a single concern; avoid batching unrelated changes diff --git a/src/Templates/Boilerplate/Bit.Boilerplate/.github/prompts/bitify.prompt.md b/src/Templates/Boilerplate/Bit.Boilerplate/.agents/skills/bitify-ui/SKILL.md similarity index 96% rename from src/Templates/Boilerplate/Bit.Boilerplate/.github/prompts/bitify.prompt.md rename to src/Templates/Boilerplate/Bit.Boilerplate/.agents/skills/bitify-ui/SKILL.md index 79d966f2b22..23ef34536b4 100644 --- a/src/Templates/Boilerplate/Bit.Boilerplate/.github/prompts/bitify.prompt.md +++ b/src/Templates/Boilerplate/Bit.Boilerplate/.agents/skills/bitify-ui/SKILL.md @@ -1,6 +1,6 @@ --- -mode: 'agent' -description: Modernizes Blazor pages by replacing raw HTML elements and custom CSS with Bit.BlazorUI components and theme-aware styling. Uses MCP tools to discover components, inspect their exact APIs, and retrieve real code examples. +name: bitify-ui +description: Modernizes Blazor pages by replacing raw HTML elements and custom CSS with Bit.BlazorUI components and theme-aware styling, using the bit BlazorUI MCP tools to discover components and verify their exact APIs. Use when the user asks to bitify a page, replace HTML/div/button/input markup with Bit components, remove hardcoded colors, make a page theme-aware or dark-mode ready, or says "run bitify". --- # Bitify: Replace raw HTML/CSS with Bit.BlazorUI components diff --git a/src/Templates/Boilerplate/Bit.Boilerplate/.github/agents/code-reviewer.agent.md b/src/Templates/Boilerplate/Bit.Boilerplate/.agents/skills/code-reviewer/SKILL.md similarity index 81% rename from src/Templates/Boilerplate/Bit.Boilerplate/.github/agents/code-reviewer.agent.md rename to src/Templates/Boilerplate/Bit.Boilerplate/.agents/skills/code-reviewer/SKILL.md index b0e12268021..ee05287566c 100644 --- a/src/Templates/Boilerplate/Bit.Boilerplate/.github/agents/code-reviewer.agent.md +++ b/src/Templates/Boilerplate/Bit.Boilerplate/.agents/skills/code-reviewer/SKILL.md @@ -1,12 +1,15 @@ --- name: code-reviewer -description: Reviews code changes against the project's coding conventions and best practices. Focuses on Bit.BlazorUI usage, theming, lifecycle methods, Mapperly conventions, structured logging, modern C#, error handling, security, and nullable awareness. Does not modify code. +description: Reviews code changes against this project's conventions - Bit.BlazorUI usage, theming, enhanced lifecycle methods, WrapHandled, Mapperly, OData, structured logging, nullable awareness, security and concurrency. Reports findings only and never modifies code. Use when the user asks to review changes, review a diff or PR, check code against project conventions, or says "run code review". +context: fork --- # Project Code Reviewer You are a code reviewer specialized in this project's conventions. Review changes and surface only genuine issues, bugs, security concerns, convention violations, and logic errors. Never comment on formatting or style that `.editorconfig` handles. +Do **not** modify code. Report findings with a file path, a line reference, and a concrete explanation of what breaks. + ## Review Checklist ### Blazor Components @@ -33,7 +36,7 @@ You are a code reviewer specialized in this project's conventions. Review change - [ ] Route carries the API version segment - `[ApiVersion(1)]` + `Route("api/v{v:apiVersion}/[controller]/[action]")` on the controller, literal `api/v1/...` on the shared interface - [ ] Every entity the controller queries either implements `ITenantAware` (so `AppDbContext` applies the tenant row filter) or is scoped by an explicit ownership term in the query - a new entity with neither is readable across tenants. -A deliberately global entity is the one exception `.github/prompts/scaffold.prompt.md` allows; flag it anyway, so the intent gets stated rather than assumed +A deliberately global entity is the one exception the **scaffold-entity** skill (`.agents/skills/scaffold-entity/SKILL.md`) allows; flag it anyway, so the intent gets stated rather than assumed ### DTOs diff --git a/src/Templates/Boilerplate/Bit.Boilerplate/.github/prompts/resx.prompt.md b/src/Templates/Boilerplate/Bit.Boilerplate/.agents/skills/localize-strings/SKILL.md similarity index 88% rename from src/Templates/Boilerplate/Bit.Boilerplate/.github/prompts/resx.prompt.md rename to src/Templates/Boilerplate/Bit.Boilerplate/.agents/skills/localize-strings/SKILL.md index 396becd07cf..16f4f04b4a9 100644 --- a/src/Templates/Boilerplate/Bit.Boilerplate/.github/prompts/resx.prompt.md +++ b/src/Templates/Boilerplate/Bit.Boilerplate/.agents/skills/localize-strings/SKILL.md @@ -1,6 +1,6 @@ --- -mode: 'agent' -description: Moves hardcoded user-facing strings from code to .resx resource files for localization. Identifies strings, adds entries to AppStrings.resx, generates C# code, and updates code to use IStringLocalizer. +name: localize-strings +description: Moves hardcoded user-facing strings out of Razor/C# files into AppStrings.resx and rewrites the call sites to use IStringLocalizer with nameof(AppStrings.Key). Use when the user explicitly asks to localize a page or component, extract hardcoded text, apply translations, fix missing resource strings, or says "run resx" / "move these strings to resx". --- # Move Hardcoded Strings to Resource Files diff --git a/src/Templates/Boilerplate/Bit.Boilerplate/.github/prompts/scaffold.prompt.md b/src/Templates/Boilerplate/Bit.Boilerplate/.agents/skills/scaffold-entity/SKILL.md similarity index 93% rename from src/Templates/Boilerplate/Bit.Boilerplate/.github/prompts/scaffold.prompt.md rename to src/Templates/Boilerplate/Bit.Boilerplate/.agents/skills/scaffold-entity/SKILL.md index 30061a3cb34..a7985089d36 100644 --- a/src/Templates/Boilerplate/Bit.Boilerplate/.github/prompts/scaffold.prompt.md +++ b/src/Templates/Boilerplate/Bit.Boilerplate/.agents/skills/scaffold-entity/SKILL.md @@ -1,6 +1,6 @@ --- -mode: 'agent' -description: Scaffolds complete CRUD entity implementations including entity model, EF configuration, DTO, Mapperly mapper, API controller, IAppController interface, resource strings, Blazor pages, and AppFeatures registration. +name: scaffold-entity +description: Scaffolds a complete CRUD entity across every layer of the Boilerplate solution - entity model, EF Core configuration and migration, DTO, Mapperly mapper, API controller, IAppController interface, AppStrings resource entries, Blazor grid and add/edit pages, and navigation integration. Use when the user asks to add a new entity, add a new feature with CRUD, scaffold a table/model, or says "run scaffold" / "scaffold Product". --- # Scaffold Complete Entity with Full CRUD @@ -84,7 +84,7 @@ Generate a complete CRUD implementation for an entity including: code-behind, controllers) follow `AGENTS.md` section 5 and write the English text through the `IStringLocalizer` indexer, e.g. `Localizer["Category saved."]`; editing `.resx` outside the DTO forces a full restart of a running hot-reload session. Moving those literals into `.resx` is a separate, explicitly-requested - pass - see `.github/prompts/resx.prompt.md`. + pass - see the **localize-strings** skill (`.agents/skills/localize-strings/SKILL.md`). - Include `Id`, `Version` properties - Add calculated properties if needed (e.g., `ProductsCount`) - Add `[JsonSerializable(typeof({DtoName}))]` to `AppJsonContext.cs` diff --git a/src/Templates/Boilerplate/Bit.Boilerplate/.claude/skills/ai-dlc/SKILL.md b/src/Templates/Boilerplate/Bit.Boilerplate/.claude/skills/ai-dlc/SKILL.md new file mode 100644 index 00000000000..c73e4249259 --- /dev/null +++ b/src/Templates/Boilerplate/Bit.Boilerplate/.claude/skills/ai-dlc/SKILL.md @@ -0,0 +1,11 @@ +--- +name: ai-dlc +description: Drives a feature end-to-end using the AI-Driven Development Lifecycle - requirements elaboration, planning and task decomposition, design, implementation, then validation - with explicit user approval before any code is written. Use when the user asks to build a feature properly/end-to-end, wants a structured dev cycle, asks for requirements-then-plan-then-implement, or says "run ai-dlc". +--- + + + +Read `.agents/skills/ai-dlc/SKILL.md` (relative to the repository root) and follow it exactly. diff --git a/src/Templates/Boilerplate/Bit.Boilerplate/.claude/skills/bitify-ui/SKILL.md b/src/Templates/Boilerplate/Bit.Boilerplate/.claude/skills/bitify-ui/SKILL.md new file mode 100644 index 00000000000..3b3801a1f1a --- /dev/null +++ b/src/Templates/Boilerplate/Bit.Boilerplate/.claude/skills/bitify-ui/SKILL.md @@ -0,0 +1,11 @@ +--- +name: bitify-ui +description: Modernizes Blazor pages by replacing raw HTML elements and custom CSS with Bit.BlazorUI components and theme-aware styling, using the bit BlazorUI MCP tools to discover components and verify their exact APIs. Use when the user asks to bitify a page, replace HTML/div/button/input markup with Bit components, remove hardcoded colors, make a page theme-aware or dark-mode ready, or says "run bitify". +--- + + + +Read `.agents/skills/bitify-ui/SKILL.md` (relative to the repository root) and follow it exactly. diff --git a/src/Templates/Boilerplate/Bit.Boilerplate/.claude/skills/code-reviewer/SKILL.md b/src/Templates/Boilerplate/Bit.Boilerplate/.claude/skills/code-reviewer/SKILL.md new file mode 100644 index 00000000000..d495b6c115c --- /dev/null +++ b/src/Templates/Boilerplate/Bit.Boilerplate/.claude/skills/code-reviewer/SKILL.md @@ -0,0 +1,12 @@ +--- +name: code-reviewer +description: Reviews code changes against this project's conventions - Bit.BlazorUI usage, theming, enhanced lifecycle methods, WrapHandled, Mapperly, OData, structured logging, nullable awareness, security and concurrency. Reports findings only and never modifies code. Use when the user asks to review changes, review a diff or PR, check code against project conventions, or says "run code review". +context: fork +--- + + + +Read `.agents/skills/code-reviewer/SKILL.md` (relative to the repository root) and follow it exactly. diff --git a/src/Templates/Boilerplate/Bit.Boilerplate/.claude/skills/localize-strings/SKILL.md b/src/Templates/Boilerplate/Bit.Boilerplate/.claude/skills/localize-strings/SKILL.md new file mode 100644 index 00000000000..dbd47740239 --- /dev/null +++ b/src/Templates/Boilerplate/Bit.Boilerplate/.claude/skills/localize-strings/SKILL.md @@ -0,0 +1,11 @@ +--- +name: localize-strings +description: Moves hardcoded user-facing strings out of Razor/C# files into AppStrings.resx and rewrites the call sites to use IStringLocalizer with nameof(AppStrings.Key). Use when the user explicitly asks to localize a page or component, extract hardcoded text, apply translations, fix missing resource strings, or says "run resx" / "move these strings to resx". +--- + + + +Read `.agents/skills/localize-strings/SKILL.md` (relative to the repository root) and follow it exactly. diff --git a/src/Templates/Boilerplate/Bit.Boilerplate/.claude/skills/scaffold-entity/SKILL.md b/src/Templates/Boilerplate/Bit.Boilerplate/.claude/skills/scaffold-entity/SKILL.md new file mode 100644 index 00000000000..5a0f3a2d6b9 --- /dev/null +++ b/src/Templates/Boilerplate/Bit.Boilerplate/.claude/skills/scaffold-entity/SKILL.md @@ -0,0 +1,11 @@ +--- +name: scaffold-entity +description: Scaffolds a complete CRUD entity across every layer of the Boilerplate solution - entity model, EF Core configuration and migration, DTO, Mapperly mapper, API controller, IAppController interface, AppStrings resource entries, Blazor grid and add/edit pages, and navigation integration. Use when the user asks to add a new entity, add a new feature with CRUD, scaffold a table/model, or says "run scaffold" / "scaffold Product". +--- + + + +Read `.agents/skills/scaffold-entity/SKILL.md` (relative to the repository root) and follow it exactly. diff --git a/src/Templates/Boilerplate/Bit.Boilerplate/.cursor/mcp.json b/src/Templates/Boilerplate/Bit.Boilerplate/.cursor/mcp.json new file mode 100644 index 00000000000..794658f9d28 --- /dev/null +++ b/src/Templates/Boilerplate/Bit.Boilerplate/.cursor/mcp.json @@ -0,0 +1,25 @@ +{ + "mcpServers": { + "bitplatform": { + "url": "https://bitplatform.dev/mcp" + }, + "aspire": { + "command": "aspire", + "args": [ + "agent", + "mcp" + ] + }, + "playwright": { + "command": "npx", + "args": [ + "-y", + "@playwright/mcp@latest", + "--output-dir", + ".playwright-mcp", + "--output-max-size", + "52428800" + ] + } + } +} diff --git a/src/Templates/Boilerplate/Bit.Boilerplate/.cursor/rules/agents.mdc b/src/Templates/Boilerplate/Bit.Boilerplate/.cursor/rules/agents.mdc deleted file mode 100644 index 71034ff26d1..00000000000 --- a/src/Templates/Boilerplate/Bit.Boilerplate/.cursor/rules/agents.mdc +++ /dev/null @@ -1,10 +0,0 @@ ---- -description: Project coding conventions, structure and behavioral directives -alwaysApply: true ---- - -# Cursor Rules - -This project uses @AGENTS.md (at the repository root) as the single source of truth for all coding conventions, project structure, technology stack, and behavioral directives. - -**Before performing any task, read the full content of `/AGENTS.md`.** diff --git a/src/Templates/Boilerplate/Bit.Boilerplate/.docs/00- Wiki.md b/src/Templates/Boilerplate/Bit.Boilerplate/.docs/00- Wiki.md index f9c570c4355..e7185834d31 100644 --- a/src/Templates/Boilerplate/Bit.Boilerplate/.docs/00- Wiki.md +++ b/src/Templates/Boilerplate/Bit.Boilerplate/.docs/00- Wiki.md @@ -10,12 +10,12 @@ This project includes **25 comprehensive documentation files** in the `.docs/` f If you have questions or need assistance: -### 1. πŸ€– **GitHub Copilot (Agent Mode)** - - Ask questions directly in your IDE using GitHub Copilot in Agent Mode +### 1. πŸ€– **Your AI Coding Agent** + - Ask questions directly in your IDE using GitHub Copilot (Agent Mode), Claude Code, Cursor, Gemini, Antigravity, Codex, Junie or Windsurf - this project ships shared instructions (`AGENTS.md`) and Agent Skills (`.agents/skills/`) that all of them understand - Get instant, context-aware answers about the project -### 2. 🌐 **Interactive Wiki** - - Visit: **[https://wiki.bitplatform.dev](https://wiki.bitplatform.dev)** +### 2. 🌐 **Ask AI on bitplatform.dev** + - Visit: **[https://bitplatform.dev/ask](https://bitplatform.dev/ask)** - Ask questions and get AI-powered answers ### 3. πŸ› **GitHub Issues** diff --git a/src/Templates/Boilerplate/Bit.Boilerplate/.docs/01- Entity Framework Core.md b/src/Templates/Boilerplate/Bit.Boilerplate/.docs/01- Entity Framework Core.md index 736331ae480..4507d13cf16 100644 --- a/src/Templates/Boilerplate/Bit.Boilerplate/.docs/01- Entity Framework Core.md +++ b/src/Templates/Boilerplate/Bit.Boilerplate/.docs/01- Entity Framework Core.md @@ -476,6 +476,8 @@ For comprehensive information about the client-side offline database, including: --- -Ask your question [here](https://wiki.bitplatform.dev) +### AI Wiki: Answered Questions + +Ask your own question [here](https://bitplatform.dev/ask) --- \ No newline at end of file diff --git a/src/Templates/Boilerplate/Bit.Boilerplate/.docs/02- DTOs, Mappers, and Mapperly.md b/src/Templates/Boilerplate/Bit.Boilerplate/.docs/02- DTOs, Mappers, and Mapperly.md index 2657a5663c6..5f1d4901ca1 100644 --- a/src/Templates/Boilerplate/Bit.Boilerplate/.docs/02- DTOs, Mappers, and Mapperly.md +++ b/src/Templates/Boilerplate/Bit.Boilerplate/.docs/02- DTOs, Mappers, and Mapperly.md @@ -366,3 +366,9 @@ private async Task SaveProfile() ``` --- + +### AI Wiki: Answered Questions + +Ask your own question [here](https://bitplatform.dev/ask) + +--- diff --git a/src/Templates/Boilerplate/Bit.Boilerplate/.docs/03- API Controllers and OData.md b/src/Templates/Boilerplate/Bit.Boilerplate/.docs/03- API Controllers and OData.md index 8472182fedc..2e31b4fce5b 100644 --- a/src/Templates/Boilerplate/Bit.Boilerplate/.docs/03- API Controllers and OData.md +++ b/src/Templates/Boilerplate/Bit.Boilerplate/.docs/03- API Controllers and OData.md @@ -895,3 +895,9 @@ While the architecture is simple, the backend still includes many advanced featu Feel free to restructure the backend however you see fit. The template provides a solid foundation and advanced features, but you're in control of the architecture. --- + +### AI Wiki: Answered Questions + +Ask your own question [here](https://bitplatform.dev/ask) + +--- diff --git a/src/Templates/Boilerplate/Bit.Boilerplate/.docs/04- Background Jobs and CancellationToken Management.md b/src/Templates/Boilerplate/Bit.Boilerplate/.docs/04- Background Jobs and CancellationToken Management.md index 3aa31a629d2..2688e2bee83 100644 --- a/src/Templates/Boilerplate/Bit.Boilerplate/.docs/04- Background Jobs and CancellationToken Management.md +++ b/src/Templates/Boilerplate/Bit.Boilerplate/.docs/04- Background Jobs and CancellationToken Management.md @@ -448,6 +448,8 @@ The job runner is registered as a scoped service so it has access to all the sam --- -Ask your own question [here](https://wiki.bitplatform.dev) +### AI Wiki: Answered Questions + +Ask your own question [here](https://bitplatform.dev/ask) --- diff --git a/src/Templates/Boilerplate/Bit.Boilerplate/.docs/05- Localization and Multi-language Support.md b/src/Templates/Boilerplate/Bit.Boilerplate/.docs/05- Localization and Multi-language Support.md index 42d40d10297..a3632b0a3c0 100644 --- a/src/Templates/Boilerplate/Bit.Boilerplate/.docs/05- Localization and Multi-language Support.md +++ b/src/Templates/Boilerplate/Bit.Boilerplate/.docs/05- Localization and Multi-language Support.md @@ -696,3 +696,9 @@ from the URL first, then the stored preference, then the OS/browser settings (se `AppClientCoordinator.ConfigureUISetup`). --- + +### AI Wiki: Answered Questions + +Ask your own question [here](https://bitplatform.dev/ask) + +--- diff --git a/src/Templates/Boilerplate/Bit.Boilerplate/.docs/06- Exception Handling and Error Management.md b/src/Templates/Boilerplate/Bit.Boilerplate/.docs/06- Exception Handling and Error Management.md index 48e6fc8d033..ba4b5ee4ffe 100644 --- a/src/Templates/Boilerplate/Bit.Boilerplate/.docs/06- Exception Handling and Error Management.md +++ b/src/Templates/Boilerplate/Bit.Boilerplate/.docs/06- Exception Handling and Error Management.md @@ -612,6 +612,6 @@ and pre-rendering. ### AI Wiki: Answered Questions -Ask your own question [here](https://wiki.bitplatform.dev) +Ask your own question [here](https://bitplatform.dev/ask) --- diff --git a/src/Templates/Boilerplate/Bit.Boilerplate/.docs/07- ASP.NET Core Identity - Authentication & Authorization.md b/src/Templates/Boilerplate/Bit.Boilerplate/.docs/07- ASP.NET Core Identity - Authentication & Authorization.md index 61be73a6b15..e9cf9780706 100644 --- a/src/Templates/Boilerplate/Bit.Boilerplate/.docs/07- ASP.NET Core Identity - Authentication & Authorization.md +++ b/src/Templates/Boilerplate/Bit.Boilerplate/.docs/07- ASP.NET Core Identity - Authentication & Authorization.md @@ -362,8 +362,8 @@ Run the project and walk through these - it is faster than reading: password and OTP sign-in, 2FA, session management and revocation, password reset, roles and permissions, external providers, privileged sessions and elevated access. -### AI Wiki: answered questions +### AI Wiki: Answered Questions -Ask your own question [here](https://wiki.bitplatform.dev). +Ask your own question [here](https://bitplatform.dev/ask) --- diff --git a/src/Templates/Boilerplate/Bit.Boilerplate/.docs/08- Blazor Pages, Components, Styling & Navigation.md b/src/Templates/Boilerplate/Bit.Boilerplate/.docs/08- Blazor Pages, Components, Styling & Navigation.md index cb1cad03c7f..5870ed88957 100644 --- a/src/Templates/Boilerplate/Bit.Boilerplate/.docs/08- Blazor Pages, Components, Styling & Navigation.md +++ b/src/Templates/Boilerplate/Bit.Boilerplate/.docs/08- Blazor Pages, Components, Styling & Navigation.md @@ -491,22 +491,22 @@ The documentation includes: - Usage patterns - Styling guides -### Automatic DeepWiki Integration +### Automatic MCP Integration -**You don't need to manually search the documentation!** +**You don't need to manually search the documentation!** -When you ask questions in **GitHub Copilot Chat** or give commands related to UI components, the system **automatically queries the DeepWiki knowledge base** for `bitfoundation/bitplatform` to find relevant information. +This project ships the **bitplatform MCP server** configuration for every supported AI coding tool, and `AGENTS.md` directs the agent to its tools (`SearchBitBlazorUI`, `GetBitBlazorUIComponent`, `GetBitBlazorUIComponentExamples`, `GetBitBlazorUIType`, `GetBitBlazorUIThemingGuide`, `FindBitBlazorUIIcons`). When you ask questions or give commands related to UI components, the agent **automatically queries these tools**, which answer from the shipped assemblies and documentation pages rather than from memory. **Example interactions:** - **You ask:** "How do I add a filter to BitDataGrid?" - - **Copilot:** Automatically searches DeepWiki and provides the answer with code examples + - **Agent:** Calls `SearchBitBlazorUI` / `GetBitBlazorUIComponentExamples` and provides the answer with real code examples - **You ask:** "How to customize BitButton colors?" - - **Copilot:** Retrieves information about `BitColor` enum and styling options + - **Agent:** Retrieves the `BitColor` enum and styling options via `GetBitBlazorUIType` and the theming guide - **You command:** "Add a BitDatePicker with validation" - - **Copilot:** Finds the correct implementation pattern and creates the code + - **Agent:** Finds the correct implementation pattern and creates the code **You can ask naturally:** - "How do I make a BitModal full screen?" @@ -515,7 +515,7 @@ When you ask questions in **GitHub Copilot Chat** or give commands related to UI - "What properties does BitChart have?" - "How can I implement a Grid System and layout using BitGrid and BitStack components, especially if I'm familiar with the Bootstrap grid system?" -The DeepWiki system handles the documentation lookup automatically! +The MCP tools handle the documentation lookup automatically! --- @@ -700,6 +700,6 @@ public partial class ProductsPage ### AI Wiki: Answered Questions -Ask your own question [here](https://wiki.bitplatform.dev) +Ask your own question [here](https://bitplatform.dev/ask) --- diff --git a/src/Templates/Boilerplate/Bit.Boilerplate/.docs/09- Dependency Injection & Service Registration.md b/src/Templates/Boilerplate/Bit.Boilerplate/.docs/09- Dependency Injection & Service Registration.md index 4bfa5972767..0f18322256d 100644 --- a/src/Templates/Boilerplate/Bit.Boilerplate/.docs/09- Dependency Injection & Service Registration.md +++ b/src/Templates/Boilerplate/Bit.Boilerplate/.docs/09- Dependency Injection & Service Registration.md @@ -302,6 +302,6 @@ protected override async ValueTask DisposeAsync(bool disposing) ### AI Wiki: Answered Questions -Ask your own question [here](https://wiki.bitplatform.dev) +Ask your own question [here](https://bitplatform.dev/ask) --- diff --git a/src/Templates/Boilerplate/Bit.Boilerplate/.docs/10- Configuration (appsettings.json).md b/src/Templates/Boilerplate/Bit.Boilerplate/.docs/10- Configuration (appsettings.json).md index 061966f3814..6197735b6f2 100644 --- a/src/Templates/Boilerplate/Bit.Boilerplate/.docs/10- Configuration (appsettings.json).md +++ b/src/Templates/Boilerplate/Bit.Boilerplate/.docs/10- Configuration (appsettings.json).md @@ -418,4 +418,10 @@ Environment is determined by `AppEnvironment.Current` which is set during build See [`Directory.Build.props`](/src/Directory.Build.props) for environment configuration and [`src/Shared/Infrastructure/Services/AppEnvironment.cs`](/src/Shared/Infrastructure/Services/AppEnvironment.cs) for the environment service. ---- \ No newline at end of file +--- + +### AI Wiki: Answered Questions + +Ask your own question [here](https://bitplatform.dev/ask) + +--- diff --git a/src/Templates/Boilerplate/Bit.Boilerplate/.docs/11- TypeScript, Build Process & JavaScript Interop.md b/src/Templates/Boilerplate/Bit.Boilerplate/.docs/11- TypeScript, Build Process & JavaScript Interop.md index 86cc8b9283d..2a069089244 100644 --- a/src/Templates/Boilerplate/Bit.Boilerplate/.docs/11- TypeScript, Build Process & JavaScript Interop.md +++ b/src/Templates/Boilerplate/Bit.Boilerplate/.docs/11- TypeScript, Build Process & JavaScript Interop.md @@ -359,3 +359,9 @@ The build process will: 4. Build the project - TypeScript compiler and esbuild will handle it automatically --- + +### AI Wiki: Answered Questions + +Ask your own question [here](https://bitplatform.dev/ask) + +--- diff --git a/src/Templates/Boilerplate/Bit.Boilerplate/.docs/12- Blazor Modes, PreRendering & PWA.md b/src/Templates/Boilerplate/Bit.Boilerplate/.docs/12- Blazor Modes, PreRendering & PWA.md index 2e0c805e233..3c19bb8589c 100644 --- a/src/Templates/Boilerplate/Bit.Boilerplate/.docs/12- Blazor Modes, PreRendering & PWA.md +++ b/src/Templates/Boilerplate/Bit.Boilerplate/.docs/12- Blazor Modes, PreRendering & PWA.md @@ -399,3 +399,9 @@ self.addEventListener('notificationclick', function (event) { 4. When user clicks notification, app opens to specified `pageUrl` (If applicable) --- + +### AI Wiki: Answered Questions + +Ask your own question [here](https://bitplatform.dev/ask) + +--- diff --git a/src/Templates/Boilerplate/Bit.Boilerplate/.docs/13- Force Update System.md b/src/Templates/Boilerplate/Bit.Boilerplate/.docs/13- Force Update System.md index 7088fd52172..40e61ac1c98 100644 --- a/src/Templates/Boilerplate/Bit.Boilerplate/.docs/13- Force Update System.md +++ b/src/Templates/Boilerplate/Bit.Boilerplate/.docs/13- Force Update System.md @@ -481,4 +481,10 @@ This allows you to: 2. Test with web users before forcing mobile users to update 3. Give mobile users more time to update (app store approval delays) ---- \ No newline at end of file +--- + +### AI Wiki: Answered Questions + +Ask your own question [here](https://bitplatform.dev/ask) + +--- diff --git a/src/Templates/Boilerplate/Bit.Boilerplate/.docs/14- Response Caching System.md b/src/Templates/Boilerplate/Bit.Boilerplate/.docs/14- Response Caching System.md index 6b878d9da21..cd0dcf5d573 100644 --- a/src/Templates/Boilerplate/Bit.Boilerplate/.docs/14- Response Caching System.md +++ b/src/Templates/Boilerplate/Bit.Boilerplate/.docs/14- Response Caching System.md @@ -699,6 +699,6 @@ announced earlier in the request. ### AI Wiki: Answered Questions -Ask your own question [here](https://wiki.bitplatform.dev) +Ask your own question [here](https://bitplatform.dev/ask) --- diff --git a/src/Templates/Boilerplate/Bit.Boilerplate/.docs/15- Logging, OpenTelemetry and Health Checks.md b/src/Templates/Boilerplate/Bit.Boilerplate/.docs/15- Logging, OpenTelemetry and Health Checks.md index 8bcfded3a1b..d7d594d5fdb 100644 --- a/src/Templates/Boilerplate/Bit.Boilerplate/.docs/15- Logging, OpenTelemetry and Health Checks.md +++ b/src/Templates/Boilerplate/Bit.Boilerplate/.docs/15- Logging, OpenTelemetry and Health Checks.md @@ -314,3 +314,9 @@ than Unhealthy: a storage or SMS-provider outage must not take an otherwise heal Anything you add that a request path genuinely depends on should report Unhealthy; anything external should not. --- + +### AI Wiki: Answered Questions + +Ask your own question [here](https://bitplatform.dev/ask) + +--- diff --git a/src/Templates/Boilerplate/Bit.Boilerplate/.docs/16- CI-CD Pipeline and Environments.md b/src/Templates/Boilerplate/Bit.Boilerplate/.docs/16- CI-CD Pipeline and Environments.md index 011cbcbdc09..39d0d800993 100644 --- a/src/Templates/Boilerplate/Bit.Boilerplate/.docs/16- CI-CD Pipeline and Environments.md +++ b/src/Templates/Boilerplate/Bit.Boilerplate/.docs/16- CI-CD Pipeline and Environments.md @@ -709,3 +709,9 @@ Enabling/Disabling AOT during `dotnet publish` command has the most impact. `dot --- - **iOS/macOS** => 120MB to 130MB --- + +### AI Wiki: Answered Questions + +Ask your own question [here](https://bitplatform.dev/ask) + +--- diff --git a/src/Templates/Boilerplate/Bit.Boilerplate/.docs/17- Automated Testing (Unitigration Tests).md b/src/Templates/Boilerplate/Bit.Boilerplate/.docs/17- Automated Testing (Unitigration Tests).md index ed305c344a1..b0df2c10d27 100644 --- a/src/Templates/Boilerplate/Bit.Boilerplate/.docs/17- Automated Testing (Unitigration Tests).md +++ b/src/Templates/Boilerplate/Bit.Boilerplate/.docs/17- Automated Testing (Unitigration Tests).md @@ -349,4 +349,10 @@ The project includes GitHub Actions workflows that run tests automatically: path: ./src/Tests/TestResults ``` ---- \ No newline at end of file +--- + +### AI Wiki: Answered Questions + +Ask your own question [here](https://bitplatform.dev/ask) + +--- diff --git a/src/Templates/Boilerplate/Bit.Boilerplate/.docs/18- Available Agent Skills.md b/src/Templates/Boilerplate/Bit.Boilerplate/.docs/18- Available Agent Skills.md new file mode 100644 index 00000000000..bd8b17c8a1a --- /dev/null +++ b/src/Templates/Boilerplate/Bit.Boilerplate/.docs/18- Available Agent Skills.md @@ -0,0 +1,155 @@ +# Stage 18: Available Agent Skills + +This project ships several specialized **Agent Skills** designed to help you with specific development tasks. Each skill is carefully crafted to follow the project's conventions and best practices, and each one works across every major AI coding tool - GitHub Copilot (VS Code, Visual Studio, github.com, CLI), Claude Code, Cursor, Gemini CLI, Gemini Code Assist, Google Antigravity, OpenAI Codex, JetBrains Junie and Windsurf - without duplicating their content per tool. + +## How skills work + +An [Agent Skill](https://agentskills.io) is a folder containing a `SKILL.md` file with YAML frontmatter (`name` and `description`) followed by markdown instructions. Agents load skills through **progressive disclosure**: + +1. Only the `description` of each skill is preloaded at session start (roughly 100 tokens each), so the agent knows *that* the skill exists and *when* it applies. +2. The body is read only when the agent decides the skill is relevant, or when you invoke it explicitly with `/`. + +That means adding skills costs almost nothing in context until one is actually needed - the opposite of putting the same instructions in `AGENTS.md`, which loads in full on every single prompt. + +## Where the files live + +`.agents/skills/` is the tool-neutral location the Agent Skills standard converged on, and almost every tool reads it natively: + +| Path | Purpose | +| --- | --- | +| `.agents/skills//SKILL.md` | **The canonical file. Edit this one.** Read natively by GitHub Copilot (VS Code, Visual Studio, github.com coding agent, Copilot CLI, JetBrains agent mode), Cursor, OpenAI Codex, JetBrains Junie, Windsurf, Google Antigravity and Gemini CLI. | +| `.claude/skills//SKILL.md` | Bridge stub for Claude Code, which only discovers skills under `.claude/skills/`. It mirrors the canonical frontmatter and delegates to the canonical file - keep only the frontmatter in sync. | +| `.gemini/commands/.toml` | Command shim that guarantees `/` in Gemini CLI and Gemini Code Assist agent mode, where Agent Skills discovery may not be enabled yet. It injects the canonical file via `@{...}`. | + +The instructions themselves follow the same single-source pattern: every tool that reads `AGENTS.md` natively (Copilot, Cursor, Codex, Junie, Windsurf, Antigravity) gets it directly, while `CLAUDE.md` and `GEMINI.md` are two-line entry points that inline it with an `@AGENTS.md` import for Claude Code and Gemini. Section 7 of `AGENTS.md` indexes the skills for anything that reads none of the skill locations. + +To add a new skill: create `.agents/skills//SKILL.md`, add a matching stub and shim, and add a row to the `AGENTS.md` section 7 index. The `description` is the most important field - write it as *"...Use when the user asks to X, Y, or says Z"*, because that sentence is the only thing the agent sees when deciding whether to load the skill. + +--- + +## Available Skills + +### 1. Scaffold Entity (`scaffold-entity`) + +**Canonical file**: `.agents/skills/scaffold-entity/SKILL.md` + +**What it does**: Generates a complete CRUD (Create, Read, Update, Delete) implementation for a new entity in your project, including all necessary layers from database to UI. + +**When to use it**: When you need to add a new data entity to your application with full CRUD functionality. + +**Key capabilities**: +- Creates Entity Type Configuration for EF Core +- Generates DTO (Data Transfer Object) with validation attributes +- Creates Mapper using Mapperly for high-performance object mapping +- Generates API Controller with OData support +- Creates IAppController Interface for strongly-typed HTTP client +- Adds Resource Strings to AppStrings.resx for localization +- Creates Data Grid Page for listing records +- Creates Add/Edit Page for creating and updating records +- Integrates with navigation (PageUrls.cs, NavBar, MainLayout items) +- Updates AppJsonContext for JSON serialization +- Generates EF Core migration + +**Example usage**: `/scaffold-entity Product with Name, Description, Price and CategoryId properties` + +--- + +### 2. Localize Strings (`localize-strings`) + +**Canonical file**: `.agents/skills/localize-strings/SKILL.md` + +**What it does**: Identifies hardcoded strings in your code and moves them to resource files (.resx) for proper localization support. + +**When to use it**: When you explicitly want hardcoded user-facing text in your Blazor components, pages, or controllers moved into `AppStrings.resx` - for example as a dedicated translation pass before a release. (Day-to-day, new text stays in the `Localizer["..."]` literal indexer per `AGENTS.md` section 5, because `.resx` edits break hot reload.) + +**Key capabilities**: +- Identifies hardcoded user-facing strings in selected code +- Adds new entries to `AppStrings.resx` with appropriate resource keys +- Generates strongly-typed resource classes +- Updates code to use `IStringLocalizer` pattern +- Uses `nameof(AppStrings.ResourceKey)` for type-safe resource access +- Preserves string formatting with placeholders (e.g., `{0}`, `{1}`) +- Follows naming conventions with descriptive resource keys + +**What it won't move**: +- CSS class names or IDs +- Configuration keys +- API endpoints or URLs +- Technical constants (file extensions, mime types) +- Log messages + +**Example usage**: `/localize-strings Dashboard.razor` + +--- + +### 3. Bitify UI (`bitify-ui`) + +**Canonical file**: `.agents/skills/bitify-ui/SKILL.md` + +**What it does**: Modernizes your Blazor pages by replacing standard HTML elements and custom CSS with Bit.BlazorUI components and theme-aware styling. + +**When to use it**: When you have pages using generic HTML elements (like `