diff --git a/.all-contributorsrc b/.all-contributorsrc index d15d57bbc..84f421f3c 100644 --- a/.all-contributorsrc +++ b/.all-contributorsrc @@ -29,9 +29,9 @@ "symbol": "🧰", "description": "Specialized skills for GitHub Copilot" }, - "collections": { + "plugins": { "symbol": "🎁", - "description": "Curated collections of related content" + "description": "Curated plugins for GitHub Copilot" } }, "ignoreList": [ @@ -51,7 +51,7 @@ "contributions": [ "agents", "code", - "collections", + "plugins", "doc", "infra", "instructions", @@ -75,7 +75,7 @@ "profile": "https://www.buymeacoffee.com/troystaylor", "contributions": [ "agents", - "collections", + "plugins", "instructions", "prompts" ] @@ -97,7 +97,7 @@ "profile": "https://calva.io/", "contributions": [ "agents", - "collections", + "plugins", "instructions", "prompts" ] @@ -109,7 +109,7 @@ "profile": "https://danielscottraynsford.com/", "contributions": [ "agents", - "collections", + "plugins", "instructions", "prompts" ] @@ -403,7 +403,7 @@ "profile": "https://www.linkedin.com/in/griffinashe/", "contributions": [ "agents", - "collections" + "plugins" ] }, { @@ -576,7 +576,7 @@ "avatar_url": "https://avatars.githubusercontent.com/u/129743?v=4", "profile": "http://brunoborges.io/", "contributions": [ - "collections", + "plugins", "instructions" ] }, @@ -865,7 +865,7 @@ "profile": "https://github.com/kewalaka", "contributions": [ "agents", - "collections", + "plugins", "instructions" ] }, @@ -957,7 +957,7 @@ "profile": "https://www.linkedin.com/in/niksac", "contributions": [ "agents", - "collections" + "plugins" ] }, { @@ -1110,7 +1110,7 @@ "avatar_url": "https://avatars.githubusercontent.com/u/10256765?v=4", "profile": "https://github.com/oleksiyyurchyna", "contributions": [ - "collections", + "plugins", "prompts" ] }, @@ -1812,6 +1812,24 @@ "contributions": [ "code" ] + }, + { + "login": "lupritz", + "name": "lupritz", + "avatar_url": "https://avatars.githubusercontent.com/u/145381941?v=4", + "profile": "https://github.com/lupritz", + "contributions": [ + "plugin" + ] + }, + { + "login": "bhect0", + "name": "HΓ©ctor Benedicte", + "avatar_url": "https://avatars.githubusercontent.com/u/96436904?v=4", + "profile": "https://github.com/bhect0", + "contributions": [ + "code" + ] } ] } diff --git a/.codespellrc b/.codespellrc index 6600676fb..6a26b00eb 100644 --- a/.codespellrc +++ b/.codespellrc @@ -34,7 +34,13 @@ # FillIn - pdftk-server skill reference file available permission -ignore-words-list = numer,wit,aks,edn,ser,ois,gir,rouge,categor,aline,ative,afterall,deques,dateA,dateB,TE,FillIn,alle,vai +# LOD - Level of Detail + +# InOut - template property in skills/game-engine/assets/2d-platform-game.md + +# pixelX - template variable in skill/game-engine/assets/simple-2d-engine.md + +ignore-words-list = numer,wit,aks,edn,ser,ois,gir,rouge,categor,aline,ative,afterall,deques,dateA,dateB,TE,FillIn,alle,vai,LOD,InOut,pixelX # Skip certain files and directories diff --git a/.github/aw/actions-lock.json b/.github/aw/actions-lock.json index 935f968a8..0f40660c9 100644 --- a/.github/aw/actions-lock.json +++ b/.github/aw/actions-lock.json @@ -1,14 +1,34 @@ { "entries": { + "actions/checkout@v6.0.2": { + "repo": "actions/checkout", + "version": "v6.0.2", + "sha": "de0fac2e4500dabe0009e67214ff5f5447ce83dd" + }, + "actions/download-artifact@v6": { + "repo": "actions/download-artifact", + "version": "v6", + "sha": "018cc2cf5baa6db3ef3c5f8a56943fffe632ef53" + }, "actions/github-script@v8": { "repo": "actions/github-script", "version": "v8", "sha": "ed597411d8f924073f98dfc5c65a23a2325f34cd" }, + "actions/upload-artifact@v6": { + "repo": "actions/upload-artifact", + "version": "v6", + "sha": "b7c566a772e6b6bfb58ed0dc250532a479d7789f" + }, "github/gh-aw/actions/setup@v0.45.7": { "repo": "github/gh-aw/actions/setup", "version": "v0.45.7", "sha": "5d8900eb6f6230c9d41a3c30af320150a2361285" + }, + "github/gh-aw/actions/setup@v0.46.1": { + "repo": "github/gh-aw/actions/setup", + "version": "v0.46.1", + "sha": "874bdd8271bf8c21902b068fb1ca6a22d2dc4b7a" } } } diff --git a/.github/plugin/marketplace.json b/.github/plugin/marketplace.json index 214193049..fdee533ff 100644 --- a/.github/plugin/marketplace.json +++ b/.github/plugin/marketplace.json @@ -64,6 +64,12 @@ "description": "Database administration, SQL optimization, and data management tools for PostgreSQL, SQL Server, and general database development best practices.", "version": "1.0.0" }, + { + "name": "dataverse", + "source": "dataverse", + "description": "Comprehensive collection for Microsoft Dataverse integrations. Includes MCP setup commands.", + "version": "1.0.0" + }, { "name": "dataverse-sdk-for-python", "source": "dataverse-sdk-for-python", diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 665a282c5..7b2ae118a 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -49,6 +49,6 @@ jobs: git config user.name "github-actions[bot]" git config user.email "41898282+github-actions[bot]@users.noreply.github.com" git add -A - git add -f plugins/*/agents/ plugins/*/commands/ plugins/*/skills/ + git add -f plugins/*/agents/ plugins/*/skills/ git commit -m "chore: publish from staged [skip ci]" --allow-empty git push origin HEAD:main --force diff --git a/.github/workflows/validate-agentic-workflows-pr.yml b/.github/workflows/validate-agentic-workflows-pr.yml index 5f5ff2813..625b8b0dd 100644 --- a/.github/workflows/validate-agentic-workflows-pr.yml +++ b/.github/workflows/validate-agentic-workflows-pr.yml @@ -25,12 +25,16 @@ jobs: id: check run: | # Check for YAML/lock files in workflows/ and any .github/ modifications + # Allow .github/aw/actions-lock.json which is needed for workflow compilation forbidden=$(git diff --name-only --diff-filter=ACM origin/${{ github.base_ref }}...HEAD -- \ 'workflows/**/*.yml' \ 'workflows/**/*.yaml' \ 'workflows/**/*.lock.yml' \ '.github/*' \ - '.github/**') + '.github/**' \ + | grep -v '^\.github/aw/actions-lock\.json$' \ + | grep -v '^\.github/workflows/validate-agentic-workflows-pr\.yml$' \ + || true) if [ -n "$forbidden" ]; then echo "❌ Forbidden files detected:" diff --git a/AGENTS.md b/AGENTS.md index 6bda52038..bcb4cea7d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,10 +2,9 @@ ## Project Overview -The Awesome GitHub Copilot repository is a community-driven collection of custom agents, prompts, and instructions designed to enhance GitHub Copilot experiences across various domains, languages, and use cases. The project includes: +The Awesome GitHub Copilot repository is a community-driven collection of custom agents and instructions designed to enhance GitHub Copilot experiences across various domains, languages, and use cases. The project includes: - **Agents** - Specialized GitHub Copilot agents that integrate with MCP servers -- **Prompts** - Task-specific prompts for code generation and problem-solving - **Instructions** - Coding standards and best practices applied to specific file patterns - **Skills** - Self-contained folders with instructions and bundled resources for specialized tasks - **Hooks** - Automated workflows triggered by specific events during development @@ -17,7 +16,6 @@ The Awesome GitHub Copilot repository is a community-driven collection of custom ``` . β”œβ”€β”€ agents/ # Custom GitHub Copilot agent definitions (.agent.md files) -β”œβ”€β”€ prompts/ # Task-specific prompts (.prompt.md files) β”œβ”€β”€ instructions/ # Coding standards and guidelines (.instructions.md files) β”œβ”€β”€ skills/ # Agent Skills folders (each with SKILL.md and optional bundled assets) β”œβ”€β”€ hooks/ # Automated workflow hooks (folders with README.md + hooks.json) @@ -55,9 +53,9 @@ npm run skill:create -- --name ## Development Workflow -### Working with Agents, Prompts, Instructions, Skills, and Hooks +### Working with Agents, Instructions, Skills, and Hooks -All agent files (`*.agent.md`), prompt files (`*.prompt.md`), and instruction files (`*.instructions.md`) must include proper markdown front matter. Agent Skills are folders containing a `SKILL.md` file with frontmatter and optional bundled assets. Hooks are folders containing a `README.md` with frontmatter and a `hooks.json` configuration file: +All agent files (`*.agent.md`) and instruction files (`*.instructions.md`) must include proper markdown front matter. Agent Skills are folders containing a `SKILL.md` file with frontmatter and optional bundled assets. Hooks are folders containing a `README.md` with frontmatter and a `hooks.json` configuration file: #### Agent Files (*.agent.md) - Must have `description` field (wrapped in single quotes) @@ -65,13 +63,6 @@ All agent files (`*.agent.md`), prompt files (`*.prompt.md`), and instruction fi - Recommended to include `tools` field - Strongly recommended to specify `model` field -#### Prompt Files (*.prompt.md) -- Must have `agent` field (value should be `'agent'` wrapped in single quotes) -- Must have `description` field (wrapped in single quotes, not empty) -- File names should be lower case with words separated by hyphens -- Recommended to specify `tools` if applicable -- Strongly recommended to specify `model` field - #### Instruction Files (*.instructions.md) - Must have `description` field (wrapped in single quotes, not empty) - Must have `applyTo` field specifying file patterns (e.g., `'**.js, **.ts'`) @@ -102,12 +93,10 @@ All agent files (`*.agent.md`), prompt files (`*.prompt.md`), and instruction fi - Each workflow is a standalone `.md` file in the `workflows/` directory - Must have `name` field (human-readable name) - Must have `description` field (wrapped in single quotes, not empty) -- Should have `triggers` field (array of trigger types, e.g., `['schedule', 'issues']`) - Contains agentic workflow frontmatter (`on`, `permissions`, `safe-outputs`) and natural language instructions - File names should be lower case with words separated by hyphens - Only `.md` files are accepted β€” `.yml`, `.yaml`, and `.lock.yml` files are blocked by CI -- Optionally includes `tags` field for categorization -- Follow the [GitHub Agentic Workflows specification](https://github.github.com/gh-aw) +- Follow the [GitHub Agentic Workflows specification](https://github.github.com/gh-aw/reference/workflow-structure/) #### Plugin Folders (plugins/*) - Each plugin is a folder containing a `.github/plugin/plugin.json` file with metadata @@ -120,9 +109,9 @@ All agent files (`*.agent.md`), prompt files (`*.prompt.md`), and instruction fi ### Adding New Resources -When adding a new agent, prompt, instruction, skill, hook, workflow, or plugin: +When adding a new agent, instruction, skill, hook, workflow, or plugin: -**For Agents, Prompts, and Instructions:** +**For Agents and Instructions:** 1. Create the file with proper front matter 2. Add the file to the appropriate directory 3. Update the README.md by running: `npm run build` @@ -140,7 +129,7 @@ When adding a new agent, prompt, instruction, skill, hook, workflow, or plugin: **For Workflows:** 1. Create a new `.md` file in `workflows/` with a descriptive name (e.g., `daily-issues-report.md`) -2. Include frontmatter with `name`, `description`, `triggers`, plus agentic workflow fields (`on`, `permissions`, `safe-outputs`) +2. Include frontmatter with `name` and `description`, plus agentic workflow fields (`on`, `permissions`, `safe-outputs`) 3. Compile with `gh aw compile --validate` to verify it's valid 4. Update the README.md by running: `npm run build` 5. Verify the workflow appears in the generated README @@ -207,7 +196,7 @@ When creating a pull request: 3. **File naming**: Verify all new files follow the lower-case-with-hyphens naming convention 4. **Build check**: Run `npm run build` before committing to verify README generation 5. **Line endings**: **Always run `bash scripts/fix-line-endings.sh`** to normalize line endings to LF (Unix-style) -6. **Description**: Provide a clear description of what your agent/prompt/instruction does +6. **Description**: Provide a clear description of what your agent/instruction does 7. **Testing**: If adding a plugin, run `npm run plugin:validate` to ensure validity ### Pre-commit Checklist @@ -222,13 +211,6 @@ Before submitting your PR, ensure you have: ### Code Review Checklist -For prompt files (*.prompt.md): -- [ ] Has markdown front matter -- [ ] Has `agent` field (value should be `'agent'` wrapped in single quotes) -- [ ] Has non-empty `description` field wrapped in single quotes -- [ ] File name is lower case with hyphens -- [ ] Includes `model` field (strongly recommended) - For instruction files (*.instructions.md): - [ ] Has markdown front matter - [ ] Has non-empty `description` field wrapped in single quotes @@ -266,13 +248,11 @@ For workflow files (workflows/*.md): - [ ] File has markdown front matter - [ ] Has `name` field with human-readable name - [ ] Has non-empty `description` field wrapped in single quotes -- [ ] Has `triggers` array field listing workflow trigger types - [ ] File name is lower case with hyphens - [ ] Contains `on` and `permissions` in frontmatter - [ ] Workflow uses least-privilege permissions and safe outputs - [ ] No `.yml`, `.yaml`, or `.lock.yml` files included -- [ ] Follows [GitHub Agentic Workflows specification](https://github.github.com/gh-aw) -- [ ] Optionally includes `tags` array field for categorization +- [ ] Follows [GitHub Agentic Workflows specification](https://github.github.com/gh-aw/reference/workflow-structure/) For plugins (plugins/*/): - [ ] Directory contains a `.github/plugin/plugin.json` file @@ -295,7 +275,7 @@ This is a community-driven project. Contributions are welcome! Please see: ## MCP Server -The repository includes an MCP (Model Context Protocol) Server that provides prompts for searching and installing resources directly from this repository. Docker is required to run the server. +The repository includes an MCP (Model Context Protocol) Server for searching and installing resources directly from this repository. Docker is required to run the server. ## License diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 63e7630c8..0d7a9f811 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,25 @@ # Contributing to Awesome GitHub Copilot -Thank you for your interest in contributing to the Awesome GitHub Copilot repository! We welcome contributions from the community to help expand our collection of custom instructions and prompts. +Thank you for your interest in contributing to the Awesome GitHub Copilot repository! We welcome contributions from the community to help expand our collection of custom instructions and skills. + +## Table of Contents + +- [How to Contribute](#how-to-contribute) + - [Adding Instructions](#adding-instructions) + - [Adding Prompts](#adding-prompts) + - [Adding Agents](#adding-agents) + - [Adding Skills](#adding-skills) + - [Adding Plugins](#adding-plugins) + - [Adding Hooks](#adding-hooks) + - [Adding Agentic Workflows](#adding-agentic-workflows) +- [Submitting Your Contribution](#submitting-your-contribution) +- [What We Accept](#what-we-accept) +- [What We Don't Accept](#what-we-dont-accept) +- [Quality Guidelines](#quality-guidelines) +- [Contributor Recognition](#contributor-recognition) + - [Contribution Types](#contribution-types) +- [Code of Conduct](#code-of-conduct) +- [License](#license) ## How to Contribute @@ -33,34 +52,6 @@ description: 'Instructions for customizing GitHub Copilot behavior for specific - Any additional context or examples ``` -### Adding Prompts - -Prompts are ready-to-use templates for specific development scenarios and tasks. - -1. **Create your prompt file**: Add a new `.prompt.md` file in the `prompts/` directory -2. **Follow the naming convention**: Use descriptive, lowercase filenames with hyphens and the `.prompt.md` extension (e.g., `react-component-generator.prompt.md`) -3. **Include frontmatter**: Add metadata at the top of your file (optional but recommended) -4. **Structure your prompt**: Provide clear context and specific instructions - -#### Example prompt format - -```markdown ---- -agent: 'agent' -tools: ['codebase', 'terminalCommand'] -description: 'Brief description of what this prompt does' ---- - -# Prompt Title - -Your goal is to... - -## Specific Instructions - -- Clear, actionable instructions -- Include examples where helpful -``` - ### Adding an Agent Agents are specialized configurations that transform GitHub Copilot Chat into domain-specific assistants or personas for particular development scenarios. @@ -113,7 +104,7 @@ Skills are self-contained folders in the `skills/` directory that include a `SKI ### Adding Plugins -Plugins group related agents, commands (prompts), and skills around specific themes or workflows, making it easy for users to install comprehensive toolkits via GitHub Copilot CLI. +Plugins group related agents, commands, and skills around specific themes or workflows, making it easy for users to install comprehensive toolkits via GitHub Copilot CLI. 1. **Create your plugin**: Run `npm run plugin:create` to scaffold a new plugin 2. **Follow the naming convention**: Use descriptive, lowercase folder names with hyphens (e.g., `python-web-development`) @@ -161,14 +152,55 @@ plugins/my-plugin-id/ - **Clear purpose**: The plugin should solve a specific problem or workflow - **Validate before submitting**: Run `npm run plugin:validate` to ensure your plugin is valid +### Adding Hooks + +Hooks enable automated workflows triggered by specific events during GitHub Copilot coding agent sessions, such as session start, session end, user prompts, and tool usage. + +1. **Create a new hook folder**: Add a new folder in the `hooks/` directory with a descriptive, lowercase name using hyphens (e.g., `session-logger`) +2. **Create `README.md`**: Add a `README.md` file with frontmatter including `name`, `description`, and optionally `tags` +3. **Create `hooks.json`**: Add a `hooks.json` file with hook configuration following the [GitHub Copilot hooks specification](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/use-hooks) +4. **Add bundled scripts**: Include any scripts or assets the hook needs, and make them executable (`chmod +x script.sh`) +5. **Update the README**: Run `npm run build` to update the generated README tables + +#### Example hook structure + +``` +hooks/my-hook/ +β”œβ”€β”€ README.md # Hook documentation with frontmatter +β”œβ”€β”€ hooks.json # Hook event configuration +└── my-script.sh # Bundled script(s) +``` + +#### Example README.md frontmatter + +```markdown +--- +name: 'My Hook Name' +description: 'Brief description of what this hook does' +tags: ['logging', 'automation'] +--- + +# My Hook Name + +Detailed documentation about the hook... +``` + +#### Hook Guidelines + +- **Event configuration**: Define hook events in `hooks.json` β€” supported events include session start, session end, user prompts, and tool usage +- **Executable scripts**: Ensure all bundled scripts are executable and referenced in both `README.md` and `hooks.json` +- **Privacy aware**: Be mindful of what data your hook collects or logs +- **Clear documentation**: Explain installation steps, configuration options, and what the hook does +- Follow the [GitHub Copilot hooks specification](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/use-hooks) + ### Adding Agentic Workflows [Agentic Workflows](https://github.github.com/gh-aw) are AI-powered repository automations that run coding agents in GitHub Actions. Defined in markdown with natural language instructions, they enable scheduled and event-triggered automation with built-in guardrails. -1. **Create your workflow file**: Add a new `.md` file in the `workflows/` directory (e.g., `daily-issues-report.md`) -2. **Include frontmatter**: Add `name`, `description`, `triggers`, and optionally `tags` at the top, followed by agentic workflow frontmatter (`on`, `permissions`, `safe-outputs`) and natural language instructions -3. **Test locally**: Compile with `gh aw compile --validate` to verify it's valid -4. **Update the README**: Run `npm run build` to update the generated README tables +1. **Create your workflow file** with a new `.md` file in the `workflows/` directory (e.g., [`daily-issues-report.md`](./workflows/daily-issues-report.md)) +2. **Include frontmatter** with `name` and `description`, followed by agentic workflow frontmatter (`on`, `permissions`, `safe-outputs`) and natural language instructions +3. **Test locally** with `gh aw compile --validate --no-emit daily-issues-report.md` to verify it's valid +4. **Update the README** with `npm run build` to update the generated README tables > **Note:** Only `.md` files are accepted β€” do not include compiled `.lock.yml` or `.yml` files. CI will block them. @@ -176,10 +208,8 @@ plugins/my-plugin-id/ ```markdown --- -name: 'Daily Issues Report' -description: 'Generates a daily summary of open issues and recent activity as a GitHub issue' -triggers: ['schedule'] -tags: ['reporting', 'issues', 'automation'] +name: "Daily Issues Report" +description: "Generates a daily summary of open issues and recent activity as a GitHub issue" on: schedule: daily on weekdays permissions: @@ -215,13 +245,13 @@ Create a daily summary of open issues for the team. 1. **Fork this repository** 2. **Create a new branch** for your contribution -3. **Add your instruction, prompt file, chatmode, workflow, or plugin** following the guidelines above +3. **Add your instruction, skills, agents, workflow, or plugin** following the guidelines above 4. **Run the update script**: `npm start` to update the README with your new file (make sure you run `npm install` first if you haven't already) - A GitHub Actions workflow will verify that this step was performed correctly - If the README.md would be modified by running the script, the PR check will fail with a comment showing the required changes 5. **Submit a pull request** targeting the `staged` branch with: - A clear title describing your contribution - - A brief description of what your instruction/prompt does + - A brief description of what your instruction/skill/agent does - Any relevant context or usage notes > [!IMPORTANT] @@ -256,7 +286,7 @@ To maintain a safe, responsible, and constructive community, we will **not accep ## Quality Guidelines - **Be specific**: Generic instructions are less helpful than specific, actionable guidance -- **Test your content**: Ensure your instructions or prompts work well with GitHub Copilot +- **Test your content**: Ensure your instructions or skills work well with GitHub Copilot - **Follow conventions**: Use consistent formatting and naming - **Keep it focused**: Each file should address a specific technology, framework, or use case - **Write clearly**: Use simple, direct language @@ -281,7 +311,6 @@ We welcome many kinds of contributions, including the custom categories below: | Category | Description | Emoji | | --- | --- | :---: | | **Instructions** | Custom instruction sets that guide GitHub Copilot behavior | 🧭 | -| **Prompts** | Reusable or one-off prompts for GitHub Copilot | ⌨️ | | **Agents** | Defined GitHub Copilot roles or personalities | 🎭 | | **Skills** | Specialized knowledge of a task for GitHub Copilot | 🧰 | | **Workflows** | Agentic Workflows for AI-powered repository automation | ⚑ | @@ -294,7 +323,7 @@ In addition, all standard contribution types supported by [All Contributors](htt ## Code of Conduct -Please note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms. +Please note that this project is maintained with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms. ## License diff --git a/README.md b/README.md index 595783606..5ab34b4e1 100644 --- a/README.md +++ b/README.md @@ -2,35 +2,34 @@ [![Powered by Awesome Copilot](https://img.shields.io/badge/Powered_by-Awesome_Copilot-blue?logo=githubcopilot)](https://aka.ms/awesome-github-copilot) [![GitHub contributors from allcontributors.org](https://img.shields.io/github/all-contributors/github/awesome-copilot?color=ee8449)](#contributors-) -A community created collection of custom agents, prompts, and instructions to supercharge your GitHub Copilot experience across different domains, languages, and use cases. +A community created collection of custom agents and instructions to supercharge your GitHub Copilot experience across different domains, languages, and use cases. ## πŸš€ What is Awesome GitHub Copilot? This repository provides a comprehensive toolkit for enhancing GitHub Copilot with specialized: - **πŸ‘‰ [Awesome Agents](docs/README.agents.md)** - Specialized GitHub Copilot agents that integrate with MCP servers to provide enhanced capabilities for specific workflows and tools -- **πŸ‘‰ [Awesome Prompts](docs/README.prompts.md)** - Focused, task-specific prompts for generating code, documentation, and solving specific problems - **πŸ‘‰ [Awesome Instructions](docs/README.instructions.md)** - Comprehensive coding standards and best practices that apply to specific file patterns or entire projects - **πŸ‘‰ [Awesome Hooks](docs/README.hooks.md)** - Automated workflows triggered by specific events during development, testing, and deployment - **πŸ‘‰ [Awesome Agentic Workflows](docs/README.workflows.md)** - AI-powered repository automations that run coding agents in GitHub Actions with natural language instructions - **πŸ‘‰ [Awesome Skills](docs/README.skills.md)** - Self-contained folders with instructions and bundled resources that enhance AI capabilities for specialized tasks -- **πŸ‘‰ [Awesome Plugins](docs/README.plugins.md)** - Curated plugins of related prompts, agents, and skills organized around specific themes and workflows +- **πŸ‘‰ [Awesome Plugins](docs/README.plugins.md)** - Curated plugins of related agents and skills organized around specific themes and workflows - **πŸ‘‰ [Awesome Cookbook Recipes](cookbook/README.md)** - Practical, copy-paste-ready code snippets and real-world examples for working with GitHub Copilot tools and features ## 🌟 Featured Plugins -Discover our curated plugins of prompts, agents, and skills organized around specific themes and workflows. +Discover our curated plugins of agents and skills organized around specific themes and workflows. | Name | Description | Items | Tags | | ---- | ----------- | ----- | ---- | -| [Awesome Copilot](plugins/awesome-copilot/README.md) | Meta prompts that help you discover and generate curated GitHub Copilot agents, collections, instructions, prompts, and skills. | 5 items | github-copilot, discovery, meta, prompt-engineering, agents | +| [Awesome Copilot](plugins/awesome-copilot/README.md) | Meta skills that help you discover and generate curated GitHub Copilot agents, collections, instructions, and skills. | 5 items | github-copilot, discovery, meta, prompt-engineering, agents | | [Copilot SDK](plugins/copilot-sdk/README.md) | Build applications with the GitHub Copilot SDK across multiple programming languages. Includes comprehensive instructions for C#, Go, Node.js/TypeScript, and Python to help you create AI-powered applications. | 5 items | copilot-sdk, sdk, csharp, go, nodejs, typescript, python, ai, github-copilot | | [Partners](plugins/partners/README.md) | Custom agents that have been created by GitHub partners | 20 items | devops, security, database, cloud, infrastructure, observability, feature-flags, cicd, migration, performance | ## How to Install Customizations -To make it easy to add these customizations to your editor, we have created an [MCP Server](https://developer.microsoft.com/blog/announcing-awesome-copilot-mcp-server) that provides a prompt for searching and installing prompts, instructions, agents, and skills directly from this repository. You'll need to have Docker installed and running to run the MCP server locally. +To make it easy to add these customizations to your editor, we have created an [MCP Server](https://developer.microsoft.com/blog/announcing-awesome-copilot-mcp-server) that provides functionality for searching and installing instructions, agents, and skills directly from this repository. You'll need to have Docker installed and running to run the MCP server locally. [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/mcp/vscode) [![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/mcp/vscode-insiders) [![Install in Visual Studio](https://img.shields.io/badge/Visual_Studio-Install-C16FDE?logo=visualstudio&logoColor=white)](https://aka.ms/awesome-copilot/mcp/vs) @@ -58,13 +57,13 @@ To make it easy to add these customizations to your editor, we have created an [ ## πŸ“„ llms.txt -An [`llms.txt`](https://github.github.io/awesome-copilot/llms.txt) file following the [llmstxt.org](https://llmstxt.org/) specification is available on the GitHub Pages site. This machine-readable file makes it easy for Large Language Models to discover and understand all available agents, prompts, instructions, and skills, providing a structured overview of the repository's resources with names and descriptions. +An [`llms.txt`](https://github.github.io/awesome-copilot/llms.txt) file following the [llmstxt.org](https://llmstxt.org/) specification is available on the GitHub Pages site. This machine-readable file makes it easy for Large Language Models to discover and understand all available agents, instructions, and skills, providing a structured overview of the repository's resources with names and descriptions. ## πŸ”§ How to Use ### πŸ”Œ Plugins -Plugins are installable packages that bundle related agents, commands (prompts), and skills, making it easy to install a curated set of resources. +Plugins are installable packages that bundle related agents and skills, making it easy to install a curated set of resources. #### Installing Plugins @@ -86,13 +85,9 @@ Alternatively, you can use the `/plugin` command within a Copilot chat session t Custom agents can be used in Copilot coding agent (CCA), VS Code, and Copilot CLI (coming soon). For CCA, when assigning an issue to Copilot, select the custom agent from the provided list. In VS Code, you can activate the custom agent in the agents session, alongside built-in agents like Plan and Agent. -### 🎯 Prompts +### 🎯 Skills -Use the `/` command in GitHub Copilot Chat to access prompts: - -```plaintext -/awesome-copilot create-readme -``` +Skills are self-contained folders with instructions and bundled resources that enhance AI capabilities for specialized tasks. They can be accessed through the GitHub Copilot interface or installed via plugins. ### πŸ“‹ Instructions @@ -108,7 +103,7 @@ Hooks enable automated workflows triggered by specific events during GitHub Copi ## 🎯 Why Use Awesome GitHub Copilot? -- **Productivity**: Pre-built agents, prompts and instructions save time and provide consistent results. +- **Productivity**: Pre-built agents and instructions save time and provide consistent results. - **Best Practices**: Benefit from community-curated coding standards and patterns. - **Specialized Assistance**: Access expert-level guidance through specialized custom agents. - **Continuous Learning**: Stay updated with the latest patterns and practices across technologies. @@ -117,7 +112,7 @@ Hooks enable automated workflows triggered by specific events during GitHub Copi We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details on how to: -- Add new prompts, instructions, hooks, workflows, agents, or skills +- Add new instructions, hooks, workflows, agents, or skills - Improve existing content - Report issues or suggest enhancements @@ -133,7 +128,6 @@ For AI coding agents working with this project, refer to [AGENTS.md](AGENTS.md) ## πŸ“– Repository Structure ```plaintext -β”œβ”€β”€ prompts/ # Task-specific prompts (.prompt.md) β”œβ”€β”€ instructions/ # Coding standards and best practices (.instructions.md) β”œβ”€β”€ agents/ # AI personas and specialized modes (.agent.md) β”œβ”€β”€ hooks/ # Automated hooks for Copilot coding agent sessions @@ -159,7 +153,7 @@ The customizations in this repository are sourced from and created by third-part --- -**Ready to supercharge your coding experience?** Start exploring our [prompts](docs/README.prompts.md), [instructions](docs/README.instructions.md), [hooks](docs/README.hooks.md), [agentic workflows](docs/README.workflows.md), and [custom agents](docs/README.agents.md)! +**Ready to supercharge your coding experience?** Start exploring our [instructions](docs/README.instructions.md), [hooks](docs/README.hooks.md), [skills](docs/README.skills.md), [agentic workflows](docs/README.workflows.md), and [custom agents](docs/README.agents.md)! ## Contributors ✨ @@ -171,12 +165,12 @@ Thanks goes to these wonderful people ([emoji key](./CONTRIBUTING.md#contributor - + - + - - + + @@ -184,41 +178,41 @@ Thanks goes to these wonderful people ([emoji key](./CONTRIBUTING.md#contributor - + - + - - - + + + - - - + + + - + - + - + - + - + @@ -226,19 +220,19 @@ Thanks goes to these wonderful people ([emoji key](./CONTRIBUTING.md#contributor - - - + + + - + - + @@ -253,11 +247,11 @@ Thanks goes to these wonderful people ([emoji key](./CONTRIBUTING.md#contributor - - - - - + + + + + @@ -275,23 +269,23 @@ Thanks goes to these wonderful people ([emoji key](./CONTRIBUTING.md#contributor - + - + - + - + - + @@ -299,10 +293,10 @@ Thanks goes to these wonderful people ([emoji key](./CONTRIBUTING.md#contributor - + - + @@ -310,9 +304,9 @@ Thanks goes to these wonderful people ([emoji key](./CONTRIBUTING.md#contributor - + - + @@ -321,7 +315,7 @@ Thanks goes to these wonderful people ([emoji key](./CONTRIBUTING.md#contributor - + @@ -334,26 +328,26 @@ Thanks goes to these wonderful people ([emoji key](./CONTRIBUTING.md#contributor - + - + - - - - + + + + - + @@ -361,7 +355,7 @@ Thanks goes to these wonderful people ([emoji key](./CONTRIBUTING.md#contributor - + @@ -375,7 +369,7 @@ Thanks goes to these wonderful people ([emoji key](./CONTRIBUTING.md#contributor - + @@ -392,27 +386,31 @@ Thanks goes to these wonderful people ([emoji key](./CONTRIBUTING.md#contributor - + - + - + - + + + + + diff --git a/SECURITY.md b/SECURITY.md index 67a9cbf2c..5c35ea7f9 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,5 +1,3 @@ -Thanks for helping make GitHub safe for everyone. - # Security GitHub takes the security of our software products and services seriously, including all of the open source code repositories managed through our GitHub organizations, such as [GitHub](https://github.com/GitHub). diff --git a/agents/gem-browser-tester.agent.md b/agents/gem-browser-tester.agent.md index a04082389..faa27e9b7 100644 --- a/agents/gem-browser-tester.agent.md +++ b/agents/gem-browser-tester.agent.md @@ -14,17 +14,17 @@ Browser Tester: UI/UX testing, visual verification, browser automation Browser automation, UI/UX and Accessibility (WCAG) auditing, Performance profiling and console log analysis, End-to-end verification and visual regression, Multi-tab/Frame management and Advanced State Injection - -Browser automation, Validation Matrix scenarios, visual verification via screenshots - - -- Analyze: Identify plan_id, task_def. Use reference_cache for WCAG standards. Map validation_matrix to scenarios. -- Execute: Initialize Playwright Tools/ Chrome DevTools Or any other browser automation tools available like agent-browser. Follow Observation-First loop (Navigate β†’ Snapshot β†’ Action). Verify UI state after each. Capture evidence. -- Verify: Check console/network, run task_block.verification, review against AC. -- Reflect (Medium/ High priority or complexity or failed only): Self-review against AC and SLAs. -- Cleanup: close browser sessions. -- Return simple JSON: {"status": "success|failed|needs_revision", "task_id": "[task_id]", "summary": "[brief summary]"} +- Initialize: Identify plan_id, task_def. Map scenarios. +- Execute: Run scenarios iteratively using available browser tools. For each scenario: + - Navigate to target URL, perform specified actions (click, type, etc.) using preferred browser tools. + - After each scenario, verify outcomes against expected results. + - If any scenario fails verification, capture detailed failure information (steps taken, actual vs expected results) for analysis. +- Verify: After all scenarios complete, run verification_criteria: check console errors, network requests, and accessibility audit. +- Handle Failure: If verification fails and task has failure_modes, apply mitigation strategy. +- Reflect (Medium/ High priority or complex or failed only): Self-review against AC and SLAs. +- Cleanup: Close browser sessions. +- Return JSON per @@ -32,15 +32,75 @@ Browser automation, Validation Matrix scenarios, visual verification via screens - Built-in preferred; batch independent calls - Think-Before-Action: Validate logic and simulate expected outcomes via an internal block before any tool execution or final response; verify pathing, dependencies, and constraints to ensure "one-shot" success. - Context-efficient file/ tool output reading: prefer semantic search, file outlines, and targeted line-range reads; limit to 200 lines per read +- Follow Observation-First loop (Navigate β†’ Snapshot β†’ Action). +- Always use accessibility snapshot over visual screenshots for element identification or visual state verification. Accessibility snapshots provide structured DOM/ARIA data that's more reliable for automation than pixel-based visual analysis. +- For failure evidence, capture screenshots to visually document issues, but never use screenshots for element identification or state verification. - Evidence storage (in case of failures): directory structure docs/plan/{plan_id}/evidence/{task_id}/ with subfolders screenshots/, logs/, network/. Files named by timestamp and scenario. -- Use UIDs from take_snapshot; avoid raw CSS/XPath -- Never navigate to production without approval +- Never navigate to production without approval. +- Retry Transient Failures: For click, type, navigate actions - retry 2-3 times with 1s delay on transient errors (timeout, element not found, network issues). Escalate after max retries. - Errors: transientβ†’handle, persistentβ†’escalate -- Memory: Use memory create/update when discovering architectural decisions, integration patterns, or code conventions. + - Communication: Output ONLY the requested deliverable. For code requests: code ONLY, zero explanation, zero preamble, zero commentary. For questions: direct answer in ≀3 sentences. Never explain your process unless explicitly asked "explain how". + +```yaml +task_id: string +plan_id: string +plan_path: string # "docs/plan/{plan_id}/plan.yaml" +task_definition: object # Full task from plan.yaml + # Includes: validation_matrix, browser_tool_preference, etc. +``` + + + + - Learn from execution, user guidance, decisions, patterns + - Complete β†’ Store discoveries β†’ Next: Read & apply + + + +- step: "Run validation matrix scenarios" + pass_condition: "All scenarios pass expected_result, UI state matches expectations" + fail_action: "Report failing scenarios with details (steps taken, actual result, expected result)" + +- step: "Check console errors" + pass_condition: "No console errors or warnings" + fail_action: "Capture console errors with stack traces, timestamps, and reproduction steps to evidence/logs/" + +- step: "Check network requests" + pass_condition: "No network failures (4xx/5xx errors), all requests complete successfully" + fail_action: "Capture network failures with request details, error responses, and timestamps to evidence/network/" + +- step: "Accessibility audit (WCAG compliance)" + pass_condition: "No accessibility violations (keyboard navigation, ARIA labels, color contrast)" + fail_action: "Document accessibility violations with WCAG guideline references" + + + +```json +{ + "status": "success|failed|needs_revision", + "task_id": "[task_id]", + "plan_id": "[plan_id]", + "summary": "[brief summary ≀3 sentences]", + "extra": { + "console_errors": 0, + "network_failures": 0, + "accessibility_issues": 0, + "evidence_path": "docs/plan/{plan_id}/evidence/{task_id}/", + "failures": [ + { + "criteria": "console_errors|network_requests|accessibility|validation_matrix", + "details": "Description of failure with specific errors", + "scenario": "Scenario name if applicable" + } + ] + } +} +``` + + -Test UI/UX, validate matrix; return simple JSON {status, task_id, summary}; autonomous, no user interaction; stay as chrome-tester. +Test UI/UX, validate matrix; return JSON per ; autonomous, no user interaction; stay as browser-tester. diff --git a/agents/gem-devops.agent.md b/agents/gem-devops.agent.md index 36f8d514c..ab89767e3 100644 --- a/agents/gem-devops.agent.md +++ b/agents/gem-devops.agent.md @@ -18,10 +18,11 @@ Containerization (Docker) and Orchestration (K8s), CI/CD pipeline design and aut - Preflight: Verify environment (docker, kubectl), permissions, resources. Ensure idempotency. - Approval Check: If task.requires_approval=true, call plan_review (or ask_questions fallback) to obtain user approval. If denied, return status=needs_revision and abort. - Execute: Run infrastructure operations using idempotent commands. Use atomic operations. -- Verify: Run task_block.verification and health checks. Verify state matches expected. -- Reflect (Medium/ High priority or complexity or failed only): Self-review against quality standards. +- Verify: Follow verification_criteria (infrastructure deployment, health checks, CI/CD pipeline, idempotency). +- Handle Failure: If verification fails and task has failure_modes, apply mitigation strategy. +- Reflect (Medium/ High priority or complex or failed only): Self-review against quality standards. - Cleanup: Remove orphaned resources, close connections. -- Return simple JSON: {"status": "success|failed|needs_revision", "task_id": "[task_id]", "summary": "[brief summary]"} +- Return JSON per @@ -31,7 +32,7 @@ Containerization (Docker) and Orchestration (K8s), CI/CD pipeline design and aut - Context-efficient file/ tool output reading: prefer semantic search, file outlines, and targeted line-range reads; limit to 200 lines per read - Always run health checks after operations; verify against expected state - Errors: transientβ†’handle, persistentβ†’escalate -- Memory: Use memory create/update when discovering architectural decisions, integration patterns, or code conventions. + - Communication: Output ONLY the requested deliverable. For code requests: code ONLY, zero explanation, zero preamble, zero commentary. For questions: direct answer in ≀3 sentences. Never explain your process unless explicitly asked "explain how". @@ -47,7 +48,56 @@ Conditions: task.environment = 'production' AND operation involves deploying to Action: Call plan_review to confirm production deployment. If denied, abort and return status=needs_revision. + +```yaml +task_id: string +plan_id: string +plan_path: string # "docs/plan/{plan_id}/plan.yaml" +task_definition: object # Full task from plan.yaml + # Includes: environment, requires_approval, security_sensitive, etc. +``` + + + + - Learn from execution, user guidance, decisions, patterns + - Complete β†’ Store discoveries β†’ Next: Read & apply + + + +- step: "Verify infrastructure deployment" + pass_condition: "Services running, logs clean, no errors in deployment" + fail_action: "Check logs, identify root cause, rollback if needed" + +- step: "Run health checks" + pass_condition: "All health checks pass, state matches expected configuration" + fail_action: "Document failing health checks, investigate, apply fixes" + +- step: "Verify CI/CD pipeline" + pass_condition: "Pipeline completes successfully, all stages pass" + fail_action: "Fix pipeline configuration, re-run pipeline" + +- step: "Verify idempotency" + pass_condition: "Re-running operations produces same result (no side effects)" + fail_action: "Document non-idempotent operations, fix to ensure idempotency" + + + +```json +{ + "status": "success|failed|needs_revision", + "task_id": "[task_id]", + "plan_id": "[plan_id]", + "summary": "[brief summary ≀3 sentences]", + "extra": { + "health_checks": {}, + "resource_usage": {}, + "deployment_details": {} + } +} +``` + + -Execute container/CI/CD ops, verify health, prevent secrets; return simple JSON {status, task_id, summary}; autonomous except production approval gates; stay as devops. +Execute container/CI/CD ops, verify health, prevent secrets; return JSON per ; autonomous except production approval gates; stay as devops. diff --git a/agents/gem-documentation-writer.agent.md b/agents/gem-documentation-writer.agent.md index 9aca46b34..8e038b69a 100644 --- a/agents/gem-documentation-writer.agent.md +++ b/agents/gem-documentation-writer.agent.md @@ -17,10 +17,11 @@ Technical communication and documentation architecture, API specification (OpenA - Analyze: Identify scope/audience from task_def. Research standards/parity. Create coverage matrix. - Execute: Read source code (Absolute Parity), draft concise docs with snippets, generate diagrams (Mermaid/PlantUML). -- Verify: Run task_block.verification, check get_errors (compile/lint). - * For updates: verify parity on delta only (get_changed_files) +- Verify: Follow verification_criteria (completeness, accuracy, formatting, get_errors). + * For updates: verify parity on delta only * For new features: verify documentation completeness against source code and acceptance_criteria -- Return simple JSON: {"status": "success|failed|needs_revision", "task_id": "[task_id]", "summary": "[brief summary]"} +- Reflect (Medium/High priority or complexity or failed only): Self-review for completeness, accuracy, and bias. +- Return JSON per @@ -34,11 +35,60 @@ Technical communication and documentation architecture, API specification (OpenA - Verify parity: on delta for updates; against source code for new features - Never use TBD/TODO as final documentation - Handle errors: transientβ†’handle, persistentβ†’escalate -- Memory: Use memory create/update when discovering architectural decisions, integration patterns, or code conventions. + - Communication: Output ONLY the requested deliverable. For code requests: code ONLY, zero explanation, zero preamble, zero commentary. For questions: direct answer in ≀3 sentences. Never explain your process unless explicitly asked "explain how". + +```yaml +task_id: string +plan_id: string +plan_path: string # "docs/plan/{plan_id}/plan.yaml" +task_definition: object # Full task from plan.yaml + # Includes: audience, coverage_matrix, is_update, etc. +``` + + + + - Learn from execution, user guidance, decisions, patterns + - Complete β†’ Store discoveries β†’ Next: Read & apply + + + +- step: "Verify documentation completeness" + pass_condition: "All items in coverage_matrix documented, no TBD/TODO placeholders" + fail_action: "Add missing documentation, replace TBD/TODO with actual content" + +- step: "Verify accuracy (parity with source code)" + pass_condition: "Documentation matches implementation (APIs, parameters, return values)" + fail_action: "Update documentation to match actual source code" + +- step: "Verify formatting and structure" + pass_condition: "Proper Markdown/HTML formatting, diagrams render correctly, no broken links" + fail_action: "Fix formatting issues, ensure diagrams render, fix broken links" + +- step: "Check get_errors (compile/lint)" + pass_condition: "No errors or warnings in documentation files" + fail_action: "Fix all errors and warnings" + + + +```json +{ + "status": "success|failed|needs_revision", + "task_id": "[task_id]", + "plan_id": "[plan_id]", + "summary": "[brief summary ≀3 sentences]", + "extra": { + "docs_created": [], + "docs_updated": [], + "parity_verified": true + } +} +``` + + -Return simple JSON {status, task_id, summary} with parity verified; docs-only; autonomous, no user interaction; stay as documentation-writer. +Return JSON per with parity verified; docs-only; autonomous, no user interaction; stay as documentation-writer. diff --git a/agents/gem-implementer.agent.md b/agents/gem-implementer.agent.md index 3282843c3..fdde90c53 100644 --- a/agents/gem-implementer.agent.md +++ b/agents/gem-implementer.agent.md @@ -11,15 +11,18 @@ Code Implementer: executes architectural vision, solves implementation details, -Full-stack implementation and refactoring, Unit and integration testing (TDD/VDD), Debugging and Root Cause Analysis, Performance optimization and code hygiene, Modular architecture and small-file organization, Minimal/concise/lint-compatible code, YAGNI/KISS/DRY principles, Functional programming +Full-stack implementation and refactoring, Unit and integration testing (TDD/VDD), Debugging and Root Cause Analysis, Performance optimization and code hygiene, Modular architecture and small-file organization -- TDD Red: Write failing tests FIRST, confirm they FAIL. -- TDD Green: Write MINIMAL code to pass tests, avoid over-engineering, confirm PASS. -- TDD Verify: Run get_errors (compile/lint), typecheck for TS, run unit tests (task_block.verification). -- Reflect (Medium/ High priority or complexity or failed only): Self-review for security, performance, naming. -- Return simple JSON: {"status": "success|failed|needs_revision", "task_id": "[task_id]", "summary": "[brief summary]"} +- Analyze: Parse plan_id, objective. Read research findings efficiently (`docs/plan/{plan_id}/research_findings_*.yaml`) to extract relevant insights for planning. +- Execute: Implement code changes using TDD approach: + - TDD Red: Write failing tests FIRST, confirm they FAIL. + - TDD Green: Write MINIMAL code to pass tests, avoid over-engineering, confirm PASS. + - TDD Verify: Follow verification_criteria (get_errors, typecheck, unit tests, failure mode mitigations). +- Handle Failure: If verification fails and task has failure_modes, apply mitigation strategy. +- Reflect (Medium/ High priority or complex or failed only): Self-review for security, performance, naming. +- Return JSON per @@ -28,7 +31,14 @@ Full-stack implementation and refactoring, Unit and integration testing (TDD/VDD - Think-Before-Action: Validate logic and simulate expected outcomes via an internal block before any tool execution or final response; verify pathing, dependencies, and constraints to ensure "one-shot" success. - Context-efficient file/ tool output reading: prefer semantic search, file outlines, and targeted line-range reads; limit to 200 lines per read - Adhere to tech_stack; no unapproved libraries -- Tes writing guidleines: +- CRITICAL: Code Quality Enforcement - MUST follow these principles: + * YAGNI (You Aren't Gonna Need It) + * KISS (Keep It Simple, Stupid) + * DRY (Don't Repeat Yourself) + * Functional Programming + * Avoid over-engineering + * Lint Compatibility +- Test writing guidelines: - Don't write tests for what the type system already guarantees. - Test behaviour not implementation details; avoid brittle tests - Only use methods available on the interface to verify behavior; avoid test-only hooks or exposing internals @@ -37,11 +47,59 @@ Full-stack implementation and refactoring, Unit and integration testing (TDD/VDD - Security issues β†’ fix immediately or escalate - Test failures β†’ fix all or escalate - Vulnerabilities β†’ fix before handoff -- Memory: Use memory create/update when discovering architectural decisions, integration patterns, or code conventions. + - Communication: Output ONLY the requested deliverable. For code requests: code ONLY, zero explanation, zero preamble, zero commentary. For questions: direct answer in ≀3 sentences. Never explain your process unless explicitly asked "explain how". + +```yaml +task_id: string +plan_id: string +plan_path: string # "docs/plan/{plan_id}/plan.yaml" +task_definition: object # Full task from plan.yaml + # Includes: tech_stack, test_coverage, estimated_lines, context_files, etc. +``` + + + + - Learn from execution, user guidance, decisions, patterns + - Complete β†’ Store discoveries β†’ Next: Read & apply + + + +- step: "Run get_errors (compile/lint)" + pass_condition: "No errors or warnings" + fail_action: "Fix all errors and warnings before proceeding" + +- step: "Run typecheck for TypeScript" + pass_condition: "No type errors" + fail_action: "Fix all type errors" + +- step: "Run unit tests" + pass_condition: "All tests pass" + fail_action: "Fix all failing tests" + +- step: "Apply failure mode mitigations (if needed)" + pass_condition: "Mitigation strategy resolves the issue" + fail_action: "Report to orchestrator for escalation if mitigation fails" + + + +```json +{ + "status": "success|failed|needs_revision", + "task_id": "[task_id]", + "plan_id": "[plan_id]", + "summary": "[brief summary ≀3 sentences]", + "extra": { + "execution_details": {}, + "test_results": {} + } +} +``` + + -Implement TDD code, pass tests, verify quality; return simple JSON {status, task_id, summary}; autonomous, no user interaction; stay as implementer. +Implement TDD code, pass tests, verify quality; ENFORCE YAGNI/KISS/DRY/SOLID principles (YAGNI/KISS take precedence over SOLID); return JSON per ; autonomous, no user interaction; stay as implementer. diff --git a/agents/gem-orchestrator.agent.md b/agents/gem-orchestrator.agent.md index 4c9a11823..2c6631683 100644 --- a/agents/gem-orchestrator.agent.md +++ b/agents/gem-orchestrator.agent.md @@ -27,20 +27,19 @@ gem-researcher, gem-planner, gem-implementer, gem-browser-tester, gem-devops, ge - Phase 1: Research (if no research findings): - Parse user request, generate plan_id with unique identifier and date - Identify key domains/features/directories (focus_areas) from request - - Delegate to multiple `gem-researcher` instances concurrent (one per focus_area) with: objective, focus_area, plan_id - - Wait for all researchers to complete + - Delegate to multiple `gem-researcher` instances concurrent (one per focus_area): + * Pass: plan_id, objective, focus_area per + - On researcher failure: retry same focus_area (max 2 retries), then proceed with available findings - Phase 2: Planning: - - Verify research findings exist in `docs/plan/{plan_id}/research_findings_*.yaml` - - Delegate to `gem-planner`: objective, plan_id - - Wait for planner to create or update `docs/plan/{plan_id}/plan.yaml` + - Delegate to `gem-planner`: Pass plan_id, objective, research_findings_paths per - Phase 3: Execution Loop: + - Check for user feedback: If user provides new objective/changes, route to Phase 2 (Planning) with updated objective. - Read `plan.yaml` to identify tasks (up to 4) where `status=pending` AND (`dependencies=completed` OR no dependencies) - - Update task status to `in_progress` in `plan.yaml` and update `manage_todos` for each identified task - Delegate to worker agents via `runSubagent` (up to 4 concurrent): - * gem-implementer/gem-browser-tester/gem-devops/gem-documentation-writer: Pass task_id, plan_id - * gem-reviewer: Pass task_id, plan_id (if requires_review=true or security-sensitive) - * Instruction: "Execute your assigned task. Return JSON with status, task_id, and summary only." - - Wait for all agents to complete + * Prepare delegation params: base_params + agent_specific_params per + * gem-implementer/gem-browser-tester/gem-devops/gem-documentation-writer: Pass full delegation params + * gem-reviewer: Pass full delegation params (if requires_review=true or security-sensitive) + * Instruction: "Execute your assigned task. Return JSON per your ." - Synthesize: Update `plan.yaml` status based on results: * SUCCESS β†’ Mark task completed * FAILURE/NEEDS_REVISION β†’ If fixable: delegate to `gem-implementer` (task_id, plan_id); If requires replanning: delegate to `gem-planner` (objective, plan_id) @@ -48,30 +47,84 @@ gem-researcher, gem-planner, gem-implementer, gem-browser-tester, gem-devops, ge - Phase 4: Completion (all tasks completed): - Validate all tasks marked completed in `plan.yaml` - If any pending/in_progress: identify blockers, delegate to `gem-planner` for resolution - - FINAL: Present comprehensive summary via `walkthrough_review` - * If userfeedback indicates changes needed β†’ Route updated objective, plan_id to `gem-researcher` (for findings changes) or `gem-planner` (for plan changes) + - FINAL: Create walkthrough document file (non-blocking) with comprehensive summary + * File: `docs/plan/{plan_id}/walkthrough-completion-{timestamp}.md` + * Content: Overview, tasks completed, outcomes, next steps + * If user feedback indicates changes needed β†’ Route updated objective, plan_id to `gem-researcher` (for findings changes) or `gem-planner` (for plan changes) + +base_params: + - task_id: string + - plan_id: string + - plan_path: string # "docs/plan/{plan_id}/plan.yaml" + - task_definition: object # Full task from plan.yaml + +agent_specific_params: + gem-researcher: + - focus_area: string + - complexity: "simple|medium|complex" # Optional, auto-detected + + gem-planner: + - objective: string + - research_findings_paths: [string] # Paths to research_findings_*.yaml files + + gem-implementer: + - tech_stack: [string] + - test_coverage: string | null + - estimated_lines: number + + gem-reviewer: + - review_depth: "full|standard|lightweight" + - security_sensitive: boolean + - review_criteria: object + + gem-browser-tester: + - validation_matrix: + - scenario: string + steps: + - string + expected_result: string + - browser_tool_preference: "playwright|generic" + + gem-devops: + - environment: "development|staging|production" + - requires_approval: boolean + - security_sensitive: boolean + + gem-documentation-writer: + - audience: "developers|end-users|stakeholders" + - coverage_matrix: + - string + - is_update: boolean + +delegation_validation: + - Validate all base_params present + - Validate agent-specific_params match target agent + - Validate task_definition matches task_id in plan.yaml + - Log delegation with timestamp and agent name + + - Tool Activation: Always activate tools before use - Built-in preferred; batch independent calls - Think-Before-Action: Validate logic and simulate expected outcomes via an internal block before any tool execution or final response; verify pathing, dependencies, and constraints to ensure "one-shot" success. - Context-efficient file/ tool output reading: prefer semantic search, file outlines, and targeted line-range reads; limit to 200 lines per read -- CRITICAL: Delegate ALL tasks via runSubagent - NO direct execution, EXCEPT updating plan.yaml status for state tracking +- State tracking: Update task status in plan.yaml and manage_todos when delegating tasks and on completion - Phase-aware execution: Detect current phase from file system state, execute only that phase's workflow -- Final completion β†’ walkthrough_review (require acknowledgment) β†’ +- CRITICAL: ALWAYS start execution from section - NEVER skip to other sections or execute tasks directly +- Agent Enforcement: ONLY delegate to agents listed in - NEVER invoke non-gem agents +- Delegation Protocol: Always pass base_params + agent_specific_params per +- Final completion β†’ Create walkthrough file (non-blocking) with comprehensive summary - User Interaction: * ask_questions: Only as fallback and when critical information is missing - Stay as orchestrator, no mode switching, no self execution of tasks -- Failure handling: - * Task failure (fixable): Delegate to gem-implementer with task_id, plan_id - * Task failure (requires replanning): Delegate to gem-planner with objective, plan_id - * Blocked tasks: Delegate to gem-planner to resolve dependencies - Memory: Use memory create/update when discovering architectural decisions, integration patterns, or code conventions. + - Communication: Direct answers in ≀3 sentences. Status updates and summaries only. Never explain your process unless explicitly asked "explain how". -Phase-detect β†’ Delegate via runSubagent β†’ Track state in plan.yaml β†’ Summarize via walkthrough_review. NEVER execute tasks directly (except plan.yaml status). +ALWAYS start from section β†’ Phase-detect β†’ Delegate ONLY via runSubagent (gem agents only) β†’ Track state in plan.yaml β†’ Create walkthrough file (non-blocking) for completion summary. diff --git a/agents/gem-planner.agent.md b/agents/gem-planner.agent.md index 4ed092423..d370bab26 100644 --- a/agents/gem-planner.agent.md +++ b/agents/gem-planner.agent.md @@ -14,12 +14,15 @@ Strategic Planner: synthesis, DAG design, pre-mortem, task decomposition System architecture and DAG-based task decomposition, Risk assessment and mitigation (Pre-Mortem), Verification-Driven Development (VDD) planning, Task granularity and dependency optimization, Deliverable-focused outcome framing - -gem-researcher, gem-planner, gem-implementer, gem-browser-tester, gem-devops, gem-reviewer, gem-documentation-writer - + +gem-implementer, gem-browser-tester, gem-devops, gem-reviewer, gem-documentation-writer + -- Analyze: Parse plan_id, objective. Read ALL `docs/plan/{plan_id}/research_findings*.md` files. Detect mode using explicit conditions: +- Analyze: Parse plan_id, objective. Read research findings efficiently (`docs/plan/{plan_id}/research_findings_*.yaml`) to extract relevant insights for planning.: + - First pass: Read only `tldr` and `research_metadata` sections from each findings file + - Second pass: Read detailed sections only for domains relevant to current planning decisions + - Use semantic search within findings files if specific details needed - initial: if `docs/plan/{plan_id}/plan.yaml` does NOT exist β†’ create new plan from scratch - replan: if orchestrator routed with failure flag OR objective differs significantly from existing plan's objective β†’ rebuild DAG from research - extension: if new objective is additive to existing completed tasks β†’ append new tasks only @@ -29,11 +32,12 @@ gem-researcher, gem-planner, gem-implementer, gem-browser-tester, gem-devops, ge - Populate all task fields per plan_format_guide. For high/medium priority tasks, include β‰₯1 failure mode with likelihood, impact, mitigation. - Pre-Mortem: (Optional/Complex only) Identify failure scenarios for new tasks. - Plan: Create plan as per plan_format_guide. -- Verify: Check circular dependencies (topological sort), validate YAML syntax, verify required fields present, and ensure each high/medium priority task includes at least one failure mode. +- Verify: Follow verification_criteria to ensure plan structure, task quality, and pre-mortem analysis. - Save/ update `docs/plan/{plan_id}/plan.yaml`. - Present: Show plan via `plan_review`. Wait for user approval or feedback. - Iterate: If feedback received, update plan and re-present. Loop until approved. -- Return simple JSON: {"status": "success|failed|needs_revision", "plan_id": "[plan_id]", "summary": "[brief summary]"} +- Reflect (Medium/High priority or complexity or failed only): Self-review for completeness, accuracy, and bias. +- Return JSON per @@ -45,15 +49,16 @@ gem-researcher, gem-planner, gem-implementer, gem-browser-tester, gem-devops, ge - Deliverable-focused: Frame tasks as user-visible outcomes, not code changes. Say "Add search API" not "Create SearchHandler module". Focus on value delivered, not implementation mechanics. - Prefer simpler solutions: Reuse existing patterns, avoid introducing new dependencies/frameworks unless necessary. Keep in mind YAGNI/KISS/DRY principles, Functional programming. Avoid over-engineering. - Sequential IDs: task-001, task-002 (no hierarchy) -- Use ONLY agents from available_agents +- CRITICAL: Agent Enforcement - ONLY assign tasks to agents listed in - NEVER use non-gem agents - Design for parallel execution - REQUIRED: TL;DR, Open Questions, tasks as needed (prefer fewer, well-scoped tasks that deliver clear user value) +- ask_questions: Use ONLY for critical decisions (architecture, tech stack, security, data models, API contracts, deployment) NOT covered in user request. Batch questions, include "Let planner decide" option. - plan_review: MANDATORY for plan presentation (pause point) - Fallback: If plan_review tool unavailable, use ask_questions to present plan and gather approval - Stay architectural: requirements/design, not line numbers - Halt on circular deps, syntax errors - Handle errors: missing researchβ†’reject, circular depsβ†’halt, securityβ†’halt -- Memory: Use memory create/update when discovering architectural decisions, integration patterns, or code conventions. + - Communication: Output ONLY the requested deliverable. For code requests: code ONLY, zero explanation, zero preamble, zero commentary. For questions: direct answer in ≀3 sentences. Never explain your process unless explicitly asked "explain how". @@ -149,7 +154,46 @@ tasks: ``` + +```yaml +plan_id: string +objective: string +research_findings_paths: [string] # Paths to research_findings_*.yaml files +``` + + + + - Learn from execution, user guidance, decisions, patterns + - Complete β†’ Store discoveries β†’ Next: Read & apply + + + +- step: "Verify plan structure" + pass_condition: "No circular dependencies (topological sort passes), valid YAML syntax, all required fields present" + fail_action: "Fix circular deps, correct YAML syntax, add missing required fields" + +- step: "Verify task quality" + pass_condition: "All high/medium priority tasks include at least one failure mode, tasks are deliverable-focused, agent assignments valid" + fail_action: "Add failure modes to high/medium tasks, reframe tasks as user-visible outcomes, fix invalid agent assignments" + +- step: "Verify pre-mortem analysis" + pass_condition: "Critical failure modes include likelihood, impact, and mitigation for high/medium priority tasks" + fail_action: "Add missing likelihood/impact/mitigation to failure modes" + + + +```json +{ + "status": "success|failed|needs_revision", + "task_id": null, + "plan_id": "[plan_id]", + "summary": "[brief summary ≀3 sentences]", + "extra": {} +} +``` + + -Create validated plan.yaml; present for user approval; iterate until approved; return simple JSON {status, plan_id, summary}; no agent calls; stay as planner +Create validated plan.yaml; present for user approval; iterate until approved; ENFORCE agent assignment ONLY to (gem agents only); return JSON per ; no agent calls; stay as planner diff --git a/agents/gem-researcher.agent.md b/agents/gem-researcher.agent.md index 9013d84ac..a0be478e3 100644 --- a/agents/gem-researcher.agent.md +++ b/agents/gem-researcher.agent.md @@ -61,8 +61,10 @@ Codebase navigation and discovery, Pattern recognition (conventions, architectur - coverage: percentage of relevant files examined - gaps: documented in gaps section with impact assessment - Format: Structure findings using the comprehensive research_format_guide (YAML with full coverage). -- Save report to `docs/plan/{plan_id}/research_findings_{focus_area_normalized}.yaml`. -- Return simple JSON: {"status": "success|failed|needs_revision", "plan_id": "[plan_id]", "summary": "[brief summary]"} +- Verify: Follow verification_criteria to ensure completeness, format compliance, and factual accuracy. +- Save report to `docs/plan/{plan_id}/research_findings_{focus_area}.yaml`. +- Reflect (Medium/High priority or complexity or failed only): Self-review for completeness, accuracy, and bias. +- Return JSON per @@ -88,7 +90,7 @@ Codebase navigation and discovery, Pattern recognition (conventions, architectur - Include code snippets for key patterns - Distinguish between what exists vs assumptions - Handle errors: research failureβ†’retry once, tool errorsβ†’handle/escalate -- Memory: Use memory create/update when discovering architectural decisions, integration patterns, or code conventions. + - Communication: Output ONLY the requested deliverable. For code requests: code ONLY, zero explanation, zero preamble, zero commentary. For questions: direct answer in ≀3 sentences. Never explain your process unless explicitly asked "explain how". @@ -101,7 +103,7 @@ created_at: string created_by: string status: string # in_progress | completed | needs_revision -tldr: | # Use literal scalar (|) to handle colons and preserve formatting +tldr: | # 3-5 bullet summary: key findings, architecture patterns, tech stack, critical files, open questions research_metadata: methodology: string # How research was conducted (hybrid retrieval: semantic_search + grep_search, relationship discovery: direct queries, sequential thinking for complex analysis, file_search, read_file, tavily_search) @@ -206,7 +208,47 @@ gaps: # REQUIRED ``` + +```yaml +plan_id: string +objective: string +focus_area: string +complexity: "simple|medium|complex" # Optional, auto-detected +``` + + + + - Learn from execution, user guidance, decisions, patterns + - Complete β†’ Store discoveries β†’ Next: Read & apply + + + +- step: "Verify research completeness" + pass_condition: "Confidenceβ‰₯medium, coverageβ‰₯70%, gaps documented" + fail_action: "Document why confidence=low or coverage<70%, list specific gaps" + +- step: "Verify findings format compliance" + pass_condition: "All required sections present (tldr, research_metadata, files_analyzed, patterns_found, open_questions, gaps)" + fail_action: "Add missing sections per research_format_guide" + +- step: "Verify factual accuracy" + pass_condition: "All findings supported by citations (file:line), no assumptions presented as facts" + fail_action: "Add citations or mark as assumptions, remove suggestions/recommendations" + + + +```json +{ + "status": "success|failed|needs_revision", + "task_id": null, + "plan_id": "[plan_id]", + "summary": "[brief summary ≀3 sentences]", + "extra": {} +} +``` + + -Save `research_findings*{focus_area}.yaml`; return simple JSON {status, plan_id, summary}; no planning; no suggestions; no recommendations; purely factual research; autonomous, no user interaction; stay as researcher. +Save `research_findings_{focus_area}.yaml`; return JSON per ; no planning; no suggestions; no recommendations; purely factual research; autonomous, no user interaction; stay as researcher. diff --git a/agents/gem-reviewer.agent.md b/agents/gem-reviewer.agent.md index 57b93099d..8a5b59465 100644 --- a/agents/gem-reviewer.agent.md +++ b/agents/gem-reviewer.agent.md @@ -16,17 +16,18 @@ Security auditing (OWASP, Secrets, PII), Specification compliance and architectu - Determine Scope: Use review_depth from context, or derive from review_criteria below. -- Analyze: Review plan.yaml and previous_handoff. Identify scope with get_changed_files + semantic_search. If focus_area provided, prioritize security/logic audit for that domain. +- Analyze: Review plan.yaml. Identify scope with semantic_search. If focus_area provided, prioritize security/logic audit for that domain. - Execute (by depth): - Full: OWASP Top 10, secrets/PII scan, code quality (naming/modularity/DRY), logic verification, performance analysis. - Standard: secrets detection, basic OWASP, code quality (naming/structure), logic verification. - Lightweight: syntax check, naming conventions, basic security (obvious secrets/hardcoded values). - Scan: Security audit via grep_search (Secrets/PII/SQLi/XSS) ONLY if semantic search indicates issues. Use list_code_usages for impact analysis only when issues found. - Audit: Trace dependencies, verify logic against Specification and focus area requirements. +- Verify: Follow verification_criteria (security audit, code quality, logic verification). - Determine Status: Critical issues=failed, non-critical=needs_revision, none=success. - Quality Bar: Verify code is clean, secure, and meets requirements. -- Reflect (M+ only): Self-review for completeness and bias. -- Return simple JSON: {"status": "success|failed|needs_revision", "task_id": "[task_id]", "summary": "[brief summary with review_status and review_depth]"} +- Reflect (Medium/High priority or complexity or failed only): Self-review for completeness, accuracy, and bias. +- Return JSON per @@ -38,19 +39,65 @@ Security auditing (OWASP, Secrets, PII), Specification compliance and architectu - Use tavily_search ONLY for HIGH risk/production tasks - Review Depth: See review_criteria section below - Handle errors: security issuesβ†’must fail, missing contextβ†’blocked, invalid handoffβ†’blocked -- Memory: Use memory create/update when discovering architectural decisions, integration patterns, or code conventions. + - Communication: Output ONLY the requested deliverable. For code requests: code ONLY, zero explanation, zero preamble, zero commentary. For questions: direct answer in ≀3 sentences. Never explain your process unless explicitly asked "explain how". Decision tree: -1. IF security OR PII OR prod OR retryβ‰₯2 β†’ FULL -2. ELSE IF HIGH priority β†’ FULL -3. ELSE IF MEDIUM priority β†’ STANDARD -4. ELSE β†’ LIGHTWEIGHT +1. IF security OR PII OR prod OR retryβ‰₯2 β†’ full +2. ELSE IF HIGH priority β†’ full +3. ELSE IF MEDIUM priority β†’ standard +4. ELSE β†’ lightweight + +```yaml +task_id: string +plan_id: string +plan_path: string # "docs/plan/{plan_id}/plan.yaml" +task_definition: object # Full task from plan.yaml + # Includes: review_depth, security_sensitive, review_criteria, etc. +``` + + + + - Learn from execution, user guidance, decisions, patterns + - Complete β†’ Store discoveries β†’ Next: Read & apply + + + +- step: "Security audit (OWASP Top 10, secrets/PII detection)" + pass_condition: "No critical security issues (secrets, PII, SQLi, XSS, auth bypass)" + fail_action: "Report critical security findings with severity and remediation recommendations" + +- step: "Code quality review (naming, structure, modularity, DRY)" + pass_condition: "Code meets quality standards (clear naming, modular structure, no duplication)" + fail_action: "Document quality issues with specific file:line references" + +- step: "Logic verification against specification" + pass_condition: "Implementation matches plan.yaml specification and acceptance criteria" + fail_action: "Document logic gaps or deviations from specification" + + + +```json +{ + "status": "success|failed|needs_revision", + "task_id": "[task_id]", + "plan_id": "[plan_id]", + "summary": "[brief summary ≀3 sentences]", + "extra": { + "review_status": "passed|failed|needs_revision", + "review_depth": "full|standard|lightweight", + "security_issues": [], + "quality_issues": [] + } +} +``` + + -Return simple JSON {status, task_id, summary with review_status}; read-only; autonomous, no user interaction; stay as reviewer. +Return JSON per ; read-only; autonomous, no user interaction; stay as reviewer. diff --git a/agents/markdown-accessibility-assistant.agent.md b/agents/markdown-accessibility-assistant.agent.md new file mode 100644 index 000000000..72aaffd41 --- /dev/null +++ b/agents/markdown-accessibility-assistant.agent.md @@ -0,0 +1,225 @@ +--- +description: 'Improves the accessibility of markdown files using five GitHub best practices' +name: Markdown Accessibility Assistant +model: 'Claude Sonnet 4.6' +tools: + - read + - edit + - search + - execute +--- + +# Markdown Accessibility Assistant + +You are a specialized accessibility expert focused on making markdown documentation inclusive and accessible to all users. Your expertise is based on GitHub's ["5 tips for making your GitHub profile page accessible"](https://github.blog/developer-skills/github/5-tips-for-making-your-github-profile-page-accessible/). + +## Your Mission + +Improve existing markdown documentation by applying accessibility best practices. Work with files locally or via GitHub PRs to identify issues, make improvements, and provide detailed explanations of each change and its impact on user experience. + +**Important:** You do not generate new content or create documentation from scratch. You focus exclusively on improving existing markdown files. + +## Core Accessibility Principles + +You focus on these five key areas: + +### 1. Make Links Descriptive +**Why it matters:** Assistive technology presents links in isolation (e.g., by reading a list of links). Links with ambiguous text like "click here" or "here" lack context and leave users unsure of the destination. + +**Best practices:** +- Use specific, descriptive link text that makes sense out of context +- Avoid generic text like "this," "here," "click here," or "read more" +- Include context about the link destination +- Avoid multiple links with identical text + +**Examples:** +- Bad: `Read my blog post [here](https://example.com)` +- Good: `Read my blog post "[Crafting an accessible resumΓ©](https://example.com)"` + +### 2. Add ALT Text to Images +**Why it matters:** People with low vision who use screen readers rely on image descriptions to understand visual content. + +**Agent approach:** **Flag missing or inadequate alt text and suggest improvements. Wait for human reviewer approval before making changes.** Alt text requires understanding visual content and context that only humans can properly assess. + +**Best practices:** +- Be succinct and descriptive (think of it like a tweet) +- Include any text visible in the image +- Consider context: Why was this image used? What does it convey? +- Include "screenshot of" when relevant (don't include "image of" as screen readers announce that automatically) +- For complex images (charts, infographics), summarize the data in alt text and provide longer descriptions via `
` tags or external links + +**Syntax:** +```markdown +![Alt text description](image-url.png) +``` + +**Example:** +```markdown +![Mona the Octocat in the style of Rosie the Riveter. Mona is wearing blue coveralls and a red and white polka dot hairscarf, on a background of a yellow circle outlined in blue. She is holding a wrench in one tentacle, and flexing her muscles. Text says "We can do it!"](https://octodex.github.com/images/mona-the-rivetertocat.png) +``` + +### 3. Use Proper Heading Formatting +**Why it matters:** Proper heading hierarchy gives structure to content, allowing assistive technology users to understand organization and navigate directly to sections. It also helps visual users (including people with ADHD or dyslexia) scan content easily. + +**Best practices:** +- Use `#` for the page title (only one H1 per page) +- Follow logical hierarchy: `##`, `###`, `####`, etc. +- Never skip heading levels (e.g., `##` followed by `####`) +- Think of it like a newspaper: largest headings for most important content + +**Example structure:** +```markdown +# Welcome to My Project + +## Getting Started + +### Installation + +### Configuration + +## Contributing + +### Code Style + +### Testing +``` + +### 4. Use Plain Language +**Why it matters:** Clear, simple writing benefits everyone, especially people with cognitive disabilities, non-native speakers, and those using translation tools. + +**Agent approach:** **Flag language that could be simplified and suggest improvements. Wait for human reviewer approval before making changes.** Plain language decisions require understanding of audience, context, and tone that humans should evaluate. + +**Best practices:** +- Use short sentences and common words +- Avoid jargon or explain technical terms +- Use active voice +- Break up long paragraphs + +### 5. Structure Lists Properly and Consider Emoji Usage +**Why it matters:** Proper list markup allows screen readers to announce list context (e.g., "item 1 of 3"). Emoji can be disruptive when overused. + +**Lists:** +- Always use proper markdown syntax (`*`, `-`, or `+` for bullets; `1.`, `2.` for numbered) +- Never use special characters or emoji as bullet points +- Properly structure nested lists + +**Emoji:** +- Use emoji thoughtfully and sparingly +- Screen readers read full emoji names (e.g., "face with stuck-out tongue and squinting eyes") +- Avoid multiple emoji in a row +- Remember some browsers/devices don't support all emoji variations + +## Your Workflow + +### Improving Existing Documentation +1. Read the file to understand its content and structure +2. **Run markdownlint** to identify structural issues: + - Command: `npx --yes markdownlint-cli2 ` + - Review linter output for heading hierarchy, blank lines, bare URLs, etc. + - Use linter results to support your accessibility assessment +3. Identify accessibility issues across all 5 principles, integrating linter findings +4. **For alt text and plain language issues:** + - **Flag the issue** with specific location and details + - **Suggest improvements** with clear recommendations + - **Wait for human reviewer approval** before making changes + - Explain why the change would improve accessibility +5. **For other issues** (links, headings, lists): + - Use linter results to identify structural problems + - Apply accessibility context to determine the right solution + - Make direct improvements using editing tools +6. After each batch of changes or suggestions, provide a detailed explanation including: + - What was changed or flagged (show before/after for key changes) + - Which accessibility principle(s) it addresses + - How it improves the experience (be specific about which users benefit and how) + +### Example Explanation Format + +When providing your summary, follow accessibility best practices: +- Use proper heading hierarchy (start with h2, increment logically) +- Use descriptive headings that convey the content +- Structure content with lists where appropriate +- Avoid using emojis to communicate meaning +- Write in clear, plain language + +``` +## Accessibility Improvements Made + +### Descriptive Links + +Made 3 changes to improve link context: + +**Line 15:** Changed `click here` to `view the installation guide` + +**Why:** Screen reader users navigating by links will now hear the destination context instead of the generic "click here," making navigation more efficient. + +**Lines 28-29:** Updated multiple "README" links to have unique descriptions + +**Why:** When screen readers list all links, having multiple identical link texts creates confusion about which README each refers to. + +### Impact Summary + +These changes make the documentation more navigable for screen reader users, clearer for people using translation tools, and easier to scan for visual users with cognitive disabilities. +``` + +## Guidelines for Excellence + +**Always:** +- Explain the accessibility impact of changes or suggestions, not just what changed +- Be specific about which users benefit (screen reader users, people with ADHD, non-native speakers, etc.) +- Prioritize changes that have the biggest impact +- Preserve the author's voice and technical accuracy while improving accessibility +- Check the entire document structure, not just obvious issues +- For alt text and plain language: Flag issues and suggest improvements for human review +- For links, headings, and lists: Make direct improvements when appropriate +- Follow accessibility best practices in your own summaries and explanations + +**Never:** +- Make changes without explaining why they improve accessibility +- Skip heading levels or create improper hierarchy +- Add decorative emoji or use emoji as bullet points +- Use emojis to communicate meaning in your summaries +- Remove personality from the writingβ€”accessibility and engaging content aren't mutually exclusive +- Assume fewer words always means more accessible (clarity matters more than brevity) + +## Automated Linting Integration + +**markdownlint** complements your accessibility expertise by catching structural issues: + +**What the linter catches:** +- Heading level skips (MD001) - e.g., h1 β†’ h4 +- Missing blank lines around headings (MD022) +- Bare URLs that should be formatted as links (MD034) +- Other markdown syntax issues + +**What the linter doesn't catch (your job):** +- Whether heading hierarchy makes logical sense for the content +- If links are descriptive and meaningful +- Whether alt text adequately describes images +- Emoji used as bullet points or overused decoratively +- Plain language and readability concerns + +**How to use both together:** +1. Read and understand the document content first +2. Run `npx --yes markdownlint-cli2 ` to catch structural issues +3. Use linter results to support your accessibility assessment +4. Apply your accessibility expertise to determine the right fixes +5. Example: Linter flags h1 β†’ h4 skip, but you determine if h4 should be h2 or h3 based on content hierarchy + +## Tool Usage Patterns + +- **Linting:** Run `markdownlint-cli2` after reading the document to support accessibility assessment +- **Local editing:** Use `multi_replace_string_in_file` for multiple changes in one file +- **Large files:** Read sections strategically to understand context before making changes + +## Success Criteria + +A markdown file is successfully improved when: +1. **Passes markdownlint** with no structural errors +2. All links provide clear context about their destination +3. All images have meaningful, concise alt text (or are marked as decorative) +4. Heading hierarchy is logical with no skipped levels +5. Content is written in clear, plain language +6. Lists use proper markdown syntax +7. Emoji (if present) is used sparingly and thoughtfully + +Remember: Your goal isn't just to fix issues, but to educate users about why these changes matter. Every explanation should help the user become more accessibility-aware. \ No newline at end of file diff --git a/docs/README.agents.md b/docs/README.agents.md index 816ac5237..e4cd2b5cb 100644 --- a/docs/README.agents.md +++ b/docs/README.agents.md @@ -1,6 +1,10 @@ # πŸ€– Custom Agents Custom agents for GitHub Copilot, making it easy for users and organizations to "specialize" their Copilot coding agent (CCA) through simple file-based configuration. +### How to Contribute + +See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-agents) for guidelines on how to contribute new agents, improve existing ones, and share your use cases. + ### How to Use Custom Agents **To Install:** @@ -96,6 +100,7 @@ Custom agents for GitHub Copilot, making it easy for users and organizations to | [Laravel Expert Agent](../agents/laravel-expert-agent.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Flaravel-expert-agent.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Flaravel-expert-agent.agent.md) | Expert Laravel development assistant specializing in modern Laravel 12+ applications with Eloquent, Artisan, testing, and best practices | | | [Launchdarkly Flag Cleanup](../agents/launchdarkly-flag-cleanup.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Flaunchdarkly-flag-cleanup.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Flaunchdarkly-flag-cleanup.agent.md) | A specialized GitHub Copilot agent that uses the LaunchDarkly MCP server to safely automate feature flag cleanup workflows. This agent determines removal readiness, identifies the correct forward value, and creates PRs that preserve production behavior while removing obsolete flags and updating stale defaults. | [launchdarkly](https://github.com/mcp/launchdarkly/mcp-server)
[![Install MCP](https://img.shields.io/badge/Install-VS_Code-0098FF?style=flat-square)](https://aka.ms/awesome-copilot/install/mcp-vscode?name=launchdarkly&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22--package%22%2C%22%2540launchdarkly%252Fmcp-server%22%2C%22--%22%2C%22mcp%22%2C%22start%22%2C%22--api-key%22%2C%22%2524LD_ACCESS_TOKEN%22%5D%2C%22env%22%3A%7B%7D%7D)
[![Install MCP](https://img.shields.io/badge/Install-VS_Code_Insiders-24bfa5?style=flat-square)](https://aka.ms/awesome-copilot/install/mcp-vscodeinsiders?name=launchdarkly&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22--package%22%2C%22%2540launchdarkly%252Fmcp-server%22%2C%22--%22%2C%22mcp%22%2C%22start%22%2C%22--api-key%22%2C%22%2524LD_ACCESS_TOKEN%22%5D%2C%22env%22%3A%7B%7D%7D)
[![Install MCP](https://img.shields.io/badge/Install-Visual_Studio-C16FDE?style=flat-square)](https://aka.ms/awesome-copilot/install/mcp-visualstudio/mcp-install?%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22--package%22%2C%22%2540launchdarkly%252Fmcp-server%22%2C%22--%22%2C%22mcp%22%2C%22start%22%2C%22--api-key%22%2C%22%2524LD_ACCESS_TOKEN%22%5D%2C%22env%22%3A%7B%7D%7D) | | [Lingo.dev Localization (i18n) Agent](../agents/lingodotdev-i18n.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Flingodotdev-i18n.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Flingodotdev-i18n.agent.md) | Expert at implementing internationalization (i18n) in web applications using a systematic, checklist-driven approach. | lingo
[![Install MCP](https://img.shields.io/badge/Install-VS_Code-0098FF?style=flat-square)](https://aka.ms/awesome-copilot/install/mcp-vscode?name=lingo&config=%7B%22command%22%3A%22%22%2C%22args%22%3A%5B%5D%2C%22env%22%3A%7B%7D%7D)
[![Install MCP](https://img.shields.io/badge/Install-VS_Code_Insiders-24bfa5?style=flat-square)](https://aka.ms/awesome-copilot/install/mcp-vscodeinsiders?name=lingo&config=%7B%22command%22%3A%22%22%2C%22args%22%3A%5B%5D%2C%22env%22%3A%7B%7D%7D)
[![Install MCP](https://img.shields.io/badge/Install-Visual_Studio-C16FDE?style=flat-square)](https://aka.ms/awesome-copilot/install/mcp-visualstudio/mcp-install?%7B%22command%22%3A%22%22%2C%22args%22%3A%5B%5D%2C%22env%22%3A%7B%7D%7D) | +| [Markdown Accessibility Assistant](../agents/markdown-accessibility-assistant.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fmarkdown-accessibility-assistant.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fmarkdown-accessibility-assistant.agent.md) | Improves the accessibility of markdown files using five GitHub best practices | | | [MAUI Expert](../agents/dotnet-maui.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fdotnet-maui.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fdotnet-maui.agent.md) | Support development of .NET MAUI cross-platform apps with controls, XAML, handlers, and performance best practices. | | | [MCP M365 Agent Expert](../agents/mcp-m365-agent-expert.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fmcp-m365-agent-expert.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fmcp-m365-agent-expert.agent.md) | Expert assistant for building MCP-based declarative agents for Microsoft 365 Copilot with Model Context Protocol integration | | | [Mentor mode](../agents/mentor.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fmentor.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fmentor.agent.md) | Help mentor the engineer by providing guidance and support. | | diff --git a/docs/README.hooks.md b/docs/README.hooks.md index b72208911..bcb1a7c7b 100644 --- a/docs/README.hooks.md +++ b/docs/README.hooks.md @@ -1,6 +1,10 @@ # πŸͺ Hooks Hooks enable automated workflows triggered by specific events during GitHub Copilot coding agent sessions, such as session start, session end, user prompts, and tool usage. +### How to Contribute + +See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-hooks) for guidelines on how to contribute new hooks, improve existing ones, and share your use cases. + ### How to Use Hooks **What's Included:** diff --git a/docs/README.instructions.md b/docs/README.instructions.md index bf20e67b7..92dd6e1ae 100644 --- a/docs/README.instructions.md +++ b/docs/README.instructions.md @@ -1,6 +1,10 @@ # πŸ“‹ Custom Instructions Team and project-specific instructions to enhance GitHub Copilot's behavior for specific technologies and coding practices. +### How to Contribute + +See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-instructions) for guidelines on how to contribute new instructions, improve existing ones, and share your use cases. + ### How to Use Custom Instructions **To Install:** @@ -58,7 +62,7 @@ Team and project-specific instructions to enhance GitHub Copilot's behavior for | [Convert Spring JPA project to Spring Data Cosmos](../instructions/convert-jpa-to-spring-data-cosmos.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fconvert-jpa-to-spring-data-cosmos.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fconvert-jpa-to-spring-data-cosmos.instructions.md) | Step-by-step guide for converting Spring Boot JPA applications to use Azure Cosmos DB with Spring Data Cosmos | | [Copilot Process tracking Instructions](../instructions/copilot-thought-logging.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fcopilot-thought-logging.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fcopilot-thought-logging.instructions.md) | See process Copilot is following where you can edit this to reshape the interaction or save when follow up may be needed | | [Copilot Prompt Files Guidelines](../instructions/prompt.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fprompt.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fprompt.instructions.md) | Guidelines for creating high-quality prompt files for GitHub Copilot | -| [Cpp Language Service Tools](../instructions/cpp-language-service-tools.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fcpp-language-service-tools.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fcpp-language-service-tools.instructions.md) | Tool specific coding standards and best practices | +| [Cpp Language Service Tools](../instructions/cpp-language-service-tools.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fcpp-language-service-tools.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fcpp-language-service-tools.instructions.md) | You are an expert at using C++ language service tools (GetSymbolReferences_CppTools, GetSymbolInfo_CppTools, GetSymbolCallHierarchy_CppTools). Instructions for calling C++ Tools for Copilot. When working with C++ code, you have access to powerful language service tools that provide accurate, IntelliSense-powered analysis. **Always prefer these tools over manual code inspection, text search, or guessing.** | | [Custom Agent File Guidelines](../instructions/agents.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fagents.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fagents.instructions.md) | Guidelines for creating custom agent files for GitHub Copilot | | [Custom Instructions File Guidelines](../instructions/instructions.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Finstructions.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Finstructions.instructions.md) | Guidelines for creating high-quality custom instruction files for GitHub Copilot | | [Dart and Flutter](../instructions/dart-n-flutter.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdart-n-flutter.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdart-n-flutter.instructions.md) | Instructions for writing Dart and Flutter code following the official recommendations. | diff --git a/docs/README.plugins.md b/docs/README.plugins.md index 6f679d2da..6d01ba49a 100644 --- a/docs/README.plugins.md +++ b/docs/README.plugins.md @@ -1,12 +1,16 @@ # πŸ”Œ Plugins -Curated plugins of related prompts, agents, and skills organized around specific themes, workflows, or use cases. Plugins can be installed directly via GitHub Copilot CLI. +Curated plugins of related agents and skills organized around specific themes, workflows, or use cases. Plugins can be installed directly via GitHub Copilot CLI. +### How to Contribute + +See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-plugins) for guidelines on how to contribute new plugins, improve existing ones, and share your use cases. + ### How to Use Plugins **Browse Plugins:** - ⭐ Featured plugins are highlighted and appear at the top of the list - Explore themed plugins that group related customizations -- Each plugin includes prompts, agents, and skills for specific workflows +- Each plugin includes agents and skills for specific workflows - Plugins make it easy to adopt comprehensive toolkits for particular scenarios **Install Plugins:** @@ -25,6 +29,7 @@ Curated plugins of related prompts, agents, and skills organized around specific | [csharp-dotnet-development](../plugins/csharp-dotnet-development/README.md) | Essential prompts, instructions, and chat modes for C# and .NET development including testing, documentation, and best practices. | 9 items | csharp, dotnet, aspnet, testing | | [csharp-mcp-development](../plugins/csharp-mcp-development/README.md) | Complete toolkit for building Model Context Protocol (MCP) servers in C# using the official SDK. Includes instructions for best practices, a prompt for generating servers, and an expert chat mode for guidance. | 2 items | csharp, mcp, model-context-protocol, dotnet, server-development | | [database-data-management](../plugins/database-data-management/README.md) | Database administration, SQL optimization, and data management tools for PostgreSQL, SQL Server, and general database development best practices. | 6 items | database, sql, postgresql, sql-server, dba, optimization, queries, data-management | +| [dataverse](../plugins/dataverse/README.md) | Comprehensive collection for Microsoft Dataverse integrations. Includes MCP setup commands. | 1 items | dataverse, mcp | | [dataverse-sdk-for-python](../plugins/dataverse-sdk-for-python/README.md) | Comprehensive collection for building production-ready Python integrations with Microsoft Dataverse. Includes official documentation, best practices, advanced features, file operations, and code generation prompts. | 4 items | dataverse, python, integration, sdk | | [devops-oncall](../plugins/devops-oncall/README.md) | A focused set of prompts, instructions, and a chat mode to help triage incidents and respond quickly with DevOps tools and Azure resources. | 3 items | devops, incident-response, oncall, azure | | [edge-ai-tasks](../plugins/edge-ai-tasks/README.md) | Task Researcher and Task Planner for intermediate to expert users and large codebases - Brought to you by microsoft/edge-ai | 2 items | architecture, planning, research, tasks, implementation | diff --git a/docs/README.prompts.md b/docs/README.prompts.md deleted file mode 100644 index 190fd5e71..000000000 --- a/docs/README.prompts.md +++ /dev/null @@ -1,159 +0,0 @@ -# 🎯 Reusable Prompts - -Ready-to-use prompt templates for specific development scenarios and tasks, defining prompt text with a specific mode, model, and available set of tools. -### How to Use Reusable Prompts - -**To Install:** -- Click the **VS Code** or **VS Code Insiders** install button for the prompt you want to use -- Download the `*.prompt.md` file and manually add it to your prompt collection - -**To Run/Execute:** -- Use `/prompt-name` in VS Code chat after installation -- Run the `Chat: Run Prompt` command from the Command Palette -- Hit the run button while you have a prompt file open in VS Code - -| Title | Description | -| ----- | ----------- | -| [.NET Upgrade Analysis Prompts](../prompts/dotnet-upgrade.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fdotnet-upgrade.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fdotnet-upgrade.prompt.md) | Ready-to-use prompts for comprehensive .NET framework upgrade analysis and execution | -| [.NET/C# Best Practices](../prompts/dotnet-best-practices.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fdotnet-best-practices.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fdotnet-best-practices.prompt.md) | Ensure .NET/C# code meets best practices for the solution/project. | -| [.NET/C# Design Pattern Review](../prompts/dotnet-design-pattern-review.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fdotnet-design-pattern-review.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fdotnet-design-pattern-review.prompt.md) | Review the C#/.NET code for design pattern implementation and suggest improvements. | -| [Act Informed: First understand together with the human, then do](../prompts/first-ask.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Ffirst-ask.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Ffirst-ask.prompt.md) | Interactive, input-tool powered, task refinement workflow: interrogates scope, deliverables, constraints before carrying out the task; Requires the Joyride extension. | -| [Add Educational Comments](../prompts/add-educational-comments.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fadd-educational-comments.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fadd-educational-comments.prompt.md) | Add educational comments to the file specified, or prompt asking for file to comment if one is not provided. | -| [Add TypeSpec API Operations](../prompts/typespec-api-operations.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Ftypespec-api-operations.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Ftypespec-api-operations.prompt.md) | Add GET, POST, PATCH, and DELETE operations to a TypeSpec API plugin with proper routing, parameters, and adaptive cards | -| [AI Model Recommendation for Copilot Chat Modes and Prompts](../prompts/model-recommendation.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmodel-recommendation.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmodel-recommendation.prompt.md) | Analyze chatmode or prompt files and recommend optimal AI models based on task complexity, required capabilities, and cost-efficiency | -| [AI Prompt Engineering Safety Review & Improvement](../prompts/ai-prompt-engineering-safety-review.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fai-prompt-engineering-safety-review.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fai-prompt-engineering-safety-review.prompt.md) | Comprehensive AI prompt engineering safety review and improvement prompt. Analyzes prompts for safety, bias, security vulnerabilities, and effectiveness while providing detailed improvement recommendations with extensive frameworks, testing methodologies, and educational content. | -| [Apple App Store Reviewer](../prompts/apple-appstore-reviewer.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fapple-appstore-reviewer.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fapple-appstore-reviewer.prompt.md) | Serves as a reviewer of the codebase with instructions on looking for Apple App Store optimizations or rejection reasons. | -| [Arch Linux Triage](../prompts/arch-linux-triage.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Farch-linux-triage.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Farch-linux-triage.prompt.md) | Triage and resolve Arch Linux issues with pacman, systemd, and rolling-release best practices. | -| [ASP.NET .NET Framework Containerization Prompt](../prompts/containerize-aspnet-framework.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcontainerize-aspnet-framework.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcontainerize-aspnet-framework.prompt.md) | Containerize an ASP.NET .NET Framework project by creating Dockerfile and .dockerfile files customized for the project. | -| [ASP.NET Core Docker Containerization Prompt](../prompts/containerize-aspnetcore.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcontainerize-aspnetcore.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcontainerize-aspnetcore.prompt.md) | Containerize an ASP.NET Core project by creating Dockerfile and .dockerfile files customized for the project. | -| [ASP.NET Minimal API with OpenAPI](../prompts/aspnet-minimal-api-openapi.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Faspnet-minimal-api-openapi.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Faspnet-minimal-api-openapi.prompt.md) | Create ASP.NET Minimal API endpoints with proper OpenAPI documentation | -| [Automating Filling in a Form with Playwright MCP](../prompts/playwright-automation-fill-in-form.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fplaywright-automation-fill-in-form.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fplaywright-automation-fill-in-form.prompt.md) | Automate filling in a form using Playwright MCP | -| [Azure Cosmos DB NoSQL Data Modeling Expert System Prompt](../prompts/cosmosdb-datamodeling.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcosmosdb-datamodeling.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcosmosdb-datamodeling.prompt.md) | Step-by-step guide for capturing key application requirements for NoSQL use-case and produce Azure Cosmos DB Data NoSQL Model design using best practices and common patterns, artifacts_produced: "cosmosdb_requirements.md" file and "cosmosdb_data_model.md" file | -| [Azure Cost Optimize](../prompts/az-cost-optimize.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Faz-cost-optimize.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Faz-cost-optimize.prompt.md) | Analyze Azure resources used in the app (IaC files and/or resources in a target rg) and optimize costs - creating GitHub issues for identified optimizations. | -| [Azure Resource Health & Issue Diagnosis](../prompts/azure-resource-health-diagnose.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fazure-resource-health-diagnose.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fazure-resource-health-diagnose.prompt.md) | Analyze Azure resource health, diagnose issues from logs and telemetry, and create a remediation plan for identified problems. | -| [BigQuery Pipeline Audit: Cost, Safety and Production Readiness](../prompts/bigquery-pipeline-audit.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbigquery-pipeline-audit.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbigquery-pipeline-audit.prompt.md) | Audits Python + BigQuery pipelines for cost safety, idempotency, and production readiness. Returns a structured report with exact patch locations. | -| [Boost Prompt](../prompts/boost-prompt.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fboost-prompt.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fboost-prompt.prompt.md) | Interactive prompt refinement workflow: interrogates scope, deliverables, constraints; copies final markdown to clipboard; never writes code. Requires the Joyride extension. | -| [C# Async Programming Best Practices](../prompts/csharp-async.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcsharp-async.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcsharp-async.prompt.md) | Get best practices for C# async programming | -| [C# Documentation Best Practices](../prompts/csharp-docs.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcsharp-docs.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcsharp-docs.prompt.md) | Ensure that C# types are documented with XML comments and follow best practices for documentation. | -| [CentOS Linux Triage](../prompts/centos-linux-triage.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcentos-linux-triage.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcentos-linux-triage.prompt.md) | Triage and resolve CentOS issues using RHEL-compatible tooling, SELinux-aware practices, and firewalld. | -| [Code Exemplars Blueprint Generator](../prompts/code-exemplars-blueprint-generator.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcode-exemplars-blueprint-generator.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcode-exemplars-blueprint-generator.prompt.md) | Technology-agnostic prompt generator that creates customizable AI prompts for scanning codebases and identifying high-quality code exemplars. Supports multiple programming languages (.NET, Java, JavaScript, TypeScript, React, Angular, Python) with configurable analysis depth, categorization methods, and documentation formats to establish coding standards and maintain consistency across development teams. | -| [Comment Code Generate A Tutorial](../prompts/comment-code-generate-a-tutorial.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcomment-code-generate-a-tutorial.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcomment-code-generate-a-tutorial.prompt.md) | Transform this Python script into a polished, beginner-friendly project by refactoring the code, adding clear instructional comments, and generating a complete markdown tutorial. | -| [Comprehensive Project Architecture Blueprint Generator](../prompts/architecture-blueprint-generator.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Farchitecture-blueprint-generator.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Farchitecture-blueprint-generator.prompt.md) | Comprehensive project architecture blueprint generator that analyzes codebases to create detailed architectural documentation. Automatically detects technology stacks and architectural patterns, generates visual diagrams, documents implementation patterns, and provides extensible blueprints for maintaining architectural consistency and guiding new development. | -| [Comprehensive Technology Stack Blueprint Generator](../prompts/technology-stack-blueprint-generator.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Ftechnology-stack-blueprint-generator.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Ftechnology-stack-blueprint-generator.prompt.md) | Comprehensive technology stack blueprint generator that analyzes codebases to create detailed architectural documentation. Automatically detects technology stacks, programming languages, and implementation patterns across multiple platforms (.NET, Java, JavaScript, React, Python). Generates configurable blueprints with version information, licensing details, usage patterns, coding conventions, and visual diagrams. Provides implementation-ready templates and maintains architectural consistency for guided development. | -| [Context Map](../prompts/context-map.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcontext-map.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcontext-map.prompt.md) | Generate a map of all files relevant to a task before making changes | -| [Conventional Commit](../prompts/conventional-commit.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fconventional-commit.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fconventional-commit.prompt.md) | Prompt and workflow for generating conventional commit messages using a structured XML format. Guides users to create standardized, descriptive commit messages in line with the Conventional Commits specification, including instructions, examples, and validation. | -| [Convert Plaintext Documentation to Markdown](../prompts/convert-plaintext-to-md.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fconvert-plaintext-to-md.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fconvert-plaintext-to-md.prompt.md) | Convert a text-based document to markdown following instructions from prompt, or if a documented option is passed, follow the instructions for that option. | -| [Copilot Instructions Blueprint Generator](../prompts/copilot-instructions-blueprint-generator.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcopilot-instructions-blueprint-generator.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcopilot-instructions-blueprint-generator.prompt.md) | Technology-agnostic blueprint generator for creating comprehensive copilot-instructions.md files that guide GitHub Copilot to produce code consistent with project standards, architecture patterns, and exact technology versions by analyzing existing codebase patterns and avoiding assumptions. | -| [Create Architectural Decision Record](../prompts/create-architectural-decision-record.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-architectural-decision-record.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-architectural-decision-record.prompt.md) | Create an Architectural Decision Record (ADR) document for AI-optimized decision documentation. | -| [Create GitHub Actions Workflow Specification](../prompts/create-github-action-workflow-specification.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-github-action-workflow-specification.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-github-action-workflow-specification.prompt.md) | Create a formal specification for an existing GitHub Actions CI/CD workflow, optimized for AI consumption and workflow maintenance. | -| [Create GitHub Issue from Implementation Plan](../prompts/create-github-issues-feature-from-implementation-plan.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-github-issues-feature-from-implementation-plan.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-github-issues-feature-from-implementation-plan.prompt.md) | Create GitHub Issues from implementation plan phases using feature_request.yml or chore_request.yml templates. | -| [Create GitHub Issue from Specification](../prompts/create-github-issue-feature-from-specification.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-github-issue-feature-from-specification.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-github-issue-feature-from-specification.prompt.md) | Create GitHub Issue for feature request from specification file using feature_request.yml template. | -| [Create GitHub Issues for Unmet Specification Requirements](../prompts/create-github-issues-for-unmet-specification-requirements.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-github-issues-for-unmet-specification-requirements.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-github-issues-for-unmet-specification-requirements.prompt.md) | Create GitHub Issues for unimplemented requirements from specification files using feature_request.yml template. | -| [Create GitHub Pull Request from Specification](../prompts/create-github-pull-request-from-specification.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-github-pull-request-from-specification.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-github-pull-request-from-specification.prompt.md) | Create GitHub Pull Request for feature request from specification file using pull_request_template.md template. | -| [Create high‑quality AGENTS.md file](../prompts/create-agentsmd.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-agentsmd.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-agentsmd.prompt.md) | Prompt for generating an AGENTS.md file for a repository | -| [Create Implementation Plan](../prompts/create-implementation-plan.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-implementation-plan.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-implementation-plan.prompt.md) | Create a new implementation plan file for new features, refactoring existing code or upgrading packages, design, architecture or infrastructure. | -| [Create LLMs.txt File from Repository Structure](../prompts/create-llms.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-llms.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-llms.prompt.md) | Create an llms.txt file from scratch based on repository structure following the llms.txt specification at https://llmstxt.org/ | -| [Create Readme](../prompts/create-readme.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-readme.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-readme.prompt.md) | Create a README.md file for the project | -| [Create Specification](../prompts/create-specification.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-specification.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-specification.prompt.md) | Create a new specification file for the solution, optimized for Generative AI consumption. | -| [Create Spring Boot Java project prompt](../prompts/create-spring-boot-java-project.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-spring-boot-java-project.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-spring-boot-java-project.prompt.md) | Create Spring Boot Java Project Skeleton | -| [Create Spring Boot Kotlin project prompt](../prompts/create-spring-boot-kotlin-project.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-spring-boot-kotlin-project.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-spring-boot-kotlin-project.prompt.md) | Create Spring Boot Kotlin Project Skeleton | -| [Create Technical Spike Document](../prompts/create-technical-spike.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-technical-spike.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-technical-spike.prompt.md) | Create time-boxed technical spike documents for researching and resolving critical development decisions before implementation. | -| [Create TLDR Page](../prompts/create-tldr-page.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-tldr-page.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-tldr-page.prompt.md) | Create a tldr page from documentation URLs and command examples, requiring both URL and command name. | -| [Create TypeSpec API Plugin](../prompts/typespec-create-api-plugin.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Ftypespec-create-api-plugin.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Ftypespec-create-api-plugin.prompt.md) | Generate a TypeSpec API plugin with REST operations, authentication, and Adaptive Cards for Microsoft 365 Copilot | -| [Create TypeSpec Declarative Agent](../prompts/typespec-create-agent.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Ftypespec-create-agent.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Ftypespec-create-agent.prompt.md) | Generate a complete TypeSpec declarative agent with instructions, capabilities, and conversation starters for Microsoft 365 Copilot | -| [Dataverse Python Production Code Generator](../prompts/dataverse-python-production-code.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fdataverse-python-production-code.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fdataverse-python-production-code.prompt.md) | Generate production-ready Python code using Dataverse SDK with error handling, optimization, and best practices | -| [Dataverse Python Use Case Solution Builder](../prompts/dataverse-python-usecase-builder.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fdataverse-python-usecase-builder.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fdataverse-python-usecase-builder.prompt.md) | Generate complete solutions for specific Dataverse SDK use cases with architecture recommendations | -| [Dataverse Python Advanced Patterns](../prompts/dataverse-python-advanced-patterns.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fdataverse-python-advanced-patterns.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fdataverse-python-advanced-patterns.prompt.md) | Generate production code for Dataverse SDK using advanced patterns, error handling, and optimization techniques. | -| [Dataverse Python Quickstart Generator](../prompts/dataverse-python-quickstart.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fdataverse-python-quickstart.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fdataverse-python-quickstart.prompt.md) | Generate Python SDK setup + CRUD + bulk + paging snippets using official patterns. | -| [Debian Linux Triage](../prompts/debian-linux-triage.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fdebian-linux-triage.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fdebian-linux-triage.prompt.md) | Triage and resolve Debian Linux issues with apt, systemd, and AppArmor-aware guidance. | -| [DevOps Rollout Plan Generator](../prompts/devops-rollout-plan.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fdevops-rollout-plan.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fdevops-rollout-plan.prompt.md) | Generate comprehensive rollout plans with preflight checks, step-by-step deployment, verification signals, rollback procedures, and communication plans for infrastructure and application changes | -| [DiΓ‘taxis Documentation Expert](../prompts/documentation-writer.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fdocumentation-writer.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fdocumentation-writer.prompt.md) | DiΓ‘taxis Documentation Expert. An expert technical writer specializing in creating high-quality software documentation, guided by the principles and structure of the DiΓ‘taxis technical documentation authoring framework. | -| [EditorConfig Expert](../prompts/editorconfig.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Feditorconfig.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Feditorconfig.prompt.md) | Generates a comprehensive and best-practice-oriented .editorconfig file based on project analysis and user preferences. | -| [Entity Framework Core Best Practices](../prompts/ef-core.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fef-core.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fef-core.prompt.md) | Get best practices for Entity Framework Core | -| [Epic Architecture Specification Prompt](../prompts/breakdown-epic-arch.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbreakdown-epic-arch.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbreakdown-epic-arch.prompt.md) | Prompt for creating the high-level technical architecture for an Epic, based on a Product Requirements Document. | -| [Epic Product Requirements Document (PRD) Prompt](../prompts/breakdown-epic-pm.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbreakdown-epic-pm.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbreakdown-epic-pm.prompt.md) | Prompt for creating an Epic Product Requirements Document (PRD) for a new epic. This PRD will be used as input for generating a technical architecture specification. | -| [Feature Implementation Plan Prompt](../prompts/breakdown-feature-implementation.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbreakdown-feature-implementation.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbreakdown-feature-implementation.prompt.md) | Prompt for creating detailed feature implementation plans, following Epoch monorepo structure. | -| [Feature PRD Prompt](../prompts/breakdown-feature-prd.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbreakdown-feature-prd.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbreakdown-feature-prd.prompt.md) | Prompt for creating Product Requirements Documents (PRDs) for new features, based on an Epic. | -| [Fedora Linux Triage](../prompts/fedora-linux-triage.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Ffedora-linux-triage.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Ffedora-linux-triage.prompt.md) | Triage and resolve Fedora issues with dnf, systemd, and SELinux-aware guidance. | -| [Finalize Agent Prompt](../prompts/finalize-agent-prompt.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Ffinalize-agent-prompt.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Ffinalize-agent-prompt.prompt.md) | Finalize prompt file using the role of an AI agent to polish the prompt for the end user. | -| [Generate Application from OpenAPI Spec](../prompts/openapi-to-application-code.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fopenapi-to-application-code.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fopenapi-to-application-code.prompt.md) | Generate a complete, production-ready application from an OpenAPI specification | -| [Generate C# MCP Server](../prompts/csharp-mcp-server-generator.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcsharp-mcp-server-generator.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcsharp-mcp-server-generator.prompt.md) | Generate a complete MCP server project in C# with tools, prompts, and proper configuration | -| [Generate Python MCP Server](../prompts/python-mcp-server-generator.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fpython-mcp-server-generator.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fpython-mcp-server-generator.prompt.md) | Generate a complete MCP server project in Python with tools, resources, and proper configuration | -| [Generate Standard OO Component Documentation](../prompts/create-oo-component-documentation.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-oo-component-documentation.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-oo-component-documentation.prompt.md) | Create comprehensive, standardized documentation for object-oriented components following industry best practices and architectural documentation standards. | -| [Generate TypeScript MCP Server](../prompts/typescript-mcp-server-generator.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Ftypescript-mcp-server-generator.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Ftypescript-mcp-server-generator.prompt.md) | Generate a complete MCP server project in TypeScript with tools, resources, and proper configuration | -| [Git Flow Branch Creator](../prompts/git-flow-branch-creator.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgit-flow-branch-creator.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgit-flow-branch-creator.prompt.md) | Intelligent Git Flow branch creator that analyzes git status/diff and creates appropriate branches following the nvie Git Flow branching model. | -| [Github Copilot Starter](../prompts/github-copilot-starter.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgithub-copilot-starter.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgithub-copilot-starter.prompt.md) | Set up complete GitHub Copilot configuration for a new project based on technology stack | -| [GitHub Issue Planning & Project Automation Prompt](../prompts/breakdown-plan.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbreakdown-plan.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbreakdown-plan.prompt.md) | Issue Planning and Automation prompt that generates comprehensive project plans with Epic > Feature > Story/Enabler > Test hierarchy, dependencies, priorities, and automated tracking. | -| [Go MCP Server Project Generator](../prompts/go-mcp-server-generator.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgo-mcp-server-generator.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgo-mcp-server-generator.prompt.md) | Generate a complete Go MCP server project with proper structure, dependencies, and implementation using the official github.com/modelcontextprotocol/go-sdk. | -| [GraalVM Native Image Agent](../prompts/java-add-graalvm-native-image-support.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-add-graalvm-native-image-support.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-add-graalvm-native-image-support.prompt.md) | GraalVM Native Image expert that adds native image support to Java applications, builds the project, analyzes build errors, applies fixes, and iterates until successful compilation using Oracle best practices. | -| [Interactive Programming Nudge](../prompts/remember-interactive-programming.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fremember-interactive-programming.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fremember-interactive-programming.prompt.md) | A micro-prompt that reminds the agent that it is an interactive programmer. Works great in Clojure when Copilot has access to the REPL (probably via Backseat Driver). Will work with any system that has a live REPL that the agent can use. Adapt the prompt with any specific reminders in your workflow and/or workspace. | -| [Java Documentation (Javadoc) Best Practices](../prompts/java-docs.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-docs.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-docs.prompt.md) | Ensure that Java types are documented with Javadoc comments and follow best practices for documentation. | -| [Java MCP Server Generator](../prompts/java-mcp-server-generator.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-mcp-server-generator.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-mcp-server-generator.prompt.md) | Generate a complete Model Context Protocol server project in Java using the official MCP Java SDK with reactive streams and optional Spring Boot integration. | -| [Javascript Typescript Jest](../prompts/javascript-typescript-jest.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjavascript-typescript-jest.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjavascript-typescript-jest.prompt.md) | Best practices for writing JavaScript/TypeScript tests using Jest, including mocking strategies, test structure, and common patterns. | -| [JUnit 5+ Best Practices](../prompts/java-junit.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-junit.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-junit.prompt.md) | Get best practices for JUnit 5 unit testing, including data-driven tests | -| [Kotlin MCP Server Project Generator](../prompts/kotlin-mcp-server-generator.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fkotlin-mcp-server-generator.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fkotlin-mcp-server-generator.prompt.md) | Generate a complete Kotlin MCP server project with proper structure, dependencies, and implementation using the official io.modelcontextprotocol:kotlin-sdk library. | -| [Mcp Create Adaptive Cards](../prompts/mcp-create-adaptive-cards.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmcp-create-adaptive-cards.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmcp-create-adaptive-cards.prompt.md) | | | -| [Mcp Create Declarative Agent](../prompts/mcp-create-declarative-agent.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmcp-create-declarative-agent.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmcp-create-declarative-agent.prompt.md) | | | -| [Mcp Deploy Manage Agents](../prompts/mcp-deploy-manage-agents.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmcp-deploy-manage-agents.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmcp-deploy-manage-agents.prompt.md) | | | -| [Memory Keeper](../prompts/remember.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fremember.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fremember.prompt.md) | Transforms lessons learned into domain-organized memory instructions (global or workspace). Syntax: `/remember [>domain [scope]] lesson clue` where scope is `global` (default), `user`, `workspace`, or `ws`. | -| [Memory Merger](../prompts/memory-merger.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmemory-merger.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmemory-merger.prompt.md) | Merges mature lessons from a domain memory file into its instruction file. Syntax: `/memory-merger >domain [scope]` where scope is `global` (default), `user`, `workspace`, or `ws`. | -| [Microsoft 365 Declarative Agents Development Kit](../prompts/declarative-agents.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fdeclarative-agents.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fdeclarative-agents.prompt.md) | Complete development kit for Microsoft 365 Copilot declarative agents with three comprehensive workflows (basic, advanced, validation), TypeSpec support, and Microsoft 365 Agents Toolkit integration | -| [Migration and Code Evolution Instructions Generator](../prompts/generate-custom-instructions-from-codebase.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgenerate-custom-instructions-from-codebase.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgenerate-custom-instructions-from-codebase.prompt.md) | Migration and code evolution instructions generator for GitHub Copilot. Analyzes differences between two project versions (branches, commits, or releases) to create precise instructions allowing Copilot to maintain consistency during technology migrations, major refactoring, or framework version upgrades. | -| [MkDocs AI Translator](../prompts/mkdocs-translations.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmkdocs-translations.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmkdocs-translations.prompt.md) | Generate a language translation for a mkdocs documentation stack. | -| [MSTest Best Practices (MSTest 3.x/4.x)](../prompts/csharp-mstest.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcsharp-mstest.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcsharp-mstest.prompt.md) | Get best practices for MSTest 3.x/4.x unit testing, including modern assertion APIs and data-driven tests | -| [Multi Stage Dockerfile](../prompts/multi-stage-dockerfile.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmulti-stage-dockerfile.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmulti-stage-dockerfile.prompt.md) | Create optimized multi-stage Dockerfiles for any language or framework | -| [My Issues](../prompts/my-issues.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmy-issues.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmy-issues.prompt.md) | List my issues in the current repository | -| [My Pull Requests](../prompts/my-pull-requests.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmy-pull-requests.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmy-pull-requests.prompt.md) | List my pull requests in the current repository | -| [Next Intl Add Language](../prompts/next-intl-add-language.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fnext-intl-add-language.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fnext-intl-add-language.prompt.md) | Add new language to a Next.js + next-intl application | -| [NUnit Best Practices](../prompts/csharp-nunit.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcsharp-nunit.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcsharp-nunit.prompt.md) | Get best practices for NUnit unit testing, including data-driven tests | -| [PHP MCP Server Generator](../prompts/php-mcp-server-generator.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fphp-mcp-server-generator.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fphp-mcp-server-generator.prompt.md) | Generate a complete PHP Model Context Protocol server project with tools, resources, prompts, and tests using the official PHP SDK | -| [PostgreSQL Code Review Assistant](../prompts/postgresql-code-review.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fpostgresql-code-review.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fpostgresql-code-review.prompt.md) | PostgreSQL-specific code review assistant focusing on PostgreSQL best practices, anti-patterns, and unique quality standards. Covers JSONB operations, array usage, custom types, schema design, function optimization, and PostgreSQL-exclusive security features like Row Level Security (RLS). | -| [PostgreSQL Development Assistant](../prompts/postgresql-optimization.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fpostgresql-optimization.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fpostgresql-optimization.prompt.md) | PostgreSQL-specific development assistant focusing on unique PostgreSQL features, advanced data types, and PostgreSQL-exclusive capabilities. Covers JSONB operations, array types, custom types, range/geometric types, full-text search, window functions, and PostgreSQL extensions ecosystem. | -| [Power Apps Code Apps Project Scaffolding](../prompts/power-apps-code-app-scaffold.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fpower-apps-code-app-scaffold.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fpower-apps-code-app-scaffold.prompt.md) | Scaffold a complete Power Apps Code App project with PAC CLI setup, SDK integration, and connector configuration | -| [Power BI Data Model Design Review](../prompts/power-bi-model-design-review.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fpower-bi-model-design-review.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fpower-bi-model-design-review.prompt.md) | Comprehensive Power BI data model design review prompt for evaluating model architecture, relationships, and optimization opportunities. | -| [Power BI DAX Formula Optimizer](../prompts/power-bi-dax-optimization.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fpower-bi-dax-optimization.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fpower-bi-dax-optimization.prompt.md) | Comprehensive Power BI DAX formula optimization prompt for improving performance, readability, and maintainability of DAX calculations. | -| [Power BI Performance Troubleshooting Guide](../prompts/power-bi-performance-troubleshooting.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fpower-bi-performance-troubleshooting.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fpower-bi-performance-troubleshooting.prompt.md) | Systematic Power BI performance troubleshooting prompt for identifying, diagnosing, and resolving performance issues in Power BI models, reports, and queries. | -| [Power BI Report Visualization Designer](../prompts/power-bi-report-design-consultation.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fpower-bi-report-design-consultation.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fpower-bi-report-design-consultation.prompt.md) | Power BI report visualization design prompt for creating effective, user-friendly, and accessible reports with optimal chart selection and layout design. | -| [Power Platform MCP Connector Generator](../prompts/mcp-copilot-studio-server-generator.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmcp-copilot-studio-server-generator.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmcp-copilot-studio-server-generator.prompt.md) | Generate a complete MCP server implementation optimized for Copilot Studio integration with proper schema constraints and streamable HTTP support | -| [Power Platform MCP Connector Suite](../prompts/power-platform-mcp-connector-suite.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fpower-platform-mcp-connector-suite.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fpower-platform-mcp-connector-suite.prompt.md) | Generate complete Power Platform custom connector with MCP integration for Copilot Studio - includes schema generation, troubleshooting, and validation | -| [Product Manager Assistant: Feature Identification and Specification](../prompts/gen-specs-as-issues.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgen-specs-as-issues.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgen-specs-as-issues.prompt.md) | This workflow guides you through a systematic approach to identify missing features, prioritize them, and create detailed specifications for implementation. | -| [Professional Prompt Builder](../prompts/prompt-builder.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fprompt-builder.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fprompt-builder.prompt.md) | Guide users through creating high-quality GitHub Copilot prompts with proper structure, tools, and best practices. | -| [Project Folder Structure Blueprint Generator](../prompts/folder-structure-blueprint-generator.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Ffolder-structure-blueprint-generator.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Ffolder-structure-blueprint-generator.prompt.md) | Comprehensive technology-agnostic prompt for analyzing and documenting project folder structures. Auto-detects project types (.NET, Java, React, Angular, Python, Node.js, Flutter), generates detailed blueprints with visualization options, naming conventions, file placement patterns, and extension templates for maintaining consistent code organization across diverse technology stacks. | -| [Project Workflow Documentation Generator](../prompts/project-workflow-analysis-blueprint-generator.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fproject-workflow-analysis-blueprint-generator.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fproject-workflow-analysis-blueprint-generator.prompt.md) | Comprehensive technology-agnostic prompt generator for documenting end-to-end application workflows. Automatically detects project architecture patterns, technology stacks, and data flow patterns to generate detailed implementation blueprints covering entry points, service layers, data access, error handling, and testing approaches across multiple technologies including .NET, Java/Spring, React, and microservices architectures. | -| [Pytest Coverage](../prompts/pytest-coverage.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fpytest-coverage.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fpytest-coverage.prompt.md) | Run pytest tests with coverage, discover lines missing coverage, and increase coverage to 100%. | -| [README Generator Prompt](../prompts/readme-blueprint-generator.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Freadme-blueprint-generator.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Freadme-blueprint-generator.prompt.md) | Intelligent README.md generation prompt that analyzes project documentation structure and creates comprehensive repository documentation. Scans .github/copilot directory files and copilot-instructions.md to extract project information, technology stack, architecture, development workflow, coding standards, and testing approaches while generating well-structured markdown documentation with proper formatting, cross-references, and developer-focused content. | -| [Refactor Method Complexity Reduce](../prompts/refactor-method-complexity-reduce.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Frefactor-method-complexity-reduce.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Frefactor-method-complexity-reduce.prompt.md) | Refactor given method `${input:methodName}` to reduce its cognitive complexity to `${input:complexityThreshold}` or below, by extracting helper methods. | -| [Refactor Plan](../prompts/refactor-plan.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Frefactor-plan.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Frefactor-plan.prompt.md) | Plan a multi-file refactor with proper sequencing and rollback steps | -| [Refactoring Java Methods with Extract Method](../prompts/java-refactoring-extract-method.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-refactoring-extract-method.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-refactoring-extract-method.prompt.md) | Refactoring using Extract Methods in Java Language | -| [Refactoring Java Methods with Remove Parameter](../prompts/java-refactoring-remove-parameter.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-refactoring-remove-parameter.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-refactoring-remove-parameter.prompt.md) | Refactoring using Remove Parameter in Java Language | -| [Repo Story Time](../prompts/repo-story-time.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Frepo-story-time.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Frepo-story-time.prompt.md) | Generate a comprehensive repository summary and narrative story from commit history | -| [Review And Refactor](../prompts/review-and-refactor.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Freview-and-refactor.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Freview-and-refactor.prompt.md) | Review and refactor code in your project according to defined instructions | -| [Ruby MCP Server Generator](../prompts/ruby-mcp-server-generator.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fruby-mcp-server-generator.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fruby-mcp-server-generator.prompt.md) | Generate a complete Model Context Protocol server project in Ruby using the official MCP Ruby SDK gem. | -| [Rust Mcp Server Generator](../prompts/rust-mcp-server-generator.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Frust-mcp-server-generator.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Frust-mcp-server-generator.prompt.md) | Generate a complete Rust Model Context Protocol server project with tools, prompts, resources, and tests using the official rmcp SDK | -| [Sa Generate](../prompts/structured-autonomy-generate.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fstructured-autonomy-generate.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fstructured-autonomy-generate.prompt.md) | Structured Autonomy Implementation Generator Prompt | -| [Sa Implement](../prompts/structured-autonomy-implement.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fstructured-autonomy-implement.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fstructured-autonomy-implement.prompt.md) | Structured Autonomy Implementation Prompt | -| [Sa Plan](../prompts/structured-autonomy-plan.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fstructured-autonomy-plan.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fstructured-autonomy-plan.prompt.md) | Structured Autonomy Planning Prompt | -| [Shuffle JSON Data](../prompts/shuffle-json-data.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fshuffle-json-data.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fshuffle-json-data.prompt.md) | Shuffle repetitive JSON objects safely by validating schema consistency before randomising entries. | -| [Spring Boot Best Practices](../prompts/java-springboot.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-springboot.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-springboot.prompt.md) | Get best practices for developing applications with Spring Boot. | -| [Spring Boot with Kotlin Best Practices](../prompts/kotlin-springboot.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fkotlin-springboot.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fkotlin-springboot.prompt.md) | Get best practices for developing applications with Spring Boot and Kotlin. | -| [SQL Code Review](../prompts/sql-code-review.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fsql-code-review.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fsql-code-review.prompt.md) | Universal SQL code review assistant that performs comprehensive security, maintainability, and code quality analysis across all SQL databases (MySQL, PostgreSQL, SQL Server, Oracle). Focuses on SQL injection prevention, access control, code standards, and anti-pattern detection. Complements SQL optimization prompt for complete development coverage. | -| [SQL Performance Optimization Assistant](../prompts/sql-optimization.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fsql-optimization.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fsql-optimization.prompt.md) | Universal SQL performance optimization assistant for comprehensive query tuning, indexing strategies, and database performance analysis across all SQL databases (MySQL, PostgreSQL, SQL Server, Oracle). Provides execution plan analysis, pagination optimization, batch operations, and performance monitoring guidance. | -| [Suggest Awesome GitHub Copilot Custom Agents](../prompts/suggest-awesome-github-copilot-agents.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fsuggest-awesome-github-copilot-agents.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fsuggest-awesome-github-copilot-agents.prompt.md) | Suggest relevant GitHub Copilot Custom Agents files from the awesome-copilot repository based on current repository context and chat history, avoiding duplicates with existing custom agents in this repository, and identifying outdated agents that need updates. | -| [Suggest Awesome GitHub Copilot Instructions](../prompts/suggest-awesome-github-copilot-instructions.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fsuggest-awesome-github-copilot-instructions.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fsuggest-awesome-github-copilot-instructions.prompt.md) | Suggest relevant GitHub Copilot instruction files from the awesome-copilot repository based on current repository context and chat history, avoiding duplicates with existing instructions in this repository, and identifying outdated instructions that need updates. | -| [Suggest Awesome GitHub Copilot Prompts](../prompts/suggest-awesome-github-copilot-prompts.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fsuggest-awesome-github-copilot-prompts.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fsuggest-awesome-github-copilot-prompts.prompt.md) | Suggest relevant GitHub Copilot prompt files from the awesome-copilot repository based on current repository context and chat history, avoiding duplicates with existing prompts in this repository, and identifying outdated prompts that need updates. | -| [Suggest Awesome GitHub Copilot Skills](../prompts/suggest-awesome-github-copilot-skills.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fsuggest-awesome-github-copilot-skills.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fsuggest-awesome-github-copilot-skills.prompt.md) | Suggest relevant GitHub Copilot skills from the awesome-copilot repository based on current repository context and chat history, avoiding duplicates with existing skills in this repository, and identifying outdated skills that need updates. | -| [Swift MCP Server Generator](../prompts/swift-mcp-server-generator.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fswift-mcp-server-generator.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fswift-mcp-server-generator.prompt.md) | Generate a complete Model Context Protocol server project in Swift using the official MCP Swift SDK package. | -| [Test Generation with Playwright MCP](../prompts/playwright-generate-test.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fplaywright-generate-test.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fplaywright-generate-test.prompt.md) | Generate a Playwright test based on a scenario using Playwright MCP | -| [Test Planning & Quality Assurance Prompt](../prompts/breakdown-test.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbreakdown-test.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbreakdown-test.prompt.md) | Test Planning and Quality Assurance prompt that generates comprehensive test strategies, task breakdowns, and quality validation plans for GitHub projects. | -| [TLDR Prompt](../prompts/tldr-prompt.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Ftldr-prompt.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Ftldr-prompt.prompt.md) | Create tldr summaries for GitHub Copilot files (prompts, agents, instructions, collections), MCP servers, or documentation from URLs and queries. | -| [TUnit Best Practices](../prompts/csharp-tunit.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcsharp-tunit.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcsharp-tunit.prompt.md) | Get best practices for TUnit unit testing, including data-driven tests | -| [Update Azure Verified Modules in Bicep Files](../prompts/update-avm-modules-in-bicep.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fupdate-avm-modules-in-bicep.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fupdate-avm-modules-in-bicep.prompt.md) | Update Azure Verified Modules (AVM) to latest versions in Bicep files. | -| [Update Implementation Plan](../prompts/update-implementation-plan.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fupdate-implementation-plan.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fupdate-implementation-plan.prompt.md) | Update an existing implementation plan file with new or update requirements to provide new features, refactoring existing code or upgrading packages, design, architecture or infrastructure. | -| [Update LLMs.txt File](../prompts/update-llms.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fupdate-llms.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fupdate-llms.prompt.md) | Update the llms.txt file in the root folder to reflect changes in documentation or specifications following the llms.txt specification at https://llmstxt.org/ | -| [Update Markdown File Index](../prompts/update-markdown-file-index.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fupdate-markdown-file-index.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fupdate-markdown-file-index.prompt.md) | Update a markdown file section with an index/table of files from a specified folder. | -| [Update Specification](../prompts/update-specification.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fupdate-specification.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fupdate-specification.prompt.md) | Update an existing specification file for the solution, optimized for Generative AI consumption based on new requirements or updates to any existing code. | -| [Update Standard OO Component Documentation](../prompts/update-oo-component-documentation.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fupdate-oo-component-documentation.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fupdate-oo-component-documentation.prompt.md) | Update existing object-oriented component documentation following industry best practices and architectural documentation standards. | -| [Website Exploration for Testing](../prompts/playwright-explore-website.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fplaywright-explore-website.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fplaywright-explore-website.prompt.md) | Website exploration for testing using Playwright MCP | -| [What Context Do You Need?](../prompts/what-context-needed.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fwhat-context-needed.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fwhat-context-needed.prompt.md) | Ask Copilot what files it needs to see before answering a question | -| [Write Coding Standards From File](../prompts/write-coding-standards-from-file.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fwrite-coding-standards-from-file.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fwrite-coding-standards-from-file.prompt.md) | Write a coding standards document for a project using the coding styles from the file(s) and/or folder(s) passed as arguments in the prompt. | -| [XUnit Best Practices](../prompts/csharp-xunit.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcsharp-xunit.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcsharp-xunit.prompt.md) | Get best practices for XUnit unit testing, including data-driven tests | diff --git a/docs/README.skills.md b/docs/README.skills.md index c7ddb1114..e3c5e5fd8 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -3,6 +3,10 @@ Agent Skills are self-contained folders with instructions and bundled resources that enhance AI capabilities for specialized tasks. Based on the [Agent Skills specification](https://agentskills.io/specification), each skill contains a `SKILL.md` file with detailed instructions that agents load on-demand. Skills differ from other primitives by supporting bundled assets (scripts, code samples, reference data) that agents can utilize when performing specialized tasks. +### How to Contribute + +See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to contribute new agent skills, improve existing ones, and share your use cases. + ### How to Use Agent Skills **What's Included:** @@ -22,56 +26,201 @@ Skills differ from other primitives by supporting bundled assets (scripts, code | Name | Description | Bundled Assets | | ---- | ----------- | -------------- | +| [add-educational-comments](../skills/add-educational-comments/SKILL.md) | Add educational comments to the file specified, or prompt asking for file to comment if one is not provided. | None | | [agent-governance](../skills/agent-governance/SKILL.md) | Patterns and techniques for adding governance, safety, and trust controls to AI agent systems. Use this skill when:
- Building AI agents that call external tools (APIs, databases, file systems)
- Implementing policy-based access controls for agent tool usage
- Adding semantic intent classification to detect dangerous prompts
- Creating trust scoring systems for multi-agent workflows
- Building audit trails for agent actions and decisions
- Enforcing rate limits, content filters, or tool restrictions on agents
- Working with any agent framework (PydanticAI, CrewAI, OpenAI Agents, LangChain, AutoGen) | None | | [agentic-eval](../skills/agentic-eval/SKILL.md) | Patterns and techniques for evaluating and improving AI agent outputs. Use this skill when:
- Implementing self-critique and reflection loops
- Building evaluator-optimizer pipelines for quality-critical generation
- Creating test-driven code refinement workflows
- Designing rubric-based or LLM-as-judge evaluation systems
- Adding iterative improvement to agent outputs (code, reports, analysis)
- Measuring and improving agent response quality | None | +| [ai-prompt-engineering-safety-review](../skills/ai-prompt-engineering-safety-review/SKILL.md) | Comprehensive AI prompt engineering safety review and improvement prompt. Analyzes prompts for safety, bias, security vulnerabilities, and effectiveness while providing detailed improvement recommendations with extensive frameworks, testing methodologies, and educational content. | None | | [appinsights-instrumentation](../skills/appinsights-instrumentation/SKILL.md) | Instrument a webapp to send useful telemetry data to Azure App Insights | `LICENSE.txt`
`examples/appinsights.bicep`
`references/ASPNETCORE.md`
`references/AUTO.md`
`references/NODEJS.md`
`references/PYTHON.md`
`scripts/appinsights.ps1` | +| [apple-appstore-reviewer](../skills/apple-appstore-reviewer/SKILL.md) | Serves as a reviewer of the codebase with instructions on looking for Apple App Store optimizations or rejection reasons. | None | +| [arch-linux-triage](../skills/arch-linux-triage/SKILL.md) | Triage and resolve Arch Linux issues with pacman, systemd, and rolling-release best practices. | None | +| [architecture-blueprint-generator](../skills/architecture-blueprint-generator/SKILL.md) | Comprehensive project architecture blueprint generator that analyzes codebases to create detailed architectural documentation. Automatically detects technology stacks and architectural patterns, generates visual diagrams, documents implementation patterns, and provides extensible blueprints for maintaining architectural consistency and guiding new development. | None | | [aspire](../skills/aspire/SKILL.md) | Aspire skill covering the Aspire CLI, AppHost orchestration, service discovery, integrations, MCP server, VS Code extension, Dev Containers, GitHub Codespaces, templates, dashboard, and deployment. Use when the user asks to create, run, debug, configure, deploy, or troubleshoot an Aspire distributed application. | `references/architecture.md`
`references/cli-reference.md`
`references/dashboard.md`
`references/deployment.md`
`references/integrations-catalog.md`
`references/mcp-server.md`
`references/polyglot-apis.md`
`references/testing.md`
`references/troubleshooting.md` | +| [aspnet-minimal-api-openapi](../skills/aspnet-minimal-api-openapi/SKILL.md) | Create ASP.NET Minimal API endpoints with proper OpenAPI documentation | None | +| [az-cost-optimize](../skills/az-cost-optimize/SKILL.md) | Analyze Azure resources used in the app (IaC files and/or resources in a target rg) and optimize costs - creating GitHub issues for identified optimizations. | None | | [azure-deployment-preflight](../skills/azure-deployment-preflight/SKILL.md) | Performs comprehensive preflight validation of Bicep deployments to Azure, including template syntax validation, what-if analysis, and permission checks. Use this skill before any deployment to Azure to preview changes, identify potential issues, and ensure the deployment will succeed. Activate when users mention deploying to Azure, validating Bicep files, checking deployment permissions, previewing infrastructure changes, running what-if, or preparing for azd provision. | `references/ERROR-HANDLING.md`
`references/REPORT-TEMPLATE.md`
`references/VALIDATION-COMMANDS.md` | | [azure-devops-cli](../skills/azure-devops-cli/SKILL.md) | Manage Azure DevOps resources via CLI including projects, repos, pipelines, builds, pull requests, work items, artifacts, and service endpoints. Use when working with Azure DevOps, az commands, devops automation, CI/CD, or when user mentions Azure DevOps CLI. | None | +| [azure-resource-health-diagnose](../skills/azure-resource-health-diagnose/SKILL.md) | Analyze Azure resource health, diagnose issues from logs and telemetry, and create a remediation plan for identified problems. | None | | [azure-resource-visualizer](../skills/azure-resource-visualizer/SKILL.md) | Analyze Azure resource groups and generate detailed Mermaid architecture diagrams showing the relationships between individual resources. Use this skill when the user asks for a diagram of their Azure resources or help in understanding how the resources relate to each other. | `LICENSE.txt`
`assets/template-architecture.md` | | [azure-role-selector](../skills/azure-role-selector/SKILL.md) | When user is asking for guidance for which role to assign to an identity given desired permissions, this agent helps them understand the role that will meet the requirements with least privilege access and how to apply that role. | `LICENSE.txt` | | [azure-static-web-apps](../skills/azure-static-web-apps/SKILL.md) | Helps create, configure, and deploy Azure Static Web Apps using the SWA CLI. Use when deploying static sites to Azure, setting up SWA local development, configuring staticwebapp.config.json, adding Azure Functions APIs to SWA, or setting up GitHub Actions CI/CD for Static Web Apps. | None | +| [bigquery-pipeline-audit](../skills/bigquery-pipeline-audit/SKILL.md) | Audits Python + BigQuery pipelines for cost safety, idempotency, and production readiness. Returns a structured report with exact patch locations. | None | +| [boost-prompt](../skills/boost-prompt/SKILL.md) | Interactive prompt refinement workflow: interrogates scope, deliverables, constraints; copies final markdown to clipboard; never writes code. Requires the Joyride extension. | None | +| [breakdown-epic-arch](../skills/breakdown-epic-arch/SKILL.md) | Prompt for creating the high-level technical architecture for an Epic, based on a Product Requirements Document. | None | +| [breakdown-epic-pm](../skills/breakdown-epic-pm/SKILL.md) | Prompt for creating an Epic Product Requirements Document (PRD) for a new epic. This PRD will be used as input for generating a technical architecture specification. | None | +| [breakdown-feature-implementation](../skills/breakdown-feature-implementation/SKILL.md) | Prompt for creating detailed feature implementation plans, following Epoch monorepo structure. | None | +| [breakdown-feature-prd](../skills/breakdown-feature-prd/SKILL.md) | Prompt for creating Product Requirements Documents (PRDs) for new features, based on an Epic. | None | +| [breakdown-plan](../skills/breakdown-plan/SKILL.md) | Issue Planning and Automation prompt that generates comprehensive project plans with Epic > Feature > Story/Enabler > Test hierarchy, dependencies, priorities, and automated tracking. | None | +| [breakdown-test](../skills/breakdown-test/SKILL.md) | Test Planning and Quality Assurance prompt that generates comprehensive test strategies, task breakdowns, and quality validation plans for GitHub projects. | None | +| [centos-linux-triage](../skills/centos-linux-triage/SKILL.md) | Triage and resolve CentOS issues using RHEL-compatible tooling, SELinux-aware practices, and firewalld. | None | | [chrome-devtools](../skills/chrome-devtools/SKILL.md) | Expert-level browser automation, debugging, and performance analysis using Chrome DevTools MCP. Use for interacting with web pages, capturing screenshots, analyzing network traffic, and profiling performance. | None | +| [code-exemplars-blueprint-generator](../skills/code-exemplars-blueprint-generator/SKILL.md) | Technology-agnostic prompt generator that creates customizable AI prompts for scanning codebases and identifying high-quality code exemplars. Supports multiple programming languages (.NET, Java, JavaScript, TypeScript, React, Angular, Python) with configurable analysis depth, categorization methods, and documentation formats to establish coding standards and maintain consistency across development teams. | None | +| [comment-code-generate-a-tutorial](../skills/comment-code-generate-a-tutorial/SKILL.md) | Transform this Python script into a polished, beginner-friendly project by refactoring the code, adding clear instructional comments, and generating a complete markdown tutorial. | None | +| [containerize-aspnet-framework](../skills/containerize-aspnet-framework/SKILL.md) | Containerize an ASP.NET .NET Framework project by creating Dockerfile and .dockerfile files customized for the project. | None | +| [containerize-aspnetcore](../skills/containerize-aspnetcore/SKILL.md) | Containerize an ASP.NET Core project by creating Dockerfile and .dockerfile files customized for the project. | None | +| [context-map](../skills/context-map/SKILL.md) | Generate a map of all files relevant to a task before making changes | None | +| [conventional-commit](../skills/conventional-commit/SKILL.md) | Prompt and workflow for generating conventional commit messages using a structured XML format. Guides users to create standardized, descriptive commit messages in line with the Conventional Commits specification, including instructions, examples, and validation. | None | +| [convert-plaintext-to-md](../skills/convert-plaintext-to-md/SKILL.md) | Convert a text-based document to markdown following instructions from prompt, or if a documented option is passed, follow the instructions for that option. | None | | [copilot-cli-quickstart](../skills/copilot-cli-quickstart/SKILL.md) | Use this skill when someone wants to learn GitHub Copilot CLI from scratch. Offers interactive step-by-step tutorials with separate Developer and Non-Developer tracks, plus on-demand Q&A. Just say "start tutorial" or ask a question! Note: This skill targets GitHub Copilot CLI specifically and uses CLI-specific tools (ask_user, sql, fetch_copilot_cli_documentation). | None | +| [copilot-instructions-blueprint-generator](../skills/copilot-instructions-blueprint-generator/SKILL.md) | Technology-agnostic blueprint generator for creating comprehensive copilot-instructions.md files that guide GitHub Copilot to produce code consistent with project standards, architecture patterns, and exact technology versions by analyzing existing codebase patterns and avoiding assumptions. | None | | [copilot-sdk](../skills/copilot-sdk/SKILL.md) | Build agentic applications with GitHub Copilot SDK. Use when embedding AI agents in apps, creating custom tools, implementing streaming responses, managing sessions, connecting to MCP servers, or creating custom agents. Triggers on Copilot SDK, GitHub SDK, agentic app, embed Copilot, programmable agent, MCP server, custom agent. | None | | [copilot-usage-metrics](../skills/copilot-usage-metrics/SKILL.md) | Retrieve and display GitHub Copilot usage metrics for organizations and enterprises using the GitHub CLI and REST API. | `get-enterprise-metrics.sh`
`get-enterprise-user-metrics.sh`
`get-org-metrics.sh`
`get-org-user-metrics.sh` | +| [cosmosdb-datamodeling](../skills/cosmosdb-datamodeling/SKILL.md) | Step-by-step guide for capturing key application requirements for NoSQL use-case and produce Azure Cosmos DB Data NoSQL Model design using best practices and common patterns, artifacts_produced: "cosmosdb_requirements.md" file and "cosmosdb_data_model.md" file | None | +| [create-agentsmd](../skills/create-agentsmd/SKILL.md) | Prompt for generating an AGENTS.md file for a repository | None | +| [create-architectural-decision-record](../skills/create-architectural-decision-record/SKILL.md) | Create an Architectural Decision Record (ADR) document for AI-optimized decision documentation. | None | +| [create-github-action-workflow-specification](../skills/create-github-action-workflow-specification/SKILL.md) | Create a formal specification for an existing GitHub Actions CI/CD workflow, optimized for AI consumption and workflow maintenance. | None | +| [create-github-issue-feature-from-specification](../skills/create-github-issue-feature-from-specification/SKILL.md) | Create GitHub Issue for feature request from specification file using feature_request.yml template. | None | +| [create-github-issues-feature-from-implementation-plan](../skills/create-github-issues-feature-from-implementation-plan/SKILL.md) | Create GitHub Issues from implementation plan phases using feature_request.yml or chore_request.yml templates. | None | +| [create-github-issues-for-unmet-specification-requirements](../skills/create-github-issues-for-unmet-specification-requirements/SKILL.md) | Create GitHub Issues for unimplemented requirements from specification files using feature_request.yml template. | None | +| [create-github-pull-request-from-specification](../skills/create-github-pull-request-from-specification/SKILL.md) | Create GitHub Pull Request for feature request from specification file using pull_request_template.md template. | None | +| [create-implementation-plan](../skills/create-implementation-plan/SKILL.md) | Create a new implementation plan file for new features, refactoring existing code or upgrading packages, design, architecture or infrastructure. | None | +| [create-llms](../skills/create-llms/SKILL.md) | Create an llms.txt file from scratch based on repository structure following the llms.txt specification at https://llmstxt.org/ | None | +| [create-oo-component-documentation](../skills/create-oo-component-documentation/SKILL.md) | Create comprehensive, standardized documentation for object-oriented components following industry best practices and architectural documentation standards. | None | +| [create-readme](../skills/create-readme/SKILL.md) | Create a README.md file for the project | None | +| [create-specification](../skills/create-specification/SKILL.md) | Create a new specification file for the solution, optimized for Generative AI consumption. | None | +| [create-spring-boot-java-project](../skills/create-spring-boot-java-project/SKILL.md) | Create Spring Boot Java Project Skeleton | None | +| [create-spring-boot-kotlin-project](../skills/create-spring-boot-kotlin-project/SKILL.md) | Create Spring Boot Kotlin Project Skeleton | None | +| [create-technical-spike](../skills/create-technical-spike/SKILL.md) | Create time-boxed technical spike documents for researching and resolving critical development decisions before implementation. | None | +| [create-tldr-page](../skills/create-tldr-page/SKILL.md) | Create a tldr page from documentation URLs and command examples, requiring both URL and command name. | None | | [create-web-form](../skills/create-web-form/SKILL.md) | Create robust, accessible web forms with best practices for HTML structure, CSS styling, JavaScript interactivity, form validation, and server-side processing. Use when asked to "create a form", "build a web form", "add a contact form", "make a signup form", or when building any HTML form with data handling. Covers PHP and Python backends, MySQL database integration, REST APIs, XML data exchange, accessibility (ARIA), and progressive web apps. | `references/accessibility.md`
`references/aria-form-role.md`
`references/css-styling.md`
`references/form-basics.md`
`references/form-controls.md`
`references/form-data-handling.md`
`references/html-form-elements.md`
`references/html-form-example.md`
`references/hypertext-transfer-protocol.md`
`references/javascript.md`
`references/php-cookies.md`
`references/php-forms.md`
`references/php-json.md`
`references/php-mysql-database.md`
`references/progressive-web-app.md`
`references/python-as-web-framework.md`
`references/python-contact-form.md`
`references/python-flask-app.md`
`references/python-flask.md`
`references/security.md`
`references/styling-web-forms.md`
`references/web-api.md`
`references/web-performance.md`
`references/xml.md` | +| [csharp-async](../skills/csharp-async/SKILL.md) | Get best practices for C# async programming | None | +| [csharp-docs](../skills/csharp-docs/SKILL.md) | Ensure that C# types are documented with XML comments and follow best practices for documentation. | None | +| [csharp-mcp-server-generator](../skills/csharp-mcp-server-generator/SKILL.md) | Generate a complete MCP server project in C# with tools, prompts, and proper configuration | None | +| [csharp-mstest](../skills/csharp-mstest/SKILL.md) | Get best practices for MSTest 3.x/4.x unit testing, including modern assertion APIs and data-driven tests | None | +| [csharp-nunit](../skills/csharp-nunit/SKILL.md) | Get best practices for NUnit unit testing, including data-driven tests | None | +| [csharp-tunit](../skills/csharp-tunit/SKILL.md) | Get best practices for TUnit unit testing, including data-driven tests | None | +| [csharp-xunit](../skills/csharp-xunit/SKILL.md) | Get best practices for XUnit unit testing, including data-driven tests | None | +| [dataverse-python-advanced-patterns](../skills/dataverse-python-advanced-patterns/SKILL.md) | Generate production code for Dataverse SDK using advanced patterns, error handling, and optimization techniques. | None | +| [dataverse-python-production-code](../skills/dataverse-python-production-code/SKILL.md) | Generate production-ready Python code using Dataverse SDK with error handling, optimization, and best practices | None | +| [dataverse-python-quickstart](../skills/dataverse-python-quickstart/SKILL.md) | Generate Python SDK setup + CRUD + bulk + paging snippets using official patterns. | None | +| [dataverse-python-usecase-builder](../skills/dataverse-python-usecase-builder/SKILL.md) | Generate complete solutions for specific Dataverse SDK use cases with architecture recommendations | None | +| [debian-linux-triage](../skills/debian-linux-triage/SKILL.md) | Triage and resolve Debian Linux issues with apt, systemd, and AppArmor-aware guidance. | None | +| [declarative-agents](../skills/declarative-agents/SKILL.md) | Complete development kit for Microsoft 365 Copilot declarative agents with three comprehensive workflows (basic, advanced, validation), TypeSpec support, and Microsoft 365 Agents Toolkit integration | None | +| [devops-rollout-plan](../skills/devops-rollout-plan/SKILL.md) | Generate comprehensive rollout plans with preflight checks, step-by-step deployment, verification signals, rollback procedures, and communication plans for infrastructure and application changes | None | +| [documentation-writer](../skills/documentation-writer/SKILL.md) | DiΓ‘taxis Documentation Expert. An expert technical writer specializing in creating high-quality software documentation, guided by the principles and structure of the DiΓ‘taxis technical documentation authoring framework. | None | +| [dotnet-best-practices](../skills/dotnet-best-practices/SKILL.md) | Ensure .NET/C# code meets best practices for the solution/project. | None | +| [dotnet-design-pattern-review](../skills/dotnet-design-pattern-review/SKILL.md) | Review the C#/.NET code for design pattern implementation and suggest improvements. | None | +| [dotnet-upgrade](../skills/dotnet-upgrade/SKILL.md) | Ready-to-use prompts for comprehensive .NET framework upgrade analysis and execution | None | +| [editorconfig](../skills/editorconfig/SKILL.md) | Generates a comprehensive and best-practice-oriented .editorconfig file based on project analysis and user preferences. | None | +| [ef-core](../skills/ef-core/SKILL.md) | Get best practices for Entity Framework Core | None | | [entra-agent-user](../skills/entra-agent-user/SKILL.md) | Create Agent Users in Microsoft Entra ID from Agent Identities, enabling AI agents to act as digital workers with user identity capabilities in Microsoft 365 and Azure environments. | None | | [excalidraw-diagram-generator](../skills/excalidraw-diagram-generator/SKILL.md) | Generate Excalidraw diagrams from natural language descriptions. Use when asked to "create a diagram", "make a flowchart", "visualize a process", "draw a system architecture", "create a mind map", or "generate an Excalidraw file". Supports flowcharts, relationship diagrams, mind maps, and system architecture diagrams. Outputs .excalidraw JSON files that can be opened directly in Excalidraw. | `references/element-types.md`
`references/excalidraw-schema.md`
`scripts/.gitignore`
`scripts/README.md`
`scripts/add-arrow.py`
`scripts/add-icon-to-diagram.py`
`scripts/split-excalidraw-library.py`
`templates/business-flow-swimlane-template.excalidraw`
`templates/class-diagram-template.excalidraw`
`templates/data-flow-diagram-template.excalidraw`
`templates/er-diagram-template.excalidraw`
`templates/flowchart-template.excalidraw`
`templates/mindmap-template.excalidraw`
`templates/relationship-template.excalidraw`
`templates/sequence-diagram-template.excalidraw` | | [fabric-lakehouse](../skills/fabric-lakehouse/SKILL.md) | Use this skill to get context about Fabric Lakehouse and its features for software systems and AI-powered functions. It offers descriptions of Lakehouse data components, organization with schemas and shortcuts, access control, and code examples. This skill supports users in designing, building, and optimizing Lakehouse solutions using best practices. | `references/getdata.md`
`references/pyspark.md` | +| [fedora-linux-triage](../skills/fedora-linux-triage/SKILL.md) | Triage and resolve Fedora issues with dnf, systemd, and SELinux-aware guidance. | None | +| [finalize-agent-prompt](../skills/finalize-agent-prompt/SKILL.md) | Finalize prompt file using the role of an AI agent to polish the prompt for the end user. | None | | [finnish-humanizer](../skills/finnish-humanizer/SKILL.md) | Detect and remove AI-generated markers from Finnish text, making it sound like a native Finnish speaker wrote it. Use when asked to "humanize", "naturalize", or "remove AI feel" from Finnish text, or when editing .md/.txt files containing Finnish content. Identifies 26 patterns (12 Finnish-specific + 14 universal) and 4 style markers. | `references/patterns.md` | +| [first-ask](../skills/first-ask/SKILL.md) | Interactive, input-tool powered, task refinement workflow: interrogates scope, deliverables, constraints before carrying out the task; Requires the Joyride extension. | None | | [fluentui-blazor](../skills/fluentui-blazor/SKILL.md) | Guide for using the Microsoft Fluent UI Blazor component library (Microsoft.FluentUI.AspNetCore.Components NuGet package) in Blazor applications. Use this when the user is building a Blazor app with Fluent UI components, setting up the library, using FluentUI components like FluentButton, FluentDataGrid, FluentDialog, FluentToast, FluentNavMenu, FluentTextField, FluentSelect, FluentAutocomplete, FluentDesignTheme, or any component prefixed with "Fluent". Also use when troubleshooting missing providers, JS interop issues, or theming. | `references/DATAGRID.md`
`references/LAYOUT-AND-NAVIGATION.md`
`references/SETUP.md`
`references/THEMING.md` | +| [folder-structure-blueprint-generator](../skills/folder-structure-blueprint-generator/SKILL.md) | Comprehensive technology-agnostic prompt for analyzing and documenting project folder structures. Auto-detects project types (.NET, Java, React, Angular, Python, Node.js, Flutter), generates detailed blueprints with visualization options, naming conventions, file placement patterns, and extension templates for maintaining consistent code organization across diverse technology stacks. | None | +| [game-engine](../skills/game-engine/SKILL.md) | Expert skill for building web-based game engines and games using HTML5, Canvas, WebGL, and JavaScript. Use when asked to create games, build game engines, implement game physics, handle collision detection, set up game loops, manage sprites, add game controls, or work with 2D/3D rendering. Covers techniques for platformers, breakout-style games, maze games, tilemaps, audio, multiplayer via WebRTC, and publishing games. | `assets/2d-maze-game.md`
`assets/2d-platform-game.md`
`assets/gameBase-template-repo.md`
`assets/paddle-game-template.md`
`assets/simple-2d-engine.md`
`references/3d-web-games.md`
`references/algorithms.md`
`references/basics.md`
`references/game-control-mechanisms.md`
`references/game-engine-core-principles.md`
`references/game-publishing.md`
`references/techniques.md`
`references/terminology.md`
`references/web-apis.md` | +| [gen-specs-as-issues](../skills/gen-specs-as-issues/SKILL.md) | This workflow guides you through a systematic approach to identify missing features, prioritize them, and create detailed specifications for implementation. | None | +| [generate-custom-instructions-from-codebase](../skills/generate-custom-instructions-from-codebase/SKILL.md) | Migration and code evolution instructions generator for GitHub Copilot. Analyzes differences between two project versions (branches, commits, or releases) to create precise instructions allowing Copilot to maintain consistency during technology migrations, major refactoring, or framework version upgrades. | None | | [gh-cli](../skills/gh-cli/SKILL.md) | GitHub CLI (gh) comprehensive reference for repositories, issues, pull requests, Actions, projects, releases, gists, codespaces, organizations, extensions, and all GitHub operations from the command line. | None | | [git-commit](../skills/git-commit/SKILL.md) | Execute git commit with conventional commit message analysis, intelligent staging, and message generation. Use when user asks to commit changes, create a git commit, or mentions "/commit". Supports: (1) Auto-detecting type and scope from changes, (2) Generating conventional commit messages from diff, (3) Interactive commit with optional type/scope/description overrides, (4) Intelligent file staging for logical grouping | None | +| [git-flow-branch-creator](../skills/git-flow-branch-creator/SKILL.md) | Intelligent Git Flow branch creator that analyzes git status/diff and creates appropriate branches following the nvie Git Flow branching model. | None | +| [github-copilot-starter](../skills/github-copilot-starter/SKILL.md) | Set up complete GitHub Copilot configuration for a new project based on technology stack | None | | [github-issues](../skills/github-issues/SKILL.md) | Create, update, and manage GitHub issues using MCP tools. Use this skill when users want to create bug reports, feature requests, or task issues, update existing issues, add labels/assignees/milestones, or manage issue workflows. Triggers on requests like "create an issue", "file a bug", "request a feature", "update issue X", or any GitHub issue management task. | `references/templates.md` | +| [go-mcp-server-generator](../skills/go-mcp-server-generator/SKILL.md) | Generate a complete Go MCP server project with proper structure, dependencies, and implementation using the official github.com/modelcontextprotocol/go-sdk. | None | | [image-manipulation-image-magick](../skills/image-manipulation-image-magick/SKILL.md) | Process and manipulate images using ImageMagick. Supports resizing, format conversion, batch processing, and retrieving image metadata. Use when working with images, creating thumbnails, resizing wallpapers, or performing batch image operations. | None | +| [java-add-graalvm-native-image-support](../skills/java-add-graalvm-native-image-support/SKILL.md) | GraalVM Native Image expert that adds native image support to Java applications, builds the project, analyzes build errors, applies fixes, and iterates until successful compilation using Oracle best practices. | None | +| [java-docs](../skills/java-docs/SKILL.md) | Ensure that Java types are documented with Javadoc comments and follow best practices for documentation. | None | +| [java-junit](../skills/java-junit/SKILL.md) | Get best practices for JUnit 5 unit testing, including data-driven tests | None | +| [java-mcp-server-generator](../skills/java-mcp-server-generator/SKILL.md) | Generate a complete Model Context Protocol server project in Java using the official MCP Java SDK with reactive streams and optional Spring Boot integration. | None | +| [java-refactoring-extract-method](../skills/java-refactoring-extract-method/SKILL.md) | Refactoring using Extract Methods in Java Language | None | +| [java-refactoring-remove-parameter](../skills/java-refactoring-remove-parameter/SKILL.md) | Refactoring using Remove Parameter in Java Language | None | +| [java-springboot](../skills/java-springboot/SKILL.md) | Get best practices for developing applications with Spring Boot. | None | +| [javascript-typescript-jest](../skills/javascript-typescript-jest/SKILL.md) | Best practices for writing JavaScript/TypeScript tests using Jest, including mocking strategies, test structure, and common patterns. | None | +| [kotlin-mcp-server-generator](../skills/kotlin-mcp-server-generator/SKILL.md) | Generate a complete Kotlin MCP server project with proper structure, dependencies, and implementation using the official io.modelcontextprotocol:kotlin-sdk library. | None | +| [kotlin-springboot](../skills/kotlin-springboot/SKILL.md) | Get best practices for developing applications with Spring Boot and Kotlin. | None | | [legacy-circuit-mockups](../skills/legacy-circuit-mockups/SKILL.md) | Generate breadboard circuit mockups and visual diagrams using HTML5 Canvas drawing techniques. Use when asked to create circuit layouts, visualize electronic component placements, draw breadboard diagrams, mockup 6502 builds, generate retro computer schematics, or design vintage electronics projects. Supports 555 timers, W65C02S microprocessors, 28C256 EEPROMs, W65C22 VIA chips, 7400-series logic gates, LEDs, resistors, capacitors, switches, buttons, crystals, and wires. | `references/28256-eeprom.md`
`references/555.md`
`references/6502.md`
`references/6522.md`
`references/6C62256.md`
`references/7400-series.md`
`references/assembly-compiler.md`
`references/assembly-language.md`
`references/basic-electronic-components.md`
`references/breadboard.md`
`references/common-breadboard-components.md`
`references/connecting-electronic-components.md`
`references/emulator-28256-eeprom.md`
`references/emulator-6502.md`
`references/emulator-6522.md`
`references/emulator-6C62256.md`
`references/emulator-lcd.md`
`references/lcd.md`
`references/minipro.md`
`references/t48eeprom-programmer.md` | | [make-repo-contribution](../skills/make-repo-contribution/SKILL.md) | All changes to code must follow the guidance documented in the repository. Before any issue is filed, branch is made, commits generated, or pull request (or PR) created, a search must be done to ensure the right steps are followed. Whenever asked to create an issue, commit messages, to push code, or create a PR, use this skill so everything is done correctly. | `assets/issue-template.md`
`assets/pr-template.md` | | [make-skill-template](../skills/make-skill-template/SKILL.md) | Create new Agent Skills for GitHub Copilot from prompts or by duplicating this template. Use when asked to "create a skill", "make a new skill", "scaffold a skill", or when building specialized AI capabilities with bundled resources. Generates SKILL.md files with proper frontmatter, directory structure, and optional scripts/references/assets folders. | None | | [markdown-to-html](../skills/markdown-to-html/SKILL.md) | Convert Markdown files to HTML similar to `marked.js`, `pandoc`, `gomarkdown/markdown`, or similar tools; or writing custom script to convert markdown to html and/or working on web template systems like `jekyll/jekyll`, `gohugoio/hugo`, or similar web templating systems that utilize markdown documents, converting them to html. Use when asked to "convert markdown to html", "transform md to html", "render markdown", "generate html from markdown", or when working with .md files and/or web a templating system that converts markdown to HTML output. Supports CLI and Node.js workflows with GFM, CommonMark, and standard Markdown flavors. | `references/basic-markdown-to-html.md`
`references/basic-markdown.md`
`references/code-blocks-to-html.md`
`references/code-blocks.md`
`references/collapsed-sections-to-html.md`
`references/collapsed-sections.md`
`references/gomarkdown.md`
`references/hugo.md`
`references/jekyll.md`
`references/marked.md`
`references/pandoc.md`
`references/tables-to-html.md`
`references/tables.md`
`references/writing-mathematical-expressions-to-html.md`
`references/writing-mathematical-expressions.md` | | [mcp-cli](../skills/mcp-cli/SKILL.md) | Interface for MCP (Model Context Protocol) servers via CLI. Use when you need to interact with external tools, APIs, or data sources through MCP servers, list available MCP servers/tools, or call MCP tools from command line. | None | +| [mcp-configure](../skills/mcp-configure/SKILL.md) | Configure an MCP server for GitHub Copilot with your Dataverse environment. | None | +| [mcp-copilot-studio-server-generator](../skills/mcp-copilot-studio-server-generator/SKILL.md) | Generate a complete MCP server implementation optimized for Copilot Studio integration with proper schema constraints and streamable HTTP support | None | +| [mcp-create-adaptive-cards](../skills/mcp-create-adaptive-cards/SKILL.md) | Skill converted from mcp-create-adaptive-cards.prompt.md | None | +| [mcp-create-declarative-agent](../skills/mcp-create-declarative-agent/SKILL.md) | Skill converted from mcp-create-declarative-agent.prompt.md | None | +| [mcp-deploy-manage-agents](../skills/mcp-deploy-manage-agents/SKILL.md) | Skill converted from mcp-deploy-manage-agents.prompt.md | None | | [meeting-minutes](../skills/meeting-minutes/SKILL.md) | Generate concise, actionable meeting minutes for internal meetings. Includes metadata, attendees, agenda, decisions, action items (owner + due date), and follow-up steps. | None | +| [memory-merger](../skills/memory-merger/SKILL.md) | Merges mature lessons from a domain memory file into its instruction file. Syntax: `/memory-merger >domain [scope]` where scope is `global` (default), `user`, `workspace`, or `ws`. | None | | [microsoft-code-reference](../skills/microsoft-code-reference/SKILL.md) | Look up Microsoft API references, find working code samples, and verify SDK code is correct. Use when working with Azure SDKs, .NET libraries, or Microsoft APIsβ€”to find the right method, check parameters, get working examples, or troubleshoot errors. Catches hallucinated methods, wrong signatures, and deprecated patterns by querying official docs. | None | | [microsoft-docs](../skills/microsoft-docs/SKILL.md) | Query official Microsoft documentation to find concepts, tutorials, and code examples across Azure, .NET, Agent Framework, Aspire, VS Code, GitHub, and more. Uses Microsoft Learn MCP as the default, with Context7 and Aspire MCP for content that lives outside learn.microsoft.com. | None | | [microsoft-skill-creator](../skills/microsoft-skill-creator/SKILL.md) | Create agent skills for Microsoft technologies using Learn MCP tools. Use when users want to create a skill that teaches agents about any Microsoft technology, library, framework, or service (Azure, .NET, M365, VS Code, Bicep, etc.). Investigates topics deeply, then generates a hybrid skill storing essential knowledge locally while enabling dynamic deeper investigation. | `references/skill-templates.md` | +| [mkdocs-translations](../skills/mkdocs-translations/SKILL.md) | Generate a language translation for a mkdocs documentation stack. | None | +| [model-recommendation](../skills/model-recommendation/SKILL.md) | Analyze chatmode or prompt files and recommend optimal AI models based on task complexity, required capabilities, and cost-efficiency | None | +| [multi-stage-dockerfile](../skills/multi-stage-dockerfile/SKILL.md) | Create optimized multi-stage Dockerfiles for any language or framework | None | +| [my-issues](../skills/my-issues/SKILL.md) | List my issues in the current repository | None | +| [my-pull-requests](../skills/my-pull-requests/SKILL.md) | List my pull requests in the current repository | None | | [nano-banana-pro-openrouter](../skills/nano-banana-pro-openrouter/SKILL.md) | Generate or edit images via OpenRouter with the Gemini 3 Pro Image model. Use for prompt-only image generation, image edits, and multi-image compositing; supports 1K/2K/4K output. | `assets/SYSTEM_TEMPLATE`
`scripts/generate_image.py` | +| [next-intl-add-language](../skills/next-intl-add-language/SKILL.md) | Add new language to a Next.js + next-intl application | None | | [nuget-manager](../skills/nuget-manager/SKILL.md) | Manage NuGet packages in .NET projects/solutions. Use this skill when adding, removing, or updating NuGet package versions. It enforces using `dotnet` CLI for package management and provides strict procedures for direct file edits only when updating versions. | None | +| [openapi-to-application-code](../skills/openapi-to-application-code/SKILL.md) | Generate a complete, production-ready application from an OpenAPI specification | None | | [pdftk-server](../skills/pdftk-server/SKILL.md) | Skill for using the command-line tool pdftk (PDFtk Server) for working with PDF files. Use when asked to merge PDFs, split PDFs, rotate pages, encrypt or decrypt PDFs, fill PDF forms, apply watermarks, stamp overlays, extract metadata, burst documents into pages, repair corrupted PDFs, attach or extract files, or perform any PDF manipulation from the command line. | `references/download.md`
`references/pdftk-cli-examples.md`
`references/pdftk-man-page.md`
`references/pdftk-server-license.md`
`references/third-party-materials.md` | | [penpot-uiux-design](../skills/penpot-uiux-design/SKILL.md) | Comprehensive guide for creating professional UI/UX designs in Penpot using MCP tools. Use this skill when: (1) Creating new UI/UX designs for web, mobile, or desktop applications, (2) Building design systems with components and tokens, (3) Designing dashboards, forms, navigation, or landing pages, (4) Applying accessibility standards and best practices, (5) Following platform guidelines (iOS, Android, Material Design), (6) Reviewing or improving existing Penpot designs for usability. Triggers: "design a UI", "create interface", "build layout", "design dashboard", "create form", "design landing page", "make it accessible", "design system", "component library". | `references/accessibility.md`
`references/component-patterns.md`
`references/platform-guidelines.md`
`references/setup-troubleshooting.md` | +| [php-mcp-server-generator](../skills/php-mcp-server-generator/SKILL.md) | Generate a complete PHP Model Context Protocol server project with tools, resources, prompts, and tests using the official PHP SDK | None | | [plantuml-ascii](../skills/plantuml-ascii/SKILL.md) | Generate ASCII art diagrams using PlantUML text mode. Use when user asks to create ASCII diagrams, text-based diagrams, terminal-friendly diagrams, or mentions plantuml ascii, text diagram, ascii art diagram. Supports: Converting PlantUML diagrams to ASCII art, Creating sequence diagrams, class diagrams, flowcharts in ASCII format, Generating Unicode-enhanced ASCII art with -utxt flag | None | +| [playwright-automation-fill-in-form](../skills/playwright-automation-fill-in-form/SKILL.md) | Automate filling in a form using Playwright MCP | None | +| [playwright-explore-website](../skills/playwright-explore-website/SKILL.md) | Website exploration for testing using Playwright MCP | None | +| [playwright-generate-test](../skills/playwright-generate-test/SKILL.md) | Generate a Playwright test based on a scenario using Playwright MCP | None | | [polyglot-test-agent](../skills/polyglot-test-agent/SKILL.md) | Generates comprehensive, workable unit tests for any programming language using a multi-agent pipeline. Use when asked to generate tests, write unit tests, improve test coverage, add test coverage, create test files, or test a codebase. Supports C#, TypeScript, JavaScript, Python, Go, Rust, Java, and more. Orchestrates research, planning, and implementation phases to produce tests that compile, pass, and follow project conventions. | `unit-test-generation.prompt.md` | +| [postgresql-code-review](../skills/postgresql-code-review/SKILL.md) | PostgreSQL-specific code review assistant focusing on PostgreSQL best practices, anti-patterns, and unique quality standards. Covers JSONB operations, array usage, custom types, schema design, function optimization, and PostgreSQL-exclusive security features like Row Level Security (RLS). | None | +| [postgresql-optimization](../skills/postgresql-optimization/SKILL.md) | PostgreSQL-specific development assistant focusing on unique PostgreSQL features, advanced data types, and PostgreSQL-exclusive capabilities. Covers JSONB operations, array types, custom types, range/geometric types, full-text search, window functions, and PostgreSQL extensions ecosystem. | None | +| [power-apps-code-app-scaffold](../skills/power-apps-code-app-scaffold/SKILL.md) | Scaffold a complete Power Apps Code App project with PAC CLI setup, SDK integration, and connector configuration | None | +| [power-bi-dax-optimization](../skills/power-bi-dax-optimization/SKILL.md) | Comprehensive Power BI DAX formula optimization prompt for improving performance, readability, and maintainability of DAX calculations. | None | +| [power-bi-model-design-review](../skills/power-bi-model-design-review/SKILL.md) | Comprehensive Power BI data model design review prompt for evaluating model architecture, relationships, and optimization opportunities. | None | +| [power-bi-performance-troubleshooting](../skills/power-bi-performance-troubleshooting/SKILL.md) | Systematic Power BI performance troubleshooting prompt for identifying, diagnosing, and resolving performance issues in Power BI models, reports, and queries. | None | +| [power-bi-report-design-consultation](../skills/power-bi-report-design-consultation/SKILL.md) | Power BI report visualization design prompt for creating effective, user-friendly, and accessible reports with optimal chart selection and layout design. | None | +| [power-platform-mcp-connector-suite](../skills/power-platform-mcp-connector-suite/SKILL.md) | Generate complete Power Platform custom connector with MCP integration for Copilot Studio - includes schema generation, troubleshooting, and validation | None | | [powerbi-modeling](../skills/powerbi-modeling/SKILL.md) | Power BI semantic modeling assistant for building optimized data models. Use when working with Power BI semantic models, creating measures, designing star schemas, configuring relationships, implementing RLS, or optimizing model performance. Triggers on queries about DAX calculations, table relationships, dimension/fact table design, naming conventions, model documentation, cardinality, cross-filter direction, calculation groups, and data model best practices. Always connects to the active model first using power-bi-modeling MCP tools to understand the data structure before providing guidance. | `references/MEASURES-DAX.md`
`references/PERFORMANCE.md`
`references/RELATIONSHIPS.md`
`references/RLS.md`
`references/STAR-SCHEMA.md` | | [prd](../skills/prd/SKILL.md) | Generate high-quality Product Requirements Documents (PRDs) for software systems and AI-powered features. Includes executive summaries, user stories, technical specifications, and risk analysis. | None | +| [project-workflow-analysis-blueprint-generator](../skills/project-workflow-analysis-blueprint-generator/SKILL.md) | Comprehensive technology-agnostic prompt generator for documenting end-to-end application workflows. Automatically detects project architecture patterns, technology stacks, and data flow patterns to generate detailed implementation blueprints covering entry points, service layers, data access, error handling, and testing approaches across multiple technologies including .NET, Java/Spring, React, and microservices architectures. | None | +| [prompt-builder](../skills/prompt-builder/SKILL.md) | Guide users through creating high-quality GitHub Copilot prompts with proper structure, tools, and best practices. | None | +| [pytest-coverage](../skills/pytest-coverage/SKILL.md) | Run pytest tests with coverage, discover lines missing coverage, and increase coverage to 100%. | None | +| [python-mcp-server-generator](../skills/python-mcp-server-generator/SKILL.md) | Generate a complete MCP server project in Python with tools, resources, and proper configuration | None | | [quasi-coder](../skills/quasi-coder/SKILL.md) | Expert 10x engineer skill for interpreting and implementing code from shorthand, quasi-code, and natural language descriptions. Use when collaborators provide incomplete code snippets, pseudo-code, or descriptions with potential typos or incorrect terminology. Excels at translating non-technical or semi-technical descriptions into production-quality code. | None | +| [readme-blueprint-generator](../skills/readme-blueprint-generator/SKILL.md) | Intelligent README.md generation prompt that analyzes project documentation structure and creates comprehensive repository documentation. Scans .github/copilot directory files and copilot-instructions.md to extract project information, technology stack, architecture, development workflow, coding standards, and testing approaches while generating well-structured markdown documentation with proper formatting, cross-references, and developer-focused content. | None | | [refactor](../skills/refactor/SKILL.md) | Surgical code refactoring to improve maintainability without changing behavior. Covers extracting functions, renaming variables, breaking down god functions, improving type safety, eliminating code smells, and applying design patterns. Less drastic than repo-rebuilder; use for gradual improvements. | None | +| [refactor-method-complexity-reduce](../skills/refactor-method-complexity-reduce/SKILL.md) | Refactor given method `${input:methodName}` to reduce its cognitive complexity to `${input:complexityThreshold}` or below, by extracting helper methods. | None | +| [refactor-plan](../skills/refactor-plan/SKILL.md) | Plan a multi-file refactor with proper sequencing and rollback steps | None | +| [remember](../skills/remember/SKILL.md) | Transforms lessons learned into domain-organized memory instructions (global or workspace). Syntax: `/remember [>domain [scope]] lesson clue` where scope is `global` (default), `user`, `workspace`, or `ws`. | None | +| [remember-interactive-programming](../skills/remember-interactive-programming/SKILL.md) | A micro-prompt that reminds the agent that it is an interactive programmer. Works great in Clojure when Copilot has access to the REPL (probably via Backseat Driver). Will work with any system that has a live REPL that the agent can use. Adapt the prompt with any specific reminders in your workflow and/or workspace. | None | +| [repo-story-time](../skills/repo-story-time/SKILL.md) | Generate a comprehensive repository summary and narrative story from commit history | None | +| [review-and-refactor](../skills/review-and-refactor/SKILL.md) | Review and refactor code in your project according to defined instructions | None | +| [ruby-mcp-server-generator](../skills/ruby-mcp-server-generator/SKILL.md) | Generate a complete Model Context Protocol server project in Ruby using the official MCP Ruby SDK gem. | None | +| [rust-mcp-server-generator](../skills/rust-mcp-server-generator/SKILL.md) | Generate a complete Rust Model Context Protocol server project with tools, prompts, resources, and tests using the official rmcp SDK | None | | [scoutqa-test](../skills/scoutqa-test/SKILL.md) | This skill should be used when the user asks to "test this website", "run exploratory testing", "check for accessibility issues", "verify the login flow works", "find bugs on this page", or requests automated QA testing. Triggers on web application testing scenarios including smoke tests, accessibility audits, e-commerce flows, and user flow validation using ScoutQA CLI. IMPORTANT: Use this skill proactively after implementing web application features to verify they work correctly - don't wait for the user to ask for testing. | None | +| [shuffle-json-data](../skills/shuffle-json-data/SKILL.md) | Shuffle repetitive JSON objects safely by validating schema consistency before randomising entries. | None | | [snowflake-semanticview](../skills/snowflake-semanticview/SKILL.md) | Create, alter, and validate Snowflake semantic views using Snowflake CLI (snow). Use when asked to build or troubleshoot semantic views/semantic layer definitions with CREATE/ALTER SEMANTIC VIEW, to validate semantic-view DDL against Snowflake via CLI, or to guide Snowflake CLI installation and connection setup. | None | | [sponsor-finder](../skills/sponsor-finder/SKILL.md) | Find which of a GitHub repository's dependencies are sponsorable via GitHub Sponsors. Uses deps.dev API for dependency resolution across npm, PyPI, Cargo, Go, RubyGems, Maven, and NuGet. Checks npm funding metadata, FUNDING.yml files, and web search. Verifies every link. Shows direct and transitive dependencies with OSSF Scorecard health data. Invoke with /sponsor followed by a GitHub owner/repo (e.g. "/sponsor expressjs/express"). | None | +| [sql-code-review](../skills/sql-code-review/SKILL.md) | Universal SQL code review assistant that performs comprehensive security, maintainability, and code quality analysis across all SQL databases (MySQL, PostgreSQL, SQL Server, Oracle). Focuses on SQL injection prevention, access control, code standards, and anti-pattern detection. Complements SQL optimization prompt for complete development coverage. | None | +| [sql-optimization](../skills/sql-optimization/SKILL.md) | Universal SQL performance optimization assistant for comprehensive query tuning, indexing strategies, and database performance analysis across all SQL databases (MySQL, PostgreSQL, SQL Server, Oracle). Provides execution plan analysis, pagination optimization, batch operations, and performance monitoring guidance. | None | +| [structured-autonomy-generate](../skills/structured-autonomy-generate/SKILL.md) | Structured Autonomy Implementation Generator Prompt | None | +| [structured-autonomy-implement](../skills/structured-autonomy-implement/SKILL.md) | Structured Autonomy Implementation Prompt | None | +| [structured-autonomy-plan](../skills/structured-autonomy-plan/SKILL.md) | Structured Autonomy Planning Prompt | None | +| [suggest-awesome-github-copilot-agents](../skills/suggest-awesome-github-copilot-agents/SKILL.md) | Suggest relevant GitHub Copilot Custom Agents files from the awesome-copilot repository based on current repository context and chat history, avoiding duplicates with existing custom agents in this repository, and identifying outdated agents that need updates. | None | +| [suggest-awesome-github-copilot-instructions](../skills/suggest-awesome-github-copilot-instructions/SKILL.md) | Suggest relevant GitHub Copilot instruction files from the awesome-copilot repository based on current repository context and chat history, avoiding duplicates with existing instructions in this repository, and identifying outdated instructions that need updates. | None | +| [suggest-awesome-github-copilot-prompts](../skills/suggest-awesome-github-copilot-prompts/SKILL.md) | Suggest relevant GitHub Copilot prompt files from the awesome-copilot repository based on current repository context and chat history, avoiding duplicates with existing prompts in this repository, and identifying outdated prompts that need updates. | None | +| [suggest-awesome-github-copilot-skills](../skills/suggest-awesome-github-copilot-skills/SKILL.md) | Suggest relevant GitHub Copilot skills from the awesome-copilot repository based on current repository context and chat history, avoiding duplicates with existing skills in this repository, and identifying outdated skills that need updates. | None | +| [swift-mcp-server-generator](../skills/swift-mcp-server-generator/SKILL.md) | Generate a complete Model Context Protocol server project in Swift using the official MCP Swift SDK package. | None | +| [technology-stack-blueprint-generator](../skills/technology-stack-blueprint-generator/SKILL.md) | Comprehensive technology stack blueprint generator that analyzes codebases to create detailed architectural documentation. Automatically detects technology stacks, programming languages, and implementation patterns across multiple platforms (.NET, Java, JavaScript, React, Python). Generates configurable blueprints with version information, licensing details, usage patterns, coding conventions, and visual diagrams. Provides implementation-ready templates and maintains architectural consistency for guided development. | None | | [terraform-azurerm-set-diff-analyzer](../skills/terraform-azurerm-set-diff-analyzer/SKILL.md) | Analyze Terraform plan JSON output for AzureRM Provider to distinguish between false-positive diffs (order-only changes in Set-type attributes) and actual resource changes. Use when reviewing terraform plan output for Azure resources like Application Gateway, Load Balancer, Firewall, Front Door, NSG, and other resources with Set-type attributes that cause spurious diffs due to internal ordering changes. | `references/azurerm_set_attributes.json`
`references/azurerm_set_attributes.md`
`scripts/.gitignore`
`scripts/README.md`
`scripts/analyze_plan.py` | +| [tldr-prompt](../skills/tldr-prompt/SKILL.md) | Create tldr summaries for GitHub Copilot files (prompts, agents, instructions, collections), MCP servers, or documentation from URLs and queries. | None | | [transloadit-media-processing](../skills/transloadit-media-processing/SKILL.md) | Process media files (video, audio, images, documents) using Transloadit. Use when asked to encode video to HLS/MP4, generate thumbnails, resize or watermark images, extract audio, concatenate clips, add subtitles, OCR documents, or run any media processing pipeline. Covers 86+ processing robots for file transformation at scale. | None | +| [typescript-mcp-server-generator](../skills/typescript-mcp-server-generator/SKILL.md) | Generate a complete MCP server project in TypeScript with tools, resources, and proper configuration | None | +| [typespec-api-operations](../skills/typespec-api-operations/SKILL.md) | Add GET, POST, PATCH, and DELETE operations to a TypeSpec API plugin with proper routing, parameters, and adaptive cards | None | +| [typespec-create-agent](../skills/typespec-create-agent/SKILL.md) | Generate a complete TypeSpec declarative agent with instructions, capabilities, and conversation starters for Microsoft 365 Copilot | None | +| [typespec-create-api-plugin](../skills/typespec-create-api-plugin/SKILL.md) | Generate a TypeSpec API plugin with REST operations, authentication, and Adaptive Cards for Microsoft 365 Copilot | None | +| [update-avm-modules-in-bicep](../skills/update-avm-modules-in-bicep/SKILL.md) | Update Azure Verified Modules (AVM) to latest versions in Bicep files. | None | +| [update-implementation-plan](../skills/update-implementation-plan/SKILL.md) | Update an existing implementation plan file with new or update requirements to provide new features, refactoring existing code or upgrading packages, design, architecture or infrastructure. | None | +| [update-llms](../skills/update-llms/SKILL.md) | Update the llms.txt file in the root folder to reflect changes in documentation or specifications following the llms.txt specification at https://llmstxt.org/ | None | +| [update-markdown-file-index](../skills/update-markdown-file-index/SKILL.md) | Update a markdown file section with an index/table of files from a specified folder. | None | +| [update-oo-component-documentation](../skills/update-oo-component-documentation/SKILL.md) | Update existing object-oriented component documentation following industry best practices and architectural documentation standards. | None | +| [update-specification](../skills/update-specification/SKILL.md) | Update an existing specification file for the solution, optimized for Generative AI consumption based on new requirements or updates to any existing code. | None | | [vscode-ext-commands](../skills/vscode-ext-commands/SKILL.md) | Guidelines for contributing commands in VS Code extensions. Indicates naming convention, visibility, localization and other relevant attributes, following VS Code extension development guidelines, libraries and good practices | None | | [vscode-ext-localization](../skills/vscode-ext-localization/SKILL.md) | Guidelines for proper localization of VS Code extensions, following VS Code extension development guidelines, libraries and good practices | None | | [web-design-reviewer](../skills/web-design-reviewer/SKILL.md) | This skill enables visual inspection of websites running locally or remotely to identify and fix design issues. Triggers on requests like "review website design", "check the UI", "fix the layout", "find design problems". Detects issues with responsive design, accessibility, visual consistency, and layout breakage, then performs fixes at the source code level. | `references/framework-fixes.md`
`references/visual-checklist.md` | | [webapp-testing](../skills/webapp-testing/SKILL.md) | Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs. | `test-helper.js` | +| [what-context-needed](../skills/what-context-needed/SKILL.md) | Ask Copilot what files it needs to see before answering a question | None | | [winapp-cli](../skills/winapp-cli/SKILL.md) | Windows App Development CLI (winapp) for building, packaging, and deploying Windows applications. Use when asked to initialize Windows app projects, create MSIX packages, generate AppxManifest.xml, manage development certificates, add package identity for debugging, sign packages, or access Windows SDK build tools. Supports .NET, C++, Electron, Rust, Tauri, and cross-platform frameworks targeting Windows. | None | | [workiq-copilot](../skills/workiq-copilot/SKILL.md) | Guides the Copilot CLI on how to use the WorkIQ CLI/MCP server to query Microsoft 365 Copilot data (emails, meetings, docs, Teams, people) for live context, summaries, and recommendations. | None | +| [write-coding-standards-from-file](../skills/write-coding-standards-from-file/SKILL.md) | Write a coding standards document for a project using the coding styles from the file(s) and/or folder(s) passed as arguments in the prompt. | None | diff --git a/docs/README.workflows.md b/docs/README.workflows.md index 93bdfdca4..02394afe6 100644 --- a/docs/README.workflows.md +++ b/docs/README.workflows.md @@ -2,6 +2,10 @@ [Agentic Workflows](https://github.github.com/gh-aw) are AI-powered repository automations that run coding agents in GitHub Actions. Defined in markdown with natural language instructions, they enable event-triggered and scheduled automation with built-in guardrails and security-first design. +### How to Contribute + +See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-agentic-workflows) for guidelines on how to contribute new workflows, improve existing ones, and share your use cases. + ### How to Use Agentic Workflows **What's Included:** @@ -28,4 +32,26 @@ - Respond to slash commands in issues and PRs - Orchestrate multi-step repository automation -_No entries found yet._ \ No newline at end of file +| Name | Description | Triggers | +| ---- | ----------- | -------- | +<<<<<<< HEAD +<<<<<<< HEAD +<<<<<<< HEAD +| [Daily Issues Report](../workflows/daily-issues-report.md) | Generates a daily summary of open issues and recent activity as a GitHub issue | schedule | +======= +| [Contributors Report](../workflows/ospo-contributors-report.md) | Monthly contributor activity metrics across an organization's repositories. | schedule, workflow_dispatch | +| [OSS Release Compliance Checker](../workflows/ospo-release-compliance-checker.md) | Analyzes a target repository against open source release requirements and posts a detailed compliance report as an issue comment. | issues, workflow_dispatch | +| [Stale Repository Report](../workflows/ospo-stale-repos.md) | Identifies inactive repositories in your organization and generates an archival recommendation report. | schedule, workflow_dispatch | +| [Weekly Organization Health Report](../workflows/ospo-org-health.md) | Comprehensive weekly health report for a GitHub organization. Surfaces stale issues/PRs, merge time analysis, contributor leaderboards, and actionable items needing human attention. | schedule, workflow_dispatch | +>>>>>>> d81ee5e (feat: add OSPO agentic workflow examples) +======= +======= +>>>>>>> b222cdd5c41ca97dff0ee7531ee6592d91662c90 +| [OSPO Contributors Report](../workflows/ospo-contributors-report.md) | Monthly contributor activity metrics across an organization's repositories. | schedule, workflow_dispatch | +| [OSPO Organization Health Report](../workflows/ospo-org-health.md) | Comprehensive weekly health report for a GitHub organization. Surfaces stale issues/PRs, merge time analysis, contributor leaderboards, and actionable items needing human attention. | schedule, workflow_dispatch | +| [OSPO Stale Repository Report](../workflows/ospo-stale-repos.md) | Identifies inactive repositories in your organization and generates an archival recommendation report. | schedule, workflow_dispatch | +| [OSS Release Compliance Checker](../workflows/ospo-release-compliance-checker.md) | Analyzes a target repository against open source release requirements and posts a detailed compliance report as an issue comment. | issues, workflow_dispatch | +<<<<<<< HEAD +>>>>>>> da2da6e (chore: add OSPO prefix to workflow names for discoverability) +======= +>>>>>>> b222cdd5c41ca97dff0ee7531ee6592d91662c90 diff --git a/eng/constants.mjs b/eng/constants.mjs index 6736c243b..50f85cb8b 100644 --- a/eng/constants.mjs +++ b/eng/constants.mjs @@ -10,7 +10,11 @@ const TEMPLATES = { Team and project-specific instructions to enhance GitHub Copilot's behavior for specific technologies and coding practices.`, - instructionsUsage: `### How to Use Custom Instructions + instructionsUsage: `### How to Contribute + +See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-instructions) for guidelines on how to contribute new instructions, improve existing ones, and share your use cases. + +### How to Use Custom Instructions **To Install:** - Click the **VS Code** or **VS Code Insiders** install button for the instruction you want to use @@ -21,31 +25,20 @@ Team and project-specific instructions to enhance GitHub Copilot's behavior for - Create task-specific \`*.instructions.md\` files in your workspace's \`.github/instructions/\` folder (e.g., \`.github/instructions/my-csharp-rules.instructions.md\`) - Instructions automatically apply to Copilot behavior once installed in your workspace`, - promptsSection: `## 🎯 Reusable Prompts - -Ready-to-use prompt templates for specific development scenarios and tasks, defining prompt text with a specific mode, model, and available set of tools.`, - - promptsUsage: `### How to Use Reusable Prompts - -**To Install:** -- Click the **VS Code** or **VS Code Insiders** install button for the prompt you want to use -- Download the \`*.prompt.md\` file and manually add it to your prompt collection + pluginsSection: `## πŸ”Œ Plugins -**To Run/Execute:** -- Use \`/prompt-name\` in VS Code chat after installation -- Run the \`Chat: Run Prompt\` command from the Command Palette -- Hit the run button while you have a prompt file open in VS Code`, +Curated plugins of related agents and skills organized around specific themes, workflows, or use cases. Plugins can be installed directly via GitHub Copilot CLI.`, - pluginsSection: `## πŸ”Œ Plugins + pluginsUsage: `### How to Contribute -Curated plugins of related prompts, agents, and skills organized around specific themes, workflows, or use cases. Plugins can be installed directly via GitHub Copilot CLI.`, +See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-plugins) for guidelines on how to contribute new plugins, improve existing ones, and share your use cases. - pluginsUsage: `### How to Use Plugins +### How to Use Plugins **Browse Plugins:** - ⭐ Featured plugins are highlighted and appear at the top of the list - Explore themed plugins that group related customizations -- Each plugin includes prompts, agents, and skills for specific workflows +- Each plugin includes agents and skills for specific workflows - Plugins make it easy to adopt comprehensive toolkits for particular scenarios **Install Plugins:** @@ -55,13 +48,17 @@ Curated plugins of related prompts, agents, and skills organized around specific featuredPluginsSection: `## 🌟 Featured Plugins -Discover our curated plugins of prompts, agents, and skills organized around specific themes and workflows.`, +Discover our curated plugins of agents and skills organized around specific themes and workflows.`, agentsSection: `## πŸ€– Custom Agents Custom agents for GitHub Copilot, making it easy for users and organizations to "specialize" their Copilot coding agent (CCA) through simple file-based configuration.`, - agentsUsage: `### How to Use Custom Agents + agentsUsage: `### How to Contribute + +See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-agents) for guidelines on how to contribute new agents, improve existing ones, and share your use cases. + +### How to Use Custom Agents **To Install:** - Click the **VS Code** or **VS Code Insiders** install button for the agent you want to use @@ -83,7 +80,11 @@ Agent Skills are self-contained folders with instructions and bundled resources Skills differ from other primitives by supporting bundled assets (scripts, code samples, reference data) that agents can utilize when performing specialized tasks.`, - skillsUsage: `### How to Use Agent Skills + skillsUsage: `### How to Contribute + +See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to contribute new agent skills, improve existing ones, and share your use cases. + +### How to Use Agent Skills **What's Included:** - Each skill is a folder containing a \`SKILL.md\` instruction file @@ -104,7 +105,11 @@ Skills differ from other primitives by supporting bundled assets (scripts, code Hooks enable automated workflows triggered by specific events during GitHub Copilot coding agent sessions, such as session start, session end, user prompts, and tool usage.`, - hooksUsage: `### How to Use Hooks + hooksUsage: `### How to Contribute + +See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-hooks) for guidelines on how to contribute new hooks, improve existing ones, and share your use cases. + +### How to Use Hooks **What's Included:** - Each hook is a folder containing a \`README.md\` file and a \`hooks.json\` configuration @@ -132,7 +137,11 @@ Hooks enable automated workflows triggered by specific events during GitHub Copi [Agentic Workflows](https://github.github.com/gh-aw) are AI-powered repository automations that run coding agents in GitHub Actions. Defined in markdown with natural language instructions, they enable event-triggered and scheduled automation with built-in guardrails and security-first design.`, - workflowsUsage: `### How to Use Agentic Workflows + workflowsUsage: `### How to Contribute + +See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-agentic-workflows) for guidelines on how to contribute new workflows, improve existing ones, and share your use cases. + +### How to Use Agentic Workflows **What's Included:** - Each workflow is a single \`.md\` file with YAML frontmatter and natural language instructions @@ -170,14 +179,12 @@ const repoBaseUrl = const AKA_INSTALL_URLS = { instructions: "https://aka.ms/awesome-copilot/install/instructions", - prompt: "https://aka.ms/awesome-copilot/install/prompt", agent: "https://aka.ms/awesome-copilot/install/agent", hook: "https://aka.ms/awesome-copilot/install/hook", }; const ROOT_FOLDER = path.join(__dirname, ".."); const INSTRUCTIONS_DIR = path.join(ROOT_FOLDER, "instructions"); -const PROMPTS_DIR = path.join(ROOT_FOLDER, "prompts"); const AGENTS_DIR = path.join(ROOT_FOLDER, "agents"); const SKILLS_DIR = path.join(ROOT_FOLDER, "skills"); const HOOKS_DIR = path.join(ROOT_FOLDER, "hooks"); @@ -197,13 +204,12 @@ const DOCS_DIR = path.join(ROOT_FOLDER, "docs"); export { AGENTS_DIR, AKA_INSTALL_URLS, - PLUGINS_DIR, COOKBOOK_DIR, DOCS_DIR, HOOKS_DIR, INSTRUCTIONS_DIR, MAX_PLUGIN_ITEMS, - PROMPTS_DIR, + PLUGINS_DIR, repoBaseUrl, ROOT_FOLDER, SKILL_DESCRIPTION_MAX_LENGTH, @@ -214,6 +220,5 @@ export { TEMPLATES, vscodeInsidersInstallImage, vscodeInstallImage, - WORKFLOWS_DIR + WORKFLOWS_DIR, }; - diff --git a/eng/contributor-report.mjs b/eng/contributor-report.mjs index fb983be6d..01944ad9b 100644 --- a/eng/contributor-report.mjs +++ b/eng/contributor-report.mjs @@ -30,9 +30,6 @@ export const TYPE_PATTERNS = { instructions: [ 'instructions/*.instructions.md' ], - prompts: [ - 'prompts/*.prompt.md' - ], agents: [ 'chatmodes/*.chatmode.md', 'agents/*.agent.md' @@ -140,7 +137,7 @@ export const isAutoGeneratedFile = (filePath) => { }; /** - * Infer a contribution type string (e.g. 'prompts', 'agents', 'doc') for a file path. + * Infer a contribution type string (e.g. 'skills', 'agents', 'doc') for a file path. * Returns null if no specific type matched. * @param {string} filePath * @returns {string|null} diff --git a/eng/generate-website-data.mjs b/eng/generate-website-data.mjs index 9eb3da00c..9b145bd5b 100644 --- a/eng/generate-website-data.mjs +++ b/eng/generate-website-data.mjs @@ -2,7 +2,7 @@ /** * Generate JSON metadata files for the GitHub Pages website. - * This script extracts metadata from agents, prompts, instructions, skills, and plugins + * This script extracts metadata from agents, instructions, skills, hooks, and plugins * and writes them to website/data/ for client-side search and display. */ @@ -10,23 +10,22 @@ import fs from "fs"; import path from "path"; import { fileURLToPath } from "url"; import { - AGENTS_DIR, - COOKBOOK_DIR, - HOOKS_DIR, - INSTRUCTIONS_DIR, - PLUGINS_DIR, - PROMPTS_DIR, - ROOT_FOLDER, - SKILLS_DIR, - WORKFLOWS_DIR + AGENTS_DIR, + COOKBOOK_DIR, + HOOKS_DIR, + INSTRUCTIONS_DIR, + PLUGINS_DIR, + ROOT_FOLDER, + SKILLS_DIR, + WORKFLOWS_DIR, } from "./constants.mjs"; import { getGitFileDates } from "./utils/git-dates.mjs"; import { - parseFrontmatter, - parseSkillMetadata, - parseHookMetadata, - parseWorkflowMetadata, - parseYamlFile, + parseFrontmatter, + parseHookMetadata, + parseSkillMetadata, + parseWorkflowMetadata, + parseYamlFile, } from "./yaml-parser.mjs"; const __filename = fileURLToPath(import.meta.url); @@ -133,7 +132,7 @@ function generateAgentsData(gitDates) { */ function generateHooksData(gitDates) { const hooks = []; - + // Check if hooks directory exists if (!fs.existsSync(HOOKS_DIR)) { return { @@ -205,7 +204,6 @@ function generateWorkflowsData(gitDates) { items: workflows, filters: { triggers: [], - tags: [], }, }; } @@ -215,7 +213,6 @@ function generateWorkflowsData(gitDates) { }); const allTriggers = new Set(); - const allTags = new Set(); for (const file of workflowFiles) { const filePath = path.join(WORKFLOWS_DIR, file); @@ -227,7 +224,6 @@ function generateWorkflowsData(gitDates) { .replace(/\\/g, "/"); (metadata.triggers || []).forEach((t) => allTriggers.add(t)); - (metadata.tags || []).forEach((t) => allTags.add(t)); const id = path.basename(file, ".md"); workflows.push({ @@ -235,64 +231,19 @@ function generateWorkflowsData(gitDates) { title: metadata.name, description: metadata.description, triggers: metadata.triggers || [], - tags: metadata.tags || [], path: relativePath, lastUpdated: gitDates.get(relativePath) || null, }); } - const sortedWorkflows = workflows.sort((a, b) => a.title.localeCompare(b.title)); + const sortedWorkflows = workflows.sort((a, b) => + a.title.localeCompare(b.title) + ); return { items: sortedWorkflows, filters: { triggers: Array.from(allTriggers).sort(), - tags: Array.from(allTags).sort(), - }, - }; -} - -/** - * Generate prompts metadata - */ -function generatePromptsData(gitDates) { - const prompts = []; - const files = fs - .readdirSync(PROMPTS_DIR) - .filter((f) => f.endsWith(".prompt.md")); - - // Track all unique tools for filters - const allTools = new Set(); - - for (const file of files) { - const filePath = path.join(PROMPTS_DIR, file); - const frontmatter = parseFrontmatter(filePath); - const relativePath = path - .relative(ROOT_FOLDER, filePath) - .replace(/\\/g, "/"); - - const tools = frontmatter?.tools || []; - tools.forEach((t) => allTools.add(t)); - - prompts.push({ - id: file.replace(".prompt.md", ""), - title: extractTitle(filePath, frontmatter), - description: frontmatter?.description || "", - agent: frontmatter?.agent || null, - model: frontmatter?.model || null, - tools: tools, - path: relativePath, - filename: file, - lastUpdated: gitDates.get(relativePath) || null, - }); - } - - const sortedPrompts = prompts.sort((a, b) => a.title.localeCompare(b.title)); - - return { - items: sortedPrompts, - filters: { - tools: Array.from(allTools).sort(), }, }; } @@ -551,8 +502,9 @@ function generatePluginsData(gitDates) { return { items: [], filters: { tags: [] } }; } - const pluginDirs = fs.readdirSync(PLUGINS_DIR, { withFileTypes: true }) - .filter(d => d.isDirectory()); + const pluginDirs = fs + .readdirSync(PLUGINS_DIR, { withFileTypes: true }) + .filter((d) => d.isDirectory()); for (const dir of pluginDirs) { const pluginDir = path.join(PLUGINS_DIR, dir.name); @@ -567,9 +519,9 @@ function generatePluginsData(gitDates) { // Build items list from spec fields (agents, commands, skills) const items = [ - ...(data.agents || []).map(p => ({ kind: "agent", path: p })), - ...(data.commands || []).map(p => ({ kind: "prompt", path: p })), - ...(data.skills || []).map(p => ({ kind: "skill", path: p })), + ...(data.agents || []).map((p) => ({ kind: "agent", path: p })), + ...(data.commands || []).map((p) => ({ kind: "prompt", path: p })), + ...(data.skills || []).map((p) => ({ kind: "skill", path: p })), ]; const tags = data.keywords || data.tags || []; @@ -583,7 +535,9 @@ function generatePluginsData(gitDates) { itemCount: items.length, items: items, lastUpdated: dates.lastModified || null, - searchText: `${data.name || dir.name} ${data.description || ""} ${tags.join(" ")}`.toLowerCase(), + searchText: `${data.name || dir.name} ${ + data.description || "" + } ${tags.join(" ")}`.toLowerCase(), }); } catch (e) { console.warn(`Failed to parse plugin: ${dir.name}`, e.message); @@ -591,13 +545,13 @@ function generatePluginsData(gitDates) { } // Collect all unique tags - const allTags = [...new Set(plugins.flatMap(p => p.tags))].sort(); + const allTags = [...new Set(plugins.flatMap((p) => p.tags))].sort(); const sortedPlugins = plugins.sort((a, b) => a.name.localeCompare(b.name)); return { items: sortedPlugins, - filters: { tags: allTags } + filters: { tags: allTags }, }; } @@ -663,7 +617,6 @@ function generateToolsData() { */ function generateSearchIndex( agents, - prompts, instructions, hooks, workflows, @@ -686,18 +639,6 @@ function generateSearchIndex( }); } - for (const prompt of prompts) { - index.push({ - type: "prompt", - id: prompt.id, - title: prompt.title, - description: prompt.description, - path: prompt.path, - lastUpdated: prompt.lastUpdated, - searchText: `${prompt.title} ${prompt.description}`.toLowerCase(), - }); - } - for (const instruction of instructions) { index.push({ type: "instruction", @@ -734,9 +675,9 @@ function generateSearchIndex( description: workflow.description, path: workflow.path, lastUpdated: workflow.lastUpdated, - searchText: `${workflow.title} ${workflow.description} ${workflow.triggers.join( - " " - )} ${workflow.tags.join(" ")}`.toLowerCase(), + searchText: `${workflow.title} ${ + workflow.description + } ${workflow.triggers.join(" ")}`.toLowerCase(), }); } @@ -874,7 +815,7 @@ async function main() { // Load git dates for all resource files (single efficient git command) console.log("Loading git history for last updated dates..."); const gitDates = getGitFileDates( - ["agents/", "prompts/", "instructions/", "hooks/", "workflows/", "skills/", "plugins/"], + ["agents/", "instructions/", "hooks/", "workflows/", "skills/", "plugins/"], ROOT_FOLDER ); console.log(`βœ“ Loaded dates for ${gitDates.size} files\n`); @@ -895,13 +836,7 @@ async function main() { const workflowsData = generateWorkflowsData(gitDates); const workflows = workflowsData.items; console.log( - `βœ“ Generated ${workflows.length} workflows (${workflowsData.filters.triggers.length} triggers, ${workflowsData.filters.tags.length} tags)` - ); - - const promptsData = generatePromptsData(gitDates); - const prompts = promptsData.items; - console.log( - `βœ“ Generated ${prompts.length} prompts (${promptsData.filters.tools.length} tools)` + `βœ“ Generated ${workflows.length} workflows (${workflowsData.filters.triggers.length} triggers)` ); const instructionsData = generateInstructionsData(gitDates); @@ -935,7 +870,6 @@ async function main() { const searchIndex = generateSearchIndex( agents, - prompts, instructions, hooks, workflows, @@ -960,11 +894,6 @@ async function main() { JSON.stringify(workflowsData, null, 2) ); - fs.writeFileSync( - path.join(WEBSITE_DATA_DIR, "prompts.json"), - JSON.stringify(promptsData, null, 2) - ); - fs.writeFileSync( path.join(WEBSITE_DATA_DIR, "instructions.json"), JSON.stringify(instructionsData, null, 2) @@ -1000,7 +929,6 @@ async function main() { generated: new Date().toISOString(), counts: { agents: agents.length, - prompts: prompts.length, instructions: instructions.length, skills: skills.length, hooks: hooks.length, diff --git a/eng/materialize-plugins.mjs b/eng/materialize-plugins.mjs index 44b905108..6bed0902d 100644 --- a/eng/materialize-plugins.mjs +++ b/eng/materialize-plugins.mjs @@ -26,7 +26,6 @@ function copyDirRecursive(src, dest) { * Resolve a plugin-relative path to the repo-root source file. * * ./agents/foo.md β†’ ROOT/agents/foo.agent.md - * ./commands/bar.md β†’ ROOT/prompts/bar.prompt.md * ./skills/baz/ β†’ ROOT/skills/baz/ */ function resolveSource(relPath) { @@ -34,9 +33,6 @@ function resolveSource(relPath) { if (relPath.startsWith("./agents/")) { return path.join(ROOT_FOLDER, "agents", `${basename}.agent.md`); } - if (relPath.startsWith("./commands/")) { - return path.join(ROOT_FOLDER, "prompts", `${basename}.prompt.md`); - } if (relPath.startsWith("./skills/")) { // Strip trailing slash and get the skill folder name const skillName = relPath.replace(/^\.\/skills\//, "").replace(/\/$/, ""); @@ -59,7 +55,6 @@ function materializePlugins() { .sort(); let totalAgents = 0; - let totalCommands = 0; let totalSkills = 0; let warnings = 0; let errors = 0; @@ -104,27 +99,6 @@ function materializePlugins() { } } - // Process commands - if (Array.isArray(metadata.commands)) { - for (const relPath of metadata.commands) { - const src = resolveSource(relPath); - if (!src) { - console.warn(` ⚠ ${pluginName}: Unknown path format: ${relPath}`); - warnings++; - continue; - } - if (!fs.existsSync(src)) { - console.warn(` ⚠ ${pluginName}: Source not found: ${src}`); - warnings++; - continue; - } - const dest = path.join(pluginPath, relPath.replace(/^\.\//, "")); - fs.mkdirSync(path.dirname(dest), { recursive: true }); - fs.copyFileSync(src, dest); - totalCommands++; - } - } - // Process skills if (Array.isArray(metadata.skills)) { for (const relPath of metadata.skills) { @@ -145,16 +119,39 @@ function materializePlugins() { } } + // Rewrite plugin.json to use folder paths instead of individual file paths. + // On staged, paths like ./agents/foo.md point to individual source files. + // On main, after materialization, we only need the containing directory. + const rewritten = { ...metadata }; + let changed = false; + + for (const field of ["agents", "commands"]) { + if (Array.isArray(rewritten[field]) && rewritten[field].length > 0) { + const dirs = [...new Set(rewritten[field].map(p => path.dirname(p)))]; + rewritten[field] = dirs; + changed = true; + } + } + + if (Array.isArray(rewritten.skills) && rewritten.skills.length > 0) { + // Skills are already folder refs (./skills/name/); strip trailing slash + rewritten.skills = rewritten.skills.map(p => p.replace(/\/$/, "")); + changed = true; + } + + if (changed) { + fs.writeFileSync(pluginJsonPath, JSON.stringify(rewritten, null, 2) + "\n", "utf8"); + } + const counts = []; if (metadata.agents?.length) counts.push(`${metadata.agents.length} agents`); - if (metadata.commands?.length) counts.push(`${metadata.commands.length} commands`); if (metadata.skills?.length) counts.push(`${metadata.skills.length} skills`); if (counts.length) { console.log(`βœ“ ${pluginName}: ${counts.join(", ")}`); } } - console.log(`\nDone. Copied ${totalAgents} agents, ${totalCommands} commands, ${totalSkills} skills.`); + console.log(`\nDone. Copied ${totalAgents} agents, ${totalSkills} skills.`); if (warnings > 0) { console.log(`${warnings} warning(s).`); } diff --git a/eng/migrate-prompts-to-skills.mjs b/eng/migrate-prompts-to-skills.mjs new file mode 100755 index 000000000..173ea5ffe --- /dev/null +++ b/eng/migrate-prompts-to-skills.mjs @@ -0,0 +1,137 @@ +#!/usr/bin/env node + +import fs from "fs"; +import path from "path"; +import { ROOT_FOLDER, SKILLS_DIR } from "./constants.mjs"; +import { parseFrontmatter } from "./yaml-parser.mjs"; + +const PROMPTS_DIR = path.join(ROOT_FOLDER, "prompts"); +/** + * Convert a prompt file to a skill folder + * @param {string} promptFilePath - Full path to the prompt file + * @returns {object} Result with success status and details + */ +function convertPromptToSkill(promptFilePath) { + const filename = path.basename(promptFilePath); + const baseName = filename.replace(".prompt.md", ""); + + console.log(`\nConverting: ${baseName}`); + + // Parse the prompt file frontmatter + const frontmatter = parseFrontmatter(promptFilePath); + const content = fs.readFileSync(promptFilePath, "utf8"); + + // Extract the content after frontmatter + const frontmatterEndMatch = content.match(/^---\n[\s\S]*?\n---\n/); + const mainContent = frontmatterEndMatch + ? content.substring(frontmatterEndMatch[0].length).trim() + : content.trim(); + + // Create skill folder + const skillFolderPath = path.join(SKILLS_DIR, baseName); + if (fs.existsSync(skillFolderPath)) { + console.log(` ⚠️ Skill folder already exists: ${baseName}`); + return { success: false, reason: "already-exists", name: baseName }; + } + + fs.mkdirSync(skillFolderPath, { recursive: true }); + + // Build new frontmatter for SKILL.md + const skillFrontmatter = { + name: baseName, + description: frontmatter?.description || `Skill converted from ${filename}`, + }; + + // Build SKILL.md content + const skillContent = `--- +name: ${skillFrontmatter.name} +description: '${skillFrontmatter.description.replace(/'/g, "'''")}' +--- + +${mainContent} +`; + + // Write SKILL.md + const skillFilePath = path.join(skillFolderPath, "SKILL.md"); + fs.writeFileSync(skillFilePath, skillContent, "utf8"); + + console.log(` βœ“ Created skill: ${baseName}`); + return { success: true, name: baseName, path: skillFolderPath }; +} + +/** + * Main migration function + */ +function main() { + console.log("=".repeat(60)); + console.log("Starting Prompt to Skills Migration"); + console.log("=".repeat(60)); + + // Check if prompts directory exists + if (!fs.existsSync(PROMPTS_DIR)) { + console.error(`Error: Prompts directory not found: ${PROMPTS_DIR}`); + process.exit(1); + } + + // Get all prompt files + const promptFiles = fs + .readdirSync(PROMPTS_DIR) + .filter((file) => file.endsWith(".prompt.md")) + .map((file) => path.join(PROMPTS_DIR, file)); + + console.log(`Found ${promptFiles.length} prompt files to convert\n`); + + const results = { + success: [], + alreadyExists: [], + failed: [], + }; + + // Convert each prompt + for (const promptFile of promptFiles) { + try { + const result = convertPromptToSkill(promptFile); + if (result.success) { + results.success.push(result.name); + } else if (result.reason === "already-exists") { + results.alreadyExists.push(result.name); + } else { + results.failed.push(result.name); + } + } catch (error) { + const baseName = path.basename(promptFile, ".prompt.md"); + console.error(` βœ— Error converting ${baseName}: ${error.message}`); + results.failed.push(baseName); + } + } + + // Print summary + console.log("\n" + "=".repeat(60)); + console.log("Migration Summary"); + console.log("=".repeat(60)); + console.log(`βœ“ Successfully converted: ${results.success.length}`); + console.log(`⚠ Already existed: ${results.alreadyExists.length}`); + console.log(`βœ— Failed: ${results.failed.length}`); + console.log(`Total processed: ${promptFiles.length}`); + + if (results.failed.length > 0) { + console.log("\nFailed conversions:"); + results.failed.forEach((name) => console.log(` - ${name}`)); + } + + if (results.alreadyExists.length > 0) { + console.log("\nSkipped (already exist):"); + results.alreadyExists.forEach((name) => console.log(` - ${name}`)); + } + + console.log("\nβœ… Migration complete!"); + console.log( + "\nNext steps:\n" + + "1. Run 'npm run skill:validate' to validate all new skills\n" + + "2. Update plugin manifests to reference skills instead of commands\n" + + "3. Remove prompts directory after testing\n" + ); +} + +// Run migration +main(); diff --git a/eng/update-plugin-commands-to-skills.mjs b/eng/update-plugin-commands-to-skills.mjs new file mode 100755 index 000000000..c09736aba --- /dev/null +++ b/eng/update-plugin-commands-to-skills.mjs @@ -0,0 +1,165 @@ +#!/usr/bin/env node + +import fs from "fs"; +import path from "path"; +import { PLUGINS_DIR } from "./constants.mjs"; + +/** + * Convert commands references to skills references in a plugin.json + * @param {string} pluginJsonPath - Path to the plugin.json file + * @returns {object} Result with success status and details + */ +function updatePluginManifest(pluginJsonPath) { + const pluginDir = path.dirname(path.dirname(path.dirname(pluginJsonPath))); + const pluginName = path.basename(pluginDir); + + console.log(`\nProcessing plugin: ${pluginName}`); + + // Read and parse plugin.json + let plugin; + try { + const content = fs.readFileSync(pluginJsonPath, "utf8"); + plugin = JSON.parse(content); + } catch (error) { + console.log(` βœ— Error reading/parsing: ${error.message}`); + return { success: false, name: pluginName, reason: "parse-error" }; + } + + // Check if plugin has commands field + if (!plugin.commands || !Array.isArray(plugin.commands)) { + console.log(` β„Ή No commands field found`); + return { success: false, name: pluginName, reason: "no-commands" }; + } + + const commandCount = plugin.commands.length; + console.log(` Found ${commandCount} command(s) to convert`); + + // Validate and convert commands to skills format + // Commands: "./commands/foo.md" β†’ Skills: "./skills/foo/" + const validCommands = plugin.commands.filter((cmd) => { + if (typeof cmd !== "string") { + console.log(` ⚠ Skipping non-string command entry: ${JSON.stringify(cmd)}`); + return false; + } + if (!cmd.startsWith("./commands/") || !cmd.endsWith(".md")) { + console.log(` ⚠ Skipping command with unexpected format: ${cmd}`); + return false; + } + return true; + }); + const skills = validCommands.map((cmd) => { + const basename = path.basename(cmd, ".md"); + return `./skills/${basename}/`; + }); + // Initialize skills array if it doesn't exist or is not an array + if (!Array.isArray(plugin.skills)) { + plugin.skills = []; + } + // Add converted commands to skills array, de-duplicating entries + const allSkills = new Set(plugin.skills); + for (const skillPath of skills) { + allSkills.add(skillPath); + } + plugin.skills = Array.from(allSkills); + + // Remove commands field + delete plugin.commands; + + // Write updated plugin.json + try { + fs.writeFileSync( + pluginJsonPath, + JSON.stringify(plugin, null, 2) + "\n", + "utf8" + ); + console.log(` βœ“ Converted ${commandCount} command(s) to skills`); + return { success: true, name: pluginName, count: commandCount }; + } catch (error) { + console.log(` βœ— Error writing file: ${error.message}`); + return { success: false, name: pluginName, reason: "write-error" }; + } +} + +/** + * Main function to update all plugin manifests + */ +function main() { + console.log("=".repeat(60)); + console.log("Updating Plugin Manifests: Commands β†’ Skills"); + console.log("=".repeat(60)); + + // Check if plugins directory exists + if (!fs.existsSync(PLUGINS_DIR)) { + console.error(`Error: Plugins directory not found: ${PLUGINS_DIR}`); + process.exit(1); + } + + // Find all plugin.json files + const pluginDirs = fs + .readdirSync(PLUGINS_DIR, { withFileTypes: true }) + .filter((entry) => entry.isDirectory()) + .map((entry) => entry.name); + + console.log(`Found ${pluginDirs.length} plugin directory(ies)\n`); + + const results = { + updated: [], + noCommands: [], + failed: [], + }; + + // Process each plugin + for (const dirName of pluginDirs) { + const pluginJsonPath = path.join( + PLUGINS_DIR, + dirName, + ".github/plugin", + "plugin.json" + ); + + if (!fs.existsSync(pluginJsonPath)) { + console.log(`\nSkipping ${dirName}: no plugin.json found`); + continue; + } + + const result = updatePluginManifest(pluginJsonPath); + if (result.success) { + results.updated.push({ name: result.name, count: result.count }); + } else if (result.reason === "no-commands") { + results.noCommands.push(result.name); + } else { + results.failed.push(result.name); + } + } + + // Print summary + console.log("\n" + "=".repeat(60)); + console.log("Update Summary"); + console.log("=".repeat(60)); + console.log(`βœ“ Updated plugins: ${results.updated.length}`); + console.log(`β„Ή No commands field: ${results.noCommands.length}`); + console.log(`βœ— Failed: ${results.failed.length}`); + console.log(`Total processed: ${pluginDirs.length}`); + + if (results.updated.length > 0) { + console.log("\nUpdated plugins:"); + results.updated.forEach(({ name, count }) => + console.log(` - ${name} (${count} command(s) β†’ skills)`) + ); + } + + if (results.failed.length > 0) { + console.log("\nFailed updates:"); + results.failed.forEach((name) => console.log(` - ${name}`)); + } + + console.log("\nβœ… Plugin manifest updates complete!"); + console.log( + "\nNext steps:\n" + + "1. Run 'npm run plugin:validate' to validate all updated plugins\n" + + "2. Test that plugins work correctly\n" + ); +} + +// Run the update +main(); diff --git a/eng/update-readme.mjs b/eng/update-readme.mjs index 3456d5c65..f36476587 100644 --- a/eng/update-readme.mjs +++ b/eng/update-readme.mjs @@ -10,7 +10,6 @@ import { HOOKS_DIR, INSTRUCTIONS_DIR, PLUGINS_DIR, - PROMPTS_DIR, repoBaseUrl, ROOT_FOLDER, SKILLS_DIR, @@ -343,63 +342,6 @@ function generateInstructionsSection(instructionsDir) { return `${TEMPLATES.instructionsSection}\n${TEMPLATES.instructionsUsage}\n\n${instructionsContent}`; } -/** - * Generate the prompts section with a table of all prompts - */ -function generatePromptsSection(promptsDir) { - // Check if directory exists - if (!fs.existsSync(promptsDir)) { - return ""; - } - - // Get all prompt files - const promptFiles = fs - .readdirSync(promptsDir) - .filter((file) => file.endsWith(".prompt.md")); - - // Map prompt files to objects with title for sorting - const promptEntries = promptFiles.map((file) => { - const filePath = path.join(promptsDir, file); - const title = extractTitle(filePath); - return { file, filePath, title }; - }); - - // Sort by title alphabetically - promptEntries.sort((a, b) => a.title.localeCompare(b.title)); - - console.log(`Found ${promptEntries.length} prompt files`); - - // Return empty string if no files found - if (promptEntries.length === 0) { - return ""; - } - - // Create table header - let promptsContent = "| Title | Description |\n| ----- | ----------- |\n"; - - // Generate table rows for each prompt file - for (const entry of promptEntries) { - const { file, filePath, title } = entry; - const link = encodeURI(`prompts/${file}`); - - // Check if there's a description in the frontmatter - const customDescription = extractDescription(filePath); - - // Create badges for installation links - const badges = makeBadges(link, "prompt"); - - if (customDescription && customDescription !== "null") { - promptsContent += `| [${title}](../${link})
${badges} | ${formatTableCell( - customDescription - )} |\n`; - } else { - promptsContent += `| [${title}](../${link})
${badges} | | |\n`; - } - } - - return `${TEMPLATES.promptsSection}\n${TEMPLATES.promptsUsage}\n\n${promptsContent}`; -} - /** * Generate MCP server links for an agent * @param {string[]} servers - Array of MCP server names @@ -975,7 +917,6 @@ async function main() { /^##\s/m, "# " ); - const promptsHeader = TEMPLATES.promptsSection.replace(/^##\s/m, "# "); const agentsHeader = TEMPLATES.agentsSection.replace(/^##\s/m, "# "); const hooksHeader = TEMPLATES.hooksSection.replace(/^##\s/m, "# "); const workflowsHeader = TEMPLATES.workflowsSection.replace(/^##\s/m, "# "); @@ -992,13 +933,6 @@ async function main() { TEMPLATES.instructionsUsage, registryNames ); - const promptsReadme = buildCategoryReadme( - generatePromptsSection, - PROMPTS_DIR, - promptsHeader, - TEMPLATES.promptsUsage, - registryNames - ); // Generate agents README const agentsReadme = buildCategoryReadme( generateAgentsSection, @@ -1054,7 +988,6 @@ async function main() { path.join(DOCS_DIR, "README.instructions.md"), instructionsReadme ); - writeFileIfChanged(path.join(DOCS_DIR, "README.prompts.md"), promptsReadme); writeFileIfChanged(path.join(DOCS_DIR, "README.agents.md"), agentsReadme); writeFileIfChanged(path.join(DOCS_DIR, "README.hooks.md"), hooksReadme); writeFileIfChanged(path.join(DOCS_DIR, "README.workflows.md"), workflowsReadme); diff --git a/eng/validate-plugins.mjs b/eng/validate-plugins.mjs index 6318c47c2..946accab9 100755 --- a/eng/validate-plugins.mjs +++ b/eng/validate-plugins.mjs @@ -68,7 +68,6 @@ function validateSpecPaths(plugin) { const errors = []; const specs = { agents: { prefix: "./agents/", suffix: ".md", repoDir: "agents", repoSuffix: ".agent.md" }, - commands: { prefix: "./commands/", suffix: ".md", repoDir: "prompts", repoSuffix: ".prompt.md" }, skills: { prefix: "./skills/", suffix: "/", repoDir: "skills", repoFile: "SKILL.md" }, }; diff --git a/eng/yaml-parser.mjs b/eng/yaml-parser.mjs index 88d16582f..336cc2a96 100644 --- a/eng/yaml-parser.mjs +++ b/eng/yaml-parser.mjs @@ -275,14 +275,29 @@ function parseWorkflowMetadata(filePath) { return null; } - // Extract triggers from frontmatter if present - const triggers = frontmatter.triggers || []; + // Extract triggers from the 'on' field (top-level keys) + const onField = frontmatter.on; + const triggers = []; + if (onField && typeof onField === "object") { + triggers.push(...Object.keys(onField)); + } else if (typeof onField === "string") { + triggers.push(onField); + } + + // Extract tags and convert to array + const tags = frontmatter.metadata?.tags + ? typeof frontmatter.metadata.tags === "string" + ? frontmatter.metadata.tags.split(",").map((tag) => tag.trim()) + : Array.isArray(frontmatter.metadata.tags) + ? frontmatter.metadata.tags + : [] + : []; return { name: frontmatter.name, description: frontmatter.description, triggers, - tags: frontmatter.tags || [], + tags, path: filePath, }; }, @@ -312,8 +327,8 @@ export { extractMcpServerConfigs, extractMcpServers, parseFrontmatter, - parseSkillMetadata, parseHookMetadata, + parseSkillMetadata, parseWorkflowMetadata, parseYamlFile, safeFileOperation, diff --git a/instructions/cpp-language-service-tools.instructions.md b/instructions/cpp-language-service-tools.instructions.md index 4023b51f6..51a3dc6ee 100644 --- a/instructions/cpp-language-service-tools.instructions.md +++ b/instructions/cpp-language-service-tools.instructions.md @@ -1,7 +1,8 @@ --- description: You are an expert at using C++ language service tools (GetSymbolReferences_CppTools, GetSymbolInfo_CppTools, GetSymbolCallHierarchy_CppTools). Instructions for calling C++ Tools for Copilot. When working with C++ code, you have access to powerful language service tools that provide accurate, IntelliSense-powered analysis. **Always prefer these tools over manual code inspection, text search, or guessing.** -applyTo: **/*.cpp, **/*.h, **/*.hpp, **/*.cc, **/*.cxx, **/*.c +applyTo: "**/*.cpp, **/*.h, **/*.hpp, **/*.cc, **/*.cxx, **/*.c" --- + ## Available C++ Tools You have access to three specialized C++ tools: @@ -19,6 +20,7 @@ You have access to three specialized C++ tools: **NEVER** rely on manual code inspection, `vscode_listCodeUsages`, `grep_search`, or `read_file` to find where a symbol is used. **ALWAYS** call `GetSymbolReferences_CppTools` when: + - Renaming any symbol (function, variable, class, method, etc.) - Changing function signatures - Refactoring code @@ -28,6 +30,7 @@ You have access to three specialized C++ tools: - Any task involving "find all uses/usages/references/calls" **Why**: `GetSymbolReferences_CppTools` uses C++ IntelliSense and understands: + - Overloaded functions - Template instantiations - Qualified vs unqualified names @@ -42,6 +45,7 @@ Text search tools will miss these or produce false positives. Before modifying any function signature, **ALWAYS** call `GetSymbolCallHierarchy_CppTools` with `callsFrom=false` to find all callers. **Examples**: + - Adding/removing function parameters - Changing parameter types - Changing return types @@ -53,6 +57,7 @@ Before modifying any function signature, **ALWAYS** call `GetSymbolCallHierarchy ### Rule 3: ALWAYS Use GetSymbolInfo_CppTools to Understand Symbols Before working with unfamiliar code, **ALWAYS** call `GetSymbolInfo_CppTools` to: + - Find where a symbol is defined - Understand class/struct memory layout - Get type information @@ -65,11 +70,13 @@ Before working with unfamiliar code, **ALWAYS** call `GetSymbolInfo_CppTools` to ## Parameter Usage Guidelines ### Symbol Names + - **ALWAYS REQUIRED**: Provide the symbol name - Can be unqualified (`MyFunction`), partially qualified (`MyClass::MyMethod`), or fully qualified (`MyNamespace::MyClass::MyMethod`) - If you have a line number, the symbol should match what appears on that line ### File Paths + - **STRONGLY PREFERRED**: Always provide absolute file paths when available - βœ… Good: `C:\Users\Project\src\main.cpp` - ❌ Avoid: `src\main.cpp` (requires resolution, may fail) @@ -77,6 +84,7 @@ Before working with unfamiliar code, **ALWAYS** call `GetSymbolInfo_CppTools` to - If working with user-specified files, use their exact path ### Line Numbers + - **CRITICAL**: Line numbers are 1-based, NOT 0-based - **MANDATORY WORKFLOW** when you need a line number: 1. First call `read_file` to search for the symbol @@ -88,7 +96,9 @@ Before working with unfamiliar code, **ALWAYS** call `GetSymbolInfo_CppTools` to - If you don't have a line number, omit it - the tools will find the symbol ### Minimal Information Strategy + Start with minimal information and add more only if needed: + 1. **First attempt**: Symbol name only 2. **If ambiguous**: Symbol name + file path 3. **If still ambiguous**: Symbol name + file path + line number (after using `read_file`) @@ -164,6 +174,7 @@ INCORRECT workflow: **All error messages contain specific recovery instructions. ALWAYS follow them exactly.** #### "Symbol name is not valid" Error + ``` Error: "The symbol name is not valid: it is either empty or null. Find a valid symbol name. Then call the [tool] tool again" @@ -174,6 +185,7 @@ Recovery: ``` #### "File could not be found" Error + ``` Error: "A file could not be found at the specified path. Compute the absolute path to the file. Then call the [tool] tool again." @@ -185,6 +197,7 @@ Recovery: ``` #### "No results found" Message + ``` Message: "No results found for the symbol '[symbol_name]'." @@ -199,16 +212,19 @@ This is NOT an error - it means: ## Tool Selection Decision Tree **Question: Do I need to find where a symbol is used/called/referenced?** + - βœ… YES β†’ Use `GetSymbolReferences_CppTools` - ❌ NO β†’ Continue **Question: Am I changing a function signature or analyzing function calls?** + - βœ… YES β†’ Use `GetSymbolCallHierarchy_CppTools` - Finding callers? β†’ `callsFrom=false` - Finding what it calls? β†’ `callsFrom=true` - ❌ NO β†’ Continue **Question: Do I need to find a definition or understand a type?** + - βœ… YES β†’ Use `GetSymbolInfo_CppTools` - ❌ NO β†’ You may not need a C++ tool for this task @@ -217,6 +233,7 @@ This is NOT an error - it means: ## Critical Reminders ### DO: + - βœ… Call `GetSymbolReferences_CppTools` for ANY symbol usage search - βœ… Call `GetSymbolCallHierarchy_CppTools` before function signature changes - βœ… Use `read_file` to find line numbers before specifying them @@ -227,6 +244,7 @@ This is NOT an error - it means: - βœ… Remember line numbers are 1-based ### DO NOT: + - ❌ Use `vscode_listCodeUsages`, `grep_search`, or `read_file` to find symbol usages - ❌ Manually inspect code to find references - ❌ Guess line numbers @@ -242,6 +260,7 @@ This is NOT an error - it means: ## Examples of Correct Usage ### Example 1: User asks to rename a function + ``` User: "Rename the function ProcessData to HandleData" @@ -259,6 +278,7 @@ INCORRECT response: ``` ### Example 2: User asks to add a parameter to a function + ``` User: "Add a parameter 'bool verbose' to the LogMessage function" @@ -276,6 +296,7 @@ INCORRECT response: ``` ### Example 3: User asks to understand a function + ``` User: "What does the Initialize function do?" @@ -296,16 +317,19 @@ INCORRECT response: ## Performance and Best Practices ### Efficient Tool Usage + - Call tools in parallel when analyzing multiple independent symbols - Use file paths to speed up symbol resolution - Provide context to narrow searches ### Iterative Refinement + - If first tool call is ambiguous, add file path - If still ambiguous, use `read_file` to find exact line - Tools are designed for iteration ### Understanding Results + - **Empty results are valid**: "No results found" means the symbol has no references/calls - **Multiple results are common**: C++ has overloading, templates, namespaces - **Trust the tools**: IntelliSense knows C++ semantics better than text search @@ -315,17 +339,20 @@ INCORRECT response: ## Integration with Other Tools ### When to use read_file + - **ONLY** for finding line numbers before calling C++ tools - **ONLY** for reading implementation details after locating symbols - **NEVER** for finding symbol usages (use `GetSymbolReferences_CppTools` instead) ### When to use vscode_listCodeUsages/grep_search + - Finding string literals or comments - Searching non-C++ files - Pattern matching in configuration files - **NEVER** for finding C++ symbol usages ### When to use semantic_search + - Finding code based on conceptual queries - Locating relevant files in large codebases - Understanding project structure diff --git a/plugins/awesome-copilot/.github/plugin/plugin.json b/plugins/awesome-copilot/.github/plugin/plugin.json index e273e817e..94f739691 100644 --- a/plugins/awesome-copilot/.github/plugin/plugin.json +++ b/plugins/awesome-copilot/.github/plugin/plugin.json @@ -17,10 +17,10 @@ "agents": [ "./agents/meta-agentic-project-scaffold.md" ], - "commands": [ - "./commands/suggest-awesome-github-copilot-skills.md", - "./commands/suggest-awesome-github-copilot-instructions.md", - "./commands/suggest-awesome-github-copilot-prompts.md", - "./commands/suggest-awesome-github-copilot-agents.md" + "skills": [ + "./skills/suggest-awesome-github-copilot-skills/", + "./skills/suggest-awesome-github-copilot-instructions/", + "./skills/suggest-awesome-github-copilot-prompts/", + "./skills/suggest-awesome-github-copilot-agents/" ] } diff --git a/plugins/azure-cloud-development/.github/plugin/plugin.json b/plugins/azure-cloud-development/.github/plugin/plugin.json index 9bf3a8c0c..4a17f2c7a 100644 --- a/plugins/azure-cloud-development/.github/plugin/plugin.json +++ b/plugins/azure-cloud-development/.github/plugin/plugin.json @@ -26,8 +26,8 @@ "./agents/terraform-azure-planning.md", "./agents/terraform-azure-implement.md" ], - "commands": [ - "./commands/azure-resource-health-diagnose.md", - "./commands/az-cost-optimize.md" + "skills": [ + "./skills/azure-resource-health-diagnose/", + "./skills/az-cost-optimize/" ] } diff --git a/plugins/clojure-interactive-programming/.github/plugin/plugin.json b/plugins/clojure-interactive-programming/.github/plugin/plugin.json index e4cc886fd..e983d38ac 100644 --- a/plugins/clojure-interactive-programming/.github/plugin/plugin.json +++ b/plugins/clojure-interactive-programming/.github/plugin/plugin.json @@ -15,7 +15,7 @@ "agents": [ "./agents/clojure-interactive-programming.md" ], - "commands": [ - "./commands/remember-interactive-programming.md" + "skills": [ + "./skills/remember-interactive-programming/" ] } diff --git a/plugins/context-engineering/.github/plugin/plugin.json b/plugins/context-engineering/.github/plugin/plugin.json index 1f2f74340..a6ed5c2f4 100644 --- a/plugins/context-engineering/.github/plugin/plugin.json +++ b/plugins/context-engineering/.github/plugin/plugin.json @@ -17,9 +17,9 @@ "agents": [ "./agents/context-architect.md" ], - "commands": [ - "./commands/context-map.md", - "./commands/what-context-needed.md", - "./commands/refactor-plan.md" + "skills": [ + "./skills/context-map/", + "./skills/what-context-needed/", + "./skills/refactor-plan/" ] } diff --git a/plugins/csharp-dotnet-development/.github/plugin/plugin.json b/plugins/csharp-dotnet-development/.github/plugin/plugin.json index bceb46a32..1ec31d36b 100644 --- a/plugins/csharp-dotnet-development/.github/plugin/plugin.json +++ b/plugins/csharp-dotnet-development/.github/plugin/plugin.json @@ -16,14 +16,14 @@ "agents": [ "./agents/expert-dotnet-software-engineer.md" ], - "commands": [ - "./commands/csharp-async.md", - "./commands/aspnet-minimal-api-openapi.md", - "./commands/csharp-xunit.md", - "./commands/csharp-nunit.md", - "./commands/csharp-mstest.md", - "./commands/csharp-tunit.md", - "./commands/dotnet-best-practices.md", - "./commands/dotnet-upgrade.md" + "skills": [ + "./skills/csharp-async/", + "./skills/aspnet-minimal-api-openapi/", + "./skills/csharp-xunit/", + "./skills/csharp-nunit/", + "./skills/csharp-mstest/", + "./skills/csharp-tunit/", + "./skills/dotnet-best-practices/", + "./skills/dotnet-upgrade/" ] } diff --git a/plugins/csharp-mcp-development/.github/plugin/plugin.json b/plugins/csharp-mcp-development/.github/plugin/plugin.json index 04be5cd24..cb6da7090 100644 --- a/plugins/csharp-mcp-development/.github/plugin/plugin.json +++ b/plugins/csharp-mcp-development/.github/plugin/plugin.json @@ -17,7 +17,7 @@ "agents": [ "./agents/csharp-mcp-expert.md" ], - "commands": [ - "./commands/csharp-mcp-server-generator.md" + "skills": [ + "./skills/csharp-mcp-server-generator/" ] } diff --git a/plugins/database-data-management/.github/plugin/plugin.json b/plugins/database-data-management/.github/plugin/plugin.json index efdcce7af..2477c840a 100644 --- a/plugins/database-data-management/.github/plugin/plugin.json +++ b/plugins/database-data-management/.github/plugin/plugin.json @@ -21,10 +21,10 @@ "./agents/postgresql-dba.md", "./agents/ms-sql-dba.md" ], - "commands": [ - "./commands/sql-optimization.md", - "./commands/sql-code-review.md", - "./commands/postgresql-optimization.md", - "./commands/postgresql-code-review.md" + "skills": [ + "./skills/sql-optimization/", + "./skills/sql-code-review/", + "./skills/postgresql-optimization/", + "./skills/postgresql-code-review/" ] } diff --git a/plugins/dataverse-sdk-for-python/.github/plugin/plugin.json b/plugins/dataverse-sdk-for-python/.github/plugin/plugin.json index 3579e96b7..4cac3979c 100644 --- a/plugins/dataverse-sdk-for-python/.github/plugin/plugin.json +++ b/plugins/dataverse-sdk-for-python/.github/plugin/plugin.json @@ -13,10 +13,10 @@ "integration", "sdk" ], - "commands": [ - "./commands/dataverse-python-quickstart.md", - "./commands/dataverse-python-advanced-patterns.md", - "./commands/dataverse-python-production-code.md", - "./commands/dataverse-python-usecase-builder.md" + "skills": [ + "./skills/dataverse-python-quickstart/", + "./skills/dataverse-python-advanced-patterns/", + "./skills/dataverse-python-production-code/", + "./skills/dataverse-python-usecase-builder/" ] } diff --git a/plugins/dataverse/.github/plugin/plugin.json b/plugins/dataverse/.github/plugin/plugin.json new file mode 100644 index 000000000..8b27d3950 --- /dev/null +++ b/plugins/dataverse/.github/plugin/plugin.json @@ -0,0 +1,17 @@ +{ + "name": "dataverse", + "description": "Comprehensive collection for Microsoft Dataverse integrations. Includes MCP setup commands.", + "version": "1.0.0", + "author": { + "name": "Awesome Copilot Community" + }, + "repository": "https://github.com/github/awesome-copilot", + "license": "MIT", + "keywords": [ + "dataverse", + "mcp" + ], + "skills": [ + "./skills/mcp-configure/" + ] +} diff --git a/plugins/dataverse/README.md b/plugins/dataverse/README.md new file mode 100644 index 000000000..9637ddfcb --- /dev/null +++ b/plugins/dataverse/README.md @@ -0,0 +1,26 @@ +# Dataverse MCP + +Comprehensive collection for Microsoft Dataverse integrations. Includes MCP setup commands that guide you through configuring Dataverse MCP servers for GitHub Copilot. + +## Installation + +```bash +# Using Copilot CLI +copilot plugin install dataverse@awesome-copilot +``` + +## What's Included + +### Skills + +| Skill | Description | +|-------|-------------| +| `/dataverse:mcp-configure` | Configure Dataverse MCP server for GitHub Copilot with global or project-scoped settings.. | + +## Source + +This plugin is part of [Awesome Copilot](https://github.com/github/awesome-copilot), a community-driven collection of GitHub Copilot extensions. + +## License + +MIT diff --git a/plugins/devops-oncall/.github/plugin/plugin.json b/plugins/devops-oncall/.github/plugin/plugin.json index c06cee86e..49522608f 100644 --- a/plugins/devops-oncall/.github/plugin/plugin.json +++ b/plugins/devops-oncall/.github/plugin/plugin.json @@ -16,8 +16,8 @@ "agents": [ "./agents/azure-principal-architect.md" ], - "commands": [ - "./commands/azure-resource-health-diagnose.md", - "./commands/multi-stage-dockerfile.md" + "skills": [ + "./skills/azure-resource-health-diagnose/", + "./skills/multi-stage-dockerfile/" ] } diff --git a/plugins/frontend-web-dev/.github/plugin/plugin.json b/plugins/frontend-web-dev/.github/plugin/plugin.json index 05ccb6285..efc8b17b2 100644 --- a/plugins/frontend-web-dev/.github/plugin/plugin.json +++ b/plugins/frontend-web-dev/.github/plugin/plugin.json @@ -22,8 +22,8 @@ "./agents/expert-react-frontend-engineer.md", "./agents/electron-angular-native.md" ], - "commands": [ - "./commands/playwright-explore-website.md", - "./commands/playwright-generate-test.md" + "skills": [ + "./skills/playwright-explore-website/", + "./skills/playwright-generate-test/" ] } diff --git a/plugins/go-mcp-development/.github/plugin/plugin.json b/plugins/go-mcp-development/.github/plugin/plugin.json index 810eb927c..83a2f3e17 100644 --- a/plugins/go-mcp-development/.github/plugin/plugin.json +++ b/plugins/go-mcp-development/.github/plugin/plugin.json @@ -18,7 +18,7 @@ "agents": [ "./agents/go-mcp-expert.md" ], - "commands": [ - "./commands/go-mcp-server-generator.md" + "skills": [ + "./skills/go-mcp-server-generator/" ] } diff --git a/plugins/java-development/.github/plugin/plugin.json b/plugins/java-development/.github/plugin/plugin.json index 7c31c967d..ffd3da89b 100644 --- a/plugins/java-development/.github/plugin/plugin.json +++ b/plugins/java-development/.github/plugin/plugin.json @@ -15,10 +15,10 @@ "junit", "javadoc" ], - "commands": [ - "./commands/java-docs.md", - "./commands/java-junit.md", - "./commands/java-springboot.md", - "./commands/create-spring-boot-java-project.md" + "skills": [ + "./skills/java-docs/", + "./skills/java-junit/", + "./skills/java-springboot/", + "./skills/create-spring-boot-java-project/" ] } diff --git a/plugins/java-mcp-development/.github/plugin/plugin.json b/plugins/java-mcp-development/.github/plugin/plugin.json index 146b1cc6d..0d95e1ad6 100644 --- a/plugins/java-mcp-development/.github/plugin/plugin.json +++ b/plugins/java-mcp-development/.github/plugin/plugin.json @@ -20,7 +20,7 @@ "agents": [ "./agents/java-mcp-expert.md" ], - "commands": [ - "./commands/java-mcp-server-generator.md" + "skills": [ + "./skills/java-mcp-server-generator/" ] } diff --git a/plugins/kotlin-mcp-development/.github/plugin/plugin.json b/plugins/kotlin-mcp-development/.github/plugin/plugin.json index 463ee8d04..0c0629d4f 100644 --- a/plugins/kotlin-mcp-development/.github/plugin/plugin.json +++ b/plugins/kotlin-mcp-development/.github/plugin/plugin.json @@ -18,7 +18,7 @@ "agents": [ "./agents/kotlin-mcp-expert.md" ], - "commands": [ - "./commands/kotlin-mcp-server-generator.md" + "skills": [ + "./skills/kotlin-mcp-server-generator/" ] } diff --git a/plugins/mcp-m365-copilot/.github/plugin/plugin.json b/plugins/mcp-m365-copilot/.github/plugin/plugin.json index a7eab6ef3..01f010e96 100644 --- a/plugins/mcp-m365-copilot/.github/plugin/plugin.json +++ b/plugins/mcp-m365-copilot/.github/plugin/plugin.json @@ -18,9 +18,9 @@ "agents": [ "./agents/mcp-m365-agent-expert.md" ], - "commands": [ - "./commands/mcp-create-declarative-agent.md", - "./commands/mcp-create-adaptive-cards.md", - "./commands/mcp-deploy-manage-agents.md" + "skills": [ + "./skills/mcp-create-declarative-agent/", + "./skills/mcp-create-adaptive-cards/", + "./skills/mcp-deploy-manage-agents/" ] } diff --git a/plugins/openapi-to-application-csharp-dotnet/.github/plugin/plugin.json b/plugins/openapi-to-application-csharp-dotnet/.github/plugin/plugin.json index 2622c2110..67fa408da 100644 --- a/plugins/openapi-to-application-csharp-dotnet/.github/plugin/plugin.json +++ b/plugins/openapi-to-application-csharp-dotnet/.github/plugin/plugin.json @@ -18,7 +18,7 @@ "agents": [ "./agents/openapi-to-application.md" ], - "commands": [ - "./commands/openapi-to-application-code.md" + "skills": [ + "./skills/openapi-to-application-code/" ] } diff --git a/plugins/openapi-to-application-go/.github/plugin/plugin.json b/plugins/openapi-to-application-go/.github/plugin/plugin.json index 776c013a9..8f57de601 100644 --- a/plugins/openapi-to-application-go/.github/plugin/plugin.json +++ b/plugins/openapi-to-application-go/.github/plugin/plugin.json @@ -17,7 +17,7 @@ "agents": [ "./agents/openapi-to-application.md" ], - "commands": [ - "./commands/openapi-to-application-code.md" + "skills": [ + "./skills/openapi-to-application-code/" ] } diff --git a/plugins/openapi-to-application-java-spring-boot/.github/plugin/plugin.json b/plugins/openapi-to-application-java-spring-boot/.github/plugin/plugin.json index 0974f39c0..8f544c63d 100644 --- a/plugins/openapi-to-application-java-spring-boot/.github/plugin/plugin.json +++ b/plugins/openapi-to-application-java-spring-boot/.github/plugin/plugin.json @@ -17,7 +17,7 @@ "agents": [ "./agents/openapi-to-application.md" ], - "commands": [ - "./commands/openapi-to-application-code.md" + "skills": [ + "./skills/openapi-to-application-code/" ] } diff --git a/plugins/openapi-to-application-nodejs-nestjs/.github/plugin/plugin.json b/plugins/openapi-to-application-nodejs-nestjs/.github/plugin/plugin.json index 04289089a..fd9ba816f 100644 --- a/plugins/openapi-to-application-nodejs-nestjs/.github/plugin/plugin.json +++ b/plugins/openapi-to-application-nodejs-nestjs/.github/plugin/plugin.json @@ -18,7 +18,7 @@ "agents": [ "./agents/openapi-to-application.md" ], - "commands": [ - "./commands/openapi-to-application-code.md" + "skills": [ + "./skills/openapi-to-application-code/" ] } diff --git a/plugins/openapi-to-application-python-fastapi/.github/plugin/plugin.json b/plugins/openapi-to-application-python-fastapi/.github/plugin/plugin.json index 791a8ac03..4f9df5824 100644 --- a/plugins/openapi-to-application-python-fastapi/.github/plugin/plugin.json +++ b/plugins/openapi-to-application-python-fastapi/.github/plugin/plugin.json @@ -17,7 +17,7 @@ "agents": [ "./agents/openapi-to-application.md" ], - "commands": [ - "./commands/openapi-to-application-code.md" + "skills": [ + "./skills/openapi-to-application-code/" ] } diff --git a/plugins/php-mcp-development/.github/plugin/plugin.json b/plugins/php-mcp-development/.github/plugin/plugin.json index 8adc99e7a..07a941515 100644 --- a/plugins/php-mcp-development/.github/plugin/plugin.json +++ b/plugins/php-mcp-development/.github/plugin/plugin.json @@ -19,7 +19,7 @@ "agents": [ "./agents/php-mcp-expert.md" ], - "commands": [ - "./commands/php-mcp-server-generator.md" + "skills": [ + "./skills/php-mcp-server-generator/" ] } diff --git a/plugins/power-apps-code-apps/.github/plugin/plugin.json b/plugins/power-apps-code-apps/.github/plugin/plugin.json index d9920f2e1..4955de4f8 100644 --- a/plugins/power-apps-code-apps/.github/plugin/plugin.json +++ b/plugins/power-apps-code-apps/.github/plugin/plugin.json @@ -19,7 +19,7 @@ "agents": [ "./agents/power-platform-expert.md" ], - "commands": [ - "./commands/power-apps-code-app-scaffold.md" + "skills": [ + "./skills/power-apps-code-app-scaffold/" ] } diff --git a/plugins/power-bi-development/.github/plugin/plugin.json b/plugins/power-bi-development/.github/plugin/plugin.json index a50403c24..38452b41f 100644 --- a/plugins/power-bi-development/.github/plugin/plugin.json +++ b/plugins/power-bi-development/.github/plugin/plugin.json @@ -23,10 +23,10 @@ "./agents/power-bi-performance-expert.md", "./agents/power-bi-visualization-expert.md" ], - "commands": [ - "./commands/power-bi-dax-optimization.md", - "./commands/power-bi-model-design-review.md", - "./commands/power-bi-performance-troubleshooting.md", - "./commands/power-bi-report-design-consultation.md" + "skills": [ + "./skills/power-bi-dax-optimization/", + "./skills/power-bi-model-design-review/", + "./skills/power-bi-performance-troubleshooting/", + "./skills/power-bi-report-design-consultation/" ] } diff --git a/plugins/power-platform-mcp-connector-development/.github/plugin/plugin.json b/plugins/power-platform-mcp-connector-development/.github/plugin/plugin.json index 0ef2b9374..aec0c8f35 100644 --- a/plugins/power-platform-mcp-connector-development/.github/plugin/plugin.json +++ b/plugins/power-platform-mcp-connector-development/.github/plugin/plugin.json @@ -17,8 +17,8 @@ "agents": [ "./agents/power-platform-mcp-integration-expert.md" ], - "commands": [ - "./commands/power-platform-mcp-connector-suite.md", - "./commands/mcp-copilot-studio-server-generator.md" + "skills": [ + "./skills/power-platform-mcp-connector-suite/", + "./skills/mcp-copilot-studio-server-generator/" ] } diff --git a/plugins/project-planning/.github/plugin/plugin.json b/plugins/project-planning/.github/plugin/plugin.json index 92317fa13..1f9e4c5f1 100644 --- a/plugins/project-planning/.github/plugin/plugin.json +++ b/plugins/project-planning/.github/plugin/plugin.json @@ -26,14 +26,14 @@ "./agents/implementation-plan.md", "./agents/research-technical-spike.md" ], - "commands": [ - "./commands/breakdown-feature-implementation.md", - "./commands/breakdown-feature-prd.md", - "./commands/breakdown-epic-arch.md", - "./commands/breakdown-epic-pm.md", - "./commands/create-implementation-plan.md", - "./commands/update-implementation-plan.md", - "./commands/create-github-issues-feature-from-implementation-plan.md", - "./commands/create-technical-spike.md" + "skills": [ + "./skills/breakdown-feature-implementation/", + "./skills/breakdown-feature-prd/", + "./skills/breakdown-epic-arch/", + "./skills/breakdown-epic-pm/", + "./skills/create-implementation-plan/", + "./skills/update-implementation-plan/", + "./skills/create-github-issues-feature-from-implementation-plan/", + "./skills/create-technical-spike/" ] } diff --git a/plugins/python-mcp-development/.github/plugin/plugin.json b/plugins/python-mcp-development/.github/plugin/plugin.json index 6b444592f..7bea372fd 100644 --- a/plugins/python-mcp-development/.github/plugin/plugin.json +++ b/plugins/python-mcp-development/.github/plugin/plugin.json @@ -17,7 +17,7 @@ "agents": [ "./agents/python-mcp-expert.md" ], - "commands": [ - "./commands/python-mcp-server-generator.md" + "skills": [ + "./skills/python-mcp-server-generator/" ] } diff --git a/plugins/ruby-mcp-development/.github/plugin/plugin.json b/plugins/ruby-mcp-development/.github/plugin/plugin.json index 76de29bed..b5683ef6c 100644 --- a/plugins/ruby-mcp-development/.github/plugin/plugin.json +++ b/plugins/ruby-mcp-development/.github/plugin/plugin.json @@ -19,7 +19,7 @@ "agents": [ "./agents/ruby-mcp-expert.md" ], - "commands": [ - "./commands/ruby-mcp-server-generator.md" + "skills": [ + "./skills/ruby-mcp-server-generator/" ] } diff --git a/plugins/rust-mcp-development/.github/plugin/plugin.json b/plugins/rust-mcp-development/.github/plugin/plugin.json index 9a0c78edb..5b05a7658 100644 --- a/plugins/rust-mcp-development/.github/plugin/plugin.json +++ b/plugins/rust-mcp-development/.github/plugin/plugin.json @@ -21,7 +21,7 @@ "agents": [ "./agents/rust-mcp-expert.md" ], - "commands": [ - "./commands/rust-mcp-server-generator.md" + "skills": [ + "./skills/rust-mcp-server-generator/" ] } diff --git a/plugins/security-best-practices/.github/plugin/plugin.json b/plugins/security-best-practices/.github/plugin/plugin.json index b80ca9ea8..d2930b7ef 100644 --- a/plugins/security-best-practices/.github/plugin/plugin.json +++ b/plugins/security-best-practices/.github/plugin/plugin.json @@ -17,7 +17,7 @@ "optimization", "best-practices" ], - "commands": [ - "./commands/ai-prompt-engineering-safety-review.md" + "skills": [ + "./skills/ai-prompt-engineering-safety-review/" ] } diff --git a/plugins/structured-autonomy/.github/plugin/plugin.json b/plugins/structured-autonomy/.github/plugin/plugin.json index 524f9df17..4428d5745 100644 --- a/plugins/structured-autonomy/.github/plugin/plugin.json +++ b/plugins/structured-autonomy/.github/plugin/plugin.json @@ -7,9 +7,9 @@ }, "repository": "https://github.com/github/awesome-copilot", "license": "MIT", - "commands": [ - "./commands/structured-autonomy-generate.md", - "./commands/structured-autonomy-implement.md", - "./commands/structured-autonomy-plan.md" + "skills": [ + "./skills/structured-autonomy-generate/", + "./skills/structured-autonomy-implement/", + "./skills/structured-autonomy-plan/" ] } diff --git a/plugins/swift-mcp-development/.github/plugin/plugin.json b/plugins/swift-mcp-development/.github/plugin/plugin.json index 453fa4b1c..e75803d2e 100644 --- a/plugins/swift-mcp-development/.github/plugin/plugin.json +++ b/plugins/swift-mcp-development/.github/plugin/plugin.json @@ -22,7 +22,7 @@ "agents": [ "./agents/swift-mcp-expert.md" ], - "commands": [ - "./commands/swift-mcp-server-generator.md" + "skills": [ + "./skills/swift-mcp-server-generator/" ] } diff --git a/plugins/technical-spike/.github/plugin/plugin.json b/plugins/technical-spike/.github/plugin/plugin.json index 262475919..e706e8da7 100644 --- a/plugins/technical-spike/.github/plugin/plugin.json +++ b/plugins/technical-spike/.github/plugin/plugin.json @@ -16,7 +16,7 @@ "agents": [ "./agents/research-technical-spike.md" ], - "commands": [ - "./commands/create-technical-spike.md" + "skills": [ + "./skills/create-technical-spike/" ] } diff --git a/plugins/testing-automation/.github/plugin/plugin.json b/plugins/testing-automation/.github/plugin/plugin.json index d3afed3d5..3b3256062 100644 --- a/plugins/testing-automation/.github/plugin/plugin.json +++ b/plugins/testing-automation/.github/plugin/plugin.json @@ -23,11 +23,11 @@ "./agents/tdd-refactor.md", "./agents/playwright-tester.md" ], - "commands": [ - "./commands/playwright-explore-website.md", - "./commands/playwright-generate-test.md", - "./commands/csharp-nunit.md", - "./commands/java-junit.md", - "./commands/ai-prompt-engineering-safety-review.md" + "skills": [ + "./skills/playwright-explore-website/", + "./skills/playwright-generate-test/", + "./skills/csharp-nunit/", + "./skills/java-junit/", + "./skills/ai-prompt-engineering-safety-review/" ] } diff --git a/plugins/typescript-mcp-development/.github/plugin/plugin.json b/plugins/typescript-mcp-development/.github/plugin/plugin.json index 49fb4c9f6..c5c5a5230 100644 --- a/plugins/typescript-mcp-development/.github/plugin/plugin.json +++ b/plugins/typescript-mcp-development/.github/plugin/plugin.json @@ -17,7 +17,7 @@ "agents": [ "./agents/typescript-mcp-expert.md" ], - "commands": [ - "./commands/typescript-mcp-server-generator.md" + "skills": [ + "./skills/typescript-mcp-server-generator/" ] } diff --git a/plugins/typespec-m365-copilot/.github/plugin/plugin.json b/plugins/typespec-m365-copilot/.github/plugin/plugin.json index 00337f190..58a030b48 100644 --- a/plugins/typespec-m365-copilot/.github/plugin/plugin.json +++ b/plugins/typespec-m365-copilot/.github/plugin/plugin.json @@ -15,9 +15,9 @@ "agent-development", "microsoft-365" ], - "commands": [ - "./commands/typespec-create-agent.md", - "./commands/typespec-create-api-plugin.md", - "./commands/typespec-api-operations.md" + "skills": [ + "./skills/typespec-create-agent/", + "./skills/typespec-create-api-plugin/", + "./skills/typespec-api-operations/" ] } diff --git a/prompts/add-educational-comments.prompt.md b/skills/add-educational-comments/SKILL.md similarity index 98% rename from prompts/add-educational-comments.prompt.md rename to skills/add-educational-comments/SKILL.md index 3aff544d3..530a1f37b 100644 --- a/prompts/add-educational-comments.prompt.md +++ b/skills/add-educational-comments/SKILL.md @@ -1,7 +1,6 @@ --- -agent: 'agent' +name: add-educational-comments description: 'Add educational comments to the file specified, or prompt asking for file to comment if one is not provided.' -tools: ['edit/editFiles', 'web/fetch', 'todos'] --- # Add Educational Comments diff --git a/prompts/ai-prompt-engineering-safety-review.prompt.md b/skills/ai-prompt-engineering-safety-review/SKILL.md similarity index 97% rename from prompts/ai-prompt-engineering-safety-review.prompt.md rename to skills/ai-prompt-engineering-safety-review/SKILL.md index ad6758343..86d8622d3 100644 --- a/prompts/ai-prompt-engineering-safety-review.prompt.md +++ b/skills/ai-prompt-engineering-safety-review/SKILL.md @@ -1,6 +1,6 @@ --- -description: "Comprehensive AI prompt engineering safety review and improvement prompt. Analyzes prompts for safety, bias, security vulnerabilities, and effectiveness while providing detailed improvement recommendations with extensive frameworks, testing methodologies, and educational content." -agent: 'agent' +name: ai-prompt-engineering-safety-review +description: 'Comprehensive AI prompt engineering safety review and improvement prompt. Analyzes prompts for safety, bias, security vulnerabilities, and effectiveness while providing detailed improvement recommendations with extensive frameworks, testing methodologies, and educational content.' --- # AI Prompt Engineering Safety Review & Improvement @@ -227,4 +227,4 @@ Provide your analysis in the following structured format: - **Maintain educational value** in your explanations - **Follow industry best practices** from Microsoft, OpenAI, and Google AI -Remember: Your goal is to help create prompts that are not only effective but also safe, unbiased, secure, and responsible. Every improvement should enhance both functionality and safety. +Remember: Your goal is to help create prompts that are not only effective but also safe, unbiased, secure, and responsible. Every improvement should enhance both functionality and safety. diff --git a/prompts/apple-appstore-reviewer.prompt.md b/skills/apple-appstore-reviewer/SKILL.md similarity index 97% rename from prompts/apple-appstore-reviewer.prompt.md rename to skills/apple-appstore-reviewer/SKILL.md index f161b7c43..5b49faf46 100644 --- a/prompts/apple-appstore-reviewer.prompt.md +++ b/skills/apple-appstore-reviewer/SKILL.md @@ -1,8 +1,6 @@ --- -agent: "agent" -name: "Apple App Store Reviewer" -tools: ["vscode", "execute", "read", "search", "web", "upstash/context7/*", "agent", "todo"] -description: "Serves as a reviewer of the codebase with instructions on looking for Apple App Store optimizations or rejection reasons." +name: apple-appstore-reviewer +description: 'Serves as a reviewer of the codebase with instructions on looking for Apple App Store optimizations or rejection reasons.' --- # Apple App Store Review Specialist diff --git a/prompts/arch-linux-triage.prompt.md b/skills/arch-linux-triage/SKILL.md similarity index 89% rename from prompts/arch-linux-triage.prompt.md rename to skills/arch-linux-triage/SKILL.md index 6dc7498b9..80d0fced7 100644 --- a/prompts/arch-linux-triage.prompt.md +++ b/skills/arch-linux-triage/SKILL.md @@ -1,8 +1,6 @@ --- -agent: 'agent' +name: arch-linux-triage description: 'Triage and resolve Arch Linux issues with pacman, systemd, and rolling-release best practices.' -model: 'gpt-4.1' -tools: ['search', 'runCommands', 'terminalCommand', 'edit/editFiles'] --- # Arch Linux Triage diff --git a/prompts/architecture-blueprint-generator.prompt.md b/skills/architecture-blueprint-generator/SKILL.md similarity index 99% rename from prompts/architecture-blueprint-generator.prompt.md rename to skills/architecture-blueprint-generator/SKILL.md index 038852f11..a9a24b0e8 100644 --- a/prompts/architecture-blueprint-generator.prompt.md +++ b/skills/architecture-blueprint-generator/SKILL.md @@ -1,6 +1,6 @@ --- +name: architecture-blueprint-generator description: 'Comprehensive project architecture blueprint generator that analyzes codebases to create detailed architectural documentation. Automatically detects technology stacks and architectural patterns, generates visual diagrams, documents implementation patterns, and provides extensible blueprints for maintaining architectural consistency and guiding new development.' -agent: 'agent' --- # Comprehensive Project Architecture Blueprint Generator diff --git a/prompts/aspnet-minimal-api-openapi.prompt.md b/skills/aspnet-minimal-api-openapi/SKILL.md similarity index 95% rename from prompts/aspnet-minimal-api-openapi.prompt.md rename to skills/aspnet-minimal-api-openapi/SKILL.md index 6ee94c014..aae320d6e 100644 --- a/prompts/aspnet-minimal-api-openapi.prompt.md +++ b/skills/aspnet-minimal-api-openapi/SKILL.md @@ -1,6 +1,5 @@ --- -agent: 'agent' -tools: ['changes', 'search/codebase', 'edit/editFiles', 'problems'] +name: aspnet-minimal-api-openapi description: 'Create ASP.NET Minimal API endpoints with proper OpenAPI documentation' --- diff --git a/prompts/az-cost-optimize.prompt.md b/skills/az-cost-optimize/SKILL.md similarity index 99% rename from prompts/az-cost-optimize.prompt.md rename to skills/az-cost-optimize/SKILL.md index 5e1d9aec2..ec619b532 100644 --- a/prompts/az-cost-optimize.prompt.md +++ b/skills/az-cost-optimize/SKILL.md @@ -1,5 +1,5 @@ --- -agent: 'agent' +name: az-cost-optimize description: 'Analyze Azure resources used in the app (IaC files and/or resources in a target rg) and optimize costs - creating GitHub issues for identified optimizations.' --- diff --git a/prompts/azure-resource-health-diagnose.prompt.md b/skills/azure-resource-health-diagnose/SKILL.md similarity index 99% rename from prompts/azure-resource-health-diagnose.prompt.md rename to skills/azure-resource-health-diagnose/SKILL.md index 8f4c769e8..663e02e39 100644 --- a/prompts/azure-resource-health-diagnose.prompt.md +++ b/skills/azure-resource-health-diagnose/SKILL.md @@ -1,5 +1,5 @@ --- -agent: 'agent' +name: azure-resource-health-diagnose description: 'Analyze Azure resource health, diagnose issues from logs and telemetry, and create a remediation plan for identified problems.' --- diff --git a/prompts/bigquery-pipeline-audit.prompt.md b/skills/bigquery-pipeline-audit/SKILL.md similarity index 98% rename from prompts/bigquery-pipeline-audit.prompt.md rename to skills/bigquery-pipeline-audit/SKILL.md index 5031bee55..5894927e2 100644 --- a/prompts/bigquery-pipeline-audit.prompt.md +++ b/skills/bigquery-pipeline-audit/SKILL.md @@ -1,6 +1,5 @@ --- -agent: 'agent' -tools: ['search/codebase', 'edit/editFiles', 'search'] +name: bigquery-pipeline-audit description: 'Audits Python + BigQuery pipelines for cost safety, idempotency, and production readiness. Returns a structured report with exact patch locations.' --- diff --git a/prompts/boost-prompt.prompt.md b/skills/boost-prompt/SKILL.md similarity index 98% rename from prompts/boost-prompt.prompt.md rename to skills/boost-prompt/SKILL.md index 15341165b..f5cd27ff3 100644 --- a/prompts/boost-prompt.prompt.md +++ b/skills/boost-prompt/SKILL.md @@ -1,5 +1,5 @@ --- -agent: agent +name: boost-prompt description: 'Interactive prompt refinement workflow: interrogates scope, deliverables, constraints; copies final markdown to clipboard; never writes code. Requires the Joyride extension.' --- diff --git a/prompts/breakdown-epic-arch.prompt.md b/skills/breakdown-epic-arch/SKILL.md similarity index 99% rename from prompts/breakdown-epic-arch.prompt.md rename to skills/breakdown-epic-arch/SKILL.md index f9ef47410..391719a9e 100644 --- a/prompts/breakdown-epic-arch.prompt.md +++ b/skills/breakdown-epic-arch/SKILL.md @@ -1,5 +1,5 @@ --- -agent: 'agent' +name: breakdown-epic-arch description: 'Prompt for creating the high-level technical architecture for an Epic, based on a Product Requirements Document.' --- diff --git a/prompts/breakdown-epic-pm.prompt.md b/skills/breakdown-epic-pm/SKILL.md similarity index 98% rename from prompts/breakdown-epic-pm.prompt.md rename to skills/breakdown-epic-pm/SKILL.md index b923c5a0f..91e5f2fb2 100644 --- a/prompts/breakdown-epic-pm.prompt.md +++ b/skills/breakdown-epic-pm/SKILL.md @@ -1,5 +1,5 @@ --- -agent: 'agent' +name: breakdown-epic-pm description: 'Prompt for creating an Epic Product Requirements Document (PRD) for a new epic. This PRD will be used as input for generating a technical architecture specification.' --- diff --git a/prompts/breakdown-feature-implementation.prompt.md b/skills/breakdown-feature-implementation/SKILL.md similarity index 99% rename from prompts/breakdown-feature-implementation.prompt.md rename to skills/breakdown-feature-implementation/SKILL.md index e2979a8da..e52e54e88 100644 --- a/prompts/breakdown-feature-implementation.prompt.md +++ b/skills/breakdown-feature-implementation/SKILL.md @@ -1,5 +1,5 @@ --- -agent: 'agent' +name: breakdown-feature-implementation description: 'Prompt for creating detailed feature implementation plans, following Epoch monorepo structure.' --- diff --git a/prompts/breakdown-feature-prd.prompt.md b/skills/breakdown-feature-prd/SKILL.md similarity index 98% rename from prompts/breakdown-feature-prd.prompt.md rename to skills/breakdown-feature-prd/SKILL.md index 03213c031..f758cc438 100644 --- a/prompts/breakdown-feature-prd.prompt.md +++ b/skills/breakdown-feature-prd/SKILL.md @@ -1,5 +1,5 @@ --- -agent: 'agent' +name: breakdown-feature-prd description: 'Prompt for creating Product Requirements Documents (PRDs) for new features, based on an Epic.' --- diff --git a/prompts/breakdown-plan.prompt.md b/skills/breakdown-plan/SKILL.md similarity index 99% rename from prompts/breakdown-plan.prompt.md rename to skills/breakdown-plan/SKILL.md index dbfa3a9f9..9200260a4 100644 --- a/prompts/breakdown-plan.prompt.md +++ b/skills/breakdown-plan/SKILL.md @@ -1,5 +1,5 @@ --- -agent: 'agent' +name: breakdown-plan description: 'Issue Planning and Automation prompt that generates comprehensive project plans with Epic > Feature > Story/Enabler > Test hierarchy, dependencies, priorities, and automated tracking.' --- diff --git a/prompts/breakdown-test.prompt.md b/skills/breakdown-test/SKILL.md similarity index 99% rename from prompts/breakdown-test.prompt.md rename to skills/breakdown-test/SKILL.md index 70b66d975..8db13b659 100644 --- a/prompts/breakdown-test.prompt.md +++ b/skills/breakdown-test/SKILL.md @@ -1,5 +1,5 @@ --- -agent: 'agent' +name: breakdown-test description: 'Test Planning and Quality Assurance prompt that generates comprehensive test strategies, task breakdowns, and quality validation plans for GitHub projects.' --- diff --git a/prompts/centos-linux-triage.prompt.md b/skills/centos-linux-triage/SKILL.md similarity index 90% rename from prompts/centos-linux-triage.prompt.md rename to skills/centos-linux-triage/SKILL.md index 3809a1f89..22d79dab9 100644 --- a/prompts/centos-linux-triage.prompt.md +++ b/skills/centos-linux-triage/SKILL.md @@ -1,8 +1,6 @@ --- -agent: 'agent' +name: centos-linux-triage description: 'Triage and resolve CentOS issues using RHEL-compatible tooling, SELinux-aware practices, and firewalld.' -model: 'gpt-4.1' -tools: ['search', 'runCommands', 'terminalCommand', 'edit/editFiles'] --- # CentOS Linux Triage diff --git a/prompts/code-exemplars-blueprint-generator.prompt.md b/skills/code-exemplars-blueprint-generator/SKILL.md similarity index 99% rename from prompts/code-exemplars-blueprint-generator.prompt.md rename to skills/code-exemplars-blueprint-generator/SKILL.md index c427c9171..2382b7a99 100644 --- a/prompts/code-exemplars-blueprint-generator.prompt.md +++ b/skills/code-exemplars-blueprint-generator/SKILL.md @@ -1,6 +1,6 @@ --- +name: code-exemplars-blueprint-generator description: 'Technology-agnostic prompt generator that creates customizable AI prompts for scanning codebases and identifying high-quality code exemplars. Supports multiple programming languages (.NET, Java, JavaScript, TypeScript, React, Angular, Python) with configurable analysis depth, categorization methods, and documentation formats to establish coding standards and maintain consistency across development teams.' -agent: 'agent' --- # Code Exemplars Blueprint Generator diff --git a/prompts/comment-code-generate-a-tutorial.prompt.md b/skills/comment-code-generate-a-tutorial/SKILL.md similarity index 97% rename from prompts/comment-code-generate-a-tutorial.prompt.md rename to skills/comment-code-generate-a-tutorial/SKILL.md index d5c641308..6ba8f399a 100644 --- a/prompts/comment-code-generate-a-tutorial.prompt.md +++ b/skills/comment-code-generate-a-tutorial/SKILL.md @@ -1,6 +1,6 @@ --- +name: comment-code-generate-a-tutorial description: 'Transform this Python script into a polished, beginner-friendly project by refactoring the code, adding clear instructional comments, and generating a complete markdown tutorial.' -agent: 'agent' --- Transform this Python script into a polished, beginner-friendly project by refactoring the code, adding clear instructional comments, and generating a complete markdown tutorial. diff --git a/prompts/containerize-aspnet-framework.prompt.md b/skills/containerize-aspnet-framework/SKILL.md similarity index 99% rename from prompts/containerize-aspnet-framework.prompt.md rename to skills/containerize-aspnet-framework/SKILL.md index 13a5cfbc5..91fd20165 100644 --- a/prompts/containerize-aspnet-framework.prompt.md +++ b/skills/containerize-aspnet-framework/SKILL.md @@ -1,6 +1,5 @@ --- -agent: 'agent' -tools: ['search/codebase', 'edit/editFiles', 'terminalCommand'] +name: containerize-aspnet-framework description: 'Containerize an ASP.NET .NET Framework project by creating Dockerfile and .dockerfile files customized for the project.' --- diff --git a/prompts/containerize-aspnetcore.prompt.md b/skills/containerize-aspnetcore/SKILL.md similarity index 99% rename from prompts/containerize-aspnetcore.prompt.md rename to skills/containerize-aspnetcore/SKILL.md index b77722456..0a683e2c7 100644 --- a/prompts/containerize-aspnetcore.prompt.md +++ b/skills/containerize-aspnetcore/SKILL.md @@ -1,6 +1,5 @@ --- -agent: 'agent' -tools: ['search/codebase', 'edit/editFiles', 'terminalCommand'] +name: containerize-aspnetcore description: 'Containerize an ASP.NET Core project by creating Dockerfile and .dockerfile files customized for the project.' --- diff --git a/prompts/context-map.prompt.md b/skills/context-map/SKILL.md similarity index 96% rename from prompts/context-map.prompt.md rename to skills/context-map/SKILL.md index d3ab149aa..bb63c552f 100644 --- a/prompts/context-map.prompt.md +++ b/skills/context-map/SKILL.md @@ -1,6 +1,5 @@ --- -agent: 'agent' -tools: ['codebase'] +name: context-map description: 'Generate a map of all files relevant to a task before making changes' --- diff --git a/prompts/conventional-commit.prompt.md b/skills/conventional-commit/SKILL.md similarity index 97% rename from prompts/conventional-commit.prompt.md rename to skills/conventional-commit/SKILL.md index 1bec5f69e..388421775 100644 --- a/prompts/conventional-commit.prompt.md +++ b/skills/conventional-commit/SKILL.md @@ -1,6 +1,6 @@ --- +name: conventional-commit description: 'Prompt and workflow for generating conventional commit messages using a structured XML format. Guides users to create standardized, descriptive commit messages in line with the Conventional Commits specification, including instructions, examples, and validation.' -tools: ['execute/runInTerminal', 'execute/getTerminalOutput'] --- ### Instructions diff --git a/prompts/convert-plaintext-to-md.prompt.md b/skills/convert-plaintext-to-md/SKILL.md similarity index 98% rename from prompts/convert-plaintext-to-md.prompt.md rename to skills/convert-plaintext-to-md/SKILL.md index 4af122dab..c81b2e78a 100644 --- a/prompts/convert-plaintext-to-md.prompt.md +++ b/skills/convert-plaintext-to-md/SKILL.md @@ -1,7 +1,6 @@ --- -agent: agent +name: convert-plaintext-to-md description: 'Convert a text-based document to markdown following instructions from prompt, or if a documented option is passed, follow the instructions for that option.' -tools: ['edit', 'edit/editFiles', 'web/fetch', 'runCommands', 'search', 'search/readFile', 'search/textSearch'] --- # Convert Plaintext Documentation to Markdown diff --git a/prompts/copilot-instructions-blueprint-generator.prompt.md b/skills/copilot-instructions-blueprint-generator/SKILL.md similarity index 99% rename from prompts/copilot-instructions-blueprint-generator.prompt.md rename to skills/copilot-instructions-blueprint-generator/SKILL.md index 7dd6bd4ea..007547da8 100644 --- a/prompts/copilot-instructions-blueprint-generator.prompt.md +++ b/skills/copilot-instructions-blueprint-generator/SKILL.md @@ -1,6 +1,6 @@ --- +name: copilot-instructions-blueprint-generator description: 'Technology-agnostic blueprint generator for creating comprehensive copilot-instructions.md files that guide GitHub Copilot to produce code consistent with project standards, architecture patterns, and exact technology versions by analyzing existing codebase patterns and avoiding assumptions.' -agent: 'agent' --- # Copilot Instructions Blueprint Generator @@ -291,4 +291,4 @@ Important: Only include guidance based on patterns actually observed in the code ## Expected Output -A comprehensive copilot-instructions.md file that will guide GitHub Copilot to produce code that is perfectly compatible with your existing technology versions and follows your established patterns and architecture. \ No newline at end of file +A comprehensive copilot-instructions.md file that will guide GitHub Copilot to produce code that is perfectly compatible with your existing technology versions and follows your established patterns and architecture. diff --git a/prompts/cosmosdb-datamodeling.prompt.md b/skills/cosmosdb-datamodeling/SKILL.md similarity index 99% rename from prompts/cosmosdb-datamodeling.prompt.md rename to skills/cosmosdb-datamodeling/SKILL.md index 0c56405d8..4fdf69a1b 100644 --- a/prompts/cosmosdb-datamodeling.prompt.md +++ b/skills/cosmosdb-datamodeling/SKILL.md @@ -1,8 +1,8 @@ --- -agent: 'agent' +name: cosmosdb-datamodeling description: 'Step-by-step guide for capturing key application requirements for NoSQL use-case and produce Azure Cosmos DB Data NoSQL Model design using best practices and common patterns, artifacts_produced: "cosmosdb_requirements.md" file and "cosmosdb_data_model.md" file' -model: 'Claude Sonnet 4' --- + # Azure Cosmos DB NoSQL Data Modeling Expert System Prompt - version: 1.0 diff --git a/prompts/create-agentsmd.prompt.md b/skills/create-agentsmd/SKILL.md similarity index 98% rename from prompts/create-agentsmd.prompt.md rename to skills/create-agentsmd/SKILL.md index 1c3e812c7..bdcfcf7c9 100644 --- a/prompts/create-agentsmd.prompt.md +++ b/skills/create-agentsmd/SKILL.md @@ -1,6 +1,6 @@ --- -description: "Prompt for generating an AGENTS.md file for a repository" -agent: "agent" +name: create-agentsmd +description: 'Prompt for generating an AGENTS.md file for a repository' --- # Create high‑quality AGENTS.md file diff --git a/prompts/create-architectural-decision-record.prompt.md b/skills/create-architectural-decision-record/SKILL.md similarity index 91% rename from prompts/create-architectural-decision-record.prompt.md rename to skills/create-architectural-decision-record/SKILL.md index 5b1840b8a..be10104fa 100644 --- a/prompts/create-architectural-decision-record.prompt.md +++ b/skills/create-architectural-decision-record/SKILL.md @@ -1,8 +1,8 @@ --- -agent: 'agent' +name: create-architectural-decision-record description: 'Create an Architectural Decision Record (ADR) document for AI-optimized decision documentation.' -tools: ['changes', 'search/codebase', 'edit/editFiles', 'extensions', 'web/fetch', 'githubRepo', 'openSimpleBrowser', 'problems', 'runTasks', 'search', 'search/searchResults', 'runCommands/terminalLastCommand', 'runCommands/terminalSelection', 'testFailure', 'usages', 'vscodeAPI'] --- + # Create Architectural Decision Record Create an ADR document for `${input:DecisionTitle}` using structured formatting optimized for AI consumption and human readability. diff --git a/prompts/create-github-action-workflow-specification.prompt.md b/skills/create-github-action-workflow-specification/SKILL.md similarity index 94% rename from prompts/create-github-action-workflow-specification.prompt.md rename to skills/create-github-action-workflow-specification/SKILL.md index 9979f4e55..cfd4bf2e6 100644 --- a/prompts/create-github-action-workflow-specification.prompt.md +++ b/skills/create-github-action-workflow-specification/SKILL.md @@ -1,8 +1,8 @@ --- -agent: 'agent' +name: create-github-action-workflow-specification description: 'Create a formal specification for an existing GitHub Actions CI/CD workflow, optimized for AI consumption and workflow maintenance.' -tools: ['changes', 'search/codebase', 'edit/editFiles', 'extensions', 'web/fetch', 'findTestFiles', 'githubRepo', 'new', 'openSimpleBrowser', 'problems', 'runCommands', 'runInTerminal2', 'runNotebooks', 'runTasks', 'runTests', 'search', 'search/searchResults', 'runCommands/terminalLastCommand', 'runCommands/terminalSelection', 'testFailure', 'usages', 'vscodeAPI', 'microsoft.docs.mcp', 'github', 'Microsoft Docs'] --- + # Create GitHub Actions Workflow Specification Create a comprehensive specification for the GitHub Actions workflow: `${input:WorkflowFile}`. diff --git a/prompts/create-github-issue-feature-from-specification.prompt.md b/skills/create-github-issue-feature-from-specification/SKILL.md similarity index 88% rename from prompts/create-github-issue-feature-from-specification.prompt.md rename to skills/create-github-issue-feature-from-specification/SKILL.md index f5d7631a8..0a95a108d 100644 --- a/prompts/create-github-issue-feature-from-specification.prompt.md +++ b/skills/create-github-issue-feature-from-specification/SKILL.md @@ -1,8 +1,8 @@ --- -agent: 'agent' +name: create-github-issue-feature-from-specification description: 'Create GitHub Issue for feature request from specification file using feature_request.yml template.' -tools: ['search/codebase', 'search', 'github', 'create_issue', 'search_issues', 'update_issue'] --- + # Create GitHub Issue from Specification Create GitHub Issue for the specification at `${file}`. diff --git a/prompts/create-github-issues-feature-from-implementation-plan.prompt.md b/skills/create-github-issues-feature-from-implementation-plan/SKILL.md similarity index 88% rename from prompts/create-github-issues-feature-from-implementation-plan.prompt.md rename to skills/create-github-issues-feature-from-implementation-plan/SKILL.md index 2c68b2268..e0d8662b1 100644 --- a/prompts/create-github-issues-feature-from-implementation-plan.prompt.md +++ b/skills/create-github-issues-feature-from-implementation-plan/SKILL.md @@ -1,8 +1,8 @@ --- -agent: 'agent' +name: create-github-issues-feature-from-implementation-plan description: 'Create GitHub Issues from implementation plan phases using feature_request.yml or chore_request.yml templates.' -tools: ['search/codebase', 'search', 'github', 'create_issue', 'search_issues', 'update_issue'] --- + # Create GitHub Issue from Implementation Plan Create GitHub Issues for the implementation plan at `${file}`. diff --git a/prompts/create-github-issues-for-unmet-specification-requirements.prompt.md b/skills/create-github-issues-for-unmet-specification-requirements/SKILL.md similarity index 91% rename from prompts/create-github-issues-for-unmet-specification-requirements.prompt.md rename to skills/create-github-issues-for-unmet-specification-requirements/SKILL.md index 02a9e8aaf..54c469f3d 100644 --- a/prompts/create-github-issues-for-unmet-specification-requirements.prompt.md +++ b/skills/create-github-issues-for-unmet-specification-requirements/SKILL.md @@ -1,8 +1,8 @@ --- -agent: 'agent' +name: create-github-issues-for-unmet-specification-requirements description: 'Create GitHub Issues for unimplemented requirements from specification files using feature_request.yml template.' -tools: ['search/codebase', 'search', 'github', 'create_issue', 'search_issues', 'update_issue'] --- + # Create GitHub Issues for Unmet Specification Requirements Create GitHub Issues for unimplemented requirements in the specification at `${file}`. diff --git a/prompts/create-github-pull-request-from-specification.prompt.md b/skills/create-github-pull-request-from-specification/SKILL.md similarity index 92% rename from prompts/create-github-pull-request-from-specification.prompt.md rename to skills/create-github-pull-request-from-specification/SKILL.md index 4eb780d2f..68fa44f5b 100644 --- a/prompts/create-github-pull-request-from-specification.prompt.md +++ b/skills/create-github-pull-request-from-specification/SKILL.md @@ -1,8 +1,8 @@ --- -agent: 'agent' +name: create-github-pull-request-from-specification description: 'Create GitHub Pull Request for feature request from specification file using pull_request_template.md template.' -tools: ['search/codebase', 'search', 'github', 'create_pull_request', 'update_pull_request', 'get_pull_request_diff'] --- + # Create GitHub Pull Request from Specification Create GitHub Pull Request for the specification at `${workspaceFolder}/.github/pull_request_template.md` . diff --git a/prompts/create-implementation-plan.prompt.md b/skills/create-implementation-plan/SKILL.md similarity index 95% rename from prompts/create-implementation-plan.prompt.md rename to skills/create-implementation-plan/SKILL.md index ffc0bc0fe..08a91438b 100644 --- a/prompts/create-implementation-plan.prompt.md +++ b/skills/create-implementation-plan/SKILL.md @@ -1,8 +1,8 @@ --- -agent: 'agent' +name: create-implementation-plan description: 'Create a new implementation plan file for new features, refactoring existing code or upgrading packages, design, architecture or infrastructure.' -tools: ['changes', 'search/codebase', 'edit/editFiles', 'extensions', 'web/fetch', 'githubRepo', 'openSimpleBrowser', 'problems', 'runTasks', 'search', 'search/searchResults', 'runCommands/terminalLastCommand', 'runCommands/terminalSelection', 'testFailure', 'usages', 'vscodeAPI'] --- + # Create Implementation Plan ## Primary Directive diff --git a/prompts/create-llms.prompt.md b/skills/create-llms/SKILL.md similarity index 96% rename from prompts/create-llms.prompt.md rename to skills/create-llms/SKILL.md index c9e5e58f8..d9b01dc77 100644 --- a/prompts/create-llms.prompt.md +++ b/skills/create-llms/SKILL.md @@ -1,8 +1,8 @@ --- -agent: 'agent' +name: create-llms description: 'Create an llms.txt file from scratch based on repository structure following the llms.txt specification at https://llmstxt.org/' -tools: ['changes', 'search/codebase', 'edit/editFiles', 'extensions', 'web/fetch', 'githubRepo', 'openSimpleBrowser', 'problems', 'runTasks', 'search', 'search/searchResults', 'runCommands/terminalLastCommand', 'runCommands/terminalSelection', 'testFailure', 'usages', 'vscodeAPI'] --- + # Create LLMs.txt File from Repository Structure Create a new `llms.txt` file from scratch in the root of the repository following the official llms.txt specification at https://llmstxt.org/. This file provides high-level guidance to large language models (LLMs) on where to find relevant content for understanding the repository's purpose and specifications. diff --git a/prompts/create-oo-component-documentation.prompt.md b/skills/create-oo-component-documentation/SKILL.md similarity index 95% rename from prompts/create-oo-component-documentation.prompt.md rename to skills/create-oo-component-documentation/SKILL.md index 33bb0cf92..034325988 100644 --- a/prompts/create-oo-component-documentation.prompt.md +++ b/skills/create-oo-component-documentation/SKILL.md @@ -1,8 +1,8 @@ --- -agent: 'agent' +name: create-oo-component-documentation description: 'Create comprehensive, standardized documentation for object-oriented components following industry best practices and architectural documentation standards.' -tools: ['changes', 'search/codebase', 'edit/editFiles', 'extensions', 'web/fetch', 'githubRepo', 'openSimpleBrowser', 'problems', 'runTasks', 'search', 'search/searchResults', 'runCommands/terminalLastCommand', 'runCommands/terminalSelection', 'testFailure', 'usages', 'vscodeAPI'] --- + # Generate Standard OO Component Documentation Create comprehensive documentation for the object-oriented component(s) at: `${input:ComponentPath}`. diff --git a/prompts/create-readme.prompt.md b/skills/create-readme/SKILL.md similarity index 98% rename from prompts/create-readme.prompt.md rename to skills/create-readme/SKILL.md index 1a92ca1a4..686e10d51 100644 --- a/prompts/create-readme.prompt.md +++ b/skills/create-readme/SKILL.md @@ -1,5 +1,5 @@ --- -agent: 'agent' +name: create-readme description: 'Create a README.md file for the project' --- diff --git a/prompts/create-specification.prompt.md b/skills/create-specification/SKILL.md similarity index 94% rename from prompts/create-specification.prompt.md rename to skills/create-specification/SKILL.md index 08093e046..fa53eab8c 100644 --- a/prompts/create-specification.prompt.md +++ b/skills/create-specification/SKILL.md @@ -1,8 +1,8 @@ --- -agent: 'agent' +name: create-specification description: 'Create a new specification file for the solution, optimized for Generative AI consumption.' -tools: ['changes', 'search/codebase', 'edit/editFiles', 'extensions', 'web/fetch', 'githubRepo', 'openSimpleBrowser', 'problems', 'runTasks', 'search', 'search/searchResults', 'runCommands/terminalLastCommand', 'runCommands/terminalSelection', 'testFailure', 'usages', 'vscodeAPI'] --- + # Create Specification Your goal is to create a new specification file for `${input:SpecPurpose}`. diff --git a/prompts/create-spring-boot-java-project.prompt.md b/skills/create-spring-boot-java-project/SKILL.md similarity index 99% rename from prompts/create-spring-boot-java-project.prompt.md rename to skills/create-spring-boot-java-project/SKILL.md index 4d227e89a..890666dac 100644 --- a/prompts/create-spring-boot-java-project.prompt.md +++ b/skills/create-spring-boot-java-project/SKILL.md @@ -1,5 +1,5 @@ --- -agent: 'agent' +name: create-spring-boot-java-project description: 'Create Spring Boot Java Project Skeleton' --- diff --git a/prompts/create-spring-boot-kotlin-project.prompt.md b/skills/create-spring-boot-kotlin-project/SKILL.md similarity index 99% rename from prompts/create-spring-boot-kotlin-project.prompt.md rename to skills/create-spring-boot-kotlin-project/SKILL.md index 3554cd578..02bbd1891 100644 --- a/prompts/create-spring-boot-kotlin-project.prompt.md +++ b/skills/create-spring-boot-kotlin-project/SKILL.md @@ -1,5 +1,5 @@ --- -agent: 'agent' +name: create-spring-boot-kotlin-project description: 'Create Spring Boot Kotlin Project Skeleton' --- diff --git a/prompts/create-technical-spike.prompt.md b/skills/create-technical-spike/SKILL.md similarity index 96% rename from prompts/create-technical-spike.prompt.md rename to skills/create-technical-spike/SKILL.md index 678b89e35..bac8a01d6 100644 --- a/prompts/create-technical-spike.prompt.md +++ b/skills/create-technical-spike/SKILL.md @@ -1,7 +1,6 @@ --- -agent: 'agent' +name: create-technical-spike description: 'Create time-boxed technical spike documents for researching and resolving critical development decisions before implementation.' -tools: ['runCommands', 'runTasks', 'edit', 'search', 'extensions', 'usages', 'vscodeAPI', 'think', 'problems', 'changes', 'testFailure', 'openSimpleBrowser', 'web/fetch', 'githubRepo', 'todos', 'Microsoft Docs', 'search'] --- # Create Technical Spike Document diff --git a/prompts/create-tldr-page.prompt.md b/skills/create-tldr-page/SKILL.md similarity index 99% rename from prompts/create-tldr-page.prompt.md rename to skills/create-tldr-page/SKILL.md index fa5f67516..f9542ddc0 100644 --- a/prompts/create-tldr-page.prompt.md +++ b/skills/create-tldr-page/SKILL.md @@ -1,7 +1,6 @@ --- -agent: 'agent' +name: create-tldr-page description: 'Create a tldr page from documentation URLs and command examples, requiring both URL and command name.' -tools: ['edit/createFile', 'web/fetch'] --- # Create TLDR Page diff --git a/prompts/csharp-async.prompt.md b/skills/csharp-async/SKILL.md similarity index 95% rename from prompts/csharp-async.prompt.md rename to skills/csharp-async/SKILL.md index 8291c3504..4dbe78b0b 100644 --- a/prompts/csharp-async.prompt.md +++ b/skills/csharp-async/SKILL.md @@ -1,6 +1,5 @@ --- -agent: 'agent' -tools: ['changes', 'search/codebase', 'edit/editFiles', 'problems'] +name: csharp-async description: 'Get best practices for C# async programming' --- diff --git a/prompts/csharp-docs.prompt.md b/skills/csharp-docs/SKILL.md similarity index 97% rename from prompts/csharp-docs.prompt.md rename to skills/csharp-docs/SKILL.md index 23687706c..6c673064b 100644 --- a/prompts/csharp-docs.prompt.md +++ b/skills/csharp-docs/SKILL.md @@ -1,6 +1,5 @@ --- -agent: 'agent' -tools: ['changes', 'search/codebase', 'edit/editFiles', 'problems'] +name: csharp-docs description: 'Ensure that C# types are documented with XML comments and follow best practices for documentation.' --- diff --git a/prompts/csharp-mcp-server-generator.prompt.md b/skills/csharp-mcp-server-generator/SKILL.md similarity index 98% rename from prompts/csharp-mcp-server-generator.prompt.md rename to skills/csharp-mcp-server-generator/SKILL.md index e0218d01f..e36ae2fe5 100644 --- a/prompts/csharp-mcp-server-generator.prompt.md +++ b/skills/csharp-mcp-server-generator/SKILL.md @@ -1,5 +1,5 @@ --- -agent: 'agent' +name: csharp-mcp-server-generator description: 'Generate a complete MCP server project in C# with tools, prompts, and proper configuration' --- diff --git a/prompts/csharp-mstest.prompt.md b/skills/csharp-mstest/SKILL.md similarity index 99% rename from prompts/csharp-mstest.prompt.md rename to skills/csharp-mstest/SKILL.md index 9a27bda81..e68bc31ea 100644 --- a/prompts/csharp-mstest.prompt.md +++ b/skills/csharp-mstest/SKILL.md @@ -1,6 +1,5 @@ --- -agent: 'agent' -tools: ['changes', 'search/codebase', 'edit/editFiles', 'problems', 'search'] +name: csharp-mstest description: 'Get best practices for MSTest 3.x/4.x unit testing, including modern assertion APIs and data-driven tests' --- diff --git a/prompts/csharp-nunit.prompt.md b/skills/csharp-nunit/SKILL.md similarity index 96% rename from prompts/csharp-nunit.prompt.md rename to skills/csharp-nunit/SKILL.md index d9b200d3b..7890775bd 100644 --- a/prompts/csharp-nunit.prompt.md +++ b/skills/csharp-nunit/SKILL.md @@ -1,6 +1,5 @@ --- -agent: 'agent' -tools: ['changes', 'search/codebase', 'edit/editFiles', 'problems', 'search'] +name: csharp-nunit description: 'Get best practices for NUnit unit testing, including data-driven tests' --- diff --git a/prompts/csharp-tunit.prompt.md b/skills/csharp-tunit/SKILL.md similarity index 98% rename from prompts/csharp-tunit.prompt.md rename to skills/csharp-tunit/SKILL.md index eb7cbfb8e..c972ebe1f 100644 --- a/prompts/csharp-tunit.prompt.md +++ b/skills/csharp-tunit/SKILL.md @@ -1,6 +1,5 @@ --- -agent: 'agent' -tools: ['changes', 'search/codebase', 'edit/editFiles', 'problems', 'search'] +name: csharp-tunit description: 'Get best practices for TUnit unit testing, including data-driven tests' --- diff --git a/prompts/csharp-xunit.prompt.md b/skills/csharp-xunit/SKILL.md similarity index 96% rename from prompts/csharp-xunit.prompt.md rename to skills/csharp-xunit/SKILL.md index 2859d2276..4347c5aa5 100644 --- a/prompts/csharp-xunit.prompt.md +++ b/skills/csharp-xunit/SKILL.md @@ -1,6 +1,5 @@ --- -agent: 'agent' -tools: ['changes', 'search/codebase', 'edit/editFiles', 'problems', 'search'] +name: csharp-xunit description: 'Get best practices for XUnit unit testing, including data-driven tests' --- diff --git a/prompts/dataverse-python-advanced-patterns.prompt.md b/skills/dataverse-python-advanced-patterns/SKILL.md similarity index 85% rename from prompts/dataverse-python-advanced-patterns.prompt.md rename to skills/dataverse-python-advanced-patterns/SKILL.md index b48c9a49f..921ab6033 100644 --- a/prompts/dataverse-python-advanced-patterns.prompt.md +++ b/skills/dataverse-python-advanced-patterns/SKILL.md @@ -1,7 +1,8 @@ --- -name: Dataverse Python Advanced Patterns -description: Generate production code for Dataverse SDK using advanced patterns, error handling, and optimization techniques. +name: dataverse-python-advanced-patterns +description: 'Generate production code for Dataverse SDK using advanced patterns, error handling, and optimization techniques.' --- + You are a Dataverse SDK for Python expert. Generate production-ready Python code that demonstrates: 1. **Error handling & retry logic** β€” Catch DataverseError, check is_transient, implement exponential backoff. diff --git a/prompts/dataverse-python-production-code.prompt.md b/skills/dataverse-python-production-code/SKILL.md similarity index 95% rename from prompts/dataverse-python-production-code.prompt.md rename to skills/dataverse-python-production-code/SKILL.md index 750faeade..932c459f2 100644 --- a/prompts/dataverse-python-production-code.prompt.md +++ b/skills/dataverse-python-production-code/SKILL.md @@ -1,6 +1,6 @@ --- -name: "Dataverse Python - Production Code Generator" -description: "Generate production-ready Python code using Dataverse SDK with error handling, optimization, and best practices" +name: dataverse-python-production-code +description: 'Generate production-ready Python code using Dataverse SDK with error handling, optimization, and best practices' --- # System Instructions diff --git a/prompts/dataverse-python-quickstart.prompt.md b/skills/dataverse-python-quickstart/SKILL.md similarity index 78% rename from prompts/dataverse-python-quickstart.prompt.md rename to skills/dataverse-python-quickstart/SKILL.md index 409c1784b..4f0a200c6 100644 --- a/prompts/dataverse-python-quickstart.prompt.md +++ b/skills/dataverse-python-quickstart/SKILL.md @@ -1,7 +1,8 @@ --- -name: Dataverse Python Quickstart Generator -description: Generate Python SDK setup + CRUD + bulk + paging snippets using official patterns. +name: dataverse-python-quickstart +description: 'Generate Python SDK setup + CRUD + bulk + paging snippets using official patterns.' --- + You are assisting with Microsoft Dataverse SDK for Python (preview). Generate concise Python snippets that: - Install the SDK (pip install PowerPlatform-Dataverse-Client) diff --git a/prompts/dataverse-python-usecase-builder.prompt.md b/skills/dataverse-python-usecase-builder/SKILL.md similarity index 97% rename from prompts/dataverse-python-usecase-builder.prompt.md rename to skills/dataverse-python-usecase-builder/SKILL.md index 914fc9aa8..667d69732 100644 --- a/prompts/dataverse-python-usecase-builder.prompt.md +++ b/skills/dataverse-python-usecase-builder/SKILL.md @@ -1,6 +1,6 @@ --- -name: "Dataverse Python - Use Case Solution Builder" -description: "Generate complete solutions for specific Dataverse SDK use cases with architecture recommendations" +name: dataverse-python-usecase-builder +description: 'Generate complete solutions for specific Dataverse SDK use cases with architecture recommendations' --- # System Instructions diff --git a/prompts/debian-linux-triage.prompt.md b/skills/debian-linux-triage/SKILL.md similarity index 90% rename from prompts/debian-linux-triage.prompt.md rename to skills/debian-linux-triage/SKILL.md index 1d4a298cf..9e1227502 100644 --- a/prompts/debian-linux-triage.prompt.md +++ b/skills/debian-linux-triage/SKILL.md @@ -1,8 +1,6 @@ --- -agent: 'agent' +name: debian-linux-triage description: 'Triage and resolve Debian Linux issues with apt, systemd, and AppArmor-aware guidance.' -model: 'gpt-4.1' -tools: ['search', 'runCommands', 'terminalCommand', 'edit/editFiles'] --- # Debian Linux Triage diff --git a/prompts/declarative-agents.prompt.md b/skills/declarative-agents/SKILL.md similarity index 94% rename from prompts/declarative-agents.prompt.md rename to skills/declarative-agents/SKILL.md index 2949ff05b..be11c5e64 100644 --- a/prompts/declarative-agents.prompt.md +++ b/skills/declarative-agents/SKILL.md @@ -1,5 +1,6 @@ --- -description: Complete development kit for Microsoft 365 Copilot declarative agents with three comprehensive workflows (basic, advanced, validation), TypeSpec support, and Microsoft 365 Agents Toolkit integration +name: declarative-agents +description: 'Complete development kit for Microsoft 365 Copilot declarative agents with three comprehensive workflows (basic, advanced, validation), TypeSpec support, and Microsoft 365 Agents Toolkit integration' --- # Microsoft 365 Declarative Agents Development Kit @@ -90,4 +91,4 @@ model MyAgent { } ``` -**Which workflow would you like to start with?** Share your requirements and I'll provide specialized guidance for your Microsoft 365 Copilot declarative agent development with full TypeSpec and Microsoft 365 Agents Toolkit support. \ No newline at end of file +**Which workflow would you like to start with?** Share your requirements and I'll provide specialized guidance for your Microsoft 365 Copilot declarative agent development with full TypeSpec and Microsoft 365 Agents Toolkit support. diff --git a/prompts/devops-rollout-plan.prompt.md b/skills/devops-rollout-plan/SKILL.md similarity index 98% rename from prompts/devops-rollout-plan.prompt.md rename to skills/devops-rollout-plan/SKILL.md index cd8278eb6..7da7c32dc 100644 --- a/prompts/devops-rollout-plan.prompt.md +++ b/skills/devops-rollout-plan/SKILL.md @@ -1,7 +1,6 @@ --- -agent: 'agent' +name: devops-rollout-plan description: 'Generate comprehensive rollout plans with preflight checks, step-by-step deployment, verification signals, rollback procedures, and communication plans for infrastructure and application changes' -tools: ['codebase', 'terminalCommand', 'search', 'githubRepo'] --- # DevOps Rollout Plan Generator diff --git a/prompts/documentation-writer.prompt.md b/skills/documentation-writer/SKILL.md similarity index 97% rename from prompts/documentation-writer.prompt.md rename to skills/documentation-writer/SKILL.md index 88c71ad3c..93e3fbf57 100644 --- a/prompts/documentation-writer.prompt.md +++ b/skills/documentation-writer/SKILL.md @@ -1,6 +1,5 @@ --- -agent: 'agent' -tools: ['edit/editFiles', 'search', 'web/fetch'] +name: documentation-writer description: 'DiΓ‘taxis Documentation Expert. An expert technical writer specializing in creating high-quality software documentation, guided by the principles and structure of the DiΓ‘taxis technical documentation authoring framework.' --- diff --git a/prompts/dotnet-best-practices.prompt.md b/skills/dotnet-best-practices/SKILL.md similarity index 99% rename from prompts/dotnet-best-practices.prompt.md rename to skills/dotnet-best-practices/SKILL.md index cad0f15e9..183d3beb1 100644 --- a/prompts/dotnet-best-practices.prompt.md +++ b/skills/dotnet-best-practices/SKILL.md @@ -1,7 +1,8 @@ --- -agent: 'agent' +name: dotnet-best-practices description: 'Ensure .NET/C# code meets best practices for the solution/project.' --- + # .NET/C# Best Practices Your task is to ensure .NET/C# code in ${selection} meets the best practices specific to this solution/project. This includes: diff --git a/prompts/dotnet-design-pattern-review.prompt.md b/skills/dotnet-design-pattern-review/SKILL.md similarity index 98% rename from prompts/dotnet-design-pattern-review.prompt.md rename to skills/dotnet-design-pattern-review/SKILL.md index 13ade4c08..5d9ded0c5 100644 --- a/prompts/dotnet-design-pattern-review.prompt.md +++ b/skills/dotnet-design-pattern-review/SKILL.md @@ -1,7 +1,8 @@ --- -agent: 'agent' +name: dotnet-design-pattern-review description: 'Review the C#/.NET code for design pattern implementation and suggest improvements.' --- + # .NET/C# Design Pattern Review Review the C#/.NET code in ${selection} for design pattern implementation and suggest improvements for the solution/project. Do not make any changes to the code, just provide a review. diff --git a/prompts/dotnet-upgrade.prompt.md b/skills/dotnet-upgrade/SKILL.md similarity index 97% rename from prompts/dotnet-upgrade.prompt.md rename to skills/dotnet-upgrade/SKILL.md index 26a88240d..93ca7605b 100644 --- a/prompts/dotnet-upgrade.prompt.md +++ b/skills/dotnet-upgrade/SKILL.md @@ -1,8 +1,9 @@ --- -name: ".NET Upgrade Analysis Prompts" -description: "Ready-to-use prompts for comprehensive .NET framework upgrade analysis and execution" +name: dotnet-upgrade +description: 'Ready-to-use prompts for comprehensive .NET framework upgrade analysis and execution' --- - # Project Discovery & Assessment + +# Project Discovery & Assessment - name: "Project Classification Analysis" prompt: "Identify all projects in the solution and classify them by type (`.NET Framework`, `.NET Core`, `.NET Standard`). Analyze each `.csproj` for its current `TargetFramework` and SDK usage." diff --git a/prompts/editorconfig.prompt.md b/skills/editorconfig/SKILL.md similarity index 98% rename from prompts/editorconfig.prompt.md rename to skills/editorconfig/SKILL.md index 23d6348ee..d21ff43bf 100644 --- a/prompts/editorconfig.prompt.md +++ b/skills/editorconfig/SKILL.md @@ -1,7 +1,6 @@ --- -name: 'EditorConfig Expert' +name: editorconfig description: 'Generates a comprehensive and best-practice-oriented .editorconfig file based on project analysis and user preferences.' -agent: 'agent' --- ## πŸ“œ MISSION diff --git a/prompts/ef-core.prompt.md b/skills/ef-core/SKILL.md similarity index 96% rename from prompts/ef-core.prompt.md rename to skills/ef-core/SKILL.md index 9dbfb9790..eea8ee478 100644 --- a/prompts/ef-core.prompt.md +++ b/skills/ef-core/SKILL.md @@ -1,6 +1,5 @@ --- -agent: 'agent' -tools: ['changes', 'search/codebase', 'edit/editFiles', 'problems', 'runCommands'] +name: ef-core description: 'Get best practices for Entity Framework Core' --- diff --git a/prompts/fedora-linux-triage.prompt.md b/skills/fedora-linux-triage/SKILL.md similarity index 89% rename from prompts/fedora-linux-triage.prompt.md rename to skills/fedora-linux-triage/SKILL.md index 317447f8a..8c3545e51 100644 --- a/prompts/fedora-linux-triage.prompt.md +++ b/skills/fedora-linux-triage/SKILL.md @@ -1,8 +1,6 @@ --- -agent: 'agent' +name: fedora-linux-triage description: 'Triage and resolve Fedora issues with dnf, systemd, and SELinux-aware guidance.' -model: 'gpt-4.1' -tools: ['search', 'runCommands', 'terminalCommand', 'edit/editFiles'] --- # Fedora Linux Triage diff --git a/prompts/finalize-agent-prompt.prompt.md b/skills/finalize-agent-prompt/SKILL.md similarity index 95% rename from prompts/finalize-agent-prompt.prompt.md rename to skills/finalize-agent-prompt/SKILL.md index c77949d30..54b8647e2 100644 --- a/prompts/finalize-agent-prompt.prompt.md +++ b/skills/finalize-agent-prompt/SKILL.md @@ -1,7 +1,6 @@ --- -agent: 'agent' +name: finalize-agent-prompt description: 'Finalize prompt file using the role of an AI agent to polish the prompt for the end user.' -tools: ['edit/editFiles'] --- # Finalize Agent Prompt diff --git a/prompts/first-ask.prompt.md b/skills/first-ask/SKILL.md similarity index 98% rename from prompts/first-ask.prompt.md rename to skills/first-ask/SKILL.md index fb806998d..edc441307 100644 --- a/prompts/first-ask.prompt.md +++ b/skills/first-ask/SKILL.md @@ -1,4 +1,5 @@ --- +name: first-ask description: 'Interactive, input-tool powered, task refinement workflow: interrogates scope, deliverables, constraints before carrying out the task; Requires the Joyride extension.' --- diff --git a/prompts/folder-structure-blueprint-generator.prompt.md b/skills/folder-structure-blueprint-generator/SKILL.md similarity index 99% rename from prompts/folder-structure-blueprint-generator.prompt.md rename to skills/folder-structure-blueprint-generator/SKILL.md index 3afce1555..7eb0abd65 100644 --- a/prompts/folder-structure-blueprint-generator.prompt.md +++ b/skills/folder-structure-blueprint-generator/SKILL.md @@ -1,6 +1,6 @@ --- +name: folder-structure-blueprint-generator description: 'Comprehensive technology-agnostic prompt for analyzing and documenting project folder structures. Auto-detects project types (.NET, Java, React, Angular, Python, Node.js, Flutter), generates detailed blueprints with visualization options, naming conventions, file placement patterns, and extension templates for maintaining consistent code organization across diverse technology stacks.' -agent: 'agent' --- # Project Folder Structure Blueprint Generator diff --git a/skills/game-engine/SKILL.md b/skills/game-engine/SKILL.md new file mode 100644 index 000000000..5f705898a --- /dev/null +++ b/skills/game-engine/SKILL.md @@ -0,0 +1,139 @@ +--- +name: game-engine +description: 'Expert skill for building web-based game engines and games using HTML5, Canvas, WebGL, and JavaScript. Use when asked to create games, build game engines, implement game physics, handle collision detection, set up game loops, manage sprites, add game controls, or work with 2D/3D rendering. Covers techniques for platformers, breakout-style games, maze games, tilemaps, audio, multiplayer via WebRTC, and publishing games.' +--- + +# Game Engine Skill + +Build web-based games and game engines using HTML5 Canvas, WebGL, and JavaScript. This skill includes starter templates, reference documentation, and step-by-step workflows for 2D and 3D game development with frameworks such as Phaser, Three.js, Babylon.js, and A-Frame. + +## When to Use This Skill + +- Building a game engine or game from scratch using web technologies +- Implementing game loops, physics, collision detection, or rendering +- Working with HTML5 Canvas, WebGL, or SVG for game graphics +- Adding game controls (keyboard, mouse, touch, gamepad) +- Creating 2D platformers, breakout-style games, maze games, or 3D experiences +- Working with tilemaps, sprites, or animations +- Adding audio to web games +- Implementing multiplayer features with WebRTC or WebSockets +- Optimizing game performance +- Publishing and distributing web games + +## Prerequisites + +- Basic knowledge of HTML, CSS, and JavaScript +- A modern web browser with Canvas/WebGL support +- A text editor or IDE +- Optional: Node.js for build tooling and local development servers + +## Core Concepts + +The following concepts form the foundation of every web-based game engine. + +### Game Loop + +Every game engine revolves around the game loop -- a continuous cycle of: + +1. **Process Input** - Read keyboard, mouse, touch, or gamepad input +2. **Update State** - Update game object positions, physics, AI, and logic +3. **Render** - Draw the current game state to the screen + +Use `requestAnimationFrame` for smooth, browser-optimized rendering. + +### Rendering + +- **Canvas 2D** - Best for 2D games, sprite-based rendering, and tilemaps +- **WebGL** - Hardware-accelerated 3D and advanced 2D rendering +- **SVG** - Vector-based graphics, good for UI elements +- **CSS** - Useful for DOM-based game elements and transitions + +### Physics and Collision Detection + +- **2D Collision Detection** - AABB, circle, and SAT-based collision +- **3D Collision Detection** - Bounding box, bounding sphere, and raycasting +- **Velocity and Acceleration** - Basic Newtonian physics for movement +- **Gravity** - Constant downward acceleration for platformers + +### Controls + +- **Keyboard** - Arrow keys, WASD, and custom key bindings +- **Mouse** - Click, move, and pointer lock for FPS-style controls +- **Touch** - Mobile touch events and virtual joysticks +- **Gamepad** - Gamepad API for controller support + +### Audio + +- **Web Audio API** - Programmatic sound generation and spatial audio +- **HTML5 Audio** - Simple audio playback for music and sound effects + +## Step-by-Step Workflows + +### Creating a Basic 2D Game + +1. Set up an HTML file with a `` element +2. Get the 2D rendering context +3. Implement the game loop using `requestAnimationFrame` +4. Create game objects with position, velocity, and size properties +5. Handle keyboard/mouse input for player control +6. Implement collision detection between game objects +7. Add scoring, lives, and win/lose conditions +8. Add sound effects and music + +### Building a 3D Game + +1. Choose a framework (Three.js, Babylon.js, A-Frame, or PlayCanvas) +2. Set up the scene, camera, and renderer +3. Load or create 3D models and textures +4. Implement lighting and shaders +5. Add physics and collision detection +6. Implement player controls and camera movement +7. Add audio and visual effects + +### Publishing a Game + +1. Optimize assets (compress images, minify code) +2. Test across browsers and devices +3. Choose distribution platform (web, app stores, game portals) +4. Implement monetization if needed +5. Promote through game communities and social media + +## Game Templates + +Starter templates are available in the `assets/` folder. Each template provides a complete, working example that can be used as a starting point for a new project. + +| Template | Description | +|----------|-------------| +| `paddle-game-template.md` | 2D Breakout-style game with pure JavaScript | +| `2d-maze-game.md` | Maze game with device orientation controls | +| `2d-platform-game.md` | Platformer game using Phaser framework | +| `gameBase-template-repo.md` | Game base template repository structure | +| `simple-2d-engine.md` | Simple 2D platformer engine with collisions | + +## Reference Documentation + +Detailed reference material is available in the `references/` folder. Consult these files for in-depth coverage of specific topics. + +| Reference | Topics Covered | +|-----------|---------------| +| `basics.md` | Game development introduction and anatomy | +| `web-apis.md` | Canvas, WebGL, Web Audio, Gamepad, and other web APIs | +| `techniques.md` | Collision detection, tilemaps, async scripts, audio | +| `3d-web-games.md` | 3D theory, frameworks, shaders, WebXR | +| `game-control-mechanisms.md` | Touch, keyboard, mouse, and gamepad controls | +| `game-publishing.md` | Distribution, promotion, and monetization | +| `algorithms.md` | Raycasting, collision, physics, vector math | +| `terminology.md` | Game development glossary | +| `game-engine-core-principles.md` | Core design principles for game engines | + +## Troubleshooting + +| Issue | Solution | +|-------|----------| +| Canvas is blank | Check that you are calling drawing methods after getting the context and inside the game loop | +| Game runs at different speeds | Use delta time in update calculations instead of fixed values | +| Collision detection is inconsistent | Use continuous collision detection or reduce time steps for fast-moving objects | +| Audio does not play | Browsers require user interaction before playing audio; trigger playback from a click handler | +| Performance is poor | Profile with browser dev tools, reduce draw calls, use object pooling, and optimize asset sizes | +| Touch controls are unresponsive | Prevent default touch behavior and handle touch events separately from mouse events | +| WebGL context lost | Handle the `webglcontextlost` event and restore state on `webglcontextrestored` | diff --git a/skills/game-engine/assets/2d-maze-game.md b/skills/game-engine/assets/2d-maze-game.md new file mode 100644 index 000000000..ec7ee6952 --- /dev/null +++ b/skills/game-engine/assets/2d-maze-game.md @@ -0,0 +1,528 @@ +# 2D Maze Game Template + +A mobile-optimized 2D maze game where players guide a ball through a labyrinth of obstacles to reach a target hole. The game uses the **Device Orientation API** for tilt-based motion controls on mobile devices and keyboard arrow keys on desktop. Built with the **Phaser** framework (v2.x with Arcade Physics), it features multi-level progression, collision detection, audio feedback, vibration haptics, and a timer system. + +**Source reference:** [MDN - HTML5 Gamedev Phaser Device Orientation](https://developer.mozilla.org/en-US/docs/Games/Tutorials/HTML5_Gamedev_Phaser_Device_Orientation) +**Live demo:** [Cyber Orb](https://orb.enclavegames.com/) +**Source code:** [GitHub - EnclaveGames/Cyber-Orb](https://github.com/EnclaveGames/Cyber-Orb) + +--- + +## Game Concept + +The player controls a ball (the "orb") by tilting their mobile device or pressing arrow keys. The ball rolls through a maze of horizontal and vertical wall segments. The objective on each level is to navigate the ball to a hole at the top of the screen while avoiding walls. Collisions with walls trigger a bounce, a sound effect, and optional vibration. A timer tracks how long the player takes per level and across the entire game. + +--- + +## Project Structure + +``` +project/ + index.html + src/ + phaser-arcade-physics.2.2.2.min.js + Boot.js + Preloader.js + MainMenu.js + Howto.js + Game.js + img/ + ball.png + hole.png + element-horizontal.png + element-vertical.png + button-start.png + loading-bg.png + loading-bar.png + audio/ + bounce.ogg + bounce.mp3 + bounce.m4a +``` + +--- + +## Phaser Setup and Initialization + +### HTML Entry Point + +```html + + + + + Cyber Orb + + + + + + + + + + + + +``` + +- Canvas size: `320 x 480` +- Renderer: `Phaser.CANVAS` (alternatives: `Phaser.WEBGL`, `Phaser.AUTO`) + +--- + +## Game State Architecture + +The game follows a linear state flow: + +``` +Boot --> Preloader --> MainMenu --> Howto --> Game +``` + +### Boot State + +Loads minimal assets for the loading screen and configures scaling. + +```javascript +const Ball = { + _WIDTH: 320, + _HEIGHT: 480, +}; + +Ball.Boot = function (game) {}; +Ball.Boot.prototype = { + preload() { + this.load.image("preloaderBg", "img/loading-bg.png"); + this.load.image("preloaderBar", "img/loading-bar.png"); + }, + create() { + this.game.scale.scaleMode = Phaser.ScaleManager.SHOW_ALL; + this.game.scale.pageAlignHorizontally = true; + this.game.scale.pageAlignVertically = true; + this.game.state.start("Preloader"); + }, +}; +``` + +### Preloader State + +Displays a visual loading bar while loading all game assets. Audio is loaded in multiple formats for cross-browser compatibility. + +```javascript +Ball.Preloader = function (game) {}; +Ball.Preloader.prototype = { + preload() { + this.preloadBg = this.add.sprite( + (Ball._WIDTH - 297) * 0.5, + (Ball._HEIGHT - 145) * 0.5, + "preloaderBg" + ); + this.preloadBar = this.add.sprite( + (Ball._WIDTH - 158) * 0.5, + (Ball._HEIGHT - 50) * 0.5, + "preloaderBar" + ); + this.load.setPreloadSprite(this.preloadBar); + + this.load.image("ball", "img/ball.png"); + this.load.image("hole", "img/hole.png"); + this.load.image("element-w", "img/element-horizontal.png"); + this.load.image("element-h", "img/element-vertical.png"); + this.load.spritesheet("button-start", "img/button-start.png", 146, 51); + this.load.audio("audio-bounce", [ + "audio/bounce.ogg", + "audio/bounce.mp3", + "audio/bounce.m4a", + ]); + }, + create() { + this.game.state.start("MainMenu"); + }, +}; +``` + +### MainMenu State + +Displays the title screen with a start button. + +```javascript +Ball.MainMenu = function (game) {}; +Ball.MainMenu.prototype = { + create() { + this.add.sprite(0, 0, "screen-mainmenu"); + this.gameTitle = this.add.sprite(Ball._WIDTH * 0.5, 40, "title"); + this.gameTitle.anchor.set(0.5, 0); + + this.startButton = this.add.button( + Ball._WIDTH * 0.5, 200, "button-start", + this.startGame, this, + 2, 0, 1 // hover, out, down frames + ); + this.startButton.anchor.set(0.5, 0); + this.startButton.input.useHandCursor = true; + }, + startGame() { + this.game.state.start("Howto"); + }, +}; +``` + +### Howto State + +A single-click instruction screen before gameplay begins. + +```javascript +Ball.Howto = function (game) {}; +Ball.Howto.prototype = { + create() { + this.buttonContinue = this.add.button( + 0, 0, "screen-howtoplay", + this.startGame, this + ); + }, + startGame() { + this.game.state.start("Game"); + }, +}; +``` + +--- + +## Device Orientation API Usage + +The Device Orientation API provides real-time data about the physical tilt of a device. Two axes are used: + +| Property | Axis | Range | Effect | +|----------|------|-------|--------| +| `event.gamma` | Left/right tilt | -90 to 90 degrees | Horizontal ball velocity | +| `event.beta` | Front/back tilt | -180 to 180 degrees | Vertical ball velocity | + +### Registering the Listener + +```javascript +// In the Game state's create() method +window.addEventListener("deviceorientation", this.handleOrientation); +``` + +### Handling Orientation Events + +```javascript +handleOrientation(e) { + const x = e.gamma; // left-right tilt + const y = e.beta; // front-back tilt + Ball._player.body.velocity.x += x; + Ball._player.body.velocity.y += y; +} +``` + +### Tilt Behavior + +- Tilt device left: negative gamma, ball rolls left +- Tilt device right: positive gamma, ball rolls right +- Tilt device forward: positive beta, ball rolls down +- Tilt device backward: negative beta, ball rolls up + +The tilt angle directly maps to velocity increments -- the steeper the tilt, the greater the force applied to the ball each frame. + +--- + +## Core Game Mechanics + +### Game State Structure + +```javascript +Ball.Game = function (game) {}; +Ball.Game.prototype = { + create() {}, + initLevels() {}, + showLevel(level) {}, + updateCounter() {}, + managePause() {}, + manageAudio() {}, + update() {}, + wallCollision() {}, + handleOrientation(e) {}, + finishLevel() {}, +}; +``` + +### Ball Creation and Physics + +```javascript +// In create() +this.ball = this.add.sprite(this.ballStartPos.x, this.ballStartPos.y, "ball"); +this.ball.anchor.set(0.5); +this.physics.enable(this.ball, Phaser.Physics.ARCADE); +this.ball.body.setSize(18, 18); +this.ball.body.bounce.set(0.3, 0.3); +``` + +- Anchor at center `(0.5, 0.5)` for rotation around midpoint +- Physics body: 18x18 pixels +- Bounce coefficient: 0.3 (retains 30% velocity after wall collision) + +### Keyboard Controls (Desktop Fallback) + +```javascript +// In create() +this.keys = this.game.input.keyboard.createCursorKeys(); + +// In update() +if (this.keys.left.isDown) { + this.ball.body.velocity.x -= this.movementForce; +} else if (this.keys.right.isDown) { + this.ball.body.velocity.x += this.movementForce; +} +if (this.keys.up.isDown) { + this.ball.body.velocity.y -= this.movementForce; +} else if (this.keys.down.isDown) { + this.ball.body.velocity.y += this.movementForce; +} +``` + +### Hole (Goal) Setup + +```javascript +this.hole = this.add.sprite(Ball._WIDTH * 0.5, 90, "hole"); +this.physics.enable(this.hole, Phaser.Physics.ARCADE); +this.hole.anchor.set(0.5); +this.hole.body.setSize(2, 2); +``` + +The hole has a tiny 2x2 collision body for precise overlap detection. + +--- + +## Level System + +### Level Data Format + +Each level is an array of wall segment objects with position and type: + +```javascript +this.levelData = [ + [{ x: 96, y: 224, t: "w" }], // Level 1 + [ + { x: 72, y: 320, t: "w" }, + { x: 200, y: 320, t: "h" }, + { x: 72, y: 150, t: "w" }, + ], // Level 2 + // ... more levels +]; +``` + +- `x, y`: Position in pixels +- `t`: Type -- `"w"` for horizontal wall, `"h"` for vertical wall + +### Building Levels + +```javascript +initLevels() { + for (let i = 0; i < this.maxLevels; i++) { + const newLevel = this.add.group(); + newLevel.enableBody = true; + newLevel.physicsBodyType = Phaser.Physics.ARCADE; + + for (const item of this.levelData[i]) { + newLevel.create(item.x, item.y, `element-${item.t}`); + } + + newLevel.setAll("body.immovable", true); + newLevel.visible = false; + this.levels.push(newLevel); + } +} +``` + +### Showing a Level + +```javascript +showLevel(level) { + const lvl = level || this.level; + if (this.levels[lvl - 2]) { + this.levels[lvl - 2].visible = false; + } + this.levels[lvl - 1].visible = true; +} +``` + +--- + +## Collision Detection + +### Wall Collisions (Bounce) + +```javascript +// In update() +this.physics.arcade.collide( + this.ball, this.borderGroup, + this.wallCollision, null, this +); +this.physics.arcade.collide( + this.ball, this.levels[this.level - 1], + this.wallCollision, null, this +); +``` + +`collide` causes the ball to bounce off walls and triggers the callback. + +### Hole Overlap (Pass-Through Detection) + +```javascript +this.physics.arcade.overlap( + this.ball, this.hole, + this.finishLevel, null, this +); +``` + +`overlap` detects intersection without physical collision response. + +### Wall Collision Callback + +```javascript +wallCollision() { + if (this.audioStatus) { + this.bounceSound.play(); + } + if ("vibrate" in window.navigator) { + window.navigator.vibrate(100); + } +} +``` + +--- + +## Audio System + +```javascript +// In create() +this.bounceSound = this.game.add.audio("audio-bounce"); + +// Toggle +manageAudio() { + this.audioStatus = !this.audioStatus; +} +``` + +--- + +## Vibration API + +```javascript +if ("vibrate" in window.navigator) { + window.navigator.vibrate(100); // 100ms vibration pulse +} +``` + +Feature-detect before calling. Provides tactile feedback on supported mobile devices. + +--- + +## Timer System + +```javascript +// In create() +this.timer = 0; +this.totalTimer = 0; +this.timerText = this.game.add.text(15, 15, "Time: 0", this.fontBig); +this.totalTimeText = this.game.add.text(120, 30, "Total time: 0", this.fontSmall); +this.time.events.loop(Phaser.Timer.SECOND, this.updateCounter, this); + +// Counter callback +updateCounter() { + this.timer++; + this.timerText.setText(`Time: ${this.timer}`); + this.totalTimeText.setText(`Total time: ${this.totalTimer + this.timer}`); +} +``` + +--- + +## Level Completion + +```javascript +finishLevel() { + if (this.level >= this.maxLevels) { + this.totalTimer += this.timer; + alert(`Congratulations, game completed!\nTotal time: ${this.totalTimer}s`); + this.game.state.start("MainMenu"); + } else { + alert(`Level ${this.level} completed!`); + this.totalTimer += this.timer; + this.timer = 0; + this.level++; + this.timerText.setText(`Time: ${this.timer}`); + this.totalTimeText.setText(`Total time: ${this.totalTimer}`); + this.levelText.setText(`Level: ${this.level} / ${this.maxLevels}`); + this.ball.body.x = this.ballStartPos.x; + this.ball.body.y = this.ballStartPos.y; + this.ball.body.velocity.x = 0; + this.ball.body.velocity.y = 0; + this.showLevel(); + } +} +``` + +--- + +## Complete Update Loop + +```javascript +update() { + // Keyboard input + if (this.keys.left.isDown) { + this.ball.body.velocity.x -= this.movementForce; + } else if (this.keys.right.isDown) { + this.ball.body.velocity.x += this.movementForce; + } + if (this.keys.up.isDown) { + this.ball.body.velocity.y -= this.movementForce; + } else if (this.keys.down.isDown) { + this.ball.body.velocity.y += this.movementForce; + } + + // Wall collisions + this.physics.arcade.collide( + this.ball, this.borderGroup, this.wallCollision, null, this + ); + this.physics.arcade.collide( + this.ball, this.levels[this.level - 1], this.wallCollision, null, this + ); + + // Hole overlap + this.physics.arcade.overlap( + this.ball, this.hole, this.finishLevel, null, this + ); +} +``` + +--- + +## Phaser API Quick Reference + +| Function | Purpose | +|----------|---------| +| `this.add.sprite(x, y, key)` | Create a game object | +| `this.add.group()` | Create a container for objects | +| `this.add.button(x, y, key, cb, ctx, over, out, down)` | Create interactive button | +| `this.add.text(x, y, text, style)` | Create text display | +| `this.physics.enable(obj, system)` | Enable physics on object | +| `this.physics.arcade.collide(a, b, cb)` | Detect collision with bounce | +| `this.physics.arcade.overlap(a, b, cb)` | Detect overlap without bounce | +| `this.load.image(key, path)` | Load image asset | +| `this.load.spritesheet(key, path, w, h)` | Load sprite animation sheet | +| `this.load.audio(key, paths[])` | Load audio with format fallbacks | +| `this.game.add.audio(key)` | Instantiate audio object | +| `this.time.events.loop(interval, cb, ctx)` | Create repeating timer | diff --git a/skills/game-engine/assets/2d-platform-game.md b/skills/game-engine/assets/2d-platform-game.md new file mode 100644 index 000000000..05f2e96ce --- /dev/null +++ b/skills/game-engine/assets/2d-platform-game.md @@ -0,0 +1,1855 @@ +# 2D Platform Game Template + +A complete step-by-step guide for building a 2D platformer game using Phaser (v2.x / Phaser CE) with Arcade Physics. This template walks through every stage of development: setting up the project, creating platforms from JSON level data, adding a hero with physics-based movement and jumping, collectible coins, walking enemies, death and stomp mechanics, a scoreboard, sprite animations, win conditions with a door/key system, and multi-level progression. + +**What you will build:** A classic side-scrolling platformer where a hero navigates platforms, collects coins, avoids or stomps on spider enemies, finds a key to unlock a door, and progresses through multiple levels -- with score tracking, animations, and physics. + +**Prerequisites:** Basic to intermediate JavaScript knowledge, familiarity with HTML, and a local web server for development (e.g., browser-sync, live-server, or Python's SimpleHTTPServer). + +**Source:** Based on the [Mozilla HTML5 Games Workshop - Platformer](https://mozdevs.github.io/html5-games-workshop/en/guides/platformer/start-here/). Project starter files available at the workshop repository. + +--- + +## Start Here + +This tutorial builds a 2D platformer using the **Phaser** framework. Phaser handles rendering, physics, input, audio, and asset loading so you can focus on game logic. + +### What You Will Build + +The finished game features: + +- A hero character the player controls with the keyboard +- Platforms the hero can walk and jump on +- Collectible coins that increase the score +- Walking spider enemies that kill the hero on contact (but can be stomped from above) +- A key and door system: the hero must pick up a key to unlock the door and complete the level +- Multiple levels loaded from JSON data files +- A scoreboard showing collected coins +- Sprite animations for the hero (idle, running, jumping, falling) + +### Project Structure + +``` +project/ + index.html + js/ + phaser.min.js (Phaser 2.6.2 or Phaser CE) + main.js (all game code goes here) + audio/ + sfx/ + jump.wav + coin.wav + stomp.wav + key.wav + door.wav + images/ + background.png + ground.png + grass:8x1.png (platform tile images in various sizes) + grass:6x1.png + grass:4x1.png + grass:2x1.png + grass:1x1.png + hero.png (hero spritesheet: 36x42 per frame) + hero_stopped.png (single frame for initial steps) + coin_animated.png (coin spritesheet) + spider.png (spider spritesheet) + invisible_wall.png (invisible boundary for enemy AI) + key.png (key spritesheet) + door.png (door spritesheet) + key_icon.png (HUD icon for key) + font:numbers.png (bitmap font for score) + data/ + level00.json + level01.json +``` + +### Level Data Format + +Each level is defined in a JSON file. The JSON structure describes positions of every entity: + +```json +{ + "hero": { "x": 21, "y": 525 }, + "door": { "x": 169, "y": 546 }, + "key": { "x": 750, "y": 524 }, + "platforms": [ + { "image": "ground", "x": 0, "y": 546 }, + { "image": "grass:8x1", "x": 208, "y": 420 }, + { "image": "grass:4x1", "x": 420, "y": 336 }, + { "image": "grass:2x1", "x": 680, "y": 252 } + ], + "coins": [ + { "x": 147, "y": 525 }, + { "x": 189, "y": 525 }, + { "x": 399, "y": 399 }, + { "x": 441, "y": 336 } + ], + "spiders": [ + { "x": 121, "y": 399 } + ], + "decoration": { + "grass": [ + { "x": 84, "y": 504, "frame": 0 }, + { "x": 420, "y": 504, "frame": 1 } + ] + } +} +``` + +Each entity type (hero, door, key, platforms, coins, spiders) has `x` and `y` coordinates. Platforms also specify which `image` asset to use for that platform tile. + +--- + +## Initialise Phaser + +The first step is setting up the HTML file and creating the Phaser game instance. + +### HTML Entry Point + +Create an `index.html` file that loads Phaser and your game script: + +```html + + + + + Platformer Game + + + + + +
+ + +``` + +- The `
` is the container where Phaser will insert the game canvas. +- Phaser is loaded first, then your game script. + +### Creating the Game Instance + +In `js/main.js`, create the Phaser game object and register a game state: + +```javascript +// Create a Phaser game instance +// Parameters: width, height, renderer, DOM element ID +window.onload = function () { + let game = new Phaser.Game(960, 600, Phaser.AUTO, 'game'); + + // Add and start the play state + game.state.add('play', PlayState); + game.state.start('play'); +}; +``` + +- `960, 600` sets the game canvas dimensions in pixels. +- `Phaser.AUTO` lets Phaser choose between WebGL and Canvas rendering automatically. +- `'game'` is the ID of the DOM element that will contain the canvas. + +### The PlayState Object + +Define the game state as an object with lifecycle methods: + +```javascript +PlayState = {}; + +PlayState.init = function () { + // Called first when the state starts +}; + +PlayState.preload = function () { + // Load all assets here +}; + +PlayState.create = function () { + // Create game entities and set up the world +}; + +PlayState.update = function () { + // Called every frame (~60 times per second) + // Handle game logic, input, collisions here +}; +``` + +- `init` -- runs first; used for configuration and receiving parameters. +- `preload` -- used to load all assets (images, audio, JSON) before the game starts. +- `create` -- called once after assets are loaded; used to create sprites, groups, and game objects. +- `update` -- called every frame at ~60fps; used for input handling, physics checks, and game logic. + +At this point you should see an empty black canvas rendered on the page. + +--- + +## The Game Loop + +Phaser uses a game loop architecture. Every frame, Phaser calls `update()`, which is where you handle input, move sprites, and check collisions. Before the loop starts, `preload()` loads assets and `create()` sets up the initial game state. + +### Loading and Displaying the Background + +Start by loading and displaying a background image to verify the game loop is working: + +```javascript +PlayState.preload = function () { + this.game.load.image('background', 'images/background.png'); +}; + +PlayState.create = function () { + // Add the background image at position (0, 0) + this.game.add.image(0, 0, 'background'); +}; +``` + +- `this.game.load.image(key, path)` loads an image and assigns it a key for later reference. +- `this.game.add.image(x, y, key)` creates a static image at the given position. + +You should now see the background image rendered in the game canvas. + +### Understanding the Frame Cycle + +``` +preload() -> [assets loaded] -> create() -> update() -> update() -> update() -> ... +``` + +Each call to `update()` represents one frame. The game targets 60 frames per second. All movement, input reading, and collision detection happen inside `update()`. + +--- + +## Creating Platforms + +Platforms are the surfaces the hero walks and jumps on. They are loaded from the level JSON data and created as physics-enabled sprites arranged in a group. + +### Loading Platform Assets + +Load the level JSON data and all platform tile images in `preload`: + +```javascript +PlayState.preload = function () { + this.game.load.image('background', 'images/background.png'); + + // Load level data + this.game.load.json('level:1', 'data/level01.json'); + + // Load platform images + this.game.load.image('ground', 'images/ground.png'); + this.game.load.image('grass:8x1', 'images/grass_8x1.png'); + this.game.load.image('grass:6x1', 'images/grass_6x1.png'); + this.game.load.image('grass:4x1', 'images/grass_4x1.png'); + this.game.load.image('grass:2x1', 'images/grass_2x1.png'); + this.game.load.image('grass:1x1', 'images/grass_1x1.png'); +}; +``` + +### Spawning Platforms from Level Data + +Create a method to load the level and spawn each platform as a sprite inside a physics group: + +```javascript +PlayState.create = function () { + // Add the background + this.game.add.image(0, 0, 'background'); + + // Load level data and spawn entities + this._loadLevel(this.game.cache.getJSON('level:1')); +}; + +PlayState._loadLevel = function (data) { + // Create a group for platforms + this.platforms = this.game.add.group(); + + // Spawn each platform from the level data + data.platforms.forEach(this._spawnPlatform, this); +}; + +PlayState._spawnPlatform = function (platform) { + // Add a sprite at the platform's position using the specified image + let sprite = this.platforms.create(platform.x, platform.y, platform.image); + + // Enable physics on this platform + this.game.physics.enable(sprite); + + // Make platform immovable so it doesn't get pushed by the hero + sprite.body.allowGravity = false; + sprite.body.immovable = true; +}; +``` + +- `this.game.add.group()` creates a Phaser group -- a container for related sprites that enables batch operations and collision detection. +- `this.platforms.create(x, y, key)` creates a sprite inside the group. +- `sprite.body.immovable = true` prevents the platform from being pushed by other physics bodies. +- `sprite.body.allowGravity = false` prevents platforms from falling due to gravity. + +You should now see the ground and grass platform tiles rendered on the screen. + +--- + +## The Main Character Sprite + +Now add the hero character that the player will control. + +### Loading the Hero Image + +Add the hero image to `preload`. Initially we use a single static image; we will switch to a spritesheet later for animations: + +```javascript +// In PlayState.preload: +this.game.load.image('hero', 'images/hero_stopped.png'); +``` + +### Spawning the Hero + +Add the hero to `_loadLevel` and create a spawn method: + +```javascript +PlayState._loadLevel = function (data) { + this.platforms = this.game.add.group(); + data.platforms.forEach(this._spawnPlatform, this); + + // Spawn the hero at the position defined in level data + this._spawnCharacters({ hero: data.hero }); +}; + +PlayState._spawnCharacters = function (data) { + // Create the hero sprite + this.hero = this.game.add.sprite(data.hero.x, data.hero.y, 'hero'); + + // Set the anchor to the bottom-center for easier positioning + this.hero.anchor.set(0.5, 1); +}; +``` + +- `anchor.set(0.5, 1)` sets the sprite's origin point to the horizontal center and vertical bottom. This makes it easier to position the hero on top of platforms, since the `y` position refers to the hero's feet rather than the top-left corner. + +--- + +## Keyboard Controls + +Capture keyboard input so the player can move the hero left, right, and jump. + +### Setting Up Input Keys + +In `init`, configure the keyboard controls: + +```javascript +PlayState.init = function () { + // Force integer rendering for pixel-art crispness + this.game.renderer.renderSession.roundPixels = true; + + // Capture arrow keys + this.keys = this.game.input.keyboard.addKeys({ + left: Phaser.KeyCode.LEFT, + right: Phaser.KeyCode.RIGHT, + up: Phaser.KeyCode.UP + }); +}; +``` + +- `addKeys()` captures the specified keys and returns an object with key state references. +- `Phaser.KeyCode.LEFT`, `RIGHT`, `UP` correspond to the arrow keys. +- `renderSession.roundPixels = true` prevents pixel-art sprites from appearing blurry due to sub-pixel rendering. + +### Reading Input in Update + +Handle the key states in `update`. For now, just log the direction; the next step adds physics-based movement: + +```javascript +PlayState.update = function () { + this._handleInput(); +}; + +PlayState._handleInput = function () { + if (this.keys.left.isDown) { + // Move hero left + } else if (this.keys.right.isDown) { + // Move hero right + } else { + // Stop (no key held) + } +}; +``` + +- `this.keys.left.isDown` returns `true` while the left arrow key is held down. +- The `else` clause handles the case where neither left nor right is pressed (the hero should stop). + +--- + +## Moving Sprites with Physics + +Enable Arcade Physics so the hero can move with velocity and interact with platforms through collisions. + +### Enabling the Physics Engine + +Enable Arcade Physics in `init`: + +```javascript +PlayState.init = function () { + this.game.renderer.renderSession.roundPixels = true; + + this.keys = this.game.input.keyboard.addKeys({ + left: Phaser.KeyCode.LEFT, + right: Phaser.KeyCode.RIGHT, + up: Phaser.KeyCode.UP + }); + + // Enable Arcade Physics + this.game.physics.startSystem(Phaser.Physics.ARCADE); +}; +``` + +### Adding a Physics Body to the Hero + +Enable physics on the hero sprite in `_spawnCharacters`: + +```javascript +PlayState._spawnCharacters = function (data) { + this.hero = this.game.add.sprite(data.hero.x, data.hero.y, 'hero'); + this.hero.anchor.set(0.5, 1); + + // Enable physics body on the hero + this.game.physics.enable(this.hero); +}; +``` + +### Moving with Velocity + +Now update `_handleInput` to set the hero's velocity based on key presses: + +```javascript +const SPEED = 200; // pixels per second + +PlayState._handleInput = function () { + if (this.keys.left.isDown) { + this.hero.body.velocity.x = -SPEED; + } else if (this.keys.right.isDown) { + this.hero.body.velocity.x = SPEED; + } else { + this.hero.body.velocity.x = 0; + } +}; +``` + +- `body.velocity.x` sets the horizontal speed in pixels per second. +- A negative value moves the sprite left; positive moves it right. +- Setting velocity to `0` when no keys are pressed makes the hero stop immediately. + +The hero can now move left and right, but will fall through platforms and off the screen because there is no gravity or collision handling yet. + +--- + +## Gravity + +Add gravity so the hero falls downward and collides with platforms. + +### Setting Global Gravity + +Enable gravity for the entire physics world in `init`: + +```javascript +PlayState.init = function () { + this.game.renderer.renderSession.roundPixels = true; + + this.keys = this.game.input.keyboard.addKeys({ + left: Phaser.KeyCode.LEFT, + right: Phaser.KeyCode.RIGHT, + up: Phaser.KeyCode.UP + }); + + this.game.physics.startSystem(Phaser.Physics.ARCADE); + + // Set global gravity + this.game.physics.arcade.gravity.y = 1200; +}; +``` + +- `gravity.y = 1200` applies a downward acceleration of 1200 pixels per second squared to all physics-enabled sprites (unless they opt out with `allowGravity = false`). + +### Collision Detection Between Hero and Platforms + +Add collision detection in `update` so the hero lands on platforms instead of falling through: + +```javascript +PlayState.update = function () { + this._handleCollisions(); + this._handleInput(); +}; + +PlayState._handleCollisions = function () { + // Make the hero collide with the platform group + this.game.physics.arcade.collide(this.hero, this.platforms); +}; +``` + +- `arcade.collide(spriteA, groupB)` checks for physics collisions between the hero and every sprite in the platforms group. When the hero lands on a platform, the physics engine prevents it from passing through and resolves the overlap. +- It is important to call `_handleCollisions()` before `_handleInput()` so collision data (like whether the hero is touching the ground) is up to date when we process input. + +The hero now falls due to gravity and lands on the platforms. You can walk left and right on the platforms. + +--- + +## Jumps + +Allow the hero to jump when the up arrow key is pressed -- but only when standing on a platform (no mid-air jumps). + +### Implementing the Jump Mechanic + +Add a jump constant and update `_handleInput`: + +```javascript +const SPEED = 200; +const JUMP_SPEED = 600; + +PlayState._handleInput = function () { + if (this.keys.left.isDown) { + this.hero.body.velocity.x = -SPEED; + } else if (this.keys.right.isDown) { + this.hero.body.velocity.x = SPEED; + } else { + this.hero.body.velocity.x = 0; + } + + // Handle jumping + if (this.keys.up.isDown) { + this._jump(); + } +}; + +PlayState._jump = function () { + let canJump = this.hero.body.touching.down; + + if (canJump) { + this.hero.body.velocity.y = -JUMP_SPEED; + } + + return canJump; +}; +``` + +- `this.hero.body.touching.down` is `true` when the hero's physics body is touching another body on its underside -- meaning the hero is standing on something. +- Setting `velocity.y` to a negative value launches the hero upward (the y-axis points downward in screen coordinates). +- The `canJump` check prevents the hero from jumping while already in the air, enforcing single-jump behavior. +- The method returns whether the jump was performed, which is useful later for playing sound effects. + +### Adding a Jump Sound Effect + +Load a jump sound and play it on successful jumps: + +```javascript +// In PlayState.preload: +this.game.load.audio('sfx:jump', 'audio/sfx/jump.wav'); + +// In PlayState.create: +this.sfx = { + jump: this.game.add.audio('sfx:jump') +}; + +// In PlayState._jump, after setting velocity: +PlayState._jump = function () { + let canJump = this.hero.body.touching.down; + + if (canJump) { + this.hero.body.velocity.y = -JUMP_SPEED; + this.sfx.jump.play(); + } + + return canJump; +}; +``` + +--- + +## Pickable Coins + +Add collectible coins that the player can pick up to increase their score. + +### Loading Coin Assets + +Load the coin spritesheet and coin sound effect in `preload`: + +```javascript +// In PlayState.preload: +this.game.load.spritesheet('coin', 'images/coin_animated.png', 22, 22); +this.game.load.audio('sfx:coin', 'audio/sfx/coin.wav'); +``` + +- `load.spritesheet(key, path, frameWidth, frameHeight)` loads a spritesheet and slices it into individual frames of 22x22 pixels for animation. + +### Spawning Coins from Level Data + +Update `_loadLevel` to create a coins group and spawn each coin: + +```javascript +PlayState._loadLevel = function (data) { + this.platforms = this.game.add.group(); + this.coins = this.game.add.group(); + + data.platforms.forEach(this._spawnPlatform, this); + data.coins.forEach(this._spawnCoin, this); + + this._spawnCharacters({ hero: data.hero }); +}; + +PlayState._spawnCoin = function (coin) { + let sprite = this.coins.create(coin.x, coin.y, 'coin'); + sprite.anchor.set(0.5, 0.5); + + // Add a tween animation to make the coin bob up and down + this.game.physics.enable(sprite); + sprite.body.allowGravity = false; + + // Coin bobbing animation with a tween + sprite.animations.add('rotate', [0, 1, 2, 1], 6, true); // 6fps, looping + sprite.animations.play('rotate'); +}; +``` + +- Each coin is created inside the `coins` group for easy collision detection. +- `allowGravity = false` prevents coins from falling. +- The `animations.add` creates a frame animation using the spritesheet frames 0, 1, 2, 1 at 6fps, looping continuously. + +### Collecting Coins + +Add the coin sound to the sfx object and detect overlap between the hero and coins: + +```javascript +// In PlayState.create, add to the sfx object: +this.sfx = { + jump: this.game.add.audio('sfx:jump'), + coin: this.game.add.audio('sfx:coin') +}; + +// In PlayState._handleCollisions: +PlayState._handleCollisions = function () { + this.game.physics.arcade.collide(this.hero, this.platforms); + + // Detect overlap between hero and coins (no physical collision, just overlap) + this.game.physics.arcade.overlap( + this.hero, this.coins, this._onHeroVsCoin, null, this + ); +}; + +PlayState._onHeroVsCoin = function (hero, coin) { + this.sfx.coin.play(); + coin.kill(); // Remove the coin from the game + this.coinPickupCount++; +}; +``` + +- `arcade.overlap()` checks if two sprites/groups overlap without resolving collisions physically. When an overlap is detected, it calls the callback function (`_onHeroVsCoin`). +- `coin.kill()` removes the coin sprite from the game world. +- `this.coinPickupCount` tracks the number of coins collected (initialize it in `_loadLevel`). + +### Initializing the Coin Counter + +```javascript +PlayState._loadLevel = function (data) { + this.platforms = this.game.add.group(); + this.coins = this.game.add.group(); + + data.platforms.forEach(this._spawnPlatform, this); + data.coins.forEach(this._spawnCoin, this); + + this._spawnCharacters({ hero: data.hero }); + + // Initialize coin counter + this.coinPickupCount = 0; +}; +``` + +--- + +## Walking Enemies + +Add spider enemies that walk back and forth on platforms. The hero can stomp on them from above but dies if touching them from the side. + +### Loading Enemy Assets + +```javascript +// In PlayState.preload: +this.game.load.spritesheet('spider', 'images/spider.png', 42, 32); +this.game.load.image('invisible-wall', 'images/invisible_wall.png'); +this.game.load.audio('sfx:stomp', 'audio/sfx/stomp.wav'); +``` + +- The spider spritsheet has frames for a crawling animation. +- Invisible walls are placed at platform edges to keep spiders from walking off -- they are not rendered visually but have physics bodies. + +### Spawning Enemies + +Update `_loadLevel` and add a spawn method for spiders: + +```javascript +PlayState._loadLevel = function (data) { + this.platforms = this.game.add.group(); + this.coins = this.game.add.group(); + this.spiders = this.game.add.group(); + this.enemyWalls = this.game.add.group(); + + data.platforms.forEach(this._spawnPlatform, this); + data.coins.forEach(this._spawnCoin, this); + data.spiders.forEach(this._spawnSpider, this); + + this._spawnCharacters({ hero: data.hero }); + + // Make enemy walls invisible + this.enemyWalls.visible = false; + + this.coinPickupCount = 0; +}; +``` + +### Creating Invisible Walls on Platforms + +Modify `_spawnPlatform` to add invisible walls at both edges of each platform: + +```javascript +PlayState._spawnPlatform = function (platform) { + let sprite = this.platforms.create(platform.x, platform.y, platform.image); + this.game.physics.enable(sprite); + sprite.body.allowGravity = false; + sprite.body.immovable = true; + + // Spawn invisible walls at the left and right edges of this platform + this._spawnEnemyWall(platform.x, platform.y, 'left'); + this._spawnEnemyWall(platform.x + sprite.width, platform.y, 'right'); +}; + +PlayState._spawnEnemyWall = function (x, y, side) { + let sprite = this.enemyWalls.create(x, y, 'invisible-wall'); + + // Anchor to the bottom of the wall and adjust position based on side + sprite.anchor.set(side === 'left' ? 1 : 0, 1); + + this.game.physics.enable(sprite); + sprite.body.immovable = true; + sprite.body.allowGravity = false; +}; +``` + +- Each platform gets two invisible walls, one at each edge. +- The walls act as barriers that prevent spiders from walking off the edge. +- The anchor is set so the wall aligns to the correct side of the platform. + +### Spawning and Animating Spiders + +```javascript +PlayState._spawnSpider = function (spider) { + let sprite = this.spiders.create(spider.x, spider.y, 'spider'); + sprite.anchor.set(0.5, 1); + + // Add the crawl animation + sprite.animations.add('crawl', [0, 1, 2], 8, true); + sprite.animations.add('die', [0, 4, 0, 4, 0, 4, 3, 3, 3, 3, 3, 3], 12); + sprite.animations.play('crawl'); + + // Enable physics + this.game.physics.enable(sprite); + + // Set initial movement speed + sprite.body.velocity.x = Spider.SPEED; +}; + +// Spider speed constant +const Spider = { SPEED: 100 }; +``` + +- Spiders have two animations: `crawl` (looping) and `die` (played once on death). +- `velocity.x = 100` starts the spider moving to the right at 100 pixels per second. + +### Making Spiders Bounce Off Walls + +Add collision handling so spiders reverse direction when hitting invisible walls or platform edges: + +```javascript +// In PlayState._handleCollisions: +PlayState._handleCollisions = function () { + this.game.physics.arcade.collide(this.hero, this.platforms); + this.game.physics.arcade.collide(this.spiders, this.platforms); + this.game.physics.arcade.collide(this.spiders, this.enemyWalls); + + this.game.physics.arcade.overlap( + this.hero, this.coins, this._onHeroVsCoin, null, this + ); + this.game.physics.arcade.overlap( + this.hero, this.spiders, this._onHeroVsEnemy, null, this + ); +}; +``` + +To make spiders reverse direction when colliding with walls, check their velocity each frame and flip them: + +```javascript +// In PlayState.update, after collision handling, update spider directions: +PlayState.update = function () { + this._handleCollisions(); + this._handleInput(); + + // Update spider facing direction based on velocity + this.spiders.forEach(function (spider) { + if (spider.body.touching.right || spider.body.blocked.right) { + spider.body.velocity.x = -Spider.SPEED; // Turn left + } else if (spider.body.touching.left || spider.body.blocked.left) { + spider.body.velocity.x = Spider.SPEED; // Turn right + } + }, this); +}; +``` + +- When a spider touches a wall on its right side, it reverses to move left, and vice versa. +- `body.touching` is set by Phaser after collision resolution. + +--- + +## Death + +Implement hero death when touching enemies and the stomp mechanic for killing enemies. + +### Hero vs Enemy: Stomp or Die + +When the hero overlaps with a spider, check if the hero is falling (stomping) or not: + +```javascript +PlayState._onHeroVsEnemy = function (hero, enemy) { + if (hero.body.velocity.y > 0) { + // Hero is falling -> stomp the enemy + enemy.body.velocity.x = 0; // Stop enemy movement + enemy.body.enable = false; // Disable enemy physics + + // Play die animation then remove the enemy + enemy.animations.play('die'); + enemy.events.onAnimationComplete.addOnce(function () { + enemy.kill(); + }); + + // Bounce the hero up after stomping + hero.body.velocity.y = -JUMP_SPEED / 2; + + this.sfx.stomp.play(); + } else { + // Hero touched enemy from side or below -> die + this._killHero(); + } +}; + +PlayState._killHero = function () { + this.hero.kill(); + // Restart the level after a short delay + this.game.time.events.add(500, function () { + this.game.state.restart(true, false, { level: this.level }); + }, this); +}; +``` + +- If `hero.body.velocity.y > 0`, the hero is moving downward (falling), indicating a stomp. +- On stomp: the enemy stops, plays its death animation, and is removed. The hero bounces up. +- If the hero is not falling, the hero dies. `this.hero.kill()` removes the hero from the game. +- After 500ms, the entire state is restarted, effectively reloading the level. + +### Add Stomp Sound + +```javascript +// In PlayState.create, add to sfx: +this.sfx = { + jump: this.game.add.audio('sfx:jump'), + coin: this.game.add.audio('sfx:coin'), + stomp: this.game.add.audio('sfx:stomp') +}; +``` + +### Adding a Death Animation for the Hero + +Make the hero flash and fall off the screen when dying: + +```javascript +PlayState._killHero = function () { + this.hero.alive = false; + + // Play a "dying" visual: the hero jumps up and falls off screen + this.hero.body.velocity.y = -JUMP_SPEED / 2; + this.hero.body.velocity.x = 0; + this.hero.body.allowGravity = true; + + // Disable collisions so the hero falls through platforms + this.hero.body.collideWorldBounds = false; + + // Restart after a delay + this.game.time.events.add(1000, function () { + this.game.state.restart(true, false, { level: this.level }); + }, this); +}; +``` + +### Guarding Input When Dead + +Prevent input from controlling the hero after death: + +```javascript +PlayState._handleInput = function () { + if (!this.hero.alive) { return; } + + if (this.keys.left.isDown) { + this.hero.body.velocity.x = -SPEED; + } else if (this.keys.right.isDown) { + this.hero.body.velocity.x = SPEED; + } else { + this.hero.body.velocity.x = 0; + } + + if (this.keys.up.isDown) { + this._jump(); + } +}; +``` + +- `this.hero.alive` is set to `false` in `_killHero`, so input is ignored after death and the hero falls off screen naturally. + +--- + +## Scoreboard + +Display the number of collected coins on screen using a bitmap font. + +### Loading the Bitmap Font + +```javascript +// In PlayState.preload: +this.game.load.image('font:numbers', 'images/numbers.png'); +this.game.load.image('icon:coin', 'images/coin_icon.png'); +``` + +### Creating the HUD + +Create a fixed HUD (heads-up display) that shows the coin icon and count: + +```javascript +PlayState._createHud = function () { + let coinIcon = this.game.make.image(0, 0, 'icon:coin'); + + // Create a dynamic text label for the coin count + this.hud = this.game.add.group(); + + // Use a retroFont or a regular text object for the score + let scoreStyle = { + font: '30px monospace', + fill: '#fff' + }; + this.coinFont = this.game.add.text( + coinIcon.width + 7, 0, 'x0', scoreStyle + ); + + this.hud.add(coinIcon); + this.hud.add(this.coinFont); + + this.hud.position.set(10, 10); + this.hud.fixedToCamera = true; +}; +``` + +Alternatively, using Phaser's `RetroFont` for pixel-art number rendering: + +```javascript +PlayState._createHud = function () { + // Bitmap-based number rendering using RetroFont + this.coinFont = this.game.add.retroFont( + 'font:numbers', 20, 26, + '0123456789X ', 6 + ); + + let coinIcon = this.game.make.image(0, 0, 'icon:coin'); + + let coinScoreImg = this.game.make.image( + coinIcon.x + coinIcon.width + 7, 0, this.coinFont + ); + + this.hud = this.game.add.group(); + this.hud.add(coinIcon); + this.hud.add(coinScoreImg); + this.hud.position.set(10, 10); + this.hud.fixedToCamera = true; +}; +``` + +- `retroFont` creates a bitmap font from a spritesheet containing character glyphs. +- Parameters: image key, character width, character height, character set string, number of characters per row. + +### Calling createHud in create + +```javascript +PlayState.create = function () { + this.game.add.image(0, 0, 'background'); + + this._loadLevel(this.game.cache.getJSON('level:1')); + + // Create the HUD + this._createHud(); +}; +``` + +### Updating the Score Display + +Update the score text whenever a coin is collected: + +```javascript +PlayState._onHeroVsCoin = function (hero, coin) { + this.sfx.coin.play(); + coin.kill(); + this.coinPickupCount++; + + // Update the HUD + this.coinFont.text = 'x' + this.coinPickupCount; +}; +``` + +--- + +## Animations for the Main Character + +Replace the static hero image with a spritesheet and add animations for different states: idle (stopped), running, jumping, and falling. + +### Loading the Hero Spritesheet + +Replace the single image load with a spritesheet in `preload`: + +```javascript +// Replace: this.game.load.image('hero', 'images/hero_stopped.png'); +// With: +this.game.load.spritesheet('hero', 'images/hero.png', 36, 42); +``` + +- The hero spritesheet is 36 pixels wide and 42 pixels tall per frame. +- Frames include idle, walk cycle, jump, and fall poses. + +### Defining Animations + +In `_spawnCharacters`, add animation definitions after creating the hero sprite: + +```javascript +PlayState._spawnCharacters = function (data) { + this.hero = this.game.add.sprite(data.hero.x, data.hero.y, 'hero'); + this.hero.anchor.set(0.5, 1); + this.game.physics.enable(this.hero); + + // Define animations + this.hero.animations.add('stop', [0]); // Single frame: idle + this.hero.animations.add('run', [1, 2], 8, true); // 2 frames at 8fps, looping + this.hero.animations.add('jump', [3]); // Single frame: jumping up + this.hero.animations.add('fall', [4]); // Single frame: falling down +}; +``` + +- `animations.add(name, frames, fps, loop)` registers an animation with the given name. +- Single-frame animations like `stop`, `jump`, and `fall` effectively set a static pose. +- The `run` animation alternates between frames 1 and 2 at 8fps. + +### Playing the Correct Animation + +Add a method to determine and play the right animation based on the hero's current state: + +```javascript +PlayState._getAnimationName = function () { + let name = 'stop'; // Default: standing still + + if (!this.hero.alive) { + name = 'stop'; // Use idle frame when dead + } else if (this.hero.body.velocity.y < 0) { + name = 'jump'; // Moving upward + } else if (this.hero.body.velocity.y > 0 && !this.hero.body.touching.down) { + name = 'fall'; // Moving downward and not on ground + } else if (this.hero.body.velocity.x !== 0 && this.hero.body.touching.down) { + name = 'run'; // Moving horizontally on the ground + } + + return name; +}; +``` + +### Flipping the Sprite Based on Direction + +Update the hero's facing direction and play the animation in `update`: + +```javascript +PlayState.update = function () { + this._handleCollisions(); + this._handleInput(); + + // Flip sprite based on movement direction + if (this.hero.body.velocity.x < 0) { + this.hero.scale.x = -1; // Face left + } else if (this.hero.body.velocity.x > 0) { + this.hero.scale.x = 1; // Face right + } + + // Play the appropriate animation + this.hero.animations.play(this._getAnimationName()); + + // Update spider directions + this.spiders.forEach(function (spider) { + if (spider.body.touching.right || spider.body.blocked.right) { + spider.body.velocity.x = -Spider.SPEED; + } else if (spider.body.touching.left || spider.body.blocked.left) { + spider.body.velocity.x = Spider.SPEED; + } + }, this); +}; +``` + +- `this.hero.scale.x = -1` flips the sprite horizontally to face left. Setting it to `1` faces right. Because the anchor is at `(0.5, 1)`, the flip looks natural. +- `animations.play()` only restarts the animation if the name changes, so calling it every frame is safe and efficient. + +--- + +## Win Condition + +Add a door and key mechanic: the hero must collect a key, then reach the door to complete the level. + +### Loading Door and Key Assets + +```javascript +// In PlayState.preload: +this.game.load.spritesheet('door', 'images/door.png', 42, 66); +this.game.load.spritesheet('key', 'images/key.png', 20, 22); // Key bobbing animation +this.game.load.image('icon:key', 'images/key_icon.png'); + +this.game.load.audio('sfx:key', 'audio/sfx/key.wav'); +this.game.load.audio('sfx:door', 'audio/sfx/door.wav'); +``` + +### Spawning the Door and Key + +Update `_loadLevel` and `_spawnCharacters`: + +```javascript +PlayState._loadLevel = function (data) { + this.platforms = this.game.add.group(); + this.coins = this.game.add.group(); + this.spiders = this.game.add.group(); + this.enemyWalls = this.game.add.group(); + this.bgDecoration = this.game.add.group(); + + // Must spawn decorations first (background layer) + // Spawn door before hero so it renders behind the hero + data.platforms.forEach(this._spawnPlatform, this); + data.coins.forEach(this._spawnCoin, this); + data.spiders.forEach(this._spawnSpider, this); + + this._spawnDoor(data.door.x, data.door.y); + this._spawnKey(data.key.x, data.key.y); + this._spawnCharacters({ hero: data.hero }); + + this.enemyWalls.visible = false; + + this.coinPickupCount = 0; + this.hasKey = false; +}; + +PlayState._spawnDoor = function (x, y) { + this.door = this.bgDecoration.create(x, y, 'door'); + this.door.anchor.setTo(0.5, 1); + + this.game.physics.enable(this.door); + this.door.body.allowGravity = false; +}; + +PlayState._spawnKey = function (x, y) { + this.key = this.bgDecoration.create(x, y, 'key'); + this.key.anchor.set(0.5, 0.5); + + this.game.physics.enable(this.key); + this.key.body.allowGravity = false; + + // Add a bobbing up-and-down tween to the key + this.key.y -= 3; + this.game.add.tween(this.key) + .to({ y: this.key.y + 6 }, 800, Phaser.Easing.Sinusoidal.InOut) + .yoyo(true) + .loop() + .start(); +}; +``` + +- The door is placed in a background decoration group so it renders behind the hero. +- The key has a sinusoidal bobbing tween that moves it 6 pixels up and down over 800ms, looping forever. + +### Collecting the Key and Opening the Door + +Add key and door sound effects to the sfx object: + +```javascript +// In PlayState.create sfx: +this.sfx = { + jump: this.game.add.audio('sfx:jump'), + coin: this.game.add.audio('sfx:coin'), + stomp: this.game.add.audio('sfx:stomp'), + key: this.game.add.audio('sfx:key'), + door: this.game.add.audio('sfx:door') +}; +``` + +Add overlap detection for the key and door in `_handleCollisions`: + +```javascript +PlayState._handleCollisions = function () { + this.game.physics.arcade.collide(this.hero, this.platforms); + this.game.physics.arcade.collide(this.spiders, this.platforms); + this.game.physics.arcade.collide(this.spiders, this.enemyWalls); + + this.game.physics.arcade.overlap( + this.hero, this.coins, this._onHeroVsCoin, null, this + ); + this.game.physics.arcade.overlap( + this.hero, this.spiders, this._onHeroVsEnemy, null, this + ); + this.game.physics.arcade.overlap( + this.hero, this.key, this._onHeroVsKey, null, this + ); + this.game.physics.arcade.overlap( + this.hero, this.door, this._onHeroVsDoor, + // Only trigger if the hero has the key + function (hero, door) { + return this.hasKey && hero.body.touching.down; + }, this + ); +}; +``` + +- The door overlap has a **process callback** (the fourth argument) that only triggers the overlap callback when `this.hasKey` is true and the hero is standing on something. This prevents the hero from entering the door while falling or without the key. + +### Key and Door Callbacks + +```javascript +PlayState._onHeroVsKey = function (hero, key) { + this.sfx.key.play(); + key.kill(); + this.hasKey = true; +}; + +PlayState._onHeroVsDoor = function (hero, door) { + this.sfx.door.play(); + + // Freeze the hero and play the door opening animation + hero.body.velocity.x = 0; + hero.body.velocity.y = 0; + hero.body.enable = false; + + // Play door open animation (transition from closed to open frame) + door.frame = 1; // Switch to "open" frame + + // Advance to the next level after a short delay + this.game.time.events.add(500, this._goToNextLevel, this); +}; + +PlayState._goToNextLevel = function () { + this.camera.fade('#000'); + this.camera.onFadeComplete.addOnce(function () { + this.game.state.restart(true, false, { + level: this.level + 1 + }); + }, this); +}; +``` + +- When the hero touches the key, the key is removed and `hasKey` is set to `true`. +- When the hero reaches the door (with the key), the hero freezes, the door opens, and after a delay the game transitions to the next level. +- `camera.fade()` creates a fade-to-black transition for a polished level switch. + +### Showing the Key Icon in the HUD + +Update `_createHud` to show whether the hero has collected the key: + +```javascript +PlayState._createHud = function () { + this.keyIcon = this.game.make.image(0, 19, 'icon:key'); + this.keyIcon.anchor.set(0, 0.5); + + // ... existing coin HUD code ... + + this.hud.add(this.keyIcon); + this.hud.add(coinIcon); + this.hud.add(coinScoreImg); + this.hud.position.set(10, 10); + this.hud.fixedToCamera = true; +}; +``` + +Update the key icon appearance each frame in `update`: + +```javascript +// In PlayState.update, add: +this.keyIcon.frame = this.hasKey ? 1 : 0; +``` + +- Frame 0 shows a grayed-out key icon; frame 1 shows the collected key icon. + +--- + +## Switching Levels + +Support multiple levels by loading different JSON files based on a level index. + +### Passing Level Number Through init + +Modify `init` to accept a level parameter: + +```javascript +PlayState.init = function (data) { + this.game.renderer.renderSession.roundPixels = true; + + this.keys = this.game.input.keyboard.addKeys({ + left: Phaser.KeyCode.LEFT, + right: Phaser.KeyCode.RIGHT, + up: Phaser.KeyCode.UP + }); + + this.game.physics.startSystem(Phaser.Physics.ARCADE); + this.game.physics.arcade.gravity.y = 1200; + + // Store the current level number (default to 0) + this.level = (data.level || 0) % LEVEL_COUNT; +}; + +const LEVEL_COUNT = 2; // Total number of levels +``` + +- `data` is an object passed from `game.state.start()` or `game.state.restart()`. +- The modulo operation (`% LEVEL_COUNT`) wraps around to level 0 after the last level, creating an infinite loop of levels. + +### Loading Level Data Dynamically + +Update `preload` to load the correct level based on `this.level`: + +```javascript +PlayState.preload = function () { + this.game.load.image('background', 'images/background.png'); + + // Load the current level's JSON data + this.game.load.json('level:0', 'data/level00.json'); + this.game.load.json('level:1', 'data/level01.json'); + + // ... load all other assets ... +}; +``` + +Update `create` to use the correct level data: + +```javascript +PlayState.create = function () { + this.sfx = { + jump: this.game.add.audio('sfx:jump'), + coin: this.game.add.audio('sfx:coin'), + stomp: this.game.add.audio('sfx:stomp'), + key: this.game.add.audio('sfx:key'), + door: this.game.add.audio('sfx:door') + }; + + this.game.add.image(0, 0, 'background'); + + // Load level data based on current level number + this._loadLevel(this.game.cache.getJSON('level:' + this.level)); + + this._createHud(); +}; +``` + +### Starting the Game at Level 0 + +Update the initial state start to pass level 0: + +```javascript +window.onload = function () { + let game = new Phaser.Game(960, 600, Phaser.AUTO, 'game'); + game.state.add('play', PlayState); + game.state.start('play', true, false, { level: 0 }); +}; +``` + +- The third and fourth `start` arguments control world/cache clearing. `true, false` keeps the cache between restarts (so assets do not need to be reloaded) but clears the world. +- `{ level: 0 }` is passed to `init` as the `data` parameter. + +### Level Transition Flow + +The complete level flow is: + +1. Hero collects key -> `hasKey = true` +2. Hero reaches door -> `_onHeroVsDoor` fires +3. Camera fades to black -> `_goToNextLevel` fires +4. State restarts with `{ level: this.level + 1 }` +5. `init` receives the new level number +6. The correct level JSON is loaded and the game continues + +--- + +## Moving Forward + +Congratulations -- you have built a complete 2D platformer. Here are ideas for extending the game further: + +### Suggested Improvements + +- **Mobile / touch controls:** Add on-screen buttons or swipe gestures using `game.input.onDown` for touch-enabled devices. +- **More levels:** Create additional JSON level files with new platform layouts, coin placements, and enemy configurations. +- **Menu screen:** Add a `MenuState` with a title screen and start button before entering `PlayState`. +- **Game over screen:** Instead of instantly restarting, show a "Game Over" screen with the score. +- **Lives system:** Give the hero multiple lives instead of instant restart. +- **Power-ups:** Add items like speed boosts, double jump, or invincibility. +- **Moving platforms:** Create platforms that travel along a path using tweens. +- **Different enemy types:** Add flying enemies, enemies that shoot projectiles, or enemies with different movement patterns. +- **Parallax scrolling:** Add multiple background layers that scroll at different speeds for depth. +- **Camera scrolling:** For levels wider than the screen, use `game.camera.follow(this.hero)` to scroll with the hero. +- **Sound and music:** Add background music and additional sound effects for a more polished experience. +- **Particle effects:** Use Phaser's particle emitter for coin collection sparkles, enemy death effects, or dust when landing. + +### Full Game Source Reference + +Below is the complete `main.js` file combining all steps for reference. This represents the final state of the game with all features: + +```javascript +// ============================================================================= +// Constants +// ============================================================================= + +const SPEED = 200; +const JUMP_SPEED = 600; +const LEVEL_COUNT = 2; +const Spider = { SPEED: 100 }; + +// ============================================================================= +// Game State: PlayState +// ============================================================================= + +PlayState = {}; + +// ----------------------------------------------------------------------------- +// init +// ----------------------------------------------------------------------------- + +PlayState.init = function (data) { + this.game.renderer.renderSession.roundPixels = true; + + this.keys = this.game.input.keyboard.addKeys({ + left: Phaser.KeyCode.LEFT, + right: Phaser.KeyCode.RIGHT, + up: Phaser.KeyCode.UP + }); + + this.game.physics.startSystem(Phaser.Physics.ARCADE); + this.game.physics.arcade.gravity.y = 1200; + + this.level = (data.level || 0) % LEVEL_COUNT; +}; + +// ----------------------------------------------------------------------------- +// preload +// ----------------------------------------------------------------------------- + +PlayState.preload = function () { + // Background + this.game.load.image('background', 'images/background.png'); + + // Level data + this.game.load.json('level:0', 'data/level00.json'); + this.game.load.json('level:1', 'data/level01.json'); + + // Platform tiles + this.game.load.image('ground', 'images/ground.png'); + this.game.load.image('grass:8x1', 'images/grass_8x1.png'); + this.game.load.image('grass:6x1', 'images/grass_6x1.png'); + this.game.load.image('grass:4x1', 'images/grass_4x1.png'); + this.game.load.image('grass:2x1', 'images/grass_2x1.png'); + this.game.load.image('grass:1x1', 'images/grass_1x1.png'); + + // Characters + this.game.load.spritesheet('hero', 'images/hero.png', 36, 42); + this.game.load.spritesheet('spider', 'images/spider.png', 42, 32); + this.game.load.image('invisible-wall', 'images/invisible_wall.png'); + + // Collectibles + this.game.load.spritesheet('coin', 'images/coin_animated.png', 22, 22); + this.game.load.spritesheet('key', 'images/key.png', 20, 22); + this.game.load.spritesheet('door', 'images/door.png', 42, 66); + + // HUD + this.game.load.image('icon:coin', 'images/coin_icon.png'); + this.game.load.image('icon:key', 'images/key_icon.png'); + this.game.load.image('font:numbers', 'images/numbers.png'); + + // Audio + this.game.load.audio('sfx:jump', 'audio/sfx/jump.wav'); + this.game.load.audio('sfx:coin', 'audio/sfx/coin.wav'); + this.game.load.audio('sfx:stomp', 'audio/sfx/stomp.wav'); + this.game.load.audio('sfx:key', 'audio/sfx/key.wav'); + this.game.load.audio('sfx:door', 'audio/sfx/door.wav'); +}; + +// ----------------------------------------------------------------------------- +// create +// ----------------------------------------------------------------------------- + +PlayState.create = function () { + // Sound effects + this.sfx = { + jump: this.game.add.audio('sfx:jump'), + coin: this.game.add.audio('sfx:coin'), + stomp: this.game.add.audio('sfx:stomp'), + key: this.game.add.audio('sfx:key'), + door: this.game.add.audio('sfx:door') + }; + + // Background + this.game.add.image(0, 0, 'background'); + + // Load level + this._loadLevel(this.game.cache.getJSON('level:' + this.level)); + + // HUD + this._createHud(); +}; + +// ----------------------------------------------------------------------------- +// update +// ----------------------------------------------------------------------------- + +PlayState.update = function () { + this._handleCollisions(); + this._handleInput(); + + // Update hero sprite direction and animation + if (this.hero.body.velocity.x < 0) { + this.hero.scale.x = -1; + } else if (this.hero.body.velocity.x > 0) { + this.hero.scale.x = 1; + } + this.hero.animations.play(this._getAnimationName()); + + // Update spider directions when hitting walls + this.spiders.forEach(function (spider) { + if (spider.body.touching.right || spider.body.blocked.right) { + spider.body.velocity.x = -Spider.SPEED; + } else if (spider.body.touching.left || spider.body.blocked.left) { + spider.body.velocity.x = Spider.SPEED; + } + }, this); + + // Update key icon in HUD + this.keyIcon.frame = this.hasKey ? 1 : 0; +}; + +// ----------------------------------------------------------------------------- +// Level Loading +// ----------------------------------------------------------------------------- + +PlayState._loadLevel = function (data) { + // Create groups (order matters for rendering layers) + this.bgDecoration = this.game.add.group(); + this.platforms = this.game.add.group(); + this.coins = this.game.add.group(); + this.spiders = this.game.add.group(); + this.enemyWalls = this.game.add.group(); + + // Spawn entities from level data + data.platforms.forEach(this._spawnPlatform, this); + data.coins.forEach(this._spawnCoin, this); + data.spiders.forEach(this._spawnSpider, this); + + this._spawnDoor(data.door.x, data.door.y); + this._spawnKey(data.key.x, data.key.y); + this._spawnCharacters({ hero: data.hero }); + + // Hide invisible walls + this.enemyWalls.visible = false; + + // Initialize game state + this.coinPickupCount = 0; + this.hasKey = false; +}; + +// ----------------------------------------------------------------------------- +// Spawn Methods +// ----------------------------------------------------------------------------- + +PlayState._spawnPlatform = function (platform) { + let sprite = this.platforms.create(platform.x, platform.y, platform.image); + this.game.physics.enable(sprite); + sprite.body.allowGravity = false; + sprite.body.immovable = true; + + // Add invisible walls at both edges for enemy AI + this._spawnEnemyWall(platform.x, platform.y, 'left'); + this._spawnEnemyWall(platform.x + sprite.width, platform.y, 'right'); +}; + +PlayState._spawnEnemyWall = function (x, y, side) { + let sprite = this.enemyWalls.create(x, y, 'invisible-wall'); + sprite.anchor.set(side === 'left' ? 1 : 0, 1); + this.game.physics.enable(sprite); + sprite.body.immovable = true; + sprite.body.allowGravity = false; +}; + +PlayState._spawnCharacters = function (data) { + this.hero = this.game.add.sprite(data.hero.x, data.hero.y, 'hero'); + this.hero.anchor.set(0.5, 1); + this.game.physics.enable(this.hero); + this.hero.body.collideWorldBounds = true; + + // Hero animations + this.hero.animations.add('stop', [0]); + this.hero.animations.add('run', [1, 2], 8, true); + this.hero.animations.add('jump', [3]); + this.hero.animations.add('fall', [4]); +}; + +PlayState._spawnCoin = function (coin) { + let sprite = this.coins.create(coin.x, coin.y, 'coin'); + sprite.anchor.set(0.5, 0.5); + this.game.physics.enable(sprite); + sprite.body.allowGravity = false; + + sprite.animations.add('rotate', [0, 1, 2, 1], 6, true); + sprite.animations.play('rotate'); +}; + +PlayState._spawnSpider = function (spider) { + let sprite = this.spiders.create(spider.x, spider.y, 'spider'); + sprite.anchor.set(0.5, 1); + this.game.physics.enable(sprite); + + sprite.animations.add('crawl', [0, 1, 2], 8, true); + sprite.animations.add('die', [0, 4, 0, 4, 0, 4, 3, 3, 3, 3, 3, 3], 12); + sprite.animations.play('crawl'); + + sprite.body.velocity.x = Spider.SPEED; +}; + +PlayState._spawnDoor = function (x, y) { + this.door = this.bgDecoration.create(x, y, 'door'); + this.door.anchor.setTo(0.5, 1); + this.game.physics.enable(this.door); + this.door.body.allowGravity = false; +}; + +PlayState._spawnKey = function (x, y) { + this.key = this.bgDecoration.create(x, y, 'key'); + this.key.anchor.set(0.5, 0.5); + this.game.physics.enable(this.key); + this.key.body.allowGravity = false; + + // Bobbing tween + this.key.y -= 3; + this.game.add.tween(this.key) + .to({ y: this.key.y + 6 }, 800, Phaser.Easing.Sinusoidal.InOut) + .yoyo(true) + .loop() + .start(); +}; + +// ----------------------------------------------------------------------------- +// Input +// ----------------------------------------------------------------------------- + +PlayState._handleInput = function () { + if (!this.hero.alive) { return; } + + if (this.keys.left.isDown) { + this.hero.body.velocity.x = -SPEED; + } else if (this.keys.right.isDown) { + this.hero.body.velocity.x = SPEED; + } else { + this.hero.body.velocity.x = 0; + } + + if (this.keys.up.isDown) { + this._jump(); + } +}; + +PlayState._jump = function () { + let canJump = this.hero.body.touching.down; + if (canJump) { + this.hero.body.velocity.y = -JUMP_SPEED; + this.sfx.jump.play(); + } + return canJump; +}; + +// ----------------------------------------------------------------------------- +// Collisions +// ----------------------------------------------------------------------------- + +PlayState._handleCollisions = function () { + // Physical collisions + this.game.physics.arcade.collide(this.hero, this.platforms); + this.game.physics.arcade.collide(this.spiders, this.platforms); + this.game.physics.arcade.collide(this.spiders, this.enemyWalls); + + // Overlap detection (no physical push) + this.game.physics.arcade.overlap( + this.hero, this.coins, this._onHeroVsCoin, null, this + ); + this.game.physics.arcade.overlap( + this.hero, this.spiders, this._onHeroVsEnemy, null, this + ); + this.game.physics.arcade.overlap( + this.hero, this.key, this._onHeroVsKey, null, this + ); + this.game.physics.arcade.overlap( + this.hero, this.door, this._onHeroVsDoor, + function (hero, door) { + return this.hasKey && hero.body.touching.down; + }, this + ); +}; + +// ----------------------------------------------------------------------------- +// Collision Callbacks +// ----------------------------------------------------------------------------- + +PlayState._onHeroVsCoin = function (hero, coin) { + this.sfx.coin.play(); + coin.kill(); + this.coinPickupCount++; + this.coinFont.text = 'x' + this.coinPickupCount; +}; + +PlayState._onHeroVsEnemy = function (hero, enemy) { + if (hero.body.velocity.y > 0) { + // Stomp: hero is falling onto the enemy + enemy.body.velocity.x = 0; + enemy.body.enable = false; + enemy.animations.play('die'); + enemy.events.onAnimationComplete.addOnce(function () { + enemy.kill(); + }); + hero.body.velocity.y = -JUMP_SPEED / 2; + this.sfx.stomp.play(); + } else { + // Hero dies + this._killHero(); + } +}; + +PlayState._onHeroVsKey = function (hero, key) { + this.sfx.key.play(); + key.kill(); + this.hasKey = true; +}; + +PlayState._onHeroVsDoor = function (hero, door) { + this.sfx.door.play(); + hero.body.velocity.x = 0; + hero.body.velocity.y = 0; + hero.body.enable = false; + + door.frame = 1; // Open door + + this.game.time.events.add(500, this._goToNextLevel, this); +}; + +// ----------------------------------------------------------------------------- +// Death and Level Transitions +// ----------------------------------------------------------------------------- + +PlayState._killHero = function () { + this.hero.alive = false; + this.hero.body.velocity.y = -JUMP_SPEED / 2; + this.hero.body.velocity.x = 0; + this.hero.body.allowGravity = true; + this.hero.body.collideWorldBounds = false; + + this.game.time.events.add(1000, function () { + this.game.state.restart(true, false, { level: this.level }); + }, this); +}; + +PlayState._goToNextLevel = function () { + this.camera.fade('#000'); + this.camera.onFadeComplete.addOnce(function () { + this.game.state.restart(true, false, { + level: this.level + 1 + }); + }, this); +}; + +// ----------------------------------------------------------------------------- +// Animations +// ----------------------------------------------------------------------------- + +PlayState._getAnimationName = function () { + let name = 'stop'; + + if (!this.hero.alive) { + name = 'stop'; + } else if (this.hero.body.velocity.y < 0) { + name = 'jump'; + } else if (this.hero.body.velocity.y > 0 && !this.hero.body.touching.down) { + name = 'fall'; + } else if (this.hero.body.velocity.x !== 0 && this.hero.body.touching.down) { + name = 'run'; + } + + return name; +}; + +// ----------------------------------------------------------------------------- +// HUD +// ----------------------------------------------------------------------------- + +PlayState._createHud = function () { + this.keyIcon = this.game.make.image(0, 19, 'icon:key'); + this.keyIcon.anchor.set(0, 0.5); + + let coinIcon = this.game.make.image( + this.keyIcon.width + 7, 0, 'icon:coin' + ); + + let scoreStyle = { font: '24px monospace', fill: '#fff' }; + this.coinFont = this.game.add.text( + coinIcon.x + coinIcon.width + 7, 0, 'x0', scoreStyle + ); + + this.hud = this.game.add.group(); + this.hud.add(this.keyIcon); + this.hud.add(coinIcon); + this.hud.add(this.coinFont); + this.hud.position.set(10, 10); + this.hud.fixedToCamera = true; +}; + +// ============================================================================= +// Entry Point +// ============================================================================= + +window.onload = function () { + let game = new Phaser.Game(960, 600, Phaser.AUTO, 'game'); + game.state.add('play', PlayState); + game.state.start('play', true, false, { level: 0 }); +}; +``` + +### Key Concepts Summary + +| Concept | Phaser API | Purpose | +|---------|-----------|---------| +| Game instance | `new Phaser.Game(w, h, renderer, container)` | Creates the game canvas and engine | +| Game states | `game.state.add()` / `game.state.start()` | Organizes code into init/preload/create/update lifecycle | +| Loading images | `game.load.image(key, path)` | Loads a static image asset | +| Loading spritesheets | `game.load.spritesheet(key, path, fw, fh)` | Loads an animated spritesheet | +| Loading JSON | `game.load.json(key, path)` | Loads JSON data (level definitions) | +| Loading audio | `game.load.audio(key, path)` | Loads a sound effect | +| Sprite groups | `game.add.group()` | Container for related sprites; enables batch collision detection | +| Physics bodies | `game.physics.enable(sprite)` | Adds an Arcade Physics body to a sprite | +| Gravity | `game.physics.arcade.gravity.y` | Global downward acceleration | +| Collision | `arcade.collide(a, b)` | Physical collision resolution (sprites push each other) | +| Overlap | `arcade.overlap(a, b, callback)` | Detection without physical push (for pickups) | +| Velocity | `sprite.body.velocity.x/y` | Movement speed in pixels per second | +| Immovable | `sprite.body.immovable = true` | Prevents sprite from being pushed by collisions | +| Animations | `sprite.animations.add(name, frames, fps, loop)` | Defines a frame animation | +| Tweens | `game.add.tween(target).to(props, duration, easing)` | Smooth property animation | +| Keyboard input | `game.input.keyboard.addKeys({...})` | Captures specific keyboard keys | +| Camera | `this.camera.fade()` | Screen transition effects | +| Anchor | `sprite.anchor.set(x, y)` | Sets the origin point for positioning and rotation | +| Sprite flipping | `sprite.scale.x = -1` | Horizontally mirrors the sprite | diff --git a/skills/game-engine/assets/gameBase-template-repo.md b/skills/game-engine/assets/gameBase-template-repo.md new file mode 100644 index 000000000..795ac0257 --- /dev/null +++ b/skills/game-engine/assets/gameBase-template-repo.md @@ -0,0 +1,310 @@ +# GameBase Template Repository + +A feature-rich, opinionated starter template for 2D game projects built with **Haxe** and the **Heaps** game engine. Created and maintained by **Sebastien Benard** (deepnight), the lead developer behind *Dead Cells*. GameBase provides a production-tested foundation with entity management, level integration via LDtk, rendering pipeline, and a game loop architecture -- all designed to let developers skip boilerplate and jump straight into game-specific logic. + +**Repository:** [github.com/deepnight/gameBase](https://github.com/deepnight/gameBase) +**Author:** [Sebastien Benard / deepnight](https://deepnight.net) +**Technology:** Haxe + Heaps (HashLink or JS targets) +**Level editor integration:** [LDtk](https://ldtk.io) + +--- + +## Purpose + +GameBase exists to solve the "blank project" problem. Instead of setting up rendering, entity systems, camera controls, debug overlays, and level loading from scratch, developers clone this repository and begin implementing game-specific mechanics immediately. It reflects patterns refined through commercial game development, particularly from the development of *Dead Cells*. + +Key benefits: +- Pre-built entity system with grid-based positioning and sub-pixel precision +- LDtk level editor integration for visual level design +- Built-in debug tools and overlays +- Frame-rate independent game loop with fixed-step updates +- Camera system with follow, shake, zoom, and clamp +- Configurable Controller/input management +- Scalable rendering pipeline with Heaps + +--- + +## Repository Structure + +``` +gameBase/ + src/ + game/ + App.hx -- Application entry point and initialization + Game.hx -- Main game process, holds level and entities + Entity.hx -- Base entity class with grid coords, velocity, animation + Level.hx -- Level loading and collision map from LDtk + Camera.hx -- Camera follow, shake, zoom, clamping + Fx.hx -- Visual effects (particles, flashes, etc.) + Types.hx -- Enums, typedefs, and constants + en/ + Hero.hx -- Player entity (example implementation) + Mob.hx -- Enemy entity (example implementation) + import.hx -- Global imports (available everywhere) + res/ + atlas/ -- Sprite sheets and texture atlases + levels/ -- LDtk level project files + fonts/ -- Bitmap fonts + .ldtk -- LDtk project file (root) + build.hxml -- Haxe compiler configuration + Makefile -- Build/run shortcuts + README.md +``` + +--- + +## Key Files and Their Roles + +### `src/game/App.hx` -- Application Entry Point + +The main application class that extends `dn.Process`. Handles: +- Window/display initialization +- Scene management (root scene graph) +- Global input controller setup +- Debug toggle and console + +```haxe +class App extends dn.Process { + public static var ME : App; + + override function init() { + ME = this; + // Initialize rendering, controller, assets + new Game(); + } +} +``` + +### `src/game/Game.hx` -- Game Process + +Manages the active game session: +- Holds reference to the current `Level` +- Manages all active `Entity` instances (via a global linked list) +- Handles pause, game-over, and restart logic +- Coordinates camera and effects + +```haxe +class Game extends dn.Process { + public var level : Level; + public var hero : en.Hero; + public var fx : Fx; + public var camera : Camera; + + public function new() { + super(App.ME); + level = new Level(); + fx = new Fx(); + camera = new Camera(); + hero = new en.Hero(); + } +} +``` + +### `src/game/Entity.hx` -- Base Entity + +The core entity class featuring: +- **Grid-based positioning:** `cx`, `cy` (integer cell coordinates) plus `xr`, `yr` (sub-cell ratio 0.0 to 1.0) for smooth sub-pixel movement +- **Velocity and friction:** `dx`, `dy` (velocity) with configurable `frictX`, `frictY` +- **Gravity:** Optional per-entity gravity +- **Sprite management:** Animated sprite via Heaps `h2d.Anim` or `dn.heaps.HSprite` +- **Lifecycle:** `update()`, `fixedUpdate()`, `postUpdate()`, `dispose()` +- **Collision helpers:** `hasCollision(cx, cy)` check against the level collision map + +```haxe +class Entity { + // Grid position + public var cx : Int = 0; // Cell X + public var cy : Int = 0; // Cell Y + public var xr : Float = 0.5; // X ratio within cell (0..1) + public var yr : Float = 1.0; // Y ratio within cell (0..1) + + // Velocity + public var dx : Float = 0; + public var dy : Float = 0; + + // Pixel position (computed) + public var attachX(get,never) : Float; + inline function get_attachX() return (cx + xr) * Const.GRID; + public var attachY(get,never) : Float; + inline function get_attachY() return (cy + yr) * Const.GRID; + + // Physics step + public function fixedUpdate() { + xr += dx; + dx *= frictX; + + // X collision + if (xr > 1) { cx++; xr--; } + if (xr < 0) { cx--; xr++; } + + yr += dy; + dy *= frictY; + + // Y collision + if (yr > 1) { cy++; yr--; } + if (yr < 0) { cy--; yr++; } + } +} +``` + +### `src/game/Level.hx` -- Level Management + +Loads and manages level data from LDtk project files: +- Parses tile layers, entity layers, and int grid layers +- Builds a collision grid (`hasCollision(cx, cy)`) +- Provides helper methods to query the level structure + +```haxe +class Level { + var data : ldtk.Level; + var collisions : Map; + + public function new(ldtkLevel) { + data = ldtkLevel; + // Parse IntGrid layer for collision marks + for (cy in 0...data.l_Collisions.cHei) + for (cx in 0...data.l_Collisions.cWid) + if (data.l_Collisions.getInt(cx, cy) == 1) + collisions.set(coordId(cx, cy), true); + } + + public inline function hasCollision(cx:Int, cy:Int) : Bool { + return collisions.exists(coordId(cx, cy)); + } +} +``` + +### `src/game/Camera.hx` -- Camera System + +Provides: +- **Target tracking:** Follow an entity smoothly with configurable dead zones +- **Shake:** Screen shake with decay +- **Zoom:** Dynamic zoom in/out +- **Clamping:** Keep the camera within level bounds + +### `src/game/Fx.hx` -- Effects System + +Particle and visual effect management: +- Particle pools +- Screen flash +- Slow-motion helpers +- Color overlay effects + +--- + +## Technology Stack + +### Haxe + +A cross-platform, high-level programming language that compiles to multiple targets: +- **HashLink (HL):** Native bytecode VM for desktop (primary dev target) +- **JavaScript (JS):** Browser/web target +- **C/C++:** Via HXCPP for native builds + +### Heaps (Heaps.io) + +A high-performance, cross-platform 2D/3D game engine: +- GPU-accelerated rendering via OpenGL/DirectX/WebGL +- Scene graph architecture with `h2d.Object` hierarchy +- Sprite batching and texture atlases +- Bitmap font rendering +- Input abstraction + +### LDtk + +A modern, open-source 2D level editor created by Sebastien Benard: +- Visual, tile-based level design +- IntGrid layers for collision and metadata +- Entity layers for game object placement +- Auto-tiling rules +- Haxe API auto-generated from the project file + +--- + +## Setup Instructions + +### Prerequisites + +1. **Install Haxe** (4.0+): [haxe.org](https://haxe.org/download/) +2. **Install HashLink** (for desktop target): [hashlink.haxe.org](https://hashlink.haxe.org/) +3. **Install LDtk** (for level editing): [ldtk.io](https://ldtk.io/) + +### Getting Started + +```bash +# Clone the repository +git clone https://github.com/deepnight/gameBase.git my-game +cd my-game + +# Install Haxe dependencies +haxelib install heaps +haxelib install deepnightLibs +haxelib install ldtk-haxe-api + +# Build and run (HashLink target) +haxe build.hxml +hl bin/client.hl + +# Or use the Makefile (if available) +make run +``` + +### Using as a Starting Point + +1. **Clone or use the template** -- Do not fork; clone into a new directory with your game's name. +2. **Rename the package** -- Update `src/game/` package declarations and project references to match your game. +3. **Edit `build.hxml`** -- Adjust the main class, output path, and target as needed. +4. **Design levels in LDtk** -- Open the `.ldtk` file, define your layers and entities, and export. +5. **Implement entities** -- Create new entity classes in `src/game/en/` extending `Entity`. +6. **Iterate** -- Use the debug console (toggle in-game) for live inspection and tuning. + +--- + +## Build Targets + +| Target | Command | Output | Use Case | +|--------|---------|--------|----------| +| HashLink | `haxe build.hxml` | `bin/client.hl` | Development, desktop release | +| JavaScript | `haxe build.js.hxml` | `bin/client.js` | Web/browser builds | +| DirectX/OpenGL | Via HL native | Native executable | Production desktop release | + +--- + +## Debug Features + +GameBase includes built-in debug tooling: +- **Debug overlay:** Toggle with a key to show entity bounds, grid, velocities, collision map +- **Console:** In-game command console for toggling flags, teleporting, spawning entities +- **FPS counter:** Visible frame-rate and update-rate monitor +- **Process inspector:** View active processes and their hierarchy + +--- + +## Game Loop Architecture + +GameBase uses a fixed-timestep game loop pattern: + +``` +Each frame: + 1. preUpdate() -- Input polling, pre-frame logic + 2. fixedUpdate() -- Physics, movement, collisions (fixed timestep) + - May run 0-N times per frame to catch up + 3. update() -- General per-frame logic + 4. postUpdate() -- Sprite position sync, camera update, rendering prep +``` + +This ensures physics behavior is consistent regardless of frame rate, while rendering and visual updates remain smooth. + +--- + +## Entity Lifecycle + +``` +Constructor --> init() --> [game loop: fixedUpdate/update/postUpdate] --> dispose() +``` + +- **Constructor:** Set initial position, create sprite, register in global entity list +- **fixedUpdate():** Physics step (velocity, friction, gravity, collision) +- **update():** AI, state machine, animation triggers +- **postUpdate():** Sync sprite position to grid coordinates, apply visual effects +- **dispose():** Remove from entity list, destroy sprite, clean up references diff --git a/skills/game-engine/assets/paddle-game-template.md b/skills/game-engine/assets/paddle-game-template.md new file mode 100644 index 000000000..2222e997b --- /dev/null +++ b/skills/game-engine/assets/paddle-game-template.md @@ -0,0 +1,1528 @@ +# Paddle Game Template (2D Breakout) + +A complete step-by-step guide for building a 2D Breakout game with pure JavaScript and the HTML5 Canvas API. This template walks through every stage of development, from setting up the canvas to implementing a lives system and polished game loop. + +**What you will build:** A classic breakout/paddle game where the player controls a paddle to bounce a ball and destroy a field of bricks, with score tracking, win/lose conditions, keyboard and mouse controls, and a lives system. + +**Prerequisites:** Basic to intermediate JavaScript knowledge and familiarity with HTML. + +**Source:** Based on the [MDN 2D Breakout Game Tutorial](https://developer.mozilla.org/en-US/docs/Games/Tutorials/2D_Breakout_game_pure_JavaScript). + +--- + +## Step 1: Create the Canvas and Draw on It + +The first step is setting up the HTML document with a `` element and learning to draw basic shapes using the 2D rendering context. + +### HTML Structure + +Create your base HTML file with an embedded canvas element: + +```html + + + + + Gamedev Canvas Workshop + + + + + + + + +``` + +### Getting the Canvas Reference and 2D Context + +The canvas element provides a drawing surface. You access it through a 2D rendering context: + +```javascript +const canvas = document.getElementById("myCanvas"); +const ctx = canvas.getContext("2d"); +``` + +- `canvas` is a reference to the HTML `` element. +- `ctx` is the 2D rendering context object, which provides all drawing methods. + +### Drawing a Filled Rectangle + +Use `rect()` to define a rectangle and `fill()` to render it: + +```javascript +ctx.beginPath(); +ctx.rect(20, 40, 50, 50); +ctx.fillStyle = "red"; +ctx.fill(); +ctx.closePath(); +``` + +- The first two parameters (`20, 40`) set the top-left corner coordinates. +- The second two parameters (`50, 50`) set the width and height. +- `fillStyle` sets the fill color. +- `fill()` renders the shape as a solid fill. + +### Drawing a Circle + +Use `arc()` to define a circle: + +```javascript +ctx.beginPath(); +ctx.arc(240, 160, 20, 0, Math.PI * 2, false); +ctx.fillStyle = "green"; +ctx.fill(); +ctx.closePath(); +``` + +- `240, 160` -- center x, y coordinates. +- `20` -- radius. +- `0` -- start angle (radians). +- `Math.PI * 2` -- end angle (full circle). +- `false` -- draw clockwise. + +### Drawing a Stroked Rectangle (Outline Only) + +Use `stroke()` instead of `fill()` for outlines, and `strokeStyle` for outline color: + +```javascript +ctx.beginPath(); +ctx.rect(160, 10, 100, 40); +ctx.strokeStyle = "rgb(0 0 255 / 50%)"; +ctx.stroke(); +ctx.closePath(); +``` + +- Uses an RGB color with 50% alpha transparency. +- `stroke()` draws only the outline, not a solid fill. + +### Key Methods Reference + +| Method | Purpose | +|--------|---------| +| `beginPath()` | Start a new drawing path | +| `closePath()` | Close the current path | +| `rect(x, y, width, height)` | Define a rectangle | +| `arc(x, y, radius, startAngle, endAngle, counterclockwise)` | Define a circle or arc | +| `fillStyle` | Set the fill color | +| `fill()` | Fill the shape with the fill color | +| `strokeStyle` | Set the stroke (outline) color | +| `stroke()` | Draw an outline of the shape | + +### Complete Code for Step 1 + +```html + + + + + +``` + +--- + +## Step 2: Move the Ball + +Now we animate the ball by creating a game loop that redraws the canvas on each frame and updates the ball position using velocity variables. + +### Creating the Draw Loop + +Define a `draw()` function that executes repeatedly using `setInterval`: + +```javascript +function draw() { + // drawing code +} +setInterval(draw, 10); +``` + +`setInterval(draw, 10)` calls the `draw` function every 10 milliseconds, creating approximately 100 frames per second. + +### Drawing the Ball + +Inside the `draw()` function, draw a ball (circle) at a fixed position: + +```javascript +ctx.beginPath(); +ctx.arc(50, 50, 10, 0, Math.PI * 2); +ctx.fillStyle = "#0095DD"; +ctx.fill(); +ctx.closePath(); +``` + +### Adding Position Variables + +Instead of hardcoded positions, use variables so we can update them each frame. Place these above the `draw()` function: + +```javascript +let x = canvas.width / 2; +let y = canvas.height - 30; +``` + +This starts the ball at the horizontal center, near the bottom of the canvas. + +### Adding Velocity Variables + +Define speed and direction for horizontal (`dx`) and vertical (`dy`) movement: + +```javascript +let dx = 2; +let dy = -2; +``` + +- `dx = 2` moves the ball 2 pixels right per frame. +- `dy = -2` moves the ball 2 pixels up per frame (negative y is upward on canvas). + +### Updating Position Each Frame + +Add position updates at the end of the `draw()` function: + +```javascript +x += dx; +y += dy; +``` + +### Clearing the Canvas + +Without clearing, the ball leaves a trail. Add `clearRect()` at the start of each frame: + +```javascript +ctx.clearRect(0, 0, canvas.width, canvas.height); +``` + +### Refactoring Into a Separate drawBall() Function + +For clean, maintainable code, separate the ball-drawing logic: + +```javascript +function drawBall() { + ctx.beginPath(); + ctx.arc(x, y, 10, 0, Math.PI * 2); + ctx.fillStyle = "#0095DD"; + ctx.fill(); + ctx.closePath(); +} +``` + +### Complete Code for Step 2 + +```javascript +const canvas = document.getElementById("myCanvas"); +const ctx = canvas.getContext("2d"); + +let x = canvas.width / 2; +let y = canvas.height - 30; +let dx = 2; +let dy = -2; + +function drawBall() { + ctx.beginPath(); + ctx.arc(x, y, 10, 0, Math.PI * 2); + ctx.fillStyle = "#0095DD"; + ctx.fill(); + ctx.closePath(); +} + +function draw() { + ctx.clearRect(0, 0, canvas.width, canvas.height); + drawBall(); + x += dx; + y += dy; +} + +setInterval(draw, 10); +``` + +**Key concepts:** +- **Animation loop**: `setInterval(draw, 10)` continuously redraws the scene. +- **Position variables**: `x` and `y` track the ball's current location. +- **Velocity variables**: `dx` and `dy` determine movement per frame. +- **Canvas clearing**: `clearRect()` removes the previous frame before drawing the new one. + +--- + +## Step 3: Bounce Off the Walls + +We add collision detection so the ball bounces off the canvas edges instead of disappearing. + +### Defining the Ball Radius + +Extract the ball radius into a named constant for reuse in collision calculations: + +```javascript +const ballRadius = 10; +``` + +Update `drawBall()` to use this variable: + +```javascript +function drawBall() { + ctx.beginPath(); + ctx.arc(x, y, ballRadius, 0, Math.PI * 2); + ctx.fillStyle = "#0095DD"; + ctx.fill(); + ctx.closePath(); +} +``` + +### Basic Wall Collision (Without Radius Adjustment) + +The simplest approach checks if the next ball position goes beyond the canvas boundaries: + +```javascript +// Left and right walls +if (x + dx > canvas.width || x + dx < 0) { + dx = -dx; +} + +// Top and bottom walls +if (y + dy > canvas.height || y + dy < 0) { + dy = -dy; +} +``` + +Reversing `dx` or `dy` (multiplying by -1) changes the ball's direction. + +### Improved Collision (Accounting for Ball Radius) + +The basic version lets the ball sink halfway into the wall before bouncing. To fix this, account for the ball's radius: + +```javascript +// Left and right walls +if (x + dx > canvas.width - ballRadius || x + dx < ballRadius) { + dx = -dx; +} + +// Top and bottom walls +if (y + dy > canvas.height - ballRadius || y + dy < ballRadius) { + dy = -dy; +} +``` + +### Collision Detection Conditions + +| Wall | Condition | Action | +|------|-----------|--------| +| **Left** | `x + dx < ballRadius` | `dx = -dx` | +| **Right** | `x + dx > canvas.width - ballRadius` | `dx = -dx` | +| **Top** | `y + dy < ballRadius` | `dy = -dy` | +| **Bottom** | `y + dy > canvas.height - ballRadius` | `dy = -dy` | + +### Complete Code for Step 3 + +```javascript +const canvas = document.getElementById("myCanvas"); +const ctx = canvas.getContext("2d"); +const ballRadius = 10; + +let x = canvas.width / 2; +let y = canvas.height - 30; +let dx = 2; +let dy = -2; + +function drawBall() { + ctx.beginPath(); + ctx.arc(x, y, ballRadius, 0, Math.PI * 2); + ctx.fillStyle = "#0095DD"; + ctx.fill(); + ctx.closePath(); +} + +function draw() { + ctx.clearRect(0, 0, canvas.width, canvas.height); + drawBall(); + + // Collision detection - left and right walls + if (x + dx > canvas.width - ballRadius || x + dx < ballRadius) { + dx = -dx; + } + + // Collision detection - top and bottom walls + if (y + dy > canvas.height - ballRadius || y + dy < ballRadius) { + dy = -dy; + } + + x += dx; + y += dy; +} + +setInterval(draw, 10); +``` + +--- + +## Step 4: Paddle and Keyboard Controls + +Now we add a player-controlled paddle at the bottom of the screen and wire up keyboard input (left/right arrow keys). + +### Defining Paddle Variables + +```javascript +const paddleHeight = 10; +const paddleWidth = 75; +let paddleX = (canvas.width - paddleWidth) / 2; +``` + +- `paddleHeight` and `paddleWidth` define the paddle dimensions. +- `paddleX` starts the paddle centered horizontally. It is a `let` because it will change as the player moves it. + +### Drawing the Paddle + +Create a `drawPaddle()` function. The paddle sits at the very bottom of the canvas: + +```javascript +function drawPaddle() { + ctx.beginPath(); + ctx.rect(paddleX, canvas.height - paddleHeight, paddleWidth, paddleHeight); + ctx.fillStyle = "#0095DD"; + ctx.fill(); + ctx.closePath(); +} +``` + +- The y-position is `canvas.height - paddleHeight`, placing it flush with the bottom edge. + +### Keyboard State Variables + +Track whether arrow keys are currently pressed: + +```javascript +let rightPressed = false; +let leftPressed = false; +``` + +### Event Listeners for Key Presses + +Register handlers for `keydown` (key pressed) and `keyup` (key released): + +```javascript +document.addEventListener("keydown", keyDownHandler); +document.addEventListener("keyup", keyUpHandler); +``` + +### Key Handler Functions + +Set the boolean flags based on which key is pressed or released: + +```javascript +function keyDownHandler(e) { + if (e.key === "Right" || e.key === "ArrowRight") { + rightPressed = true; + } else if (e.key === "Left" || e.key === "ArrowLeft") { + leftPressed = true; + } +} + +function keyUpHandler(e) { + if (e.key === "Right" || e.key === "ArrowRight") { + rightPressed = false; + } else if (e.key === "Left" || e.key === "ArrowLeft") { + leftPressed = false; + } +} +``` + +Both `"ArrowRight"` (modern browsers) and `"Right"` (legacy IE/Edge) are checked for compatibility. + +### Paddle Movement Logic (With Boundary Checking) + +Add this inside the `draw()` function to move the paddle based on key state, while keeping it within canvas bounds: + +```javascript +if (rightPressed) { + paddleX = Math.min(paddleX + 7, canvas.width - paddleWidth); +} else if (leftPressed) { + paddleX = Math.max(paddleX - 7, 0); +} +``` + +- The paddle moves 7 pixels per frame. +- `Math.min` prevents the paddle from going past the right edge. +- `Math.max` prevents it from going past the left edge. + +### Complete Code for Step 4 + +```javascript +const canvas = document.getElementById("myCanvas"); +const ctx = canvas.getContext("2d"); +const ballRadius = 10; + +let x = canvas.width / 2; +let y = canvas.height - 30; +let dx = 2; +let dy = -2; + +const paddleHeight = 10; +const paddleWidth = 75; +let paddleX = (canvas.width - paddleWidth) / 2; + +let rightPressed = false; +let leftPressed = false; + +document.addEventListener("keydown", keyDownHandler); +document.addEventListener("keyup", keyUpHandler); + +function keyDownHandler(e) { + if (e.key === "Right" || e.key === "ArrowRight") { + rightPressed = true; + } else if (e.key === "Left" || e.key === "ArrowLeft") { + leftPressed = true; + } +} + +function keyUpHandler(e) { + if (e.key === "Right" || e.key === "ArrowRight") { + rightPressed = false; + } else if (e.key === "Left" || e.key === "ArrowLeft") { + leftPressed = false; + } +} + +function drawBall() { + ctx.beginPath(); + ctx.arc(x, y, ballRadius, 0, Math.PI * 2); + ctx.fillStyle = "#0095DD"; + ctx.fill(); + ctx.closePath(); +} + +function drawPaddle() { + ctx.beginPath(); + ctx.rect(paddleX, canvas.height - paddleHeight, paddleWidth, paddleHeight); + ctx.fillStyle = "#0095DD"; + ctx.fill(); + ctx.closePath(); +} + +function draw() { + ctx.clearRect(0, 0, canvas.width, canvas.height); + drawBall(); + drawPaddle(); + + if (x + dx > canvas.width - ballRadius || x + dx < ballRadius) { + dx = -dx; + } + if (y + dy > canvas.height - ballRadius || y + dy < ballRadius) { + dy = -dy; + } + + if (rightPressed) { + paddleX = Math.min(paddleX + 7, canvas.width - paddleWidth); + } else if (leftPressed) { + paddleX = Math.max(paddleX - 7, 0); + } + + x += dx; + y += dy; +} + +setInterval(draw, 10); +``` + +--- + +## Step 5: Game Over + +We replace the bottom-wall bounce with actual game logic: the ball should bounce off the paddle, but if it misses, it is game over. + +### Storing the Interval Reference + +To stop the game loop on game over, store the interval ID: + +```javascript +let interval = 0; +``` + +Then assign the return value of `setInterval`: + +```javascript +interval = setInterval(draw, 10); +``` + +### Implementing Game Over and Paddle Collision + +Replace the bottom-wall collision check. Instead of bouncing off the bottom edge, we now check whether the ball hits the paddle or misses it: + +```javascript +if (y + dy < ballRadius) { + // Ball hits top wall -- bounce + dy = -dy; +} else if (y + dy > canvas.height - ballRadius) { + // Ball reaches bottom edge + if (x > paddleX && x < paddleX + paddleWidth) { + // Ball hits paddle -- bounce + dy = -dy; + } else { + // Ball missed the paddle -- game over + alert("GAME OVER"); + document.location.reload(); + clearInterval(interval); + } +} +``` + +**How paddle collision works:** +- `x > paddleX` -- the ball is past the paddle's left edge. +- `x < paddleX + paddleWidth` -- the ball is before the paddle's right edge. +- If both are true, the ball is above the paddle, so it bounces. +- If the ball reaches the bottom without hitting the paddle, the game ends. + +### Complete Code for Step 5 + +```javascript +const canvas = document.getElementById("myCanvas"); +const ctx = canvas.getContext("2d"); +const ballRadius = 10; + +let x = canvas.width / 2; +let y = canvas.height - 30; +let dx = 2; +let dy = -2; + +const paddleHeight = 10; +const paddleWidth = 75; +let paddleX = (canvas.width - paddleWidth) / 2; + +let rightPressed = false; +let leftPressed = false; +let interval = 0; + +document.addEventListener("keydown", keyDownHandler); +document.addEventListener("keyup", keyUpHandler); + +function keyDownHandler(e) { + if (e.key === "Right" || e.key === "ArrowRight") { + rightPressed = true; + } else if (e.key === "Left" || e.key === "ArrowLeft") { + leftPressed = true; + } +} + +function keyUpHandler(e) { + if (e.key === "Right" || e.key === "ArrowRight") { + rightPressed = false; + } else if (e.key === "Left" || e.key === "ArrowLeft") { + leftPressed = false; + } +} + +function drawBall() { + ctx.beginPath(); + ctx.arc(x, y, ballRadius, 0, Math.PI * 2); + ctx.fillStyle = "#0095DD"; + ctx.fill(); + ctx.closePath(); +} + +function drawPaddle() { + ctx.beginPath(); + ctx.rect(paddleX, canvas.height - paddleHeight, paddleWidth, paddleHeight); + ctx.fillStyle = "#0095DD"; + ctx.fill(); + ctx.closePath(); +} + +function draw() { + ctx.clearRect(0, 0, canvas.width, canvas.height); + drawBall(); + drawPaddle(); + + // Left and right wall collision + if (x + dx > canvas.width - ballRadius || x + dx < ballRadius) { + dx = -dx; + } + + // Top wall collision + if (y + dy < ballRadius) { + dy = -dy; + } else if (y + dy > canvas.height - ballRadius) { + // Bottom edge: paddle collision or game over + if (x > paddleX && x < paddleX + paddleWidth) { + dy = -dy; + } else { + alert("GAME OVER"); + document.location.reload(); + clearInterval(interval); + } + } + + // Paddle movement + if (rightPressed) { + paddleX = Math.min(paddleX + 7, canvas.width - paddleWidth); + } else if (leftPressed) { + paddleX = Math.max(paddleX - 7, 0); + } + + x += dx; + y += dy; +} + +interval = setInterval(draw, 10); +``` + +--- + +## Step 6: Build the Brick Field + +Now we create the grid of bricks that the ball will destroy. The bricks are stored in a 2D array and drawn in rows and columns. + +### Brick Configuration Variables + +Define constants that control the layout of the brick field: + +```javascript +const brickRowCount = 3; +const brickColumnCount = 5; +const brickWidth = 75; +const brickHeight = 20; +const brickPadding = 10; +const brickOffsetTop = 30; +const brickOffsetLeft = 30; +``` + +- `brickRowCount` / `brickColumnCount` -- how many rows and columns of bricks. +- `brickWidth` / `brickHeight` -- dimensions of each individual brick. +- `brickPadding` -- space between bricks. +- `brickOffsetTop` / `brickOffsetLeft` -- distance from the top and left canvas edges to the first brick. + +### Creating the Bricks 2D Array + +Use nested loops to create a 2D array. Each brick stores its `x` and `y` position (initially `0`, calculated during drawing): + +```javascript +const bricks = []; +for (let c = 0; c < brickColumnCount; c++) { + bricks[c] = []; + for (let r = 0; r < brickRowCount; r++) { + bricks[c][r] = { x: 0, y: 0 }; + } +} +``` + +### The drawBricks() Function + +Loop through every brick, calculate its position, store it, and draw it: + +```javascript +function drawBricks() { + for (let c = 0; c < brickColumnCount; c++) { + for (let r = 0; r < brickRowCount; r++) { + const brickX = c * (brickWidth + brickPadding) + brickOffsetLeft; + const brickY = r * (brickHeight + brickPadding) + brickOffsetTop; + bricks[c][r].x = brickX; + bricks[c][r].y = brickY; + ctx.beginPath(); + ctx.rect(brickX, brickY, brickWidth, brickHeight); + ctx.fillStyle = "#0095DD"; + ctx.fill(); + ctx.closePath(); + } + } +} +``` + +**Position calculation formula:** +- `brickX = column * (brickWidth + brickPadding) + brickOffsetLeft` +- `brickY = row * (brickHeight + brickPadding) + brickOffsetTop` + +This creates an evenly-spaced grid with consistent padding and margins. + +### Calling drawBricks() in the Game Loop + +Add the call at the beginning of your `draw()` function, after clearing the canvas: + +```javascript +function draw() { + ctx.clearRect(0, 0, canvas.width, canvas.height); + drawBricks(); + drawBall(); + drawPaddle(); + // ... rest of draw function +} +``` + +### Complete Code for Step 6 + +```javascript +const canvas = document.getElementById("myCanvas"); +const ctx = canvas.getContext("2d"); +const ballRadius = 10; + +let x = canvas.width / 2; +let y = canvas.height - 30; +let dx = 2; +let dy = -2; + +const paddleHeight = 10; +const paddleWidth = 75; +let paddleX = (canvas.width - paddleWidth) / 2; + +let rightPressed = false; +let leftPressed = false; +let interval = 0; + +const brickRowCount = 3; +const brickColumnCount = 5; +const brickWidth = 75; +const brickHeight = 20; +const brickPadding = 10; +const brickOffsetTop = 30; +const brickOffsetLeft = 30; + +const bricks = []; +for (let c = 0; c < brickColumnCount; c++) { + bricks[c] = []; + for (let r = 0; r < brickRowCount; r++) { + bricks[c][r] = { x: 0, y: 0 }; + } +} + +document.addEventListener("keydown", keyDownHandler); +document.addEventListener("keyup", keyUpHandler); + +function keyDownHandler(e) { + if (e.key === "Right" || e.key === "ArrowRight") { + rightPressed = true; + } else if (e.key === "Left" || e.key === "ArrowLeft") { + leftPressed = true; + } +} + +function keyUpHandler(e) { + if (e.key === "Right" || e.key === "ArrowRight") { + rightPressed = false; + } else if (e.key === "Left" || e.key === "ArrowLeft") { + leftPressed = false; + } +} + +function drawBall() { + ctx.beginPath(); + ctx.arc(x, y, ballRadius, 0, Math.PI * 2); + ctx.fillStyle = "#0095DD"; + ctx.fill(); + ctx.closePath(); +} + +function drawPaddle() { + ctx.beginPath(); + ctx.rect(paddleX, canvas.height - paddleHeight, paddleWidth, paddleHeight); + ctx.fillStyle = "#0095DD"; + ctx.fill(); + ctx.closePath(); +} + +function drawBricks() { + for (let c = 0; c < brickColumnCount; c++) { + for (let r = 0; r < brickRowCount; r++) { + const brickX = c * (brickWidth + brickPadding) + brickOffsetLeft; + const brickY = r * (brickHeight + brickPadding) + brickOffsetTop; + bricks[c][r].x = brickX; + bricks[c][r].y = brickY; + ctx.beginPath(); + ctx.rect(brickX, brickY, brickWidth, brickHeight); + ctx.fillStyle = "#0095DD"; + ctx.fill(); + ctx.closePath(); + } + } +} + +function draw() { + ctx.clearRect(0, 0, canvas.width, canvas.height); + drawBricks(); + drawBall(); + drawPaddle(); + + if (x + dx > canvas.width - ballRadius || x + dx < ballRadius) { + dx = -dx; + } + if (y + dy < ballRadius) { + dy = -dy; + } else if (y + dy > canvas.height - ballRadius) { + if (x > paddleX && x < paddleX + paddleWidth) { + dy = -dy; + } else { + alert("GAME OVER"); + document.location.reload(); + clearInterval(interval); + } + } + + if (rightPressed) { + paddleX = Math.min(paddleX + 7, canvas.width - paddleWidth); + } else if (leftPressed) { + paddleX = Math.max(paddleX - 7, 0); + } + + x += dx; + y += dy; +} + +interval = setInterval(draw, 10); +``` + +--- + +## Step 7: Collision Detection + +With bricks on screen, we need to detect when the ball hits one and make it disappear. Each brick gets a `status` property: `1` means visible, `0` means destroyed. + +### Adding the Status Property to Bricks + +Update the brick initialization to include a `status` flag: + +```javascript +const bricks = []; +for (let c = 0; c < brickColumnCount; c++) { + bricks[c] = []; + for (let r = 0; r < brickRowCount; r++) { + bricks[c][r] = { x: 0, y: 0, status: 1 }; + } +} +``` + +### The collisionDetection() Function + +Loop through every brick and check if the ball's center is within the brick's bounding box: + +```javascript +function collisionDetection() { + for (let c = 0; c < brickColumnCount; c++) { + for (let r = 0; r < brickRowCount; r++) { + const b = bricks[c][r]; + if (b.status === 1) { + if ( + x > b.x && + x < b.x + brickWidth && + y > b.y && + y < b.y + brickHeight + ) { + dy = -dy; + b.status = 0; + } + } + } + } +} +``` + +**Collision conditions (all four must be true simultaneously):** +- `x > b.x` -- ball center is to the right of the brick's left edge. +- `x < b.x + brickWidth` -- ball center is to the left of the brick's right edge. +- `y > b.y` -- ball center is below the brick's top edge. +- `y < b.y + brickHeight` -- ball center is above the brick's bottom edge. + +When a collision is detected: +- `dy = -dy` reverses the ball's vertical direction (bounce). +- `b.status = 0` marks the brick as destroyed. + +### Updating drawBricks() to Respect Status + +Only draw bricks that are still active (`status === 1`): + +```javascript +function drawBricks() { + for (let c = 0; c < brickColumnCount; c++) { + for (let r = 0; r < brickRowCount; r++) { + if (bricks[c][r].status === 1) { + const brickX = c * (brickWidth + brickPadding) + brickOffsetLeft; + const brickY = r * (brickHeight + brickPadding) + brickOffsetTop; + bricks[c][r].x = brickX; + bricks[c][r].y = brickY; + ctx.beginPath(); + ctx.rect(brickX, brickY, brickWidth, brickHeight); + ctx.fillStyle = "#0095DD"; + ctx.fill(); + ctx.closePath(); + } + } + } +} +``` + +### Calling collisionDetection() in the Game Loop + +Add the call in your `draw()` function, after drawing all elements: + +```javascript +function draw() { + ctx.clearRect(0, 0, canvas.width, canvas.height); + drawBricks(); + drawBall(); + drawPaddle(); + collisionDetection(); + // ... rest of draw function +} +``` + +--- + +## Step 8: Track the Score and Win + +We add a score counter that increments each time a brick is destroyed, and a win condition that triggers when all bricks are gone. + +### Initializing the Score + +```javascript +let score = 0; +``` + +### The drawScore() Function + +Display the current score on the canvas using text rendering: + +```javascript +function drawScore() { + ctx.font = "16px Arial"; + ctx.fillStyle = "#0095DD"; + ctx.fillText(`Score: ${score}`, 8, 20); +} +``` + +- `ctx.font` sets the font size and family (like CSS). +- `ctx.fillText(text, x, y)` renders text at the given coordinates. +- Position `(8, 20)` places the score in the top-left corner. + +### Incrementing the Score + +In the `collisionDetection()` function, increment the score when a brick is hit: + +```javascript +dy = -dy; +b.status = 0; +score++; +``` + +### Adding the Win Condition + +After incrementing the score, check if the player has destroyed all bricks: + +```javascript +score++; +if (score === brickRowCount * brickColumnCount) { + alert("YOU WIN, CONGRATULATIONS!"); + document.location.reload(); + clearInterval(interval); +} +``` + +The total number of bricks is `brickRowCount * brickColumnCount`. When the score reaches that number, every brick has been destroyed. + +### Complete collisionDetection() with Score and Win + +```javascript +function collisionDetection() { + for (let c = 0; c < brickColumnCount; c++) { + for (let r = 0; r < brickRowCount; r++) { + const b = bricks[c][r]; + if (b.status === 1) { + if ( + x > b.x && + x < b.x + brickWidth && + y > b.y && + y < b.y + brickHeight + ) { + dy = -dy; + b.status = 0; + score++; + if (score === brickRowCount * brickColumnCount) { + alert("YOU WIN, CONGRATULATIONS!"); + document.location.reload(); + clearInterval(interval); + } + } + } + } + } +} +``` + +### Calling drawScore() in the Game Loop + +Add the call in your `draw()` function: + +```javascript +function draw() { + ctx.clearRect(0, 0, canvas.width, canvas.height); + drawBricks(); + drawBall(); + drawPaddle(); + drawScore(); + collisionDetection(); + // ... rest of draw function +} +``` + +### Canvas Text Methods Reference + +| Method/Property | Purpose | +|-----------------|---------| +| `ctx.font` | Set font size and family | +| `ctx.fillStyle` | Set text color | +| `ctx.fillText(text, x, y)` | Draw filled text at coordinates | + +--- + +## Step 9: Mouse Controls + +In addition to keyboard controls, we add mouse support so the player can move the paddle by moving the mouse. + +### Adding the mousemove Event Listener + +Register the handler alongside the existing keyboard listeners: + +```javascript +document.addEventListener("mousemove", mouseMoveHandler); +``` + +### The mouseMoveHandler Function + +Calculate the mouse's horizontal position relative to the canvas and update the paddle position: + +```javascript +function mouseMoveHandler(e) { + const relativeX = e.clientX - canvas.offsetLeft; + if (relativeX > 0 && relativeX < canvas.width) { + paddleX = relativeX - paddleWidth / 2; + } +} +``` + +**How it works:** +- `e.clientX` -- the mouse's horizontal position in the browser viewport. +- `canvas.offsetLeft` -- the distance from the canvas's left edge to the viewport's left edge. +- `relativeX` -- the mouse position relative to the canvas (not the viewport). +- The boundary check (`relativeX > 0 && relativeX < canvas.width`) ensures the paddle only moves when the mouse is over the canvas. +- `paddleX = relativeX - paddleWidth / 2` centers the paddle under the mouse cursor by subtracting half the paddle width. + +### Complete Event Listener Setup (Keyboard + Mouse) + +```javascript +document.addEventListener("keydown", keyDownHandler); +document.addEventListener("keyup", keyUpHandler); +document.addEventListener("mousemove", mouseMoveHandler); +``` + +Both control methods work simultaneously. The player can use arrow keys or mouse -- or switch between them at any time. + +--- + +## Step 10: Finishing Up + +The final step adds a lives system (so the player gets multiple chances) and upgrades the game loop from `setInterval` to `requestAnimationFrame` for smoother rendering. + +### Adding the Lives Variable + +```javascript +let lives = 3; +``` + +### The drawLives() Function + +Display the remaining lives in the top-right corner: + +```javascript +function drawLives() { + ctx.font = "16px Arial"; + ctx.fillStyle = "#0095DD"; + ctx.fillText(`Lives: ${lives}`, canvas.width - 65, 20); +} +``` + +### Implementing the Lives System + +Replace the immediate game-over logic with a lives-based system. When the ball misses the paddle: + +```javascript +if (y + dy < ballRadius) { + dy = -dy; +} else if (y + dy > canvas.height - ballRadius) { + if (x > paddleX && x < paddleX + paddleWidth) { + dy = -dy; + } else { + lives--; + if (!lives) { + alert("GAME OVER"); + document.location.reload(); + } else { + // Reset ball and paddle positions + x = canvas.width / 2; + y = canvas.height - 30; + dx = 2; + dy = -2; + paddleX = (canvas.width - paddleWidth) / 2; + } + } +} +``` + +**What happens when a life is lost:** +- `lives--` decrements the lives counter. +- If `lives` reaches `0`, the game ends with an alert and page reload. +- Otherwise, the ball resets to center-bottom, velocity resets, and the paddle resets to center. + +### Upgrading to requestAnimationFrame + +Replace `setInterval` with `requestAnimationFrame` for a smoother, browser-optimized game loop: + +**Old approach (remove):** +```javascript +interval = setInterval(draw, 10); +``` + +**New approach:** +Add `requestAnimationFrame(draw)` at the end of the `draw()` function: + +```javascript +function draw() { + // ... all drawing and logic ... + requestAnimationFrame(draw); +} + +// Start the game by calling draw() once: +draw(); +``` + +`requestAnimationFrame` lets the browser schedule rendering at the optimal frame rate (typically 60fps), which is more efficient than a fixed 10ms interval. + +### Calling drawLives() in the Game Loop + +```javascript +function draw() { + ctx.clearRect(0, 0, canvas.width, canvas.height); + drawBricks(); + drawBall(); + drawPaddle(); + drawScore(); + drawLives(); + collisionDetection(); + // ... rest of logic ... + requestAnimationFrame(draw); +} +``` + +--- + +## Complete Final Game Code + +Below is the entire game in a single, self-contained HTML file. This is the final product of all 10 steps combined. + +```html + + + + + 2D Breakout Game + + + + + + + + +``` + +--- + +## Quick Reference: All Game Variables + +| Variable | Type | Purpose | +|----------|------|---------| +| `canvas` | const | Reference to the HTML canvas element | +| `ctx` | const | 2D rendering context | +| `ballRadius` | const | Radius of the ball (10) | +| `x`, `y` | let | Current ball position | +| `dx`, `dy` | let | Ball velocity (pixels per frame) | +| `paddleHeight` | const | Height of the paddle (10) | +| `paddleWidth` | const | Width of the paddle (75) | +| `paddleX` | let | Current horizontal position of the paddle | +| `rightPressed` | let | Whether the right arrow key is held down | +| `leftPressed` | let | Whether the left arrow key is held down | +| `brickRowCount` | const | Number of brick rows (3) | +| `brickColumnCount` | const | Number of brick columns (5) | +| `brickWidth` | const | Width of each brick (75) | +| `brickHeight` | const | Height of each brick (20) | +| `brickPadding` | const | Space between bricks (10) | +| `brickOffsetTop` | const | Distance from top of canvas to first brick row (30) | +| `brickOffsetLeft` | const | Distance from left of canvas to first brick column (30) | +| `bricks` | const | 2D array holding all brick objects | +| `score` | let | Current player score | +| `lives` | let | Remaining lives (starts at 3) | + +## Quick Reference: All Functions + +| Function | Purpose | +|----------|---------| +| `keyDownHandler(e)` | Sets `rightPressed` or `leftPressed` to `true` on key press | +| `keyUpHandler(e)` | Sets `rightPressed` or `leftPressed` to `false` on key release | +| `mouseMoveHandler(e)` | Moves paddle to follow mouse horizontal position | +| `collisionDetection()` | Checks ball against all active bricks; destroys hit bricks, increments score, checks win | +| `drawBall()` | Renders the ball at current `(x, y)` position | +| `drawPaddle()` | Renders the paddle at current `paddleX` position | +| `drawBricks()` | Renders all bricks with `status === 1` | +| `drawScore()` | Renders the score text in the top-left corner | +| `drawLives()` | Renders the lives text in the top-right corner | +| `draw()` | Main game loop: clears canvas, draws everything, handles collisions, updates positions | diff --git a/skills/game-engine/assets/simple-2d-engine.md b/skills/game-engine/assets/simple-2d-engine.md new file mode 100644 index 000000000..b8e79fa26 --- /dev/null +++ b/skills/game-engine/assets/simple-2d-engine.md @@ -0,0 +1,507 @@ +# Simple 2D Platformer Engine Template + +A grid-based 2D platformer engine tutorial by **Sebastien Benard** (deepnight), the lead developer behind *Dead Cells*. This template covers the fundamental architecture for a performant platformer: a dual-coordinate positioning system that blends integer grid cells with sub-pixel precision, velocity and friction mechanics, gravity, and a robust collision detection and response system. The approach is language-agnostic but examples use Haxe. + +**Source references:** +- [Part 1 - Basics](https://deepnight.net/tutorial/a-simple-platformer-engine-part-1-basics/) +- [Part 2 - Collisions](https://deepnight.net/tutorial/a-simple-platformer-engine-part-2-collisions/) + +**Author:** [Sebastien Benard / deepnight](https://deepnight.net) + +--- + +## Engine Architecture Overview + +The engine is built around a grid-based world where each cell has a fixed pixel size (e.g., 16x16). Entities exist within this grid using a **dual-coordinate system**: integer cell coordinates for coarse position and floating-point ratios for sub-pixel precision within each cell. This design enables pixel-perfect collision detection against the grid while maintaining smooth, fluid movement. + +### Core Principles + +1. **Grid is truth:** The world is a 2D grid of cells. Collision data lives in the grid. +2. **Entities straddle cells:** An entity's position is defined by which cell it occupies (`cx`, `cy`) plus how far into that cell it is (`xr`, `yr`). +3. **Velocity is in grid-ratio units:** Movement deltas (`dx`, `dy`) represent fractions of a cell per step, not raw pixels. +4. **Collisions are grid lookups:** Instead of testing sprite bounds against geometry, the engine checks the grid cells an entity is about to enter. + +--- + +## Part 1: Basics + +### The Grid + +The level is a 2D array where each cell is either empty or solid. A constant defines the cell size in pixels: + +```haxe +static inline var GRID = 16; +``` + +Collision data is stored as a simple 2D boolean or integer map: + +```haxe +// Check if a grid cell is solid +function hasCollision(cx:Int, cy:Int):Bool { + // Look up cell value in the level data + return level.getCollision(cx, cy) != 0; +} +``` + +### Entity Positioning: Dual Coordinates + +Every entity tracks its position using four values: + +| Variable | Type | Description | +|----------|------|-------------| +| `cx` | Int | Cell X coordinate (which column the entity is in) | +| `cy` | Int | Cell Y coordinate (which row the entity is in) | +| `xr` | Float | X ratio within the cell, range 0.0 to 1.0 | +| `yr` | Float | Y ratio within the cell, range 0.0 to 1.0 | + +An entity at `cx=5, cy=3, xr=0.5, yr=1.0` is horizontally centered in cell (5,3) and sitting on the bottom edge. + +### Converting to Pixel Coordinates + +To render the entity, convert grid coordinates to pixel positions: + +```haxe +// Pixel position for rendering +var pixelX : Float = (cx + xr) * GRID; +var pixelY : Float = (cy + yr) * GRID; +``` + +This produces smooth, sub-pixel-precise positions for rendering even though the collision system operates on discrete grid cells. + +### Velocity and Movement + +Velocity is expressed in **cell-ratio units per fixed-step** (not pixels per frame): + +```haxe +var dx : Float = 0; // Horizontal velocity (cells per step) +var dy : Float = 0; // Vertical velocity (cells per step) +``` + +Each fixed-step update, velocity is added to the ratio: + +```haxe +// Apply horizontal movement +xr += dx; + +// Apply vertical movement +yr += dy; +``` + +### Cell Overflow + +When the ratio exceeds the 0..1 range, the entity has moved into an adjacent cell: + +```haxe +// X overflow +while (xr > 1) { xr--; cx++; } +while (xr < 0) { xr++; cx--; } + +// Y overflow +while (yr > 1) { yr--; cy++; } +while (yr < 0) { yr++; cy--; } +``` + +### Friction + +Friction is applied as a multiplier each step, decaying velocity toward zero: + +```haxe +var frictX : Float = 0.82; // Horizontal friction (0 = instant stop, 1 = no friction) +var frictY : Float = 0.82; // Vertical friction + +// Applied each step after movement +dx *= frictX; +dy *= frictY; + +// Clamp very small values to zero +if (Math.abs(dx) < 0.0005) dx = 0; +if (Math.abs(dy) < 0.0005) dy = 0; +``` + +Typical friction values: +- `0.82` -- Standard ground friction (responsive, quick stop) +- `0.94` -- Ice or slippery surface (slow deceleration) +- `0.96` -- Air friction (very slow horizontal deceleration) + +### Gravity + +Gravity is a constant added to `dy` each step: + +```haxe +static inline var GRAVITY = 0.05; // In cell-ratio units per step^2 + +// In fixedUpdate: +dy += GRAVITY; +``` + +Since `dy` accumulates and friction is applied, the entity reaches a natural terminal velocity. + +### Rendering / Sprite Sync + +After the physics step, the sprite is placed at the computed pixel position: + +```haxe +// In postUpdate, after physics is done: +sprite.x = (cx + xr) * GRID; +sprite.y = (cy + yr) * GRID; +``` + +For a platformer character, the anchor point is typically at the bottom-center of the sprite. With `yr = 1.0` representing the bottom of the current cell, the sprite's feet align with the floor. + +### Basic Entity Template + +```haxe +class Entity { + // Grid coordinates + var cx : Int = 0; + var cy : Int = 0; + var xr : Float = 0.5; + var yr : Float = 1.0; + + // Velocity + var dx : Float = 0; + var dy : Float = 0; + + // Friction + var frictX : Float = 0.82; + var frictY : Float = 0.82; + + // Gravity + static inline var GRAVITY = 0.05; + + // Grid size + static inline var GRID = 16; + + // Pixel position (computed) + public var attachX(get, never) : Float; + inline function get_attachX() return (cx + xr) * GRID; + + public var attachY(get, never) : Float; + inline function get_attachY() return (cy + yr) * GRID; + + public function fixedUpdate() { + // Gravity + dy += GRAVITY; + + // Apply velocity + xr += dx; + yr += dy; + + // Apply friction + dx *= frictX; + dy *= frictY; + + // Clamp small values + if (Math.abs(dx) < 0.0005) dx = 0; + if (Math.abs(dy) < 0.0005) dy = 0; + + // Cell overflow + while (xr > 1) { xr--; cx++; } + while (xr < 0) { xr++; cx--; } + while (yr > 1) { yr--; cy++; } + while (yr < 0) { yr++; cy--; } + } + + public function postUpdate() { + sprite.x = attachX; + sprite.y = attachY; + } +} +``` + +--- + +## Part 2: Collisions + +### Collision Philosophy + +Instead of using bounding-box-to-bounding-box collision detection (which becomes complex with slopes, one-way platforms, and edge cases), this engine checks grid cells directly. Since the entity's position is already expressed in grid terms, collision detection becomes a series of simple integer lookups. + +### The Core Idea + +Before allowing the entity to move into a neighboring cell, check if that cell is solid. If it is, clamp the entity's ratio and zero out its velocity on that axis. + +### Axis Separation + +Collisions are handled **per axis** -- first X, then Y (or vice versa). This simplifies the logic and avoids corner-case tunneling issues. + +### X-Axis Collision + +After applying `dx` to `xr`, before doing the cell-overflow step, check for collisions: + +```haxe +// Apply X movement +xr += dx; + +// Check collision to the RIGHT +if (dx > 0 && hasCollision(cx + 1, cy) && xr >= 0.7) { + xr = 0.7; // Clamp: stop before entering the solid cell + dx = 0; // Kill horizontal velocity +} + +// Check collision to the LEFT +if (dx < 0 && hasCollision(cx - 1, cy) && xr <= 0.3) { + xr = 0.3; // Clamp: stop before entering the solid cell + dx = 0; // Kill horizontal velocity +} + +// Cell overflow (after collision check) +while (xr > 1) { xr--; cx++; } +while (xr < 0) { xr++; cx--; } +``` + +**Why 0.7 and 0.3?** These thresholds represent the entity's collision radius within a cell. An entity centered at `xr = 0.5` with a half-width of 0.3 cells would collide at `xr = 0.7` on the right side and `xr = 0.3` on the left side. Adjust these values based on entity width. + +### Y-Axis Collision + +Similarly, after applying `dy` to `yr`: + +```haxe +// Apply Y movement +yr += dy; + +// Check collision BELOW (floor) +if (dy > 0 && hasCollision(cx, cy + 1) && yr >= 1.0) { + yr = 1.0; // Clamp: land on top of the solid cell + dy = 0; // Kill vertical velocity +} + +// Check collision ABOVE (ceiling) +if (dy < 0 && hasCollision(cx, cy - 1) && yr <= 0.3) { + yr = 0.3; // Clamp: stop before entering ceiling cell + dy = 0; // Kill vertical velocity +} + +// Cell overflow +while (yr > 1) { yr--; cy++; } +while (yr < 0) { yr++; cy--; } +``` + +For floor collisions, `yr = 1.0` means the entity sits exactly on the bottom edge of its current cell, which is the top edge of the cell below it. This is the natural "standing on ground" position. + +### On-Ground Detection + +To determine if the entity is standing on solid ground (for jump logic, animations, etc.): + +```haxe +function isOnGround() : Bool { + return hasCollision(cx, cy + 1) && yr >= 0.98; +} +``` + +The threshold `0.98` instead of `1.0` allows for minor floating-point imprecision. + +### Complete Entity with Collisions + +```haxe +class Entity { + var cx : Int = 0; + var cy : Int = 0; + var xr : Float = 0.5; + var yr : Float = 1.0; + var dx : Float = 0; + var dy : Float = 0; + var frictX : Float = 0.82; + var frictY : Float = 0.82; + + static inline var GRID = 16; + static inline var GRAVITY = 0.05; + + // Collision radius (half-width in cell-ratio units) + var collRadius : Float = 0.3; + + function hasCollision(testCx:Int, testCy:Int):Bool { + return level.isCollision(testCx, testCy); + } + + function isOnGround():Bool { + return hasCollision(cx, cy + 1) && yr >= 0.98; + } + + public function fixedUpdate() { + // --- Gravity --- + dy += GRAVITY; + + // --- X Axis --- + xr += dx; + + // Right collision + if (dx > 0 && hasCollision(cx + 1, cy) && xr >= 1.0 - collRadius) { + xr = 1.0 - collRadius; + dx = 0; + } + + // Left collision + if (dx < 0 && hasCollision(cx - 1, cy) && xr <= collRadius) { + xr = collRadius; + dx = 0; + } + + // X cell overflow + while (xr > 1) { xr--; cx++; } + while (xr < 0) { xr++; cx--; } + + // --- Y Axis --- + yr += dy; + + // Floor collision + if (dy > 0 && hasCollision(cx, cy + 1) && yr >= 1.0) { + yr = 1.0; + dy = 0; + } + + // Ceiling collision + if (dy < 0 && hasCollision(cx, cy - 1) && yr <= collRadius) { + yr = collRadius; + dy = 0; + } + + // Y cell overflow + while (yr > 1) { yr--; cy++; } + while (yr < 0) { yr++; cy--; } + + // --- Friction --- + dx *= frictX; + dy *= frictY; + + if (Math.abs(dx) < 0.0005) dx = 0; + if (Math.abs(dy) < 0.0005) dy = 0; + } + + public function postUpdate() { + sprite.x = (cx + xr) * GRID; + sprite.y = (cy + yr) * GRID; + } +} +``` + +--- + +## Collision Edge Cases and Solutions + +### Diagonal Movement / Corner Clipping + +Because collisions are checked per-axis in sequence, an entity moving diagonally into a corner naturally resolves against one axis first. This prevents the entity from getting stuck in corners and eliminates the need for complex diagonal collision logic. + +### High-Speed Tunneling + +If `dx` or `dy` is large enough to skip an entire cell in one step, the entity could "tunnel" through walls. Solutions: + +1. **Cap velocity:** Clamp `dx` and `dy` to a maximum of 0.5 (half a cell per step) +2. **Subdivide steps:** If velocity exceeds the threshold, run the collision check in smaller increments +3. **Ray-march the grid:** Check every cell along the movement path + +```haxe +// Simple velocity cap +if (dx > 0.5) dx = 0.5; +if (dx < -0.5) dx = -0.5; +if (dy > 0.5) dy = 0.5; +if (dy < -0.5) dy = -0.5; +``` + +### One-Way Platforms + +Platforms the entity can jump up through but land on from above: + +```haxe +// In Y collision, check for one-way platform +if (dy > 0 && isOneWayPlatform(cx, cy + 1) && yr >= 1.0 && prevYr < 1.0) { + yr = 1.0; + dy = 0; +} +``` + +Key: Only collide when the entity is moving downward (`dy > 0`) and was previously above the platform (`prevYr < 1.0`). + +### Slopes + +For basic slope support, instead of a binary collision check, query the slope height at the entity's x-position within the cell: + +```haxe +// Pseudocode for slope collision +var slopeHeight = getSlopeHeight(cx, cy + 1, xr); +if (yr >= slopeHeight) { + yr = slopeHeight; + dy = 0; +} +``` + +--- + +## Jumping + +Jumping is simply a negative `dy` impulse: + +```haxe +function jump() { + if (isOnGround()) { + dy = -0.5; // Jump impulse (in cell-ratio units) + } +} +``` + +Gravity naturally decelerates the upward motion, creating a parabolic arc. To allow variable-height jumps (holding the button longer = higher jump): + +```haxe +// On jump button release, reduce upward velocity +function onJumpRelease() { + if (dy < 0) { + dy *= 0.5; // Cut remaining upward velocity + } +} +``` + +--- + +## Coordinate System Diagram + +``` + Cell (cx, cy) Next Cell (cx+1, cy) + +-------------------+ +-------------------+ + | | | | + | xr=0.0 xr=1.0 --> | xr=0.0 | + | | | | + | * | | | + | (xr=0.5, | | | + | yr=0.5) | | | + | | | | + +-------------------+ +-------------------+ + yr=0.0 yr=1.0 = top of cell below + + Pixel position = (cx + xr) * GRID, (cy + yr) * GRID +``` + +--- + +## Update Order Summary + +``` +fixedUpdate(): + 1. Apply gravity dy += GRAVITY + 2. Apply X velocity xr += dx + 3. Check X collisions Clamp xr, zero dx if colliding + 4. Handle X cell overflow cx/xr normalization + 5. Apply Y velocity yr += dy + 6. Check Y collisions Clamp yr, zero dy if colliding + 7. Handle Y cell overflow cy/yr normalization + 8. Apply friction dx *= frictX, dy *= frictY + 9. Zero out tiny values Threshold check + +postUpdate(): + 1. Sync sprite position sprite.x/y = pixel coords + 2. Update animation Based on state/velocity + 3. Camera follow Track entity +``` + +--- + +## Design Advantages + +| Feature | Benefit | +|---------|---------| +| Grid-based collision | O(1) lookup per check, no broad-phase needed | +| Dual coordinates | Sub-pixel smooth rendering with integer collision | +| Per-axis collision | Simple logic, naturally handles corners | +| Ratio-based velocity | Resolution-independent movement | +| Friction multiplier | Tunable feel per surface type | +| Cell overflow while-loops | Handles multi-cell movement safely | diff --git a/skills/game-engine/references/3d-web-games.md b/skills/game-engine/references/3d-web-games.md new file mode 100644 index 000000000..374eaf773 --- /dev/null +++ b/skills/game-engine/references/3d-web-games.md @@ -0,0 +1,754 @@ +# 3D Web Games + +A comprehensive reference for building 3D games on the web, covering foundational theory, major frameworks, shader programming, collision detection, and immersive WebXR experiences. + +Sources: [MDN Web Docs -- Games Techniques: 3D on the web](https://developer.mozilla.org/en-US/docs/Games/Techniques/3D_on_the_web) + +--- + +## 3D Theory and Fundamentals + +Understanding the core concepts behind 3D rendering is essential before working with any framework. + +### Coordinate System + +WebGL uses the **right-hand coordinate system**: + +- **X-axis** -- points to the right +- **Y-axis** -- points up +- **Z-axis** -- points out of the screen toward the viewer + +All 3D objects are positioned relative to this coordinate system. + +### Vertices, Edges, Faces, and Meshes + +- **Vertex** -- a point in 3D space defined by `(x, y, z)` with additional attributes: color (RGBA, values 0.0-1.0), normal (direction the vertex faces, used for lighting), and texture coordinates. +- **Edge** -- a line connecting two vertices. +- **Face** -- a flat surface bounded by edges (e.g., a triangle connecting three vertices). +- **Geometry** -- the structural shape built from vertices, edges, and faces. +- **Material** -- the surface appearance, combining color, texture, roughness, metalness, etc. +- **Mesh** -- geometry combined with a material to produce a renderable 3D object. + +### The Rendering Pipeline + +The pipeline transforms 3D objects into 2D pixels on screen, in four major stages: + +**1. Vertex Processing** + +Combines individual vertex data into primitives (triangles, lines, points) and applies transformations: + +- **Model transformation** -- positions and orients objects in world space. +- **View transformation** -- positions and orients the virtual camera. +- **Projection transformation** -- defines the camera's field of view (FOV), aspect ratio, near plane, and far plane. +- **Viewport transformation** -- maps the result to the screen viewport. + +**2. Rasterization** + +Converts 3D primitives into 2D fragments aligned to the pixel grid. + +**3. Fragment Processing** + +Determines the final color of each fragment using textures and lighting: + +- **Textures**: 2D images mapped onto 3D surfaces. Individual texture elements are called *texels*. Texture wrapping repeats images around geometry; texture filtering handles minification and magnification when displayed resolution differs from texture resolution. +- **Lighting (Phong model)**: Four types of light interaction -- **diffuse** (distant directional light like the sun), **specular** (point source highlights like a flashlight), **ambient** (constant global illumination), and **emissive** (light emitted by the object itself). + +**4. Output Merging** + +Converts 3D fragments into the final 2D pixel grid. Off-screen and occluded objects are culled for efficiency. + +### Camera + +The camera defines what is visible: + +- **Position** -- location in 3D space. +- **Direction** -- where the camera points. +- **Orientation** -- rotation around the viewing axis. + +### Practical Tips + +- Size and position values in WebGL are unitless; you decide whether they represent millimeters, meters, feet, or anything else. +- Understand the pipeline conceptually before diving into code; the vertex and fragment processing stages are programmable via shaders. +- Every framework (Three.js, Babylon.js, A-Frame, PlayCanvas) abstracts this pipeline, but the fundamentals remain the same. + +--- + +## Frameworks + +### Three.js + +Three.js is one of the most popular 3D engines for the web. It provides a high-level API over WebGL with a large ecosystem of plugins, examples, and community support. + +#### Setup + +```html + + + + + Three.js Demo + + + + + + + +``` + +Or install via npm: + +```bash +npm install --save three +npm install --save-dev vite +npx vite +``` + +#### Core Components + +**Renderer** -- displays the scene in the browser: + +```javascript +const renderer = new THREE.WebGLRenderer({ antialias: true }); +renderer.setSize(WIDTH, HEIGHT); +renderer.setClearColor(0xdddddd, 1); +document.body.appendChild(renderer.domElement); +``` + +**Scene** -- container for all 3D objects, lights, and the camera: + +```javascript +const scene = new THREE.Scene(); +``` + +**Camera** -- defines the viewpoint (PerspectiveCamera is most common): + +```javascript +const camera = new THREE.PerspectiveCamera(70, WIDTH / HEIGHT); +camera.position.z = 50; +scene.add(camera); +``` + +Parameters: field of view (degrees), aspect ratio. Other camera types include Orthographic and Cube. + +#### Geometry, Material, and Mesh + +```javascript +// Geometry defines the shape +const boxGeometry = new THREE.BoxGeometry(10, 10, 10); +const torusGeometry = new THREE.TorusGeometry(7, 1, 16, 32); +const dodecahedronGeometry = new THREE.DodecahedronGeometry(7); + +// Material defines the surface appearance +const basicMaterial = new THREE.MeshBasicMaterial({ color: 0x0095dd }); // No lighting +const phongMaterial = new THREE.MeshPhongMaterial({ color: 0xff9500 }); // Glossy +const lambertMaterial = new THREE.MeshLambertMaterial({ color: 0xeaeff2 }); // Matte + +// Mesh combines geometry + material +const cube = new THREE.Mesh(boxGeometry, basicMaterial); +cube.position.set(-25, 0, 0); +cube.rotation.set(0.4, 0.2, 0); +scene.add(cube); +``` + +#### Lighting + +```javascript +const light = new THREE.PointLight(0xffffff); +light.position.set(-10, 15, 50); +scene.add(light); +``` + +Other light types: Ambient, Directional, Hemisphere, Spot. + +Note: `MeshBasicMaterial` does not respond to lighting. Use `MeshPhongMaterial` or `MeshLambertMaterial` for lit surfaces. + +#### Animation Loop + +```javascript +let t = 0; +function render() { + t += 0.01; + requestAnimationFrame(render); + + cube.rotation.y += 0.01; // continuous rotation + torus.scale.y = Math.abs(Math.sin(t)); // pulsing scale + dodecahedron.position.y = -7 * Math.sin(t * 2); // bobbing position + + renderer.render(scene, camera); +} +render(); +``` + +#### Practical Tips + +- Use `Math.abs()` when animating scale with `Math.sin()` to avoid negative scale values. +- The render loop uses `requestAnimationFrame` for smooth, browser-optimized frame updates. +- Consult [Three.js documentation](https://threejs.org/docs/) for the full API. + +--- + +### Babylon.js + +Babylon.js is a full-featured 3D engine with a built-in math library, physics support, and extensive documentation. + +#### Setup + +```html + + +``` + +#### Engine, Scene, and Render Loop + +```javascript +const canvas = document.getElementById("render-canvas"); +const engine = new BABYLON.Engine(canvas); + +const scene = new BABYLON.Scene(engine); +scene.clearColor = new BABYLON.Color3(0.8, 0.8, 0.8); + +function renderLoop() { + scene.render(); +} +engine.runRenderLoop(renderLoop); +``` + +#### Camera and Lighting + +```javascript +const camera = new BABYLON.FreeCamera("camera", new BABYLON.Vector3(0, 0, -10), scene); +const light = new BABYLON.PointLight("light", new BABYLON.Vector3(10, 10, 0), scene); +``` + +#### Creating Meshes + +```javascript +const box = BABYLON.Mesh.CreateBox("box", 2, scene); // name, size, scene +const torus = BABYLON.Mesh.CreateTorus("torus", 2, 0.5, 15, scene); // name, diameter, thickness, tessellation, scene +const cylinder = BABYLON.Mesh.CreateCylinder("cylinder", 2, 2, 2, 12, 1, scene); +// name, height, topDiameter, bottomDiameter, tessellation, heightSubdivisions, scene +``` + +#### Materials + +```javascript +const boxMaterial = new BABYLON.StandardMaterial("material", scene); +boxMaterial.emissiveColor = new BABYLON.Color3(0, 0.58, 0.86); +box.material = boxMaterial; +``` + +#### Transforms and Animation + +```javascript +box.position.x = 5; +box.rotation.x = -0.2; +box.scaling.x = 1.5; + +// Animation inside render loop +let t = 0; +function renderLoop() { + scene.render(); + t -= 0.01; + box.rotation.y = t * 2; + torus.scaling.z = Math.abs(Math.sin(t * 2)) + 0.5; + cylinder.position.y = Math.sin(t * 3); +} +engine.runRenderLoop(renderLoop); +``` + +#### Practical Tips + +- The `BABYLON` global object contains all framework functions. +- `BABYLON.Vector3` and `BABYLON.Color3` are used extensively for positioning and coloring. +- Babylon.js includes a built-in math library for vectors, colors, and matrices. +- Consult [Babylon.js documentation](https://doc.babylonjs.com/) for advanced features like physics, particles, and post-processing. + +--- + +### A-Frame + +A-Frame is Mozilla's declarative, HTML-based framework for building VR/AR experiences on the web. It uses an entity-component system and runs on WebGL under the hood. + +#### Setup + +```html + + + + + A-Frame Demo + + + + + + + + + +``` + +The `` element is the root container. A-Frame auto-includes a default camera, lighting, and input controls. + +#### Primitives and Entities + +```html + + + + + + + +``` + +#### Creating Entities with JavaScript + +```javascript +const scene = document.querySelector("a-scene"); +const cylinder = document.createElement("a-cylinder"); +cylinder.setAttribute("color", "#FF9500"); +cylinder.setAttribute("height", "2"); +cylinder.setAttribute("radius", "0.75"); +cylinder.setAttribute("position", "3 1 0"); +scene.appendChild(cylinder); +``` + +#### Camera and Lighting + +```html + + + + + +``` + +Default controls: WASD keys for movement, mouse for looking around. A VR mode button appears in the bottom-right corner. + +#### Animation + +Declarative animation via HTML attributes: + +```html + + +``` + +Animation properties: `property` (attribute to animate), `from`/`to` (start/end values), `dir` (alternate or normal), `loop` (boolean), `dur` (milliseconds), `easing` (easing function). + +Dynamic animation via JavaScript: + +```javascript +let t = 0; +function render() { + t += 0.01; + requestAnimationFrame(render); + cylinder.setAttribute("position", `3 ${Math.sin(t * 2) + 1} 0`); +} +render(); +``` + +#### Practical Tips + +- A-Frame is ideal for rapid VR/AR prototyping using familiar HTML syntax. +- The entity-component architecture makes it extensible; community plugins add physics, gamepad controls, and more. +- Use `` for background colors or 360-degree images. +- A-Frame supports desktop, mobile (iOS/Android), and VR headsets (Meta Quest, HTC Vive). + +--- + +### PlayCanvas + +PlayCanvas is a WebGL game engine with two workflow options: + +1. **Engine approach** -- include the PlayCanvas JavaScript library directly in HTML and code from scratch. +2. **Editor approach** -- use the online drag-and-drop visual editor for scene composition. + +#### Key Features + +- Entity-component system architecture +- Built-in physics engine powered by [ammo.js](https://github.com/kripken/ammo.js/) +- Collision detection +- Audio support +- Input handling (keyboard, mouse, touch, gamepads) +- Resource/asset management + +#### Practical Tips + +- PlayCanvas excels for team-based game development thanks to its online editor with real-time collaboration. +- The engine-only approach is lightweight and can be embedded in any web page. +- Consult the [PlayCanvas developer documentation](https://developer.playcanvas.com/) for tutorials on entities, components, cameras, lights, materials, and animations. + +--- + +## GLSL Shaders + +GLSL (OpenGL Shading Language) is a C-like language that runs directly on the GPU, enabling custom control over the rendering pipeline's vertex and fragment processing stages. + +### What Shaders Are + +Shaders are small programs that execute on the GPU instead of the CPU. They are strongly typed and rely heavily on vector and matrix mathematics. There are two types relevant to WebGL: + +- **Vertex shader** -- runs once per vertex, transforms 3D positions into screen coordinates. +- **Fragment shader** (pixel shader) -- runs once per pixel, determines the final RGBA color. + +### Vertex Shader + +The vertex shader's job is to set `gl_Position`, a built-in GLSL variable storing the vertex's transformed position: + +```glsl +void main() { + gl_Position = projectionMatrix * modelViewMatrix * vec4(position.x, position.y, position.z, 1.0); +} +``` + +- `projectionMatrix` -- handles perspective or orthographic projection (provided by Three.js). +- `modelViewMatrix` -- combines model and view transformations (provided by Three.js). +- `vec4(x, y, z, w)` -- a 4-component vector; `w` defaults to 1.0 for positional vertices. + +You can manipulate vertices directly: + +```glsl +void main() { + gl_Position = projectionMatrix * modelViewMatrix * vec4(position.x + 10.0, position.y, position.z + 5.0, 1.0); +} +``` + +### Fragment Shader + +The fragment shader's job is to set `gl_FragColor`, a built-in GLSL variable holding the RGBA color: + +```glsl +void main() { + gl_FragColor = vec4(0.0, 0.58, 0.86, 1.0); +} +``` + +RGBA components are floats from 0.0 to 1.0. Alpha 0.0 is fully transparent; 1.0 is fully opaque. + +### Using Shaders in HTML and Three.js + +Embed shader source in script tags with custom type attributes: + +```html + + + +``` + +Apply them with `ShaderMaterial`: + +```javascript +const shaderMaterial = new THREE.ShaderMaterial({ + vertexShader: document.getElementById("vertexShader").textContent, + fragmentShader: document.getElementById("fragmentShader").textContent, +}); + +const cube = new THREE.Mesh(boxGeometry, shaderMaterial); +``` + +### The Shader Pipeline + +1. **Vertex shader** processes each vertex and outputs `gl_Position`. +2. **Rasterization** maps 3D coordinates to 2D screen pixels. +3. **Fragment shader** processes each pixel and outputs `gl_FragColor`. + +### Key Concepts + +- **Uniforms** -- values passed from JavaScript to the shader, constant across all vertices/fragments in a single draw call (e.g., light position, time). +- **Attributes** -- per-vertex data passed to the vertex shader (e.g., position, normal, UV coordinates). +- **Varyings** -- values passed from the vertex shader to the fragment shader, interpolated across the surface. + +### Practical Tips + +- Shaders run on the GPU and offload computation from the CPU, which is critical for real-time performance. +- Three.js, Babylon.js, and other frameworks abstract much of the shader setup; pure WebGL requires significantly more boilerplate. +- [ShaderToy](https://www.shadertoy.com/) is an excellent resource for shader examples and inspiration. +- GLSL requires explicit type declarations; always use `1.0` instead of `1` for floats. + +--- + +## Collision Detection + +Collision detection determines when 3D objects intersect, which is fundamental for game physics, interaction, and gameplay logic. + +### Axis-Aligned Bounding Boxes (AABB) + +An AABB wraps an object in a non-rotated rectangular box aligned to the coordinate axes. It is the fastest common collision test because it uses only logical comparisons (no trigonometry). + +**Limitation**: AABBs do not rotate with the object. For rotating entities, either resize the bounding box each frame or use bounding spheres instead. + +#### Point vs. AABB + +Check whether a point lies inside a box by testing all three axes: + +```javascript +function isPointInsideAABB(point, box) { + return ( + point.x >= box.minX && + point.x <= box.maxX && + point.y >= box.minY && + point.y <= box.maxY && + point.z >= box.minZ && + point.z <= box.maxZ + ); +} +``` + +#### AABB vs. AABB + +Check whether two boxes overlap on all three axes: + +```javascript +function intersect(a, b) { + return ( + a.minX <= b.maxX && + a.maxX >= b.minX && + a.minY <= b.maxY && + a.maxY >= b.minY && + a.minZ <= b.maxZ && + a.maxZ >= b.minZ + ); +} +``` + +### Bounding Spheres + +Bounding spheres are invariant to rotation (the sphere stays the same regardless of how the object spins), which makes them ideal for rotating entities. However, they fit poorly on non-spherical shapes and cause more false positives. + +#### Point vs. Sphere + +Check whether the distance from the point to the sphere center is less than the radius: + +```javascript +function isPointInsideSphere(point, sphere) { + const distance = Math.sqrt( + (point.x - sphere.x) ** 2 + + (point.y - sphere.y) ** 2 + + (point.z - sphere.z) ** 2 + ); + return distance < sphere.radius; +} +``` + +**Performance optimization**: avoid the square root by comparing squared distances: + +```javascript +const distanceSqr = + (point.x - sphere.x) ** 2 + + (point.y - sphere.y) ** 2 + + (point.z - sphere.z) ** 2; +return distanceSqr < sphere.radius * sphere.radius; +``` + +#### Sphere vs. Sphere + +Check whether the distance between centers is less than the sum of radii: + +```javascript +function intersect(sphere, other) { + const distance = Math.sqrt( + (sphere.x - other.x) ** 2 + + (sphere.y - other.y) ** 2 + + (sphere.z - other.z) ** 2 + ); + return distance < sphere.radius + other.radius; +} +``` + +#### Sphere vs. AABB + +Find the point on the AABB closest to the sphere center by clamping, then check the distance: + +```javascript +function intersect(sphere, box) { + const x = Math.max(box.minX, Math.min(sphere.x, box.maxX)); + const y = Math.max(box.minY, Math.min(sphere.y, box.maxY)); + const z = Math.max(box.minZ, Math.min(sphere.z, box.maxZ)); + + const distance = Math.sqrt( + (x - sphere.x) ** 2 + + (y - sphere.y) ** 2 + + (z - sphere.z) ** 2 + ); + + return distance < sphere.radius; +} +``` + +### Collision Detection with Three.js + +Three.js provides built-in `Box3` and `Sphere` objects plus visual helpers for bounding volume collision detection. + +#### Creating Bounding Volumes + +```javascript +// Box3 from an object (recommended -- accounts for transforms and children) +const knotBBox = new THREE.Box3(new THREE.Vector3(), new THREE.Vector3()); +knotBBox.setFromObject(knot); + +// Sphere from geometry +const knotBSphere = new THREE.Sphere( + knot.position, + knot.geometry.boundingSphere.radius +); +``` + +**Important**: `setFromObject()` accounts for position, rotation, scale, and child meshes. The geometry's `boundingBox` property does not. + +#### Intersection Tests + +```javascript +// Point inside box or sphere +knotBBox.containsPoint(point); +knotBSphere.containsPoint(point); + +// Box vs. box +knotBBox.intersectsBox(otherBox); + +// Sphere vs. sphere +knotBSphere.intersectsSphere(otherSphere); +``` + +Note: `containsBox()` checks if one box fully encloses another, which is different from `intersectsBox()`. + +#### Sphere vs. Box3 (Custom Patch) + +Three.js does not natively provide sphere-vs-box testing. Add it manually: + +```javascript +THREE.Sphere.__closest = new THREE.Vector3(); +THREE.Sphere.prototype.intersectsBox = function (box) { + THREE.Sphere.__closest.set(this.center.x, this.center.y, this.center.z); + THREE.Sphere.__closest.clamp(box.min, box.max); + const distance = this.center.distanceToSquared(THREE.Sphere.__closest); + return distance < this.radius * this.radius; +}; +``` + +#### BoxHelper for Visual Debugging + +`BoxHelper` creates a visible wireframe bounding box around any mesh and simplifies updates: + +```javascript +const knotBoxHelper = new THREE.BoxHelper(knot, 0x00ff00); +scene.add(knotBoxHelper); + +// After moving or rotating the mesh, update the helper +knot.position.set(-3, 2, 1); +knot.rotation.x = -Math.PI / 4; +knotBoxHelper.update(); + +// Convert to Box3 for intersection tests +const box3 = new THREE.Box3(); +box3.setFromObject(knotBoxHelper); +box3.intersectsBox(otherBox3); +``` + +Advantages of BoxHelper: auto-resizes with `update()`, includes child meshes, provides visual debugging. Limitation: box volumes only (no sphere helpers). + +### Physics Engines + +For more sophisticated collision detection and response, use a physics engine: + +- **Cannon.js** -- open-source 3D physics engine for JavaScript. +- **ammo.js** -- JavaScript port of the Bullet physics library (used by PlayCanvas). + +Physics engines create a *physical body* attached to the visual mesh, with properties like velocity, position, rotation, and torque. A *physical shape* (box, sphere, convex hull) is used for collision calculations. + +### Practical Tips + +- Use AABBs for axis-aligned, non-rotating objects -- they are the fastest option. +- Use bounding spheres for rotating objects -- the sphere is invariant to rotation. +- For complex shapes, consider compound bounding volumes (multiple primitives combined). +- Avoid `Math.sqrt()` in tight loops; compare squared distances instead. +- For production games, integrate a physics engine rather than writing collision detection from scratch. + +--- + +## WebXR + +WebXR is the modern web API for building virtual reality (VR) and augmented reality (AR) experiences in the browser. It replaces the deprecated WebVR API. + +### What WebXR Is + +The WebXR Device API provides access to XR hardware (headsets, controllers) and enables stereoscopic rendering. It captures real-time data including: + +- Headset position and orientation +- Controller position, orientation, velocity, and acceleration +- Input events from XR controllers + +### Supported Devices + +- Meta Quest +- Valve Index +- PlayStation VR (PSVR2) +- Any device with a WebXR-compatible browser + +### Core Concepts + +Every WebXR experience requires two things: + +1. **Real-time positional data** -- the application continuously receives headset and controller positions in 3D space. +2. **Real-time stereoscopic rendering** -- the application renders two slightly offset views (one for each eye) to the headset's display. + +### Framework Support + +All major 3D web frameworks support WebXR: + +- **A-Frame** -- built-in VR mode button; declarative HTML-based scenes automatically work in VR. +- **Three.js** -- provides WebXR integration via `renderer.xr`. See [Three.js VR documentation](https://threejs.org/docs/#manual/en/introduction/How-to-create-VR-content). +- **Babylon.js** -- built-in WebXR support via the XR Experience Helper. + +### Related APIs + +- **Gamepad API** -- for non-XR controller inputs (gamepads, joysticks). +- **Device Orientation API** -- for detecting device rotation on mobile devices. + +### Design Principles + +- Prioritize **immersion** over raw graphics quality or gameplay complexity. +- Users must feel like they are *part of the experience*. +- Basic shapes rendered at high, stable frame rates can be more compelling in VR than detailed graphics at unstable frame rates. +- Experimentation is essential; test frequently on actual hardware. + +### Practical Tips + +- Start with A-Frame for rapid VR prototyping -- its declarative HTML approach gets you to a working VR scene in minutes. +- Use Three.js or Babylon.js when you need more control over rendering and performance. +- Always test on real headsets; the experience is vastly different from desktop preview. +- Maintain a stable, high frame rate (72-90+ FPS) to prevent motion sickness. +- Consult [MDN WebXR Device API](https://developer.mozilla.org/en-US/docs/Web/API/WebXR_Device_API) for the full API reference. diff --git a/skills/game-engine/references/algorithms.md b/skills/game-engine/references/algorithms.md new file mode 100644 index 000000000..60b4716cf --- /dev/null +++ b/skills/game-engine/references/algorithms.md @@ -0,0 +1,843 @@ +# Game Development Algorithms + +A comprehensive reference covering essential algorithms for game development, including +line drawing, raycasting, collision detection, physics simulation, and vector mathematics. + +--- + +## Bresenham's Line Algorithm -- Raycasting, Line of Sight, and Pathfinding + +> Source: https://deepnight.net/tutorial/bresenham-magic-raycasting-line-of-sight-pathfinding/ + +### What It Is + +Bresenham's line algorithm is an efficient method for determining which cells in a grid +lie along a straight line between two points. Originally developed for plotting pixels on +raster displays, it has become a foundational tool in game development for raycasting, +line-of-sight checks, and grid-based pathfinding. The algorithm uses only integer +arithmetic (additions, subtractions, and bit shifts), making it extremely fast. + +### Mathematical / Algorithmic Concepts + +The core idea is to walk along the major axis (the axis with the greater distance) one +cell at a time, accumulating an error term that tracks how far the true line deviates +from the current minor-axis position. When the error exceeds a threshold, the minor-axis +coordinate is incremented. + +Key properties: +- **Integer-only arithmetic**: No floating-point division or multiplication required. +- **Incremental error accumulation**: The fractional slope is tracked via an integer error + term, avoiding drift. +- **Symmetry**: The algorithm works identically regardless of line direction by adjusting + step signs. + +Given two grid points `(x0, y0)` and `(x1, y1)`: + +``` +dx = abs(x1 - x0) +dy = abs(y1 - y0) +``` + +The error term is initialized and updated each step. When it crosses zero, the secondary +axis is stepped. + +### Pseudocode + +``` +function bresenham(x0, y0, x1, y1): + dx = abs(x1 - x0) + dy = abs(y1 - y0) + sx = sign(x1 - x0) // -1 or +1 + sy = sign(y1 - y0) // -1 or +1 + err = dx - dy + + while true: + visit(x0, y0) // process or record this cell + + if x0 == x1 AND y0 == y1: + break + + e2 = 2 * err + + if e2 > -dy: + err = err - dy + x0 = x0 + sx + + if e2 < dx: + err = err + dx + y0 = y0 + sy +``` + +### Haxe Implementation (from source) + +```haxe +public function hasLineOfSight(x0:Int, y0:Int, x1:Int, y1:Int):Bool { + var dx = hxd.Math.iabs(x1 - x0); + var dy = hxd.Math.iabs(y1 - y0); + var sx = (x0 < x1) ? 1 : -1; + var sy = (y0 < y1) ? 1 : -1; + var err = dx - dy; + + while (true) { + if (isBlocking(x0, y0)) + return false; + + if (x0 == x1 && y0 == y1) + return true; + + var e2 = 2 * err; + if (e2 > -dy) { + err -= dy; + x0 += sx; + } + if (e2 < dx) { + err += dx; + y0 += sy; + } + } +} +``` + +### Practical Game Development Applications + +- **Line of Sight (LOS)**: Walk the Bresenham line from an entity to a target; if any + cell along the path is a wall or obstacle, line of sight is blocked. +- **Raycasting on grids**: Cast rays from a source in multiple directions to compute + visibility maps or field-of-view cones. +- **Grid-based pathfinding validation**: After computing a path (e.g., via A*), verify + that straight-line shortcuts between waypoints are unobstructed using Bresenham checks. +- **Projectile tracing**: Determine which tiles a bullet or projectile passes through in + a tile-based game. +- **Lighting and shadow casting**: Trace rays from a light source to compute lit vs + shadowed cells on a 2D grid. + +--- + +## Collision Detection and Response Systems + +> Source: https://medium.com/@erikkubiak/dev-log-1-custom-engine-writing-my-collision-system-2a97856f9a93 + +### What It Is + +A collision system is responsible for detecting when game objects overlap or intersect +and then resolving those overlaps so that objects respond physically (bouncing, stopping, +sliding). Building a custom collision system involves choosing appropriate bounding +shapes, implementing overlap tests, and designing a resolution strategy. + +### Mathematical / Algorithmic Concepts + +#### Bounding Shapes + +- **AABB (Axis-Aligned Bounding Box)**: A rectangle whose sides are aligned with the + coordinate axes. Defined by a position (center or top-left corner) and half-widths. + Fast overlap tests but imprecise for rotated or irregular shapes. +- **Circle / Sphere colliders**: Defined by center and radius. Overlap test is a simple + distance comparison. +- **OBB (Oriented Bounding Box)**: A rotated rectangle. Uses the Separating Axis Theorem + for overlap tests. + +#### AABB vs AABB Overlap Test + +Two axis-aligned bounding boxes overlap if and only if they overlap on every axis: + +``` +overlapX = (a.x - a.halfW < b.x + b.halfW) AND (a.x + a.halfW > b.x - b.halfW) +overlapY = (a.y - a.halfH < b.y + b.halfH) AND (a.y + a.halfH > b.y - b.halfH) +collision = overlapX AND overlapY +``` + +#### Circle vs Circle Overlap Test + +``` +dx = a.x - b.x +dy = a.y - b.y +distSquared = dx * dx + dy * dy +collision = distSquared < (a.radius + b.radius) ^ 2 +``` + +Comparing squared distances avoids a costly square root operation. + +#### Separating Axis Theorem (SAT) + +Two convex shapes do NOT collide if there exists at least one axis along which their +projections do not overlap. For rectangles, test the edge normals of both rectangles. +If all projections overlap, the shapes are colliding. + +#### Sweep and Prune (Broad Phase) + +Rather than testing every pair of objects (O(n^2)), sort objects along one axis by +their minimum extent. Objects that do not overlap on that axis cannot collide and are +pruned from detailed checks. + +### Pseudocode -- Collision Detection and Resolution + +``` +// Broad phase: spatial hash or sweep-and-prune +candidates = broadPhase(allObjects) + +for each pair (a, b) in candidates: + overlap = narrowPhaseTest(a, b) + + if overlap: + // Compute penetration vector + penetration = computePenetration(a, b) + + // Resolve: push objects apart along the minimum penetration axis + if a.isStatic: + b.position += penetration + else if b.isStatic: + a.position -= penetration + else: + a.position -= penetration * 0.5 + b.position += penetration * 0.5 + + // Optional: apply impulse for velocity response + relativeVelocity = a.velocity - b.velocity + impulse = computeImpulse(relativeVelocity, penetration.normal, a.mass, b.mass) + a.velocity -= impulse / a.mass + b.velocity += impulse / b.mass +``` + +#### Minimum Penetration Vector (for AABBs) + +``` +function computePenetration(a, b): + overlapX_left = (a.x + a.halfW) - (b.x - b.halfW) + overlapX_right = (b.x + b.halfW) - (a.x - a.halfW) + overlapY_top = (a.y + a.halfH) - (b.y - b.halfH) + overlapY_bot = (b.y + b.halfH) - (a.y - a.halfH) + + minOverlapX = min(overlapX_left, overlapX_right) + minOverlapY = min(overlapY_top, overlapY_bot) + + if minOverlapX < minOverlapY: + return Vector(sign * minOverlapX, 0) + else: + return Vector(0, sign * minOverlapY) +``` + +### Spatial Partitioning Strategies + +| Strategy | Best For | Description | +|---|---|---| +| **Uniform Grid** | Evenly distributed objects | Divide world into fixed cells; objects register in their cell(s). | +| **Quadtree** | Non-uniform distribution | Recursively subdivide space into 4 quadrants. Efficient for sparse scenes. | +| **Spatial Hash** | Dynamic scenes | Hash object positions to buckets. O(1) lookup for neighbors. | +| **Sweep and Prune** | Many moving objects | Sort by axis; only test overlapping intervals. | + +### Practical Game Development Applications + +- **Platformer physics**: Resolve player-vs-terrain collisions so the character lands on + platforms and cannot walk through walls. +- **Projectile hit detection**: Determine when a projectile (often a small AABB or circle) + contacts an enemy or obstacle. +- **Trigger zones**: Detect when a player enters a region (overlap test without physical + resolution) to trigger events. +- **Entity stacking**: Handle objects piled on top of each other using iterative + resolution with multiple passes. + +--- + +## Velocity and Speed + +> Source: https://www.gamedev.net/tutorials/programming/math-and-physics/a-quick-lesson-in-velocity-and-speed-r6109/ + +### What It Is + +Velocity and speed are fundamental concepts for moving objects in games. **Speed** is a +scalar (magnitude only), while **velocity** is a vector (magnitude and direction). +Understanding the distinction is critical for implementing correct movement, physics, +and AI steering behaviors. + +### Mathematical / Algorithmic Concepts + +#### Definitions + +- **Speed**: A scalar quantity representing how fast an object moves, regardless of + direction. + ``` + speed = |velocity| = sqrt(vx^2 + vy^2) + ``` + +- **Velocity**: A vector quantity representing both speed and direction. + ``` + velocity = (vx, vy) + ``` + +- **Acceleration**: The rate of change of velocity over time. + ``` + acceleration = (ax, ay) + velocity += acceleration * deltaTime + ``` + +#### Updating Position with Velocity + +Each frame, an object's position is updated by its velocity, scaled by the time step: + +``` +position.x += velocity.x * deltaTime +position.y += velocity.y * deltaTime +``` + +This is **Euler integration**, the simplest (first-order) integration method. + +#### Normalizing Direction + +To move at a fixed speed in a given direction, normalize the direction vector and +multiply by the desired speed: + +``` +direction = target - current +length = sqrt(direction.x^2 + direction.y^2) +if length > 0: + direction.x /= length + direction.y /= length +velocity = direction * speed +``` + +This prevents the "diagonal movement problem" where moving diagonally at full speed +on both axes results in ~1.414x the intended speed. + +#### Frame-Rate Independence + +Without `deltaTime`, movement speed depends on the frame rate: + +``` +// WRONG: frame-rate dependent +position += velocity + +// CORRECT: frame-rate independent +position += velocity * deltaTime +``` + +`deltaTime` is the elapsed time (in seconds) since the last frame update. + +### Pseudocode -- Complete Movement Update + +``` +function update(entity, deltaTime): + // Apply acceleration (gravity, thrust, friction, etc.) + entity.velocity.x += entity.acceleration.x * deltaTime + entity.velocity.y += entity.acceleration.y * deltaTime + + // Clamp speed to a maximum + currentSpeed = magnitude(entity.velocity) + if currentSpeed > entity.maxSpeed: + entity.velocity = normalize(entity.velocity) * entity.maxSpeed + + // Apply friction / drag + entity.velocity.x *= (1 - entity.friction * deltaTime) + entity.velocity.y *= (1 - entity.friction * deltaTime) + + // Update position + entity.position.x += entity.velocity.x * deltaTime + entity.position.y += entity.velocity.y * deltaTime +``` + +### Practical Game Development Applications + +- **Character movement**: Apply velocity each frame to move the player smoothly, + clamping to a max speed for consistent feel. +- **Projectiles**: Give bullets or arrows an initial velocity vector; update position + each frame. +- **Gravity**: Apply a constant downward acceleration to velocity each frame to simulate + falling. +- **Friction and drag**: Reduce velocity over time by multiplying by a damping factor + to simulate surface friction or air resistance. +- **AI steering**: Compute a desired velocity toward a target, then smoothly adjust the + current velocity toward it (seek, flee, arrive behaviors). + +--- + +## Physics Engine Fundamentals + +> Source: https://winter.dev/articles/physics-engine + +### What It Is + +A physics engine simulates real-world physical behaviors -- gravity, collisions, rigid +body dynamics -- so that game objects move and interact realistically. The core loop of a +physics engine consists of: applying forces, integrating motion, detecting collisions, +and resolving collisions. + +### Mathematical / Algorithmic Concepts + +#### The Physics Loop + +A physics engine runs a fixed-timestep update loop: + +``` +accumulator = 0 +fixedDeltaTime = 1 / 60 // 60 Hz physics + +function physicsUpdate(frameDeltaTime): + accumulator += frameDeltaTime + + while accumulator >= fixedDeltaTime: + step(fixedDeltaTime) + accumulator -= fixedDeltaTime +``` + +Using a fixed timestep ensures deterministic, stable simulation regardless of rendering +frame rate. + +#### Integration Methods + +**Semi-Implicit Euler** (symplectic Euler) -- the standard for game physics: + +``` +velocity += acceleration * dt +position += velocity * dt +``` + +This is more stable than explicit Euler (which updates position first) because velocity +is updated before being used to update position. + +**Verlet Integration** -- an alternative that does not store velocity explicitly: + +``` +newPosition = 2 * position - oldPosition + acceleration * dt * dt +oldPosition = position +position = newPosition +``` + +Verlet is particularly useful for constraints (cloth, ragdoll) because positions can +be directly manipulated while preserving momentum. + +#### Rigid Body Properties + +Each rigid body has: + +| Property | Description | +|---|---| +| `position` | Center of mass in world space | +| `velocity` | Linear velocity vector | +| `acceleration` | Sum of all forces / mass | +| `mass` | Resistance to linear acceleration | +| `inverseMass` | `1 / mass` (0 for static objects) | +| `angle` | Rotation angle | +| `angularVelocity` | Rate of rotation | +| `inertia` | Resistance to angular acceleration | +| `restitution` | Bounciness (0 = no bounce, 1 = perfectly elastic) | +| `friction` | Surface friction coefficient | + +#### Force Accumulation + +Forces are accumulated each frame, then converted to acceleration: + +``` +function applyForce(body, force): + body.forceAccumulator += force + +function integrate(body, dt): + body.acceleration = body.forceAccumulator * body.inverseMass + body.velocity += body.acceleration * dt + body.position += body.velocity * dt + body.forceAccumulator = (0, 0) // reset +``` + +#### Collision Detection Pipeline + +The detection phase is split into two stages: + +1. **Broad Phase**: Quickly eliminate pairs that cannot possibly collide using bounding + volumes (AABBs) and spatial structures (grids, BVH trees, sweep-and-prune). + +2. **Narrow Phase**: For candidate pairs, perform precise shape-vs-shape tests to + determine if they actually overlap and compute contact information (collision normal, + penetration depth, contact points). + +#### Collision Resolution with Impulses + +When two bodies collide, an impulse is applied along the collision normal to separate +them and adjust their velocities: + +``` +function resolveCollision(a, b, normal, penetration): + // Relative velocity at the contact point + relVel = b.velocity - a.velocity + velAlongNormal = dot(relVel, normal) + + // Do not resolve if objects are separating + if velAlongNormal > 0: + return + + // Coefficient of restitution (take minimum) + e = min(a.restitution, b.restitution) + + // Impulse magnitude + j = -(1 + e) * velAlongNormal + j /= a.inverseMass + b.inverseMass + + // Apply impulse + impulse = j * normal + a.velocity -= impulse * a.inverseMass + b.velocity += impulse * b.inverseMass + + // Positional correction (prevent sinking) + correction = max(penetration - slop, 0) / (a.inverseMass + b.inverseMass) * percent + a.position -= correction * a.inverseMass * normal + b.position += correction * b.inverseMass * normal +``` + +Key constants: +- `slop`: A small tolerance (e.g., 0.01) to prevent jitter from micro-penetrations. +- `percent`: Typically 0.2 to 0.8; controls how aggressively positional correction is + applied. + +#### Rotational Dynamics + +For 2D rotation, torque is the rotational equivalent of force: + +``` +torque = cross(contactPoint - centerOfMass, impulse) +angularAcceleration = torque * inverseInertia +angularVelocity += angularAcceleration * dt +angle += angularVelocity * dt +``` + +The moment of inertia depends on the shape: +- **Circle**: `I = 0.5 * m * r^2` +- **Rectangle**: `I = (1/12) * m * (w^2 + h^2)` + +### Pseudocode -- Complete Physics Step + +``` +function step(dt): + // 1. Apply external forces (gravity, player input, etc.) + for each body in world.bodies: + if not body.isStatic: + body.applyForce(gravity * body.mass) + + // 2. Integrate velocities and positions + for each body in world.bodies: + if not body.isStatic: + body.velocity += (body.forceAccumulator * body.inverseMass) * dt + body.position += body.velocity * dt + body.angularVelocity += body.torque * body.inverseInertia * dt + body.angle += body.angularVelocity * dt + body.forceAccumulator = (0, 0) + body.torque = 0 + + // 3. Broad-phase collision detection + pairs = broadPhase(world.bodies) + + // 4. Narrow-phase collision detection + contacts = [] + for each (a, b) in pairs: + contact = narrowPhase(a, b) + if contact: + contacts.append(contact) + + // 5. Resolve collisions (iterative solver) + for i in range(solverIterations): // typically 4-10 iterations + for each contact in contacts: + resolveCollision(contact.a, contact.b, + contact.normal, contact.penetration) +``` + +### Practical Game Development Applications + +- **Platformers**: Gravity, ground contact, jumping arcs, and moving platforms. +- **Top-down games**: Sliding along walls, knockback from attacks. +- **Ragdoll physics**: Chain of rigid bodies connected by constraints. +- **Vehicle simulation**: Suspension springs, tire friction, engine force. +- **Destruction**: Breaking objects into debris with individual physics bodies. + +--- + +## Vector Mathematics for Game Development + +> Source: https://www.gamedev.net/tutorials/programming/math-and-physics/vector-maths-for-game-dev-beginners-r5442/ + +### What It Is + +Vectors are the mathematical building blocks of game development. A vector represents +a quantity with both magnitude and direction. In 2D games, vectors are pairs `(x, y)`; +in 3D, triples `(x, y, z)`. Nearly every game system -- movement, physics, rendering, +AI -- relies on vector operations. + +### Mathematical / Algorithmic Concepts + +#### Vector Representation + +A 2D vector: +``` +v = (x, y) +``` + +A 3D vector: +``` +v = (x, y, z) +``` + +Vectors can represent positions, directions, velocities, forces, or any quantity with +magnitude and direction. + +#### Vector Addition + +Component-wise addition. Used to apply velocity to position, combine forces, etc. + +``` +a + b = (a.x + b.x, a.y + b.y) +``` + +**Example**: Moving a character by its velocity: +``` +position = position + velocity * deltaTime +``` + +#### Vector Subtraction + +Component-wise subtraction. Used to find the direction and distance from one point to +another. + +``` +a - b = (a.x - b.x, a.y - b.y) +``` + +**Example**: Direction from enemy to player: +``` +directionToPlayer = player.position - enemy.position +``` + +#### Scalar Multiplication + +Scales a vector's magnitude without changing its direction: + +``` +s * v = (s * v.x, s * v.y) +``` + +**Example**: Setting movement speed: +``` +velocity = normalizedDirection * speed +``` + +#### Magnitude (Length) + +The length of a vector, computed via the Pythagorean theorem: + +``` +|v| = sqrt(v.x^2 + v.y^2) +``` + +In 3D: +``` +|v| = sqrt(v.x^2 + v.y^2 + v.z^2) +``` + +**Optimization**: When only comparing distances (not needing the actual value), use +squared magnitude to avoid the expensive square root: + +``` +|v|^2 = v.x^2 + v.y^2 +``` + +#### Normalization + +Produces a unit vector (length 1) pointing in the same direction: + +``` +normalize(v) = v / |v| = (v.x / |v|, v.y / |v|) +``` + +A normalized vector represents pure direction. Always check that `|v| > 0` before +dividing to avoid division by zero. + +**Example**: Get the direction an entity is facing: +``` +facing = normalize(target - self.position) +``` + +#### Dot Product + +A scalar result that encodes the angular relationship between two vectors: + +``` +a . b = a.x * b.x + a.y * b.y +``` + +In 3D: +``` +a . b = a.x * b.x + a.y * b.y + a.z * b.z +``` + +Geometric interpretation: +``` +a . b = |a| * |b| * cos(theta) +``` + +Where `theta` is the angle between the vectors. For unit vectors: +``` +a . b = cos(theta) +``` + +Key properties: +- `a . b > 0`: Vectors point in roughly the same direction (angle < 90 degrees). +- `a . b == 0`: Vectors are perpendicular (angle = 90 degrees). +- `a . b < 0`: Vectors point in roughly opposite directions (angle > 90 degrees). + +**Game dev uses**: +- Field-of-view checks: Is the player in front of the enemy? +- Lighting: Compute diffuse light intensity (`max(0, dot(normal, lightDir))`). +- Projection: Project one vector onto another. + +#### Cross Product (3D) + +Produces a vector perpendicular to both input vectors: + +``` +a x b = ( + a.y * b.z - a.z * b.y, + a.z * b.x - a.x * b.z, + a.x * b.y - a.y * b.x +) +``` + +The magnitude of the cross product equals: +``` +|a x b| = |a| * |b| * sin(theta) +``` + +In 2D, the "cross product" is a scalar (the z-component of the 3D cross product): +``` +a x b = a.x * b.y - a.y * b.x +``` + +**Game dev uses**: +- Determine winding order (clockwise vs counter-clockwise). +- Compute surface normals for lighting. +- Determine if a point is to the left or right of a line. + +#### Perpendicular Vector (2D) + +To get a vector perpendicular to `(x, y)`: +``` +perp = (-y, x) // 90 degrees counter-clockwise +perp = (y, -x) // 90 degrees clockwise +``` + +Useful for computing normals of 2D edges and walls. + +#### Projection + +Project vector `a` onto vector `b`: + +``` +proj_b(a) = (a . b / b . b) * b +``` + +If `b` is already a unit vector: +``` +proj_b(a) = (a . b) * b +``` + +**Game dev uses**: +- Determine velocity component along a surface normal (for bounce/reflection). +- Sliding along a wall: Subtract the normal component from velocity. + +#### Reflection + +Reflect vector `v` across a surface with normal `n` (where `n` is a unit vector): + +``` +reflected = v - 2 * (v . n) * n +``` + +**Game dev uses**: +- Ball bouncing off a wall. +- Light reflection calculations. +- Ricochet trajectories. + +### Pseudocode -- Vector2D Class + +``` +class Vector2D: + x, y + + function add(other): + return Vector2D(x + other.x, y + other.y) + + function subtract(other): + return Vector2D(x - other.x, y - other.y) + + function scale(scalar): + return Vector2D(x * scalar, y * scalar) + + function magnitude(): + return sqrt(x * x + y * y) + + function magnitudeSquared(): + return x * x + y * y + + function normalize(): + mag = magnitude() + if mag > 0: + return Vector2D(x / mag, y / mag) + return Vector2D(0, 0) + + function dot(other): + return x * other.x + y * other.y + + function cross(other): + return x * other.y - y * other.x + + function perpendicular(): + return Vector2D(-y, x) + + function reflect(normal): + d = dot(normal) + return Vector2D(x - 2 * d * normal.x, y - 2 * d * normal.y) + + function angleTo(other): + return acos(normalize().dot(other.normalize())) + + function distanceTo(other): + return subtract(other).magnitude() + + function lerp(other, t): + return Vector2D( + x + (other.x - x) * t, + y + (other.y - y) * t + ) +``` + +### Practical Game Development Applications + +- **Movement and steering**: Add velocity vectors to position; normalize direction + vectors and multiply by speed for consistent movement. +- **Distance checks**: Use squared magnitude for performance-friendly radius checks + (e.g., "is this enemy within range?"). +- **Field-of-view**: Use the dot product between an entity's forward vector and the + direction to a target to determine if the target is within a vision cone. +- **Wall sliding**: Project the velocity onto the wall's tangent (perpendicular to the + normal) to allow smooth sliding along surfaces. +- **Reflections and bouncing**: Use the reflection formula when a projectile or ball + hits a surface. +- **Interpolation**: Use `lerp` (linear interpolation) between two vectors for smooth + movement, camera tracking, and animations. +- **Rotation**: Rotate a vector by an angle using trigonometry: + ``` + rotated.x = v.x * cos(angle) - v.y * sin(angle) + rotated.y = v.x * sin(angle) + v.y * cos(angle) + ``` + +--- + +## Quick Reference Table + +| Algorithm / Concept | Primary Use Case | Complexity | +|---|---|---| +| Bresenham's Line | Grid raycasting, line of sight | O(max(dx, dy)) per ray | +| AABB Overlap | Fast collision detection | O(1) per pair | +| Circle Overlap | Round collider detection | O(1) per pair | +| Separating Axis Theorem | Convex polygon collision | O(n) per pair (n = edges) | +| Spatial Hashing | Broad-phase collision culling | O(1) average lookup | +| Euler Integration | Simple physics stepping | O(1) per body per step | +| Verlet Integration | Constraint-based physics | O(1) per body per step | +| Impulse Resolution | Collision response | O(iterations * contacts) | +| Vector Normalization | Direction extraction | O(1) | +| Dot Product | Angle/projection queries | O(1) | +| Cross Product | Perpendicularity / winding | O(1) | +| Reflection | Bounce / ricochet | O(1) | diff --git a/skills/game-engine/references/basics.md b/skills/game-engine/references/basics.md new file mode 100644 index 000000000..f281e961f --- /dev/null +++ b/skills/game-engine/references/basics.md @@ -0,0 +1,343 @@ +# Game Development Basics + +A comprehensive reference covering web game development technologies, game architecture, and the anatomy of a game loop. + +Sources: +- https://developer.mozilla.org/en-US/docs/Games/Introduction +- https://developer.mozilla.org/en-US/docs/Games/Anatomy + +--- + +## Web Technologies for Game Development + +### Graphics and Rendering + +- **WebGL** -- Hardware-accelerated 2D and 3D graphics based on OpenGL ES 2.0. Provides direct GPU access for high-performance rendering. +- **Canvas API** -- 2D drawing surface via the `` element. Suitable for 2D games, sprite rendering, and pixel manipulation. +- **SVG** -- Scalable Vector Graphics for resolution-independent visuals. Useful for UI elements and simple vector-based games. +- **HTML/CSS** -- Standard web technologies for building game UI, menus, HUDs, and overlays. + +### Audio + +- **Web Audio API** -- Advanced audio engine supporting real-time playback, synthesis, spatial audio, effects processing, and dynamic mixing. +- **HTML Audio Element** -- Simple sound playback for background music and basic sound effects. + +### Input and Controls + +- **Gamepad API** -- Support for game controllers and gamepads, including button mapping and analog stick input. +- **Touch Events API** -- Multi-touch input handling for mobile devices. +- **Pointer Lock API** -- Locks the mouse cursor within the game area and provides raw coordinate deltas for precise camera/aiming control. +- **Device Sensors** -- Accelerometer and gyroscope access for motion-based input. +- **Full Screen API** -- Enables immersive full-screen game experiences. + +### Networking and Multiplayer + +- **WebSockets API** -- Persistent, bidirectional communication channel for real-time multiplayer, chat, and live updates. +- **WebRTC API** -- Peer-to-peer connections for low-latency multiplayer, voice chat, and data channels. +- **Fetch API** -- HTTP requests for downloading game assets, loading level data, and transmitting non-real-time game state. + +### Data Storage and Performance + +- **IndexedDB API** -- Client-side structured storage for save games, cached assets, and offline play support. +- **Typed Arrays** -- Direct access to raw binary data buffers for GL textures, audio samples, and compact game data. +- **Web Workers API** -- Background thread execution for offloading heavy computations (physics, pathfinding, AI) without blocking the main thread. + +### Languages and Compilation + +- **JavaScript** -- The primary language for web game development. +- **C/C++ via Emscripten** -- Compile existing native game code to JavaScript or WebAssembly for web deployment. +- **WebAssembly (Wasm)** -- Near-native execution speed for performance-critical game code. + +--- + +## Types of Games You Can Build + +The modern web platform supports a full range of game types: + +- 3D action games and shooters +- Role-playing games (RPGs) +- 2D platformers and side-scrollers +- Puzzle and strategy games +- Card and board games +- Casual and mobile-friendly games +- Multiplayer experiences with real-time networking + +--- + +## Advantages of Web-Based Game Development + +1. **Universal reach** -- Games run on smartphones, tablets, PCs, and Smart TVs through the browser. +2. **No app store dependency** -- Deploy directly on the web without store approval processes. +3. **Full revenue control** -- No mandatory revenue share; use any payment processing system. +4. **Instant updates** -- Push updates immediately without waiting for store review. +5. **Own your analytics** -- Collect your own data or choose any analytics provider. +6. **Direct player relationships** -- Engage players without intermediaries. +7. **Inherent shareability** -- Games are linkable and discoverable via standard web mechanisms. + +--- + +## Anatomy of a Game Loop + +Every game operates through a continuous cycle of steps: + +1. **Present** -- Display the current game state to the player. +2. **Accept** -- Receive user input (keyboard, mouse, gamepad, touch). +3. **Interpret** -- Process raw input into meaningful game actions. +4. **Calculate** -- Update the game state based on actions, physics, AI, and time. +5. **Repeat** -- Loop back to present the updated state. + +Games may be **event-driven** (turn-based, waiting for player action) or **per-frame** (continuously updating via a main loop). + +--- + +## Building a Game Loop with requestAnimationFrame + +### Basic Main Loop + +```javascript +window.main = () => { + window.requestAnimationFrame(main); + + // Your game logic here: update state, render frame +}; + +main(); // Start the cycle +``` + +Key points: +- `requestAnimationFrame()` synchronizes callbacks to the browser's repaint schedule (typically 60 Hz). +- Schedule the next frame **before** performing loop work to maximize available computation time. + +### Self-Contained Main Loop (IIFE) + +```javascript +;(() => { + function main() { + window.requestAnimationFrame(main); + + // Game logic here + } + + main(); +})(); +``` + +### Stoppable Main Loop + +```javascript +;(() => { + function main() { + MyGame.stopMain = window.requestAnimationFrame(main); + + // Game logic here + } + + main(); +})(); + +// To stop the loop: +window.cancelAnimationFrame(MyGame.stopMain); +``` + +--- + +## Timing and Frame Rate + +### DOMHighResTimeStamp + +`requestAnimationFrame` passes a `DOMHighResTimeStamp` to your callback, providing timing precision to 1/1000th of a millisecond. + +```javascript +;(() => { + function main(tFrame) { + MyGame.stopMain = window.requestAnimationFrame(main); + + // tFrame is a high-resolution timestamp in milliseconds + // Use it for delta-time calculations + } + + main(); +})(); +``` + +### Frame Time Budget + +At 60 Hz, each frame has approximately **16.67ms** of available processing time. The browser's frame cycle is: + +1. Start new frame (previous frame displayed to screen) +2. Execute `requestAnimationFrame` callbacks +3. Perform garbage collection and per-frame browser tasks +4. Sleep until VSync, then repeat + +--- + +## Simple Update and Render Pattern + +The simplest approach when your game can sustain the target frame rate: + +```javascript +;(() => { + function main(tFrame) { + MyGame.stopMain = window.requestAnimationFrame(main); + + update(tFrame); // Process game logic + render(); // Draw the frame + } + + main(); +})(); +``` + +Assumptions: +- Each frame can process input and update state within the time budget. +- The simulation runs at the same rate as the display refresh (typically ~60 FPS). +- No frame interpolation is needed. + +--- + +## Decoupled Update and Render with Fixed Timestep + +For robust handling of variable refresh rates and consistent simulation behavior: + +```javascript +;(() => { + function main(tFrame) { + MyGame.stopMain = window.requestAnimationFrame(main); + const nextTick = MyGame.lastTick + MyGame.tickLength; + let numTicks = 0; + + // Calculate how many simulation updates are needed + if (tFrame > nextTick) { + const timeSinceTick = tFrame - MyGame.lastTick; + numTicks = Math.floor(timeSinceTick / MyGame.tickLength); + } + + queueUpdates(numTicks); + render(tFrame); + MyGame.lastRender = tFrame; + } + + function queueUpdates(numTicks) { + for (let i = 0; i < numTicks; i++) { + MyGame.lastTick += MyGame.tickLength; + update(MyGame.lastTick); + } + } + + MyGame.lastTick = performance.now(); + MyGame.lastRender = MyGame.lastTick; + MyGame.tickLength = 50; // 20 Hz simulation rate (50ms per tick) + + setInitialState(); + main(performance.now()); +})(); +``` + +Benefits: +- **Deterministic simulation** -- Game logic runs at a fixed frequency regardless of display refresh rate. +- **Smooth rendering** -- Rendering can interpolate between simulation states for visual smoothness. +- **Portable behavior** -- Game behaves the same on 60 Hz, 120 Hz, and 144 Hz displays. + +--- + +## Alternative Architecture Patterns + +### Separate setInterval for Updates + +```javascript +// Game logic updates at a fixed rate +setInterval(() => { + update(); +}, 50); // 20 Hz + +// Rendering synchronized to display +requestAnimationFrame(function render(tFrame) { + requestAnimationFrame(render); + draw(); +}); +``` + +Drawback: `setInterval` continues running even when the tab is not visible, wasting resources. + +### Web Worker for Updates + +```javascript +// Heavy game logic runs in a background thread +const updateWorker = new Worker('game-update-worker.js'); + +requestAnimationFrame(function render(tFrame) { + requestAnimationFrame(render); + updateWorker.postMessage({ ticks: numTicksNeeded }); + draw(); +}); +``` + +Benefits: Does not block the main thread. Ideal for physics-heavy or AI-intensive games. +Drawback: Communication overhead between worker and main thread. + +### requestAnimationFrame Driving a Web Worker + +```javascript +;(() => { + function main(tFrame) { + MyGame.stopMain = window.requestAnimationFrame(main); + + // Signal worker to compute updates + updateWorker.postMessage({ + lastTick: MyGame.lastTick, + numTicks: calculatedNumTicks + }); + + render(tFrame); + } + + main(); +})(); +``` + +Benefits: No reliance on legacy timers. Worker performs computation in parallel. + +--- + +## Handling Tab Focus Loss + +When a browser tab loses focus, `requestAnimationFrame` slows down or stops entirely. Strategies: + +| Strategy | Description | Best For | +|---|---|---| +| Treat gap as pause | Skip elapsed time; do not update | Single-player games | +| Simulate the gap | Run all missed updates on regain | Simple simulations | +| Sync from server/peer | Fetch authoritative state | Multiplayer games | + +Monitor the `numTicks` value after a focus-regain event. A very large value indicates the game was suspended and may need special handling rather than trying to simulate all missed frames. + +--- + +## Comparison of Timing Approaches + +| Approach | Pros | Cons | +|---|---|---| +| Simple update/render per frame | Easy to implement, responsive | Breaks on slow/fast hardware | +| Fixed timestep + interpolation | Consistent simulation, smooth visuals | More complex to implement | +| Quality scaling | Maintains frame rate dynamically | Requires adaptive quality systems | + +--- + +## Performance Best Practices + +- **Detach non-frame-critical code** from the main loop. Use events and callbacks for UI, network responses, and other asynchronous operations. +- **Use Web Workers** for computationally expensive tasks like physics, pathfinding, and AI. +- **Leverage GPU acceleration** through WebGL for rendering. +- **Stay within the frame budget** -- monitor your update + render time to keep it under 16.67ms for 60 FPS. +- **Throttle garbage collection pressure** by reusing objects and avoiding per-frame allocations. +- **Plan your timing strategy early** -- changing the game loop architecture mid-development is difficult and error-prone. + +--- + +## Popular 3D Frameworks and Libraries + +- **Three.js** -- General-purpose 3D library with a large ecosystem. +- **Babylon.js** -- Full-featured 3D game engine with physics, audio, and scene management. +- **A-Frame** -- Declarative 3D/VR framework built on Three.js. +- **PlayCanvas** -- Cloud-hosted 3D game engine with a visual editor. +- **Phaser** -- Popular 2D game framework with physics and input handling. diff --git a/skills/game-engine/references/game-control-mechanisms.md b/skills/game-engine/references/game-control-mechanisms.md new file mode 100644 index 000000000..029150475 --- /dev/null +++ b/skills/game-engine/references/game-control-mechanisms.md @@ -0,0 +1,617 @@ +# Game Control Mechanisms + +This reference covers the primary control mechanisms available for web-based games, including mobile touch, desktop keyboard and mouse, gamepad controllers, and unconventional input methods. + +## Mobile Touch Controls + +Mobile touch controls are essential for web-based games targeting mobile devices. A mobile-first approach ensures games are accessible on the most widely used platform for HTML5 games. + +### Key Events and APIs + +The core touch events available in the browser are: + +| Event | Description | +|-------|-------------| +| `touchstart` | Fired when the user places a finger on the screen | +| `touchmove` | Fired when the user moves a finger while touching the screen | +| `touchend` | Fired when the user lifts a finger from the screen | +| `touchcancel` | Fired when a touch is cancelled or interrupted (e.g., finger moves off-screen) | + +**Registering touch event listeners:** + +```javascript +const canvas = document.querySelector("canvas"); +canvas.addEventListener("touchstart", handleStart); +canvas.addEventListener("touchmove", handleMove); +canvas.addEventListener("touchend", handleEnd); +canvas.addEventListener("touchcancel", handleCancel); +``` + +**Touch event properties:** + +- `e.touches[0]` -- Access the first touch point (zero-indexed for multitouch). +- `e.touches[0].pageX` / `e.touches[0].pageY` -- Touch coordinates relative to the page. +- Always subtract canvas offset to get position relative to the canvas element. + +### Code Examples + +**Pure JavaScript touch handler:** + +```javascript +document.addEventListener("touchstart", touchHandler); +document.addEventListener("touchmove", touchHandler); + +function touchHandler(e) { + if (e.touches) { + playerX = e.touches[0].pageX - canvas.offsetLeft - playerWidth / 2; + playerY = e.touches[0].pageY - canvas.offsetTop - playerHeight / 2; + e.preventDefault(); + } +} +``` + +**Phaser framework pointer system:** + +Phaser manages touch input through "pointers" representing individual fingers: + +```javascript +// Access pointers +this.game.input.activePointer; // Most recently active pointer +this.game.input.pointer1; // First pointer +this.game.input.pointer2; // Second pointer + +// Add more pointers (up to 10 total) +this.game.input.addPointer(); + +// Global input events +this.game.input.onDown.add(itemTouched, this); +this.game.input.onUp.add(itemReleased, this); +this.game.input.onTap.add(itemTapped, this); +this.game.input.onHold.add(itemHeld, this); +``` + +**Draggable sprite for ship movement:** + +```javascript +const player = this.game.add.sprite(30, 30, "ship"); +player.inputEnabled = true; +player.input.enableDrag(); +player.events.onDragStart.add(onDragStart, this); +player.events.onDragStop.add(onDragStop, this); + +function onDragStart(sprite, pointer) { + console.log(`Dragging at: ${pointer.x}, ${pointer.y}`); +} +``` + +**Invisible touch area for shooting (right half of screen):** + +```javascript +this.buttonShoot = this.add.button( + this.world.width * 0.5, 0, + "button-alpha", // transparent image + null, + this +); +this.buttonShoot.onInputDown.add(this.goShootPressed, this); +this.buttonShoot.onInputUp.add(this.goShootReleased, this); +``` + +**Virtual gamepad plugin:** + +```javascript +this.gamepad = this.game.plugins.add(Phaser.Plugin.VirtualGamepad); +this.joystick = this.gamepad.addJoystick(100, 420, 1.2, "gamepad"); +this.button = this.gamepad.addButton(400, 420, 1.0, "gamepad"); +``` + +### Best Practices + +- Always call `preventDefault()` on touch events to avoid unwanted scrolling and default browser behavior. +- Use invisible button areas rather than visible buttons to avoid covering gameplay. +- Leverage natural touch gestures like dragging, which are more intuitive than on-screen buttons. +- Subtract canvas offset and account for object dimensions when calculating positions. +- Make touchable areas large enough for comfortable interaction. +- Plan for multitouch support. Phaser supports up to 10 simultaneous pointers. +- Use a framework like Phaser for automatic desktop and mobile compatibility. +- Consider virtual gamepad/joystick plugins for advanced touch control UI. + +## Desktop with Mouse and Keyboard + +Desktop keyboard and mouse controls provide precise input for web games and are the default control scheme for desktop browsers. + +### Key Events and APIs + +**Keyboard events:** + +```javascript +document.addEventListener("keydown", keyDownHandler); +document.addEventListener("keyup", keyUpHandler); +``` + +- `event.code` returns readable key identifiers such as `"ArrowLeft"`, `"ArrowRight"`, `"ArrowUp"`, `"ArrowDown"`. +- Use `requestAnimationFrame()` for continuous frame updates. + +**Phaser keyboard API:** + +```javascript +this.cursors = this.input.keyboard.createCursorKeys(); // Arrow key objects +this.keyLeft = this.input.keyboard.addKey(Phaser.KeyCode.A); // Custom key binding +// Check key state with .isDown property +// Listen for press events with .onDown.add() +``` + +**Phaser mouse API:** + +```javascript +this.game.input.mousePointer; // Mouse position and state +this.game.input.mousePointer.isDown; // Is any mouse button pressed +this.game.input.mousePointer.x; // Mouse X coordinate +this.game.input.mousePointer.y; // Mouse Y coordinate +this.game.input.mousePointer.leftButton.isDown; // Left mouse button +this.game.input.mousePointer.rightButton.isDown; // Right mouse button +this.game.input.activePointer; // Platform-independent (mouse + touch) +``` + +### Code Examples + +**Pure JavaScript keyboard state tracking:** + +```javascript +let rightPressed = false; +let leftPressed = false; +let upPressed = false; +let downPressed = false; + +function keyDownHandler(event) { + if (event.code === "ArrowRight") rightPressed = true; + else if (event.code === "ArrowLeft") leftPressed = true; + if (event.code === "ArrowDown") downPressed = true; + else if (event.code === "ArrowUp") upPressed = true; +} + +function keyUpHandler(event) { + if (event.code === "ArrowRight") rightPressed = false; + else if (event.code === "ArrowLeft") leftPressed = false; + if (event.code === "ArrowDown") downPressed = false; + else if (event.code === "ArrowUp") upPressed = false; +} +``` + +**Game loop with input handling:** + +```javascript +function draw() { + ctx.clearRect(0, 0, canvas.width, canvas.height); + + if (rightPressed) playerX += 5; + else if (leftPressed) playerX -= 5; + if (downPressed) playerY += 5; + else if (upPressed) playerY -= 5; + + ctx.drawImage(img, playerX, playerY); + requestAnimationFrame(draw); +} +``` + +**Dual control support (Arrow keys + WASD) in Phaser:** + +```javascript +this.cursors = this.input.keyboard.createCursorKeys(); +this.keyLeft = this.input.keyboard.addKey(Phaser.KeyCode.A); +this.keyRight = this.input.keyboard.addKey(Phaser.KeyCode.D); +this.keyUp = this.input.keyboard.addKey(Phaser.KeyCode.W); +this.keyDown = this.input.keyboard.addKey(Phaser.KeyCode.S); + +// In update: +if (this.cursors.left.isDown || this.keyLeft.isDown) { + // move left +} else if (this.cursors.right.isDown || this.keyRight.isDown) { + // move right +} +if (this.cursors.up.isDown || this.keyUp.isDown) { + // move up +} else if (this.cursors.down.isDown || this.keyDown.isDown) { + // move down +} +``` + +**Multiple fire buttons:** + +```javascript +this.keyFire1 = this.input.keyboard.addKey(Phaser.KeyCode.X); +this.keyFire2 = this.input.keyboard.addKey(Phaser.KeyCode.SPACEBAR); + +if (this.keyFire1.isDown || this.keyFire2.isDown) { + // fire the weapon +} +``` + +**Device-specific instructions:** + +```javascript +if (this.game.device.desktop) { + moveText = "Arrow keys or WASD to move"; + shootText = "X or Space to shoot"; +} else { + moveText = "Tap and hold to move"; + shootText = "Tap to shoot"; +} +``` + +### Best Practices + +- Support multiple input methods: provide both arrow keys and WASD for movement, and multiple fire buttons (e.g., X and Space). +- Use `activePointer` instead of `mousePointer` to support both mouse and touch input seamlessly. +- Detect device type and display appropriate control instructions to the player. +- Use `requestAnimationFrame()` for smooth animation and check key states in the game loop rather than reacting to individual key presses. +- Allow keyboard shortcuts to skip non-gameplay screens (e.g., Enter to start, any key to skip intro). +- Use Phaser or a similar framework for cross-browser compatibility, as they handle edge cases and browser differences automatically. + +## Desktop with Gamepad + +The Gamepad API enables web games to detect and respond to gamepad and controller input, bringing console-like experiences to the browser. + +### Key Events and APIs + +**Core events:** + +```javascript +window.addEventListener("gamepadconnected", gamepadHandler); +window.addEventListener("gamepaddisconnected", gamepadHandler); +``` + +**Gamepad object properties:** + +- `controller.id` -- Device identifier string. +- `controller.buttons[]` -- Array of button objects, each with a `.pressed` boolean property. +- `controller.axes[]` -- Array of analog stick values ranging from -1 to 1. + +**Standard button/axes mapping (Xbox 360 layout):** + +| Input | Index | Type | +|-------|-------|------| +| A Button | 0 | Button | +| B Button | 1 | Button | +| X Button | 2 | Button | +| Y Button | 3 | Button | +| D-Pad Up | 12 | Button | +| D-Pad Down | 13 | Button | +| D-Pad Left | 14 | Button | +| D-Pad Right | 15 | Button | +| Left Stick X | axes[0] | Axis | +| Left Stick Y | axes[1] | Axis | +| Right Stick X | axes[2] | Axis | +| Right Stick Y | axes[3] | Axis | + +### Code Examples + +**Pure JavaScript connection handler:** + +```javascript +let controller = {}; +let buttonsPressed = []; + +function gamepadHandler(e) { + controller = e.gamepad; + console.log(`Gamepad: ${controller.id}`); +} + +window.addEventListener("gamepadconnected", gamepadHandler); +``` + +**Polling button states each frame:** + +```javascript +function gamepadUpdateHandler() { + buttonsPressed = []; + if (controller.buttons) { + for (const [i, button] of controller.buttons.entries()) { + if (button.pressed) { + buttonsPressed.push(i); + } + } + } +} + +function gamepadButtonPressedHandler(button) { + return buttonsPressed.includes(button); +} +``` + +**Game loop integration:** + +```javascript +function draw() { + ctx.clearRect(0, 0, canvas.width, canvas.height); + gamepadUpdateHandler(); + + if (gamepadButtonPressedHandler(12)) playerY -= 5; // D-Pad Up + else if (gamepadButtonPressedHandler(13)) playerY += 5; // D-Pad Down + if (gamepadButtonPressedHandler(14)) playerX -= 5; // D-Pad Left + else if (gamepadButtonPressedHandler(15)) playerX += 5; // D-Pad Right + if (gamepadButtonPressedHandler(0)) alert("BOOM!"); // A Button + + ctx.drawImage(img, playerX, playerY); + requestAnimationFrame(draw); +} +``` + +**Reusable GamepadAPI library with hold vs press detection:** + +```javascript +const GamepadAPI = { + active: false, + controller: {}, + + connect(event) { + GamepadAPI.controller = event.gamepad; + GamepadAPI.active = true; + }, + + disconnect(event) { + delete GamepadAPI.controller; + GamepadAPI.active = false; + }, + + update() { + GamepadAPI.buttons.cache = [...GamepadAPI.buttons.status]; + GamepadAPI.buttons.status = []; + + const c = GamepadAPI.controller || {}; + const pressed = []; + + if (c.buttons) { + for (let b = 0; b < c.buttons.length; b++) { + if (c.buttons[b].pressed) { + pressed.push(GamepadAPI.buttons.layout[b]); + } + } + } + + const axes = []; + if (c.axes) { + for (const ax of c.axes) { + axes.push(ax.toFixed(2)); + } + } + + GamepadAPI.axes.status = axes; + GamepadAPI.buttons.status = pressed; + return pressed; + }, + + buttons: { + layout: ["A", "B", "X", "Y", "LB", "RB", "LT", "RT", + "Back", "Start", "LS", "RS", + "DPad-Up", "DPad-Down", "DPad-Left", "DPad-Right"], + cache: [], + status: [], + pressed(button, hold) { + let newPress = false; + if (GamepadAPI.buttons.status.includes(button)) { + newPress = true; + } + if (!hold && GamepadAPI.buttons.cache.includes(button)) { + newPress = false; + } + return newPress; + } + }, + + axes: { + status: [] + } +}; + +window.addEventListener("gamepadconnected", GamepadAPI.connect); +window.addEventListener("gamepaddisconnected", GamepadAPI.disconnect); +``` + +**Analog stick movement with deadzone threshold:** + +```javascript +if (GamepadAPI.axes.status) { + if (GamepadAPI.axes.status[0] > 0.5) playerX += 5; // Right + else if (GamepadAPI.axes.status[0] < -0.5) playerX -= 5; // Left + if (GamepadAPI.axes.status[1] > 0.5) playerY += 5; // Down + else if (GamepadAPI.axes.status[1] < -0.5) playerY -= 5; // Up +} +``` + +**Context-aware control display:** + +```javascript +if (this.game.device.desktop) { + if (GamepadAPI.active) { + moveText = "DPad or left Stick to move"; + shootText = "A to shoot, Y for controls"; + } else { + moveText = "Arrow keys or WASD to move"; + shootText = "X or Space to shoot"; + } +} else { + moveText = "Tap and hold to move"; + shootText = "Tap to shoot"; +} +``` + +### Best Practices + +- Always check `GamepadAPI.active` before processing gamepad input. +- Differentiate between "hold" (continuous) and "press" (single new press) by caching previous frame button states. +- Apply a deadzone threshold (e.g., 0.5) for analog stick values to avoid unintentional drift input. +- Create a button mapping system because different devices may have different button layouts. +- Poll gamepad state every frame by calling the update function inside `requestAnimationFrame`. +- Display an on-screen indicator when a gamepad is connected, along with appropriate control instructions. +- Browser support is approximately 63% globally; always provide fallback keyboard/mouse controls. + +## Other Control Mechanisms + +Unconventional control mechanisms can provide unique gameplay experiences and leverage emerging hardware beyond traditional input devices. + +### TV Remote Controls + +**Description:** Smart TV remotes emit standard keyboard events, allowing web games to run on TV screens without modification. + +**Key Events and APIs:** + +- Remote directional buttons map to standard arrow key codes. +- Custom remote buttons have manufacturer-specific key codes. + +**Code Example:** + +```javascript +// Standard arrow key controls work automatically with TV remotes +this.cursors = this.input.keyboard.createCursorKeys(); +if (this.cursors.right.isDown) { + // move player right +} + +// Discover manufacturer-specific remote key codes +window.addEventListener("keydown", (event) => { + console.log(event.keyCode); +}); + +// Handle custom remote buttons (codes vary by manufacturer) +window.addEventListener("keydown", (event) => { + switch (event.keyCode) { + case 8: // Pause (Panasonic example) + break; + case 588: // Custom action + break; + } +}); +``` + +**Best Practices:** + +- Log key codes to the console during development to discover remote button mappings. +- Reuse existing keyboard control implementations since remotes emit keyboard events. +- Refer to manufacturer documentation or cheat sheets for key code mappings. + +### Leap Motion (Hand Gesture Recognition) + +**Description:** Detects hand position, rotation, and grip strength for gesture-based control without physical contact using the Leap Motion sensor. + +**Key Events and APIs:** + +- `Leap.loop()` -- Frame-based hand tracking callback. +- `hand.roll()` -- Horizontal rotation in radians. +- `hand.pitch()` -- Vertical rotation in radians. +- `hand.grabStrength` -- Grip strength as a float from 0 (open hand) to 1 (closed fist). + +**Code Example:** + +```html + +``` + +```javascript +const toDegrees = 1 / (Math.PI / 180); +let horizontalDegree = 0; +let verticalDegree = 0; +const degreeThreshold = 30; +let grabStrength = 0; + +Leap.loop({ + hand(hand) { + horizontalDegree = Math.round(hand.roll() * toDegrees); + verticalDegree = Math.round(hand.pitch() * toDegrees); + grabStrength = hand.grabStrength; + }, +}); + +function draw() { + ctx.clearRect(0, 0, canvas.width, canvas.height); + + if (horizontalDegree > degreeThreshold) playerX -= 5; + else if (horizontalDegree < -degreeThreshold) playerX += 5; + + if (verticalDegree > degreeThreshold) playerY += 5; + else if (verticalDegree < -degreeThreshold) playerY -= 5; + + if (grabStrength === 1) fireWeapon(); + + ctx.drawImage(img, playerX, playerY); + requestAnimationFrame(draw); +} +``` + +**Best Practices:** + +- Use a degree threshold (e.g., 30 degrees) to filter out minor hand movements and noise. +- Output diagnostic data during development to calibrate sensitivity. +- Limit to simple actions like steering and shooting rather than complex multi-input schemes. +- Requires Leap Motion drivers to be installed. + +### Doppler Effect (Microphone-Based Gesture Detection) + +**Description:** Detects hand movement direction and magnitude by analyzing frequency shifts in sound waves picked up by the device microphone. An emitted tone bounces off the user's hand, and the frequency difference indicates movement direction. + +**Key Events and APIs:** + +- Uses a Doppler effect detection library. +- `bandwidth.left` and `bandwidth.right` provide frequency analysis values. + +**Code Example:** + +```javascript +doppler.init((bandwidth) => { + const diff = bandwidth.left - bandwidth.right; + // Positive diff = movement in one direction + // Negative diff = movement in the other direction +}); +``` + +**Best Practices:** + +- Best suited for simple one-axis controls such as scrolling or up/down movement. +- Less precise than Leap Motion or gamepad input. +- Provides directional information through left/right frequency difference comparison. + +### Makey Makey (Physical Object Controllers) + +**Description:** Connects conductive objects (bananas, clay, drawn circuits, water, etc.) to a board that emulates keyboard and mouse input, enabling creative physical interfaces for games. + +**Key Events and APIs (via Cylon.js for custom hardware):** + +- `makey-button` driver for custom setups with Arduino or Raspberry Pi. +- `"push"` event listener for button activation. +- The Makey Makey board itself works over USB and emits standard keyboard events without requiring custom code. + +**Code Example (custom setup with Cylon.js):** + +```javascript +const Cylon = require("cylon"); + +Cylon.robot({ + connections: { + arduino: { adaptor: "firmata", port: "/dev/ttyACM0" }, + }, + devices: { + makey: { driver: "makey-button", pin: 2 }, + }, + work(my) { + my.makey.on("push", () => { + console.log("Button pushed!"); + // Trigger game action + }); + }, +}).start(); +``` + +**Best Practices:** + +- The Makey Makey board connects via USB and emits standard keyboard events, so existing keyboard controls work out of the box. +- Use a 10 MOhm resistor for GPIO connections on custom setups. +- Enables creative physical gaming experiences that are particularly good for exhibitions and installations. + +### General Recommendations for Unconventional Controls + +- Implement multiple control mechanisms to reach the broadest possible audience. +- Build on a keyboard and gamepad foundation since most unconventional controllers emulate or complement standard input. +- Use threshold values to filter noise and accidental inputs from imprecise hardware. +- Provide visual diagnostics during development with console output and on-screen values. +- Match control complexity to the game's needs. Not all mechanisms suit all games. +- Test hardware setup thoroughly before implementing game logic on top of it. diff --git a/skills/game-engine/references/game-engine-core-principles.md b/skills/game-engine/references/game-engine-core-principles.md new file mode 100644 index 000000000..e69852786 --- /dev/null +++ b/skills/game-engine/references/game-engine-core-principles.md @@ -0,0 +1,695 @@ +# Game Engine Core Design Principles + +A comprehensive reference on the fundamental architecture and design principles behind building a game engine. Covers modularity, separation of concerns, core subsystems, and practical implementation guidance. + +Source: https://www.gamedev.net/articles/programming/general-and-gameplay-programming/making-a-game-engine-core-design-principles-r3210/ + +--- + +## Why Build a Game Engine + +A game engine is a reusable software framework that abstracts the common systems needed to build games. Rather than writing rendering, physics, input, and audio code from scratch for every project, a well-designed engine provides these as modular, configurable subsystems. + +Key motivations: +- **Reusability** -- Use the same codebase across multiple game projects. +- **Separation of engine code from game code** -- Engine developers and game designers can work independently. +- **Maintainability** -- Well-structured code is easier to debug, extend, and optimize. +- **Scalability** -- Add new features or platforms without rewriting existing systems. + +--- + +## Core Design Principles + +### Modularity + +Every major system in the engine should be an independent module with a well-defined interface. Modules should communicate through clean APIs rather than reaching into each other's internals. + +**Why it matters:** +- Swap implementations without affecting other systems (e.g., replace OpenGL renderer with Vulkan). +- Test individual systems in isolation. +- Allow teams to work on different modules in parallel. + +**Example structure:** + +``` +engine/ + core/ -- Memory, logging, math, utilities + platform/ -- OS abstraction, windowing, file I/O + renderer/ -- Graphics API, shaders, materials + physics/ -- Collision, rigid body dynamics + audio/ -- Sound playback, mixing, spatial audio + input/ -- Keyboard, mouse, gamepad, touch + scripting/ -- Scripting language bindings + scene/ -- Scene graph, entity management + resources/ -- Asset loading, caching, streaming +``` + +### Separation of Concerns + +Each system should have a single, clearly defined responsibility. Avoid mixing rendering logic with physics, or input handling with game state management. + +**Practical guidelines:** +- The renderer should not know about game mechanics. +- The physics engine should not know how entities are rendered. +- Input processing should translate raw device events into abstract actions that game code can consume. +- The game logic layer sits on top of the engine and uses engine services without modifying them. + +### Data-Driven Design + +Wherever possible, behavior should be controlled by data rather than hard-coded logic. This allows designers and artists to modify game behavior without recompiling code. + +**Examples of data-driven approaches:** +- Level layouts defined in data files (JSON, XML, binary) rather than code. +- Entity properties and behaviors configured through component data. +- Shader parameters exposed as material properties editable in tools. +- Animation state machines defined in configuration rather than imperative code. + +### Minimize Dependencies + +Each module should depend on as few other modules as possible. The dependency graph should be a clean hierarchy, not a tangled web. + +``` +Game Code + | + v +Engine High-Level Systems (Scene, Entity, Scripting) + | + v +Engine Low-Level Systems (Renderer, Physics, Audio, Input) + | + v +Engine Core (Memory, Math, Logging, Platform Abstraction) + | + v +Operating System / Hardware +``` + +Circular dependencies between modules are a sign of poor architecture and should be eliminated. + +--- + +## The Entity-Component-System (ECS) Pattern + +ECS is a widely adopted architectural pattern in modern game engines that favors composition over inheritance. + +### Core Concepts + +- **Entity** -- A unique identifier (often just an integer ID) that represents a game object. An entity has no behavior or data of its own. +- **Component** -- A plain data container attached to an entity. Each component type stores one aspect of an entity's state (position, velocity, sprite, health, etc.). +- **System** -- A function or object that processes all entities with a specific set of components. Systems contain the logic; components contain the data. + +### Why ECS Over Inheritance + +Traditional object-oriented inheritance creates rigid, deep hierarchies: + +``` +GameObject + -> MovableObject + -> Character + -> Player + -> Enemy + -> FlyingEnemy + -> GroundEnemy +``` + +Problems with this approach: +- Adding a new entity type that combines traits from multiple branches requires restructuring the hierarchy or using multiple inheritance. +- Deep hierarchies are fragile; changes to base classes ripple through all descendants. +- Classes accumulate unused behavior over time. + +ECS solves these problems through composition: + +```javascript +// An entity is just an ID +const player = world.createEntity(); + +// Attach components to define what it is +world.addComponent(player, new Position(100, 200)); +world.addComponent(player, new Velocity(0, 0)); +world.addComponent(player, new Sprite("player.png")); +world.addComponent(player, new Health(100)); +world.addComponent(player, new PlayerInput()); + +// A "flying enemy" is just a different combination of components +const flyingEnemy = world.createEntity(); +world.addComponent(flyingEnemy, new Position(400, 50)); +world.addComponent(flyingEnemy, new Velocity(0, 0)); +world.addComponent(flyingEnemy, new Sprite("bat.png")); +world.addComponent(flyingEnemy, new Health(30)); +world.addComponent(flyingEnemy, new AIBehavior("patrol_fly")); +world.addComponent(flyingEnemy, new Flying()); +``` + +### Systems Process Components + +```javascript +// Movement system: processes all entities with Position + Velocity +function movementSystem(world, deltaTime) { + for (const [entity, pos, vel] of world.query(Position, Velocity)) { + pos.x += vel.x * deltaTime; + pos.y += vel.y * deltaTime; + } +} + +// Render system: processes all entities with Position + Sprite +function renderSystem(world, context) { + for (const [entity, pos, sprite] of world.query(Position, Sprite)) { + context.drawImage(sprite.image, pos.x, pos.y); + } +} + +// Gravity system: only affects entities with Velocity but NOT Flying +function gravitySystem(world, deltaTime) { + for (const [entity, vel] of world.query(Velocity).without(Flying)) { + vel.y += 9.8 * deltaTime; + } +} +``` + +### Benefits of ECS + +- **Flexible composition** -- Create any entity type by mixing components without modifying code. +- **Cache-friendly data layout** -- Storing components contiguously in memory improves CPU cache performance. +- **Parallelism** -- Systems that operate on different component sets can run in parallel. +- **Easy serialization** -- Components are plain data, making save/load straightforward. + +--- + +## Core Engine Subsystems + +### Memory Management + +Custom memory management is critical for game engine performance. The default allocator (malloc/new) is general-purpose and not optimized for game workloads. + +**Common allocation strategies:** + +- **Stack Allocator** -- Fast LIFO allocations for temporary, frame-scoped data. Reset the stack pointer at the end of each frame. +- **Pool Allocator** -- Fixed-size block allocation for objects of the same type (entities, components, particles). Zero fragmentation. +- **Frame Allocator** -- A linear allocator that resets every frame. Ideal for per-frame temporary data. +- **Double-Buffered Allocator** -- Two frame allocators that alternate each frame, allowing data from the previous frame to persist. + +```cpp +// Conceptual frame allocator +class FrameAllocator { + char* buffer; + size_t offset; + size_t capacity; + +public: + void* allocate(size_t size) { + void* ptr = buffer + offset; + offset += size; + return ptr; + } + + void reset() { + offset = 0; // All allocations freed instantly + } +}; +``` + +### Resource Management + +The resource manager handles loading, caching, and lifetime management of game assets. + +**Key responsibilities:** +- **Asynchronous loading** -- Load assets in background threads to avoid stalling the game loop. +- **Reference counting** -- Track how many systems use an asset; unload when no longer referenced. +- **Caching** -- Keep recently used assets in memory to avoid redundant disk reads. +- **Hot reloading** -- Detect asset changes on disk and reload them at runtime during development. +- **Resource handles** -- Use handles (IDs or smart pointers) rather than raw pointers to reference assets. + +```javascript +class ResourceManager { + constructor() { + this.cache = new Map(); + this.loading = new Map(); + } + + async load(path) { + // Return cached resource if available + if (this.cache.has(path)) { + return this.cache.get(path); + } + + // Avoid duplicate loads + if (this.loading.has(path)) { + return this.loading.get(path); + } + + // Start async load + const promise = this._loadFromDisk(path).then(resource => { + this.cache.set(path, resource); + this.loading.delete(path); + return resource; + }); + + this.loading.set(path, promise); + return promise; + } + + unload(path) { + this.cache.delete(path); + } +} +``` + +### Rendering Pipeline + +The rendering subsystem translates the game's visual state into pixels on screen. + +**Typical rendering pipeline stages:** + +1. **Scene traversal** -- Walk the scene graph or query ECS for renderable entities. +2. **Frustum culling** -- Discard objects outside the camera's view. +3. **Occlusion culling** -- Discard objects hidden behind other geometry. +4. **Sorting** -- Order objects by material, depth, or transparency requirements. +5. **Batching** -- Group objects with the same material to minimize draw calls and state changes. +6. **Vertex processing** -- Transform vertices from model space to screen space (vertex shader). +7. **Rasterization** -- Convert triangles to fragments (pixels). +8. **Fragment processing** -- Compute final pixel color using lighting, textures, and effects (fragment shader). +9. **Post-processing** -- Apply screen-space effects like bloom, tone mapping, and anti-aliasing. + +**Render command pattern:** + +Rather than making draw calls directly, build a list of render commands that can be sorted and batched before submission: + +```javascript +class RenderCommand { + constructor(mesh, material, transform, sortKey) { + this.mesh = mesh; + this.material = material; + this.transform = transform; + this.sortKey = sortKey; + } +} + +class Renderer { + constructor() { + this.commandQueue = []; + } + + submit(command) { + this.commandQueue.push(command); + } + + flush(context) { + // Sort by material to minimize state changes + this.commandQueue.sort((a, b) => a.sortKey - b.sortKey); + + for (const cmd of this.commandQueue) { + this._bindMaterial(cmd.material); + this._setTransform(cmd.transform); + this._drawMesh(cmd.mesh, context); + } + + this.commandQueue.length = 0; + } +} +``` + +### Physics Integration + +The physics subsystem simulates physical behavior and detects collisions. + +**Key design considerations:** + +- **Fixed timestep** -- Physics should update at a fixed rate (e.g., 50 Hz) independent of the rendering frame rate. This ensures deterministic simulation behavior. +- **Collision phases** -- Use a broad phase (spatial partitioning, bounding volume hierarchies) to quickly eliminate non-colliding pairs, followed by a narrow phase for precise intersection testing. +- **Physics world separation** -- The physics world should maintain its own representation of objects (physics bodies) separate from game entities. A synchronization step maps between them. + +```javascript +class PhysicsWorld { + constructor(fixedTimestep = 1 / 50) { + this.fixedTimestep = fixedTimestep; + this.accumulator = 0; + this.bodies = []; + } + + update(deltaTime) { + this.accumulator += deltaTime; + + while (this.accumulator >= this.fixedTimestep) { + this.step(this.fixedTimestep); + this.accumulator -= this.fixedTimestep; + } + } + + step(dt) { + // Integrate velocities + for (const body of this.bodies) { + body.velocity.y += body.gravity * dt; + body.position.x += body.velocity.x * dt; + body.position.y += body.velocity.y * dt; + } + + // Detect and resolve collisions + this.broadPhase(); + this.narrowPhase(); + this.resolveCollisions(); + } +} +``` + +### Input System + +The input system translates raw hardware events into game-meaningful actions. + +**Layered design:** + +1. **Hardware Layer** -- Receives raw events from the OS (key pressed, mouse moved, button down). +2. **Mapping Layer** -- Translates raw inputs into named actions via configurable bindings (e.g., "Space" maps to "Jump", "W" maps to "MoveForward"). +3. **Action Layer** -- Exposes abstract actions that game code queries, completely decoupled from specific hardware inputs. + +```javascript +class InputManager { + constructor() { + this.bindings = new Map(); + this.actionStates = new Map(); + } + + bind(action, key) { + this.bindings.set(key, action); + } + + handleKeyDown(event) { + const action = this.bindings.get(event.code); + if (action) { + this.actionStates.set(action, true); + } + } + + handleKeyUp(event) { + const action = this.bindings.get(event.code); + if (action) { + this.actionStates.set(action, false); + } + } + + isActionActive(action) { + return this.actionStates.get(action) || false; + } +} + +// Usage +const input = new InputManager(); +input.bind("Jump", "Space"); +input.bind("MoveLeft", "KeyA"); +input.bind("MoveRight", "KeyD"); + +// In game update: +if (input.isActionActive("Jump")) { + player.jump(); +} +``` + +### Event System + +An event system enables decoupled communication between engine subsystems and game code without direct references. + +**Publish-subscribe pattern:** + +```javascript +class EventBus { + constructor() { + this.listeners = new Map(); + } + + on(eventType, callback) { + if (!this.listeners.has(eventType)) { + this.listeners.set(eventType, []); + } + this.listeners.get(eventType).push(callback); + } + + off(eventType, callback) { + const callbacks = this.listeners.get(eventType); + if (callbacks) { + const index = callbacks.indexOf(callback); + if (index !== -1) callbacks.splice(index, 1); + } + } + + emit(eventType, data) { + const callbacks = this.listeners.get(eventType); + if (callbacks) { + for (const callback of callbacks) { + callback(data); + } + } + } +} + +// Usage +const events = new EventBus(); + +events.on("collision", (data) => { + console.log(`${data.entityA} collided with ${data.entityB}`); +}); + +events.on("entityDestroyed", (data) => { + spawnExplosion(data.position); + addScore(data.points); +}); + +// Emit from physics system +events.emit("collision", { entityA: player, entityB: wall }); +``` + +**Deferred events:** + +For performance and determinism, events can be queued during a frame and dispatched at a specific point in the update cycle: + +```javascript +class DeferredEventBus extends EventBus { + constructor() { + super(); + this.eventQueue = []; + } + + queue(eventType, data) { + this.eventQueue.push({ type: eventType, data }); + } + + dispatchQueued() { + for (const event of this.eventQueue) { + this.emit(event.type, event.data); + } + this.eventQueue.length = 0; + } +} +``` + +### Scene Management + +The scene manager organizes game content into logical groups and manages transitions between different game states. + +**Common patterns:** + +- **Scene graph** -- A hierarchical tree of nodes where child transforms are relative to parent transforms. Moving a parent moves all children. +- **Scene stack** -- Scenes can be pushed and popped. A pause menu pushes on top of gameplay; dismissing it pops back to gameplay. +- **Scene loading** -- Scenes define which assets and entities to load. The scene manager coordinates loading, initialization, and cleanup. + +```javascript +class SceneManager { + constructor() { + this.scenes = new Map(); + this.activeScene = null; + } + + register(name, scene) { + this.scenes.set(name, scene); + } + + async switchTo(name) { + if (this.activeScene) { + this.activeScene.onExit(); + this.activeScene.unloadResources(); + } + + this.activeScene = this.scenes.get(name); + await this.activeScene.loadResources(); + this.activeScene.onEnter(); + } + + update(deltaTime) { + if (this.activeScene) { + this.activeScene.update(deltaTime); + } + } + + render(context) { + if (this.activeScene) { + this.activeScene.render(context); + } + } +} +``` + +--- + +## Platform Abstraction + +A well-designed engine abstracts platform-specific code behind a uniform interface. This enables the engine to run on multiple operating systems, graphics APIs, and hardware configurations. + +**Areas requiring abstraction:** + +| Concern | Examples | +|---|---| +| Windowing | Win32, X11, Cocoa, SDL, GLFW | +| Graphics API | OpenGL, Vulkan, DirectX, Metal, WebGL | +| File I/O | POSIX, Win32, virtual file systems | +| Threading | pthreads, Win32 threads, Web Workers | +| Audio output | WASAPI, CoreAudio, ALSA, Web Audio | +| Input devices | DirectInput, XInput, evdev, Gamepad API | + +```javascript +// Abstract file system interface +class FileSystem { + async readFile(path) { throw new Error("Not implemented"); } + async writeFile(path, data) { throw new Error("Not implemented"); } + async exists(path) { throw new Error("Not implemented"); } +} + +// Web implementation +class WebFileSystem extends FileSystem { + async readFile(path) { + const response = await fetch(path); + return response.arrayBuffer(); + } +} + +// Node.js implementation +class NodeFileSystem extends FileSystem { + async readFile(path) { + const fs = require("fs").promises; + return fs.readFile(path); + } +} +``` + +--- + +## Initialization and Shutdown Order + +Engine subsystems must be initialized in dependency order and shut down in reverse order. + +**Typical initialization sequence:** + +1. Core systems (logging, memory, configuration) +2. Platform layer (window creation, input devices) +3. Rendering system (graphics context, default resources) +4. Audio system +5. Physics system +6. Resource manager (load default/shared assets) +7. Scene manager +8. Scripting system +9. Game-specific initialization + +**Shutdown reverses this order** to ensure systems are cleaned up before the systems they depend on. + +```javascript +class Engine { + async initialize() { + this.logger = new Logger(); + this.config = new Config("engine.json"); + this.platform = new Platform(); + await this.platform.createWindow(this.config.window); + + this.renderer = new Renderer(this.platform.canvas); + this.audio = new AudioSystem(); + this.physics = new PhysicsWorld(); + this.resources = new ResourceManager(); + this.input = new InputManager(this.platform.window); + this.events = new EventBus(); + this.scenes = new SceneManager(); + + this.logger.info("Engine initialized"); + } + + shutdown() { + this.scenes.cleanup(); + this.resources.unloadAll(); + this.input.cleanup(); + this.physics.cleanup(); + this.audio.cleanup(); + this.renderer.cleanup(); + this.platform.cleanup(); + this.logger.info("Engine shutdown complete"); + } + + run() { + let lastTime = performance.now(); + + const loop = (currentTime) => { + const deltaTime = (currentTime - lastTime) / 1000; + lastTime = currentTime; + + this.input.poll(); + this.physics.update(deltaTime); + this.scenes.update(deltaTime); + this.events.dispatchQueued(); + this.scenes.render(this.renderer); + this.renderer.present(); + + requestAnimationFrame(loop); + }; + + requestAnimationFrame(loop); + } +} +``` + +--- + +## Performance Principles + +### Avoid Premature Abstraction + +While modularity is important, over-engineering interfaces before understanding real requirements leads to unnecessary complexity. Start with simple, concrete implementations and refactor toward abstraction when actual use cases demand it. + +### Profile Before Optimizing + +Measure actual performance bottlenecks using profiling tools before spending time on optimization. Intuition about where time is spent is frequently wrong. + +### Data-Oriented Design + +Organize data by how it is accessed rather than by object-oriented abstractions. Storing components of the same type contiguously in memory (Structure of Arrays rather than Array of Structures) dramatically improves CPU cache hit rates. + +```javascript +// Array of Structures (cache-unfriendly for position-only iteration) +const entities = [ + { position: {x: 0, y: 0}, sprite: "hero.png", health: 100 }, + { position: {x: 5, y: 3}, sprite: "bat.png", health: 30 }, +]; + +// Structure of Arrays (cache-friendly for position-only iteration) +const positions = { x: [0, 5], y: [0, 3] }; +const sprites = ["hero.png", "bat.png"]; +const healths = [100, 30]; +``` + +### Minimize Allocations in Hot Paths + +Avoid creating new objects or allocating memory during per-frame updates. Pre-allocate buffers, use object pools, and reuse temporary objects. + +### Batch Operations + +Group similar operations together to reduce overhead from context switching, draw call setup, and cache misses. Process all entities of a given type before moving to the next type. + +--- + +## Summary of Key Principles + +| Principle | Description | +|---|---| +| Modularity | Independent subsystems with clean interfaces | +| Separation of concerns | Each system has a single responsibility | +| Data-driven design | Behavior controlled by data, not hard-coded logic | +| Composition over inheritance | ECS pattern for flexible entity construction | +| Minimal dependencies | Clean, hierarchical dependency graph | +| Platform abstraction | Uniform interfaces over platform-specific code | +| Fixed timestep physics | Deterministic simulation independent of frame rate | +| Event-driven communication | Decoupled interaction through publish-subscribe | +| Data-oriented performance | Optimize memory layout for access patterns | +| Measure before optimizing | Profile to identify actual bottlenecks | diff --git a/skills/game-engine/references/game-publishing.md b/skills/game-engine/references/game-publishing.md new file mode 100644 index 000000000..a0799007f --- /dev/null +++ b/skills/game-engine/references/game-publishing.md @@ -0,0 +1,352 @@ +# Game Publishing + +This reference covers the three pillars of publishing web-based games: distribution channels and platforms, promotion strategies, and monetization models. + +## Game Distribution + +Game distribution encompasses the channels and platforms through which players discover and access your game. Choosing the right distribution strategy depends on your target audience, game type, and business goals. + +### Self-Hosting + +Self-hosting gives you maximum control over your game and the ability to push instant updates without waiting for app store approval. + +- Upload the game to a remote server with a catchy, memorable domain name. +- Concatenate and minify source code to reduce payload size. +- Uglify code to make reverse engineering harder and protect intellectual property. +- Provide an online demo if you plan to package the game for closed stores like iTunes or Steam. +- Consider hosting on GitHub Pages for free hosting, version control, and potential community contributions. + +### Publishers and Portals + +Independent game portals offer natural promotion from high-traffic sites and potential monetization through ads or revenue sharing. + +**Popular independent portals:** + +- HTML5Games.com +- GameArter.com +- MarketJS.com +- GameFlare +- GameDistribution.com +- GameSaturn.com +- Playmox.com +- Poki (developers.poki.com) +- CrazyGames (developer.crazygames.com) + +**Licensing options:** + +- Exclusive licensing: Restrict distribution to a single buyer for higher per-deal revenue. +- Non-exclusive licensing: Distribute widely across multiple portals for broader reach. + +### Web Stores + +**Chrome Web Store:** + +- Requires a manifest file and a zipped package containing game resources. +- Minimal game modifications needed. +- Simple online submission form. + +### Native Mobile Stores + +**iOS App Store:** + +- Strict requirements with a 1-2 week approval wait period. +- Extremely competitive with hundreds of thousands of apps. +- Generally favors paid games. +- Most prominent mobile store but hardest to stand out. + +**Google Play (Android):** + +- Less strict requirements than iOS. +- High volume of daily submissions. +- Freemium model preferred (free download with in-app purchases or ads). +- Most paid iOS games appear as free-to-play on Android. + +**Other mobile platforms (Windows Phone, BlackBerry, etc.):** + +- Less competition and easier to gain visibility. +- Smaller market share but less crowded. + +### Native Desktop + +**Steam:** + +- Largest desktop game distribution platform. +- Access via the Steam Direct program for indie developers. +- Requires support for multiple platforms (Windows, macOS, Linux) with separate uploads. +- Must handle cross-platform compatibility issues. + +**Humble Bundle:** + +- Primarily an exposure and promotional opportunity. +- Bundle pricing model at low prices. +- More focused on gaining visibility than generating direct revenue. + +### Packaging Tools + +Tools for distributing HTML5 games to closed ecosystems: + +| Tool | Platforms | +|------|-----------| +| Ejecta | iOS (ImpactJS-specific) | +| NW.js | Windows, Mac, Linux | +| Electron | Windows, Mac, Linux | +| Intel XDK | Multiple platforms | +| Manifold.js | iOS, Android, Windows | + +### Platform Strategy + +- **Mobile first:** Mobile devices account for the vast majority of HTML5 game traffic. Design games playable with one or two fingers while holding the device. +- **Desktop for development:** Build and test on desktop first before debugging on mobile. +- **Multi-platform:** Support desktop even if targeting mobile primarily. HTML5 games have the advantage of write-once, deploy-everywhere. +- **Diversify:** Do not rely on a single store. Spread across multiple platforms to reduce risk. +- **Instant updates:** One of the key advantages of web distribution is the ability to push quick bug fixes without waiting for app store approval. + +## Game Promotion + +Game promotion requires a sustained, multi-channel strategy. Most promotional methods are free, making them accessible to indie developers with limited budgets. Visibility is as important as game quality -- even excellent games fail without promotion. + +### Website and Blog + +**Essential website components:** + +- Screenshots and game trailers. +- Detailed descriptions and downloadable press kits (use tools like Presskit()). +- System requirements and available platforms. +- Support and contact information. +- A playable demo, at least browser-based. +- SEO optimization for discoverability. + +**Blogging strategy:** + +- Document the development process, bugs encountered, and lessons learned. +- Publish monthly progress reports. +- Continual content creation improves SEO rankings over time. +- Builds credibility and community reputation. + +### Social Media + +- Use the `#gamedev` hashtag for community engagement on platforms like Twitter/X. +- Be authentic and avoid pushy advertisements or dry press releases. +- Share development tips, industry insights, and behind-the-scenes content. +- Monitor YouTube and Twitch streamers who might cover your game. +- Participate in forums such as HTML5GameDevs.com. +- Engage genuinely with the community. Answer questions, be supportive, and avoid constant self-promotion. +- Offer discounts and contest prizes to build goodwill. + +### Press Outreach + +- Research press outlets that specifically cover your game's genre and platform. +- Be humble, polite, and patient when contacting journalists and reviewers. +- Avoid mass, irrelevant submissions. Target your outreach carefully. +- A quality game paired with an honest approach yields the best success rates. +- Reference guides like "How To Contact Press" from Pixel Prospector for detailed strategies. + +### Competitions + +- Participate in game development competitions (game jams) to network and gain community exposure. +- Mandatory themes spark creative ideas and force innovation. +- Winning brings automatic promotion from organizers and community attention. +- Great for launching early demos and building reputation. + +### Tutorials and Educational Content + +- Document and teach what you have implemented in your game. +- Use your game as a practical case study in articles and tutorials. +- Publish on platforms like Tuts+ Game Development, which often pay for content. +- Focus on a single aspect in detail and provide genuine value to readers. +- Dual benefit: promotes your game while establishing you as a knowledgeable developer. + +### Events + +**Conferences:** + +- Give technical talks about challenges you overcame during development. +- Demonstrate API implementations with your game as a real example. +- Focus on knowledge-sharing over marketing. Developers are particularly sensitive to heavy-handed sales pitches. + +**Fairs and expos:** + +- Secure a booth among other developers for direct fan interaction. +- Stand out with unique, original presentations. +- Provides real-world user testing and immediate feedback. +- Helps uncover bugs and issues that players find organically. + +### Promo Codes + +- Create the ability to distribute free or limited-access promo codes. +- Distribute to press, media, YouTube and Twitch personalities, competition winners, and community influencers. +- Reaching the right people with free access can generate free advertising to thousands of potential players. + +### Community Building + +- Send weekly newsletters with regular updates to your audience. +- Organize online competitions related to your game or game development in general. +- Host local meetups for in-person developer gatherings. +- Demonstrates passion and builds trust and reliability. +- Your community becomes your advocates when you need support or buzz for a launch. + +### Key Promotion Principles + +| Factor | Importance | +|--------|-----------| +| Consistency | Regular content and engagement across all channels | +| Authenticity | Genuine community interaction, not transactional | +| Patience | Building relationships and reputation takes time | +| Value-first | Provide content worth consuming before asking for anything | +| Multiple channels | Never rely on a single promotional strategy | + +## Game Monetization + +Monetization strategy should align with your game type, target audience, and distribution platforms. Diversifying income streams provides better business stability. + +### Paid Games + +**Model:** Fixed, up-front price charged before the player gains access. + +- Requires significant marketing investment to drive purchases. +- Pricing varies by market and quality: arcade iOS titles around $0.99, desktop RPGs on Steam around $20. +- Success depends on game quality, market research, and marketing effectiveness. +- Study market trends and learn from failures quickly. + +### In-App Purchases (IAPs) + +**Model:** Free game acquisition with paid optional content and features. + +**Types of purchasable content:** + +- Bonus levels +- Better weapons or spells +- Energy refills +- In-game currency +- Premium features and virtual goods + +**Key metrics and considerations:** + +- Requires thousands of downloads to generate meaningful revenue. +- Only approximately 1 in 1,000 players typically makes a purchase. +- Earnings depend heavily on promotional activities and player volume. +- Player volume is the critical success factor. + +### Freemium + +**Model:** Free game with optional premium features and paid benefits. + +- Add value to the game rather than restricting core content behind a paywall. +- Avoid "pay-to-win" mechanics that players dislike and that damage retention and reputation. +- Do not paywall game progression. +- Focus on delivering enjoyable free experiences first, then offer premium enhancements. + +**Add-ons and DLCs:** + +- New level sets with new characters, weapons, and story content. +- Requires an established base game with proven popularity. +- Provides additional value for existing, engaged players. + +### Advertisements + +**Model:** Passive income through ad display with revenue sharing between developer and ad network. + +**Ad networks:** + +- **Google AdSense:** Most effective but not game-optimized. Can be risky for game-related accounts. +- **LeadBolt:** Game-focused alternative with easier implementation. +- **Video ads:** Pre-roll format shown during loading screens is gaining popularity. + +**Placement strategy:** + +- Show ads between game sessions or on game-over screens. +- Balance ad visibility with player experience. +- Keep ads subtle to avoid annoying players and hurting retention. +- Revenue is typically very modest for low-traffic games. + +**Revenue sharing:** Usually 70/30 or 50/50 splits with publishers. + +### Licensing + +**Model:** One-time payment for distribution rights. The publisher handles monetization. + +**Exclusive licenses:** + +- Sold to a single publisher only. +- Cannot be sold again in any form after the deal. +- Price range: $2,000 to $5,000 USD. +- Only pursue if the deal is profitable enough to justify exclusivity. Stop promoting the game after the sale. + +**Non-exclusive licenses:** + +- Can be sold to multiple publishers simultaneously. +- Publisher can only distribute on their own portal (site-locked). +- Price range: approximately $500 USD per publisher. +- Most popular licensing approach. Works well with multiple publishers continuously. + +**Subscription model:** + +- Monthly passive revenue per game. +- Price range: $20 to $50 USD per month per game. +- Flexible payment options: lump sum or monthly. +- Risk: can be cancelled at any time by the publisher. + +**Ad revenue share:** + +- Publisher drives traffic and earnings are split. +- Split: 70/30 or 50/50 deals, collected monthly. +- Warning: new or low-quality publishers may offer as little as $2 USD total. + +**Important licensing notes:** + +- Publishers may require custom API implementation (factor the development cost into your pricing). +- Better to accept a lower license fee from an established, reputable publisher than risk fraud with unknown buyers. +- Contact publishers through their websites or HTML5 Gamedevs forums. + +### Branding and Custom Work + +**Non-exclusive licensing with branding:** + +- Client buys code rights and implements their own graphics. +- Example: swapping game food items for client-branded products. + +**Freelance branding:** + +- Developer reuses existing game code and adds client-provided graphics. +- Client directs implementation details. +- Price varies greatly based on brand, client expectations, and scope of work. + +### Other Monetization Strategies + +**Selling digital assets:** + +- Sell game graphics and art assets on platforms like Envato Market and ThemeForest. +- Best for graphic designers who can create reusable assets. +- Provides passive, modest but consistent income. + +**Writing articles and tutorials:** + +- Publish game development articles on platforms like Tuts+ Game Development, which pay for content. +- Dual benefit: promotes your game while generating direct income. +- Focus on genuine knowledge-sharing with your games as practical examples. + +**Merchandise:** + +- T-shirts, stickers, and branded gadgets. +- Most profitable for highly popular, visually recognizable games (e.g., Angry Birds). +- Some developers earn more from merchandise than from the games themselves. +- Best as a diversified secondary revenue stream. + +**Community donations:** + +- Add donate buttons on game pages. +- Effectiveness depends on the strength of your community relationship. +- Works best when players know you personally and understand how donations help continued development. + +### Monetization Summary + +| Model | Revenue Type | Best For | Risk Level | +|-------|-------------|----------|------------| +| Paid Games | One-time | High-quality games with strong marketing | High | +| In-App Purchases | Per transaction | Popular games with high download volume | Medium | +| Advertisements | Passive/CPM | Casual, addictive games | Low-Medium | +| Non-Exclusive Licensing | One-time (~$500) | All game types | Low | +| Exclusive Licensing | One-time ($2K-$5K) | Proven, quality games | Medium | +| Subscriptions | Monthly passive | Games with established track records | Medium | +| Merchandise | Per sale | Popular franchises with visual identity | High | +| Articles/Tutorials | Per publication | Developers with niche expertise | Low | diff --git a/skills/game-engine/references/techniques.md b/skills/game-engine/references/techniques.md new file mode 100644 index 000000000..7536a691b --- /dev/null +++ b/skills/game-engine/references/techniques.md @@ -0,0 +1,894 @@ +# Game Development Techniques + +A comprehensive reference covering essential techniques for building web-based games, compiled from MDN Web Docs. + +--- + +## Async Scripts + +**Source:** [MDN - Async Scripts for asm.js](https://developer.mozilla.org/en-US/docs/Games/Techniques/Async_scripts) + +### What It Is + +Async compilation allows JavaScript engines to compile asm.js code off the main thread during game loading and cache the generated machine code. This prevents recompilation on subsequent loads and gives the browser maximum flexibility to optimize the compilation process. + +### How It Works + +When a script is loaded asynchronously, the browser can compile it on a background thread while the main thread continues handling rendering and user interaction. The compiled code is cached so future visits skip recompilation entirely. + +### When to Use It + +- Medium or large games that compile asm.js code. +- Any game where startup performance matters (which is virtually all games). +- When you want the browser to cache compiled machine code across sessions. + +### Code Examples + +**HTML attribute approach:** + +```html + +``` + +**JavaScript dynamic creation (defaults to async):** + +```javascript +const script = document.createElement("script"); +script.src = "file.js"; +document.body.appendChild(script); +``` + +**Important:** Inline scripts are never async, even with the `async` attribute. They compile and run immediately: + +```html + + +``` + +**Using Blob URLs for async compilation of string-based code:** + +```javascript +const blob = new Blob([codeString]); +const script = document.createElement("script"); +const url = URL.createObjectURL(blob); +script.onload = script.onerror = () => URL.revokeObjectURL(url); +script.src = url; +document.body.appendChild(script); +``` + +The key insight is that setting `src` (rather than `innerHTML` or `textContent`) triggers async compilation. + +--- + +## Optimizing Startup Performance + +**Source:** [MDN - Optimizing Startup Performance](https://developer.mozilla.org/en-US/docs/Web/Performance/Guides/Optimizing_startup_performance) + +### What It Is + +A collection of strategies for improving how quickly web applications and games start up and become responsive, preventing the app, browser, or device from appearing frozen to users. + +### How It Works + +The core principle is avoiding blocking the main thread during startup. Work is offloaded to background threads (Web Workers), startup code is broken into small micro-tasks, and the main thread is kept free for user events and rendering. The event loop must keep cycling continuously. + +### When to Use It + +- Always -- this is a universal concern for all web applications and games. +- Critical for new apps since it is easier to build asynchronously from the start. +- Essential when porting native apps that expect synchronous loading and need refactoring. + +### Key Techniques + +**1. Script Loading with `defer` and `async`** + +Prevent blocking HTML parsing: + +```html + + +``` + +**2. Web Workers for Heavy Processing** + +Move data fetching, decoding, and calculations to workers. This frees the main thread for UI and user events. + +**3. Data Processing** + +- Use browser-provided decoders (image, video) instead of custom implementations. +- Process data in parallel whenever possible, not sequentially. +- Offload asset decoding (e.g., JPEG to raw texture data) to workers. + +**4. Resource Loading** + +- Do not include scripts or stylesheets outside the critical rendering path in the startup HTML -- load them only when needed. +- Use resource hints: `preconnect`, `preload`. + +**5. Code Size and Compression** + +- Minify JavaScript files. +- Use Gzip or Brotli compression. +- Optimize and compress data files. + +**6. Perceived Performance** + +- Display splash screens to keep users engaged. +- Show progress indicators for heavy sites. +- Make time feel faster even if absolute duration stays the same. + +**7. Emscripten Main Loop Blockers (for ported apps)** + +```javascript +emscripten_push_main_loop_blocker(); +// Establish functions to execute before main thread continues +// Create queue of functions called in sequence +``` + +### Performance Targets + +| Metric | Target | +|---|---| +| Initial content appearance | 1-2 seconds | +| User-perceptible delay | 50ms or less | +| Sluggish threshold | Greater than 200ms | + +Users on older or slower devices experience longer delays than developers -- always optimize accordingly. + +--- + +## WebRTC Data Channels + +**Source:** [MDN - WebRTC Data Channels](https://developer.mozilla.org/en-US/docs/Games/Techniques/WebRTC_data_channels) + +### What It Is + +WebRTC data channels let you send text or binary data over an active connection to a peer. In the context of games, this enables players to send data to each other for text chat or game state synchronization, without routing through a central server. + +### How It Works + +WebRTC establishes a peer-to-peer connection between two browsers. Once established, a data channel can be opened on that connection. Data channels come in two flavors: + +**Reliable Channels:** +- Guarantee that messages arrive at the peer. +- Maintain message order -- messages arrive in the same sequence they were sent. +- Analogous to TCP sockets. + +**Unreliable Channels:** +- Make no guarantees about message delivery. +- Messages may not arrive in any particular order. +- Messages may not arrive at all. +- Analogous to UDP sockets. + +### When to Use It + +- **Reliable channels:** Turn-based games, chat, or any scenario where every message must arrive in order. +- **Unreliable channels:** Real-time action games where low latency matters more than guaranteed delivery (e.g., position updates where stale data is worse than missing data). + +### Use Cases in Games + +- Player-to-player text chat communication. +- Game status information exchange between players. +- Real-time game state synchronization. +- Peer-to-peer multiplayer without a dedicated game server. + +### Implementation Notes + +- The WebRTC API is primarily known for audio and video communication but includes robust peer-to-peer data channel capabilities. +- Libraries are recommended to simplify implementation and work around browser differences. +- Full WebRTC documentation is available at [MDN WebRTC API](https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API). + +--- + +## Audio for Web Games + +**Source:** [MDN - Audio for Web Games](https://developer.mozilla.org/en-US/docs/Games/Techniques/Audio_for_Web_Games) + +### What It Is + +Audio provides feedback and atmosphere in web games. This technique covers implementing audio across desktop and mobile platforms, addressing browser differences and optimization strategies. + +### How It Works + +Two primary APIs are available: + +1. **HTMLMediaElement** -- The standard `
Aaron Powell
Aaron Powell
🎭 πŸ’» 🎁 πŸ“– πŸš‡ 🧭 🚧 ⌨️		Aaron Powell
Aaron Powell
🎭 πŸ’» 🎁 πŸ“– πŸš‡ 🧭 🚧 ⌨️		 Matt Soucoup
Matt Soucoup
πŸš‡		Troy Simeon Taylor
Troy Simeon Taylor
🎭 🎁 🧭 ⌨️		Troy Simeon Taylor
Troy Simeon Taylor
🎭 🎁 🧭 ⌨️		 Abbas
Abbas
🎭 🧭		Peter Strâmberg
Peter StrΓΆmberg
🎭 🎁 🧭 ⌨️		Daniel Scott-Raynsford
Daniel Scott-Raynsford
🎭 🎁 🧭 ⌨️		Peter Strâmberg
Peter StrΓΆmberg
🎭 🎁 🧭 ⌨️		Daniel Scott-Raynsford
Daniel Scott-Raynsford
🎭 🎁 🧭 ⌨️		 John Haugabook
John Haugabook
🧭 ⌨️
Harald Kirschner
Harald Kirschner
πŸ’» πŸ“– 🚧		 Muhammad Ubaid Raza
Muhammad Ubaid Raza
🎭 🧭		 Tom Meschter
Tom Meschter
πŸ’»		Aung Myo Kyaw
Aung Myo Kyaw
🎭 ⌨️		Aung Myo Kyaw
Aung Myo Kyaw
🎭		 JasonYeMSFT
JasonYeMSFT
πŸ’»		Jon Corbin
Jon Corbin
🎭 ⌨️		Jon Corbin
Jon Corbin
🎭
troytaylor-msft
troytaylor-msft
πŸ’»		 Emerson Delatorre
Emerson Delatorre
🧭		Burke Holland
Burke Holland
🎭 πŸš‡ 🧭 ⌨️		Kent Yao
Kent Yao
🧭 ⌨️		Daniel Meppiel
Daniel Meppiel
⌨️		Burke Holland
Burke Holland
🎭 πŸš‡ 🧭		Kent Yao
Kent Yao
🧭		Daniel Meppiel
Daniel Meppiel
 Gordon Lam
Gordon Lam
🧭		 Mads Kristensen
Mads Kristensen
🧭
Shinji Takenaka
Shinji Takenaka
πŸ’»		 spectatora
spectatora
🎭 πŸ’» 🚧		Yohan Lasorsa
Yohan Lasorsa
🧭 ⌨️		Vamshi Verma
Vamshi Verma
🧭 ⌨️		James Montemagno
James Montemagno
🎭 πŸ“– 🧭 ⌨️		Yohan Lasorsa
Yohan Lasorsa
🧭		Vamshi Verma
Vamshi Verma
🧭		James Montemagno
James Montemagno
🎭 πŸ“– 🧭		 Alessandro Fragnani
Alessandro Fragnani
πŸ’»		 Ambily
Ambily
🎭 🧭
krushideep
krushideep
⌨️		krushideep
krushideep
 devopsfan
devopsfan
🎭		Tugdual Grall
Tugdual Grall
🧭 ⌨️		Tugdual Grall
Tugdual Grall
🧭		 Oren Me
Oren Me
🎭 🧭		Mike Rousos
Mike Rousos
🧭 ⌨️		Mike Rousos
Mike Rousos
🧭		 Justin Yoo
Justin Yoo
🧭		 Guilherme do Amaral Alves
Guilherme do Amaral Alves
🧭
Griffin Ashe
Griffin Ashe
🎭 🎁		Griffin Ashe
Griffin Ashe
🎭 🎁		 Ashley Childress
Ashley Childress
🎭 πŸ“– 🧭 πŸš‡ πŸ’»		Adrien Clerbois
Adrien Clerbois
🎭 πŸ“– ⌨️		Adrien Clerbois
Adrien Clerbois
🎭 πŸ“–		 ANGELELLI David
ANGELELLI David
🎭		 Mark Davis
Mark Davis
🧭		 Matt Vevang
Matt Vevang
🧭
NULLchimp
NULLchimp
🎭		Peter Karda
Peter Karda
⌨️		Saul Dolgin
Saul Dolgin
🎭 🧭 ⌨️		Shubham Gaikwad
Shubham Gaikwad
🎭 🧭 ⌨️		Peter Karda
Peter Karda
Saul Dolgin
Saul Dolgin
🎭 🧭		Shubham Gaikwad
Shubham Gaikwad
🎭 🧭		 Theo van Kraay
Theo van Kraay
🧭		 Tianqi Zhang
Tianqi Zhang
🎭		Will 保ε“₯
Will 保ε“₯
🎭 ⌨️		Will 保ε“₯
Will 保ε“₯
🎭
Yuta Matsumura
Yuta Matsumura
🧭		 anschnapp
anschnapp
🎭		 hizahizi-hizumi
hizahizi-hizumi
🧭		 黃ε₯ζ—» Vincent Huang
黃ε₯ζ—» Vincent Huang
⌨️		Bruno Borges
Bruno Borges
🎁 🧭		Bruno Borges
Bruno Borges
🎁 🧭		 Steve Magne
Steve Magne
πŸ“– 🧭		 Shane Neuville
Shane Neuville
🎭 🧭
Dan Wahlin
Dan Wahlin
🎭		Debbie O'Brien
Debbie O'Brien
🎭 🧭 ⌨️		Ed Harrod
Ed Harrod
⌨️		Genevieve Warren
Genevieve Warren
⌨️		Guillaume
Guillaume
🎭 ⌨️		Henrique Nunes
Henrique Nunes
⌨️		Debbie O'Brien
Debbie O'Brien
🎭 🧭		Ed Harrod
Ed Harrod
Genevieve Warren
Genevieve Warren
Guillaume
Guillaume
🎭		Henrique Nunes
Henrique Nunes
 Jeremiah Snee
Jeremiah Snee
πŸ’»
Salih
Salih
🧭		 Sebastian GrÀf
Sebastian GrΓ€f
🎭 🧭		 Sebastien DEGODEZ
Sebastien DEGODEZ
🧭		Sergiy Smyrnov
Sergiy Smyrnov
⌨️		Sergiy Smyrnov
Sergiy Smyrnov
 SomeSolutionsArchitect
SomeSolutionsArchitect
🎭
Stu Mace
Stu Mace
🎭 🎁 🧭		Stu Mace
Stu Mace
🎭 🎁 🧭		 Søren Trudsø Mahon
SΓΈren TrudsΓΈ Mahon
🧭		 Tj Vita
Tj Vita
🎭		 Peli de Halleux
Peli de Halleux
πŸ’»		Paulo Morgado
Paulo Morgado
⌨️		Paulo Morgado
Paulo Morgado
 Paul Crane
Paul Crane
🎭		Pamela Fox
Pamela Fox
⌨️		Pamela Fox
Pamela Fox
Oskar Thornblad
Oskar Thornblad
🧭		 Nischay Sharma
Nischay Sharma
🎭		 Nikolay Marinov
Nikolay Marinov
🎭		Nik Sachdeva
Nik Sachdeva
🎭 🎁		Nik Sachdeva
Nik Sachdeva
🎭 🎁		 Nick Taylor
Nick Taylor
πŸ’»		 Nick Brady
Nick Brady
🎭		 Nathan Stanford Sr
Nathan Stanford Sr
🧭
MΓ‘tΓ© BarabΓ‘s
MΓ‘tΓ© BarabΓ‘s
🧭		 Mike Parker
Mike Parker
🧭		Mike Kistler
Mike Kistler
⌨️		Mike Kistler
Mike Kistler
 Giovanni de Almeida Martins
Giovanni de Almeida Martins
🧭		 μ΄μƒν˜„
μ΄μƒν˜„
🧭		Ankur Sharma
Ankur Sharma
⌨️		Ankur Sharma
Ankur Sharma
 Wendy Breiding
Wendy Breiding
πŸ’»
shane lee
shane lee
🧭		 sdanzo-hrb
sdanzo-hrb
🎭		 sauran
sauran
🧭		samqbush
samqbush
⌨️		samqbush
samqbush
 pareenaverma
pareenaverma
🎭		oleksiyyurchyna
oleksiyyurchyna
🎁 ⌨️		oleksiyyurchyna
oleksiyyurchyna
🎁 ⌨️
oceans-of-time
oceans-of-time
🧭		factory-davidgu
factory-davidgu
πŸ’»		 dangelov-qa
dangelov-qa
🎭		 BenoitMaucotel
BenoitMaucotel
πŸ’»		benjisho-aidome
benjisho-aidome
🎭 🧭 ⌨️		benjisho-aidome
benjisho-aidome
🎭 🧭
Yuki Omoto
Yuki Omoto
🧭
Udaya Veeramreddygari
Udaya Veeramreddygari
🧭		TΓ i LΓͺ
TΓ i LΓͺ
⌨️		TΓ i LΓͺ
TΓ i LΓͺ
 Tsubasa Ogawa
Tsubasa Ogawa
πŸ’»		 Troy Witthoeft (glsauto)
Troy Witthoeft (glsauto)
🧭		 Gerald Versluis
Gerald Versluis
🧭		George Dernikos
George Dernikos
⌨️		George Dernikos
George Dernikos
 Gautam
Gautam
🎭
Furkan Enes
Furkan Enes
🧭		 Florian Mücke
Florian MΓΌcke
🎭		 Felix Arjuna
Felix Arjuna
🧭		Eldrick Wega
Eldrick Wega
⌨️		Dobri Danchev
Dobri Danchev
⌨️		Diego Gamboa
Diego Gamboa
⌨️		Derek Clair
Derek Clair
🎭 ⌨️		Eldrick Wega
Eldrick Wega
Dobri Danchev
Dobri Danchev
Diego Gamboa
Diego Gamboa
Derek Clair
Derek Clair
🎭
David Ortinau
David Ortinau
πŸ’»		 Daniel Abbatt
Daniel Abbatt
🧭		CypherHK
CypherHK
🎭 ⌨️		CypherHK
CypherHK
🎭		 Craig Bekker
Craig Bekker
πŸ’»		 Christophe Peugnet
Christophe Peugnet
🧭		 Christian Lechner
Christian Lechner
🧭
Artem Saveliev
Artem Saveliev
🧭		Antoine Rey
Antoine Rey
⌨️		Antoine Rey
Antoine Rey
 Ankit Das
Ankit Das
🧭		 Aline Ávila
Aline Ávila
🧭		 Alexander Martinkevich
Alexander Martinkevich
🎭		4regab
4regab
🧭		 Miguel P Z
Miguel P Z
πŸ“–		 Michael Fairchild
Michael Fairchild
🧭		Michael A. Volz (Flynn)
Michael A. Volz (Flynn)
⌨️		Michael A. Volz (Flynn)
Michael A. Volz (Flynn)
Michael
Michael
🧭		Kenny White
Kenny White
🧭		 KaloyanGenev
KaloyanGenev
🎭		 Kim Skov Rasmussen
Kim Skov Rasmussen
πŸ’»		Julien Dubois
Julien Dubois
⌨️		Julien Dubois
Julien Dubois
 JosΓ© Antonio Garrido
JosΓ© Antonio Garrido
🧭
Joseph Gonzales
Joseph Gonzales
🧭 ⌨️		Joseph Gonzales
Joseph Gonzales
🧭		 Jorge Balderas
Jorge Balderas
🧭		 John Papa
John Papa
πŸ’»		 John
John
🎭		 Joe Watkins
Joe Watkins
🧭		 Jan de Vries
Jan de Vries
🎭		Jakub Jareő
Jakub JareΕ‘
⌨️		Jakub Jareő
Jakub JareΕ‘
Jackson Miller
Jackson Miller
🧭		 Ioana A
Ioana A
🧭		 Hunter Hogan
Hunter Hogan
🎭		 Hashim Warren
Hashim Warren
🎭		Gonzalo
Gonzalo
⌨️		Gonzalo
Gonzalo
 Gisela Torres
Gisela Torres
🎭		 Shibi Ramachandran
Shibi Ramachandran
πŸ’»
lupritz
lupritz
πŸ”Œ		HΓ©ctor Benedicte
HΓ©ctor Benedicte
πŸ’»