diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 5f99cf4c..603c306b 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,10 +1,10 @@ ## Pull Request Checklist - [ ] I have read and followed the [CONTRIBUTING.md](https://github.com/github/awesome-copilot/blob/main/CONTRIBUTING.md) guidelines. -- [ ] My contribution adds a new instruction, prompt, agent, or skill file in the correct directory. +- [ ] My contribution adds a new instruction, prompt, agent, skill, or workflow file in the correct directory. - [ ] The file follows the required naming convention. - [ ] The content is clearly structured and follows the example format. -- [ ] I have tested my instructions, prompt, agent, or skill with GitHub Copilot. +- [ ] I have tested my instructions, prompt, agent, skill, or workflow with GitHub Copilot. - [ ] I have run `npm start` and verified that `README.md` is up to date. --- @@ -22,7 +22,8 @@ - [ ] New agent file. - [ ] New plugin. - [ ] New skill file. -- [ ] Update to existing instruction, prompt, agent, plugin, or skill. +- [ ] New agentic workflow. +- [ ] Update to existing instruction, prompt, agent, plugin, skill, or workflow. - [ ] Other (please specify): --- diff --git a/.github/workflows/validate-agentic-workflows-pr.yml b/.github/workflows/validate-agentic-workflows-pr.yml new file mode 100644 index 00000000..5f5ff281 --- /dev/null +++ b/.github/workflows/validate-agentic-workflows-pr.yml @@ -0,0 +1,125 @@ +name: Validate Agentic Workflow Contributions + +on: + pull_request: + branches: [staged] + types: [opened, synchronize, reopened] + paths: + - "workflows/**" + +permissions: + contents: read + pull-requests: write + +jobs: + check-forbidden-files: + name: Block forbidden files + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Check for forbidden files + id: check + run: | + # Check for YAML/lock files in workflows/ and any .github/ modifications + forbidden=$(git diff --name-only --diff-filter=ACM origin/${{ github.base_ref }}...HEAD -- \ + 'workflows/**/*.yml' \ + 'workflows/**/*.yaml' \ + 'workflows/**/*.lock.yml' \ + '.github/*' \ + '.github/**') + + if [ -n "$forbidden" ]; then + echo "❌ Forbidden files detected:" + echo "$forbidden" + echo "files<> "$GITHUB_OUTPUT" + echo "$forbidden" >> "$GITHUB_OUTPUT" + echo "EOF" >> "$GITHUB_OUTPUT" + exit 1 + else + echo "βœ… No forbidden files found" + fi + + - name: Comment on PR + if: failure() + uses: marocchino/sticky-pull-request-comment@v2 + with: + header: workflow-forbidden-files + message: | + ## 🚫 Forbidden files in `workflows/` + + Only `.md` markdown files are accepted in the `workflows/` directory. The following are **not allowed**: + - Compiled workflow files (`.yml`, `.yaml`, `.lock.yml`) β€” could contain untrusted Actions code + - `.github/` modifications β€” workflow contributions must not modify repository configuration + + **Files that must be removed:** + ``` + ${{ steps.check.outputs.files }} + ``` + + Contributors provide the workflow **source** (`.md`) only. Compilation happens downstream via `gh aw compile`. + + Please remove these files and push again. + + compile-workflows: + name: Compile and validate + needs: check-forbidden-files + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Install gh-aw CLI + uses: github/gh-aw/actions/setup-cli@main + + - name: Compile workflow files + id: compile + run: | + exit_code=0 + found=0 + + # Find all .md files directly in workflows/ + for workflow_file in workflows/*.md; do + [ -f "$workflow_file" ] || continue + + found=$((found + 1)) + echo "::group::Compiling $workflow_file" + if gh aw compile --validate "$workflow_file"; then + echo "βœ… $workflow_file compiled successfully" + else + echo "❌ $workflow_file failed to compile" + exit_code=1 + fi + echo "::endgroup::" + done + + if [ "$found" -eq 0 ]; then + echo "No workflow .md files found to validate." + else + echo "Validated $found workflow file(s)." + fi + + echo "status=$( [ $exit_code -eq 0 ] && echo success || echo failure )" >> "$GITHUB_OUTPUT" + exit $exit_code + + - name: Comment on PR if compilation failed + if: failure() + uses: marocchino/sticky-pull-request-comment@v2 + with: + header: workflow-validation + message: | + ## ❌ Agentic Workflow compilation failed + + One or more workflow files in `workflows/` failed to compile with `gh aw compile --validate`. + + Please fix the errors and push again. You can test locally with: + + ```bash + gh extension install github/gh-aw + gh aw compile --validate .md + ``` + + See the [Agentic Workflows documentation](https://github.github.com/gh-aw) for help. diff --git a/.github/workflows/validate-readme.yml b/.github/workflows/validate-readme.yml index 6df185e3..e9ae9dfe 100644 --- a/.github/workflows/validate-readme.yml +++ b/.github/workflows/validate-readme.yml @@ -9,6 +9,7 @@ on: - "prompts/**" - "agents/**" - "plugins/**" + - "workflows/**" - "*.js" - "README.md" - "docs/**" diff --git a/AGENTS.md b/AGENTS.md index b2dbd6fd..6bda5203 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,6 +9,7 @@ The Awesome GitHub Copilot repository is a community-driven collection of custom - **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 +- **Workflows** - [Agentic Workflows](https://github.github.com/gh-aw) for AI-powered repository automation in GitHub Actions - **Plugins** - Installable packages that group related agents, commands, and skills around specific themes ## Repository Structure @@ -20,6 +21,7 @@ The Awesome GitHub Copilot repository is a community-driven collection of custom β”œβ”€β”€ 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) +β”œβ”€β”€ workflows/ # Agentic Workflows (.md files for GitHub Actions automation) β”œβ”€β”€ plugins/ # Installable plugin packages (folders with plugin.json) β”œβ”€β”€ docs/ # Documentation for different resource types β”œβ”€β”€ eng/ # Build and automation scripts @@ -96,6 +98,17 @@ All agent files (`*.agent.md`), prompt files (`*.prompt.md`), and instruction fi - Follow the [GitHub Copilot hooks specification](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/use-hooks) - Optionally includes `tags` field for categorization +#### Workflow Files (workflows/*.md) +- 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) + #### Plugin Folders (plugins/*) - Each plugin is a folder containing a `.github/plugin/plugin.json` file with metadata - plugin.json must have `name` field (matching the folder name) @@ -107,7 +120,7 @@ All agent files (`*.agent.md`), prompt files (`*.prompt.md`), and instruction fi ### Adding New Resources -When adding a new agent, prompt, instruction, skill, hook, or plugin: +When adding a new agent, prompt, instruction, skill, hook, workflow, or plugin: **For Agents, Prompts, and Instructions:** 1. Create the file with proper front matter @@ -125,6 +138,14 @@ When adding a new agent, prompt, instruction, skill, hook, or plugin: 7. Verify the hook appears in the generated README +**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`) +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 + + **For Skills:** 1. Run `npm run skill:create` to scaffold a new skill folder 2. Edit the generated SKILL.md file with your instructions @@ -241,6 +262,18 @@ For hook folders (hooks/*/): - [ ] Follows [GitHub Copilot hooks specification](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/use-hooks) - [ ] Optionally includes `tags` array field for categorization +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 + For plugins (plugins/*/): - [ ] Directory contains a `.github/plugin/plugin.json` file - [ ] Directory contains a `README.md` file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index da0d4e91..63e7630c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -161,11 +161,61 @@ 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 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 + +> **Note:** Only `.md` files are accepted β€” do not include compiled `.lock.yml` or `.yml` files. CI will block them. + +#### Workflow file example + +```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'] +on: + schedule: daily on weekdays +permissions: + contents: read + issues: read +safe-outputs: + create-issue: + title-prefix: "[daily-report] " + labels: [report] +--- + +## Daily Issues Report + +Create a daily summary of open issues for the team. + +## What to Include + +- New issues opened in the last 24 hours +- Issues closed or resolved +- Stale issues that need attention +``` + +#### Workflow Guidelines + +- **Security first**: Use least-privilege permissions and safe outputs instead of direct write access +- **Clear instructions**: Write clear natural language instructions in the workflow body +- **Descriptive names**: Use lowercase filenames with hyphens (e.g., `daily-issues-report.md`) +- **Test locally**: Use `gh aw compile --validate` to verify your workflow compiles +- **No compiled files**: Only submit the `.md` source β€” `.lock.yml` and `.yml` files are not accepted +- Learn more at the [Agentic Workflows documentation](https://github.github.com/gh-aw) + ## Submitting Your Contribution 1. **Fork this repository** 2. **Create a new branch** for your contribution -3. **Add your instruction, prompt file, chatmode, or plugin** following the guidelines above +3. **Add your instruction, prompt file, chatmode, 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 @@ -234,6 +284,7 @@ We welcome many kinds of contributions, including the custom categories below: | **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 | ⚑ | | **Plugins** | Installable packages of related prompts, agents, or skills | 🎁 | In addition, all standard contribution types supported by [All Contributors](https://allcontributors.org/emoji-key/) are recognized. diff --git a/README.md b/README.md index 5dd398d3..81544b7a 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,7 @@ This repository provides a comprehensive toolkit for enhancing GitHub Copilot wi - **πŸ‘‰ [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 Cookbook Recipes](cookbook/README.md)** - Practical, copy-paste-ready code snippets and real-world examples for working with GitHub Copilot tools and features @@ -101,6 +102,10 @@ Instructions automatically apply to files based on their patterns and provide co Hooks enable automated workflows triggered by specific events during GitHub Copilot coding agent sessions (like sessionStart, sessionEnd, userPromptSubmitted). They can automate tasks like logging, auto-committing changes, or integrating with external services. +### ⚑ 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 event-triggered and scheduled automation β€” from issue triage to daily reports. + ## 🎯 Why Use Awesome GitHub Copilot? - **Productivity**: Pre-built agents, prompts and instructions save time and provide consistent results. @@ -112,7 +117,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, agents, or skills +- Add new prompts, instructions, hooks, workflows, agents, or skills - Improve existing content - Report issues or suggest enhancements @@ -131,6 +136,8 @@ For AI coding agents working with this project, refer to [AGENTS.md](AGENTS.md) β”œβ”€β”€ 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 +β”œβ”€β”€ workflows/ # Agentic Workflows for GitHub Actions automation β”œβ”€β”€ plugins/ # Installable plugins bundling related items β”œβ”€β”€ scripts/ # Utility scripts for maintenance └── skills/ # AI capabilities for specialized tasks @@ -152,7 +159,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), and [custom agents](docs/README.agents.md)! +**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)! ## Contributors ✨ diff --git a/docs/README.instructions.md b/docs/README.instructions.md index 73250e54..bf20e67b 100644 --- a/docs/README.instructions.md +++ b/docs/README.instructions.md @@ -54,9 +54,11 @@ Team and project-specific instructions to enhance GitHub Copilot's behavior for | [Comprehensive Guide: Converting Spring Boot Cassandra Applications to use Azure Cosmos DB with Spring Data Cosmos (spring-data-cosmos)](../instructions/convert-cassandra-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-cassandra-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-cassandra-to-spring-data-cosmos.instructions.md) | Step-by-step guide for converting Spring Boot Cassandra applications to use Azure Cosmos DB with Spring Data Cosmos | | [Containerization & Docker Best Practices](../instructions/containerization-docker-best-practices.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%2Fcontainerization-docker-best-practices.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%2Fcontainerization-docker-best-practices.instructions.md) | Comprehensive best practices for creating optimized, secure, and efficient Docker images and managing containers. Covers multi-stage builds, image layer optimization, security scanning, and runtime best practices. | | [Context Engineering](../instructions/context-engineering.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%2Fcontext-engineering.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%2Fcontext-engineering.instructions.md) | Guidelines for structuring code and projects to maximize GitHub Copilot effectiveness through better context management | +| [Context7-aware development](../instructions/context7.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%2Fcontext7.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%2Fcontext7.instructions.md) | Use Context7 for authoritative external docs and API references when local context is insufficient | | [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 | | [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. | @@ -113,6 +115,7 @@ Team and project-specific instructions to enhance GitHub Copilot's behavior for | [Makefile Development Instructions](../instructions/makefile.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%2Fmakefile.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%2Fmakefile.instructions.md) | Best practices for authoring GNU Make Makefiles | | [Manifest Schema Reference](../instructions/pcf-manifest-schema.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%2Fpcf-manifest-schema.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%2Fpcf-manifest-schema.instructions.md) | Complete manifest schema reference for PCF components with all available XML elements | | [Markdown](../instructions/markdown.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%2Fmarkdown.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%2Fmarkdown.instructions.md) | Documentation and content creation standards | +| [Markdown Accessibility Review Guidelines](../instructions/markdown-accessibility.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%2Fmarkdown-accessibility.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%2Fmarkdown-accessibility.instructions.md) | Markdown accessibility guidelines based on GitHub's 5 best practices for inclusive documentation | | [MCP-based M365 Copilot Development Guidelines](../instructions/mcp-m365-copilot.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%2Fmcp-m365-copilot.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%2Fmcp-m365-copilot.instructions.md) | Best practices for building MCP-based declarative agents and API plugins for Microsoft 365 Copilot with Model Context Protocol integration | | [Memory Bank](../instructions/memory-bank.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%2Fmemory-bank.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%2Fmemory-bank.instructions.md) | Bank specific coding standards and best practices | | [Microsoft 365 Declarative Agents Development Guidelines](../instructions/declarative-agents-microsoft365.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%2Fdeclarative-agents-microsoft365.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%2Fdeclarative-agents-microsoft365.instructions.md) | Comprehensive development guidelines for Microsoft 365 Copilot declarative agents with schema v1.5, TypeSpec integration, and Microsoft 365 Agents Toolkit workflows | @@ -144,6 +147,7 @@ Team and project-specific instructions to enhance GitHub Copilot's behavior for | [Power Platform MCP Custom Connector Development](../instructions/power-platform-mcp-development.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%2Fpower-platform-mcp-development.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%2Fpower-platform-mcp-development.instructions.md) | Instructions for developing Power Platform custom connectors with Model Context Protocol (MCP) integration for Microsoft Copilot Studio | | [PowerShell Cmdlet Development Guidelines](../instructions/powershell.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%2Fpowershell.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%2Fpowershell.instructions.md) | PowerShell cmdlet and scripting best practices based on Microsoft guidelines | | [PowerShell Pester v5 Testing Guidelines](../instructions/powershell-pester-5.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%2Fpowershell-pester-5.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%2Fpowershell-pester-5.instructions.md) | PowerShell Pester testing best practices based on Pester v5 conventions | +| [Project Context](../instructions/moodle.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%2Fmoodle.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%2Fmoodle.instructions.md) | Instructions for GitHub Copilot to generate code in a Moodle project context. | | [Python Coding Conventions](../instructions/python.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%2Fpython.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%2Fpython.instructions.md) | Python coding conventions and guidelines | | [Python MCP Server Development](../instructions/python-mcp-server.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%2Fpython-mcp-server.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%2Fpython-mcp-server.instructions.md) | Instructions for building Model Context Protocol (MCP) servers using the Python SDK | | [Quarkus](../instructions/quarkus.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%2Fquarkus.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%2Fquarkus.instructions.md) | Quarkus development standards and instructions | diff --git a/docs/README.prompts.md b/docs/README.prompts.md index c618c44c..190fd5e7 100644 --- a/docs/README.prompts.md +++ b/docs/README.prompts.md @@ -31,6 +31,7 @@ Ready-to-use prompt templates for specific development scenarios and tasks, defi | [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. | diff --git a/docs/README.skills.md b/docs/README.skills.md index 00f19db5..c7ddb111 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -36,6 +36,7 @@ Skills differ from other primitives by supporting bundled assets (scripts, code | [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` | | [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` | +| [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` | | [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` | diff --git a/docs/README.workflows.md b/docs/README.workflows.md new file mode 100644 index 00000000..93bdfdca --- /dev/null +++ b/docs/README.workflows.md @@ -0,0 +1,31 @@ +# ⚑ 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 event-triggered and scheduled automation with built-in guardrails and security-first design. + +### How to Use Agentic Workflows + +**What's Included:** +- Each workflow is a single `.md` file with YAML frontmatter and natural language instructions +- Workflows are compiled to `.lock.yml` GitHub Actions files via `gh aw compile` +- Workflows follow the [GitHub Agentic Workflows specification](https://github.github.com/gh-aw) + +**To Install:** +- Install the `gh aw` CLI extension: `gh extension install github/gh-aw` +- Copy the workflow `.md` file to your repository's `.github/workflows/` directory +- Compile with `gh aw compile` to generate the `.lock.yml` file +- Commit both the `.md` and `.lock.yml` files + +**To Activate/Use:** +- Workflows run automatically based on their configured triggers (schedules, events, slash commands) +- Use `gh aw run ` to trigger a manual run +- Monitor runs with `gh aw status` and `gh aw logs` + +**When to Use:** +- Automate issue triage and labeling +- Generate daily status reports +- Maintain documentation automatically +- Run scheduled code quality checks +- Respond to slash commands in issues and PRs +- Orchestrate multi-step repository automation + +_No entries found yet._ \ No newline at end of file diff --git a/eng/clean-materialized-plugins.mjs b/eng/clean-materialized-plugins.mjs new file mode 100644 index 00000000..a3545524 --- /dev/null +++ b/eng/clean-materialized-plugins.mjs @@ -0,0 +1,62 @@ +#!/usr/bin/env node + +import fs from "fs"; +import path from "path"; +import { ROOT_FOLDER } from "./constants.mjs"; + +const PLUGINS_DIR = path.join(ROOT_FOLDER, "plugins"); +const MATERIALIZED_DIRS = ["agents", "commands", "skills"]; + +function cleanPlugin(pluginPath) { + let removed = 0; + for (const subdir of MATERIALIZED_DIRS) { + const target = path.join(pluginPath, subdir); + if (fs.existsSync(target) && fs.statSync(target).isDirectory()) { + const count = countFiles(target); + fs.rmSync(target, { recursive: true, force: true }); + removed += count; + console.log(` Removed ${path.basename(pluginPath)}/${subdir}/ (${count} files)`); + } + } + return removed; +} + +function countFiles(dir) { + let count = 0; + for (const entry of fs.readdirSync(dir, { withFileTypes: true })) { + if (entry.isDirectory()) { + count += countFiles(path.join(dir, entry.name)); + } else { + count++; + } + } + return count; +} + +function main() { + console.log("Cleaning materialized files from plugins...\n"); + + if (!fs.existsSync(PLUGINS_DIR)) { + console.error(`Error: plugins directory not found at ${PLUGINS_DIR}`); + process.exit(1); + } + + const pluginDirs = fs.readdirSync(PLUGINS_DIR, { withFileTypes: true }) + .filter(entry => entry.isDirectory()) + .map(entry => entry.name) + .sort(); + + let total = 0; + for (const dirName of pluginDirs) { + total += cleanPlugin(path.join(PLUGINS_DIR, dirName)); + } + + console.log(); + if (total === 0) { + console.log("βœ… No materialized files found. Plugins are already clean."); + } else { + console.log(`βœ… Removed ${total} materialized file(s) from plugins.`); + } +} + +main(); diff --git a/eng/constants.mjs b/eng/constants.mjs index 1f1e95ec..6736c243 100644 --- a/eng/constants.mjs +++ b/eng/constants.mjs @@ -127,6 +127,36 @@ Hooks enable automated workflows triggered by specific events during GitHub Copi - Track usage analytics - Integrate with external tools and services - Custom session workflows`, + + workflowsSection: `## ⚑ 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 event-triggered and scheduled automation with built-in guardrails and security-first design.`, + + workflowsUsage: `### How to Use Agentic Workflows + +**What's Included:** +- Each workflow is a single \`.md\` file with YAML frontmatter and natural language instructions +- Workflows are compiled to \`.lock.yml\` GitHub Actions files via \`gh aw compile\` +- Workflows follow the [GitHub Agentic Workflows specification](https://github.github.com/gh-aw) + +**To Install:** +- Install the \`gh aw\` CLI extension: \`gh extension install github/gh-aw\` +- Copy the workflow \`.md\` file to your repository's \`.github/workflows/\` directory +- Compile with \`gh aw compile\` to generate the \`.lock.yml\` file +- Commit both the \`.md\` and \`.lock.yml\` files + +**To Activate/Use:** +- Workflows run automatically based on their configured triggers (schedules, events, slash commands) +- Use \`gh aw run \` to trigger a manual run +- Monitor runs with \`gh aw status\` and \`gh aw logs\` + +**When to Use:** +- Automate issue triage and labeling +- Generate daily status reports +- Maintain documentation automatically +- Run scheduled code quality checks +- Respond to slash commands in issues and PRs +- Orchestrate multi-step repository automation`, }; const vscodeInstallImage = @@ -152,6 +182,7 @@ const AGENTS_DIR = path.join(ROOT_FOLDER, "agents"); const SKILLS_DIR = path.join(ROOT_FOLDER, "skills"); const HOOKS_DIR = path.join(ROOT_FOLDER, "hooks"); const PLUGINS_DIR = path.join(ROOT_FOLDER, "plugins"); +const WORKFLOWS_DIR = path.join(ROOT_FOLDER, "workflows"); const COOKBOOK_DIR = path.join(ROOT_FOLDER, "cookbook"); const MAX_PLUGIN_ITEMS = 50; @@ -182,6 +213,7 @@ export { SKILLS_DIR, TEMPLATES, vscodeInsidersInstallImage, - vscodeInstallImage + vscodeInstallImage, + WORKFLOWS_DIR }; diff --git a/eng/generate-website-data.mjs b/eng/generate-website-data.mjs index 5ac93e31..9eb3da00 100644 --- a/eng/generate-website-data.mjs +++ b/eng/generate-website-data.mjs @@ -17,13 +17,15 @@ import { PLUGINS_DIR, PROMPTS_DIR, ROOT_FOLDER, - SKILLS_DIR + SKILLS_DIR, + WORKFLOWS_DIR } from "./constants.mjs"; import { getGitFileDates } from "./utils/git-dates.mjs"; import { parseFrontmatter, parseSkillMetadata, parseHookMetadata, + parseWorkflowMetadata, parseYamlFile, } from "./yaml-parser.mjs"; @@ -192,6 +194,64 @@ function generateHooksData(gitDates) { }; } +/** + * Generate workflows metadata (flat .md files) + */ +function generateWorkflowsData(gitDates) { + const workflows = []; + + if (!fs.existsSync(WORKFLOWS_DIR)) { + return { + items: workflows, + filters: { + triggers: [], + tags: [], + }, + }; + } + + const workflowFiles = fs.readdirSync(WORKFLOWS_DIR).filter((file) => { + return file.endsWith(".md") && file !== ".gitkeep"; + }); + + const allTriggers = new Set(); + const allTags = new Set(); + + for (const file of workflowFiles) { + const filePath = path.join(WORKFLOWS_DIR, file); + const metadata = parseWorkflowMetadata(filePath); + if (!metadata) continue; + + const relativePath = path + .relative(ROOT_FOLDER, filePath) + .replace(/\\/g, "/"); + + (metadata.triggers || []).forEach((t) => allTriggers.add(t)); + (metadata.tags || []).forEach((t) => allTags.add(t)); + + const id = path.basename(file, ".md"); + workflows.push({ + id, + 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)); + + return { + items: sortedWorkflows, + filters: { + triggers: Array.from(allTriggers).sort(), + tags: Array.from(allTags).sort(), + }, + }; +} + /** * Generate prompts metadata */ @@ -606,6 +666,7 @@ function generateSearchIndex( prompts, instructions, hooks, + workflows, skills, plugins ) { @@ -665,6 +726,20 @@ function generateSearchIndex( }); } + for (const workflow of workflows) { + index.push({ + type: "workflow", + id: workflow.id, + title: workflow.title, + description: workflow.description, + path: workflow.path, + lastUpdated: workflow.lastUpdated, + searchText: `${workflow.title} ${workflow.description} ${workflow.triggers.join( + " " + )} ${workflow.tags.join(" ")}`.toLowerCase(), + }); + } + for (const skill of skills) { index.push({ type: "skill", @@ -799,7 +874,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/", "skills/", "plugins/"], + ["agents/", "prompts/", "instructions/", "hooks/", "workflows/", "skills/", "plugins/"], ROOT_FOLDER ); console.log(`βœ“ Loaded dates for ${gitDates.size} files\n`); @@ -817,6 +892,12 @@ async function main() { `βœ“ Generated ${hooks.length} hooks (${hooksData.filters.hooks.length} hook types, ${hooksData.filters.tags.length} tags)` ); + 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( @@ -857,6 +938,7 @@ async function main() { prompts, instructions, hooks, + workflows, skills, plugins ); @@ -873,6 +955,11 @@ async function main() { JSON.stringify(hooksData, null, 2) ); + fs.writeFileSync( + path.join(WEBSITE_DATA_DIR, "workflows.json"), + JSON.stringify(workflowsData, null, 2) + ); + fs.writeFileSync( path.join(WEBSITE_DATA_DIR, "prompts.json"), JSON.stringify(promptsData, null, 2) @@ -917,6 +1004,7 @@ async function main() { instructions: instructions.length, skills: skills.length, hooks: hooks.length, + workflows: workflows.length, plugins: plugins.length, tools: tools.length, samples: samplesData.totalRecipes, diff --git a/eng/update-readme.mjs b/eng/update-readme.mjs index f14a0bc0..3456d5c6 100644 --- a/eng/update-readme.mjs +++ b/eng/update-readme.mjs @@ -17,12 +17,14 @@ import { TEMPLATES, vscodeInsidersInstallImage, vscodeInstallImage, + WORKFLOWS_DIR, } from "./constants.mjs"; import { extractMcpServerConfigs, parseFrontmatter, parseSkillMetadata, parseHookMetadata, + parseWorkflowMetadata, } from "./yaml-parser.mjs"; const __filename = fileURLToPath(import.meta.url); @@ -577,6 +579,61 @@ function generateHooksSection(hooksDir) { return `${TEMPLATES.hooksSection}\n${TEMPLATES.hooksUsage}\n\n${content}`; } +/** + * Generate the workflows section with a table of all agentic workflows + */ +function generateWorkflowsSection(workflowsDir) { + if (!fs.existsSync(workflowsDir)) { + console.log(`Workflows directory does not exist: ${workflowsDir}`); + return ""; + } + + // Get all .md workflow files (flat, no subfolders) + const workflowFiles = fs.readdirSync(workflowsDir).filter((file) => { + return file.endsWith(".md") && file !== ".gitkeep"; + }); + + // Parse each workflow file + const workflowEntries = workflowFiles + .map((file) => { + const filePath = path.join(workflowsDir, file); + const metadata = parseWorkflowMetadata(filePath); + if (!metadata) return null; + + return { + file, + name: metadata.name, + description: metadata.description, + triggers: metadata.triggers, + tags: metadata.tags, + }; + }) + .filter((entry) => entry !== null) + .sort((a, b) => a.name.localeCompare(b.name)); + + console.log(`Found ${workflowEntries.length} workflow(s)`); + + if (workflowEntries.length === 0) { + return ""; + } + + // Create table header + let content = + "| Name | Description | Triggers |\n| ---- | ----------- | -------- |\n"; + + // Generate table rows for each workflow + for (const workflow of workflowEntries) { + const link = `../workflows/${workflow.file}`; + const triggers = workflow.triggers.length > 0 ? workflow.triggers.join(", ") : "N/A"; + + content += `| [${workflow.name}](${link}) | ${formatTableCell( + workflow.description + )} | ${triggers} |\n`; + } + + return `${TEMPLATES.workflowsSection}\n${TEMPLATES.workflowsUsage}\n\n${content}`; +} + /** * Generate the skills section with a table of all skills */ @@ -921,6 +978,7 @@ async function main() { 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, "# "); const skillsHeader = TEMPLATES.skillsSection.replace(/^##\s/m, "# "); const pluginsHeader = TEMPLATES.pluginsSection.replace( /^##\s/m, @@ -959,6 +1017,15 @@ async function main() { registryNames ); + // Generate workflows README + const workflowsReadme = buildCategoryReadme( + generateWorkflowsSection, + WORKFLOWS_DIR, + workflowsHeader, + TEMPLATES.workflowsUsage, + registryNames + ); + // Generate skills README const skillsReadme = buildCategoryReadme( generateSkillsSection, @@ -990,6 +1057,7 @@ async function main() { 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); writeFileIfChanged(path.join(DOCS_DIR, "README.skills.md"), skillsReadme); writeFileIfChanged( path.join(DOCS_DIR, "README.plugins.md"), diff --git a/eng/yaml-parser.mjs b/eng/yaml-parser.mjs index 8ef9f8a7..88d16582 100644 --- a/eng/yaml-parser.mjs +++ b/eng/yaml-parser.mjs @@ -253,6 +253,44 @@ function parseHookMetadata(hookPath) { ); } +/** + * Parse workflow metadata from a standalone .md workflow file + * @param {string} filePath - Path to the workflow .md file + * @returns {object|null} Workflow metadata or null on error + */ +function parseWorkflowMetadata(filePath) { + return safeFileOperation( + () => { + if (!fs.existsSync(filePath)) { + return null; + } + + const frontmatter = parseFrontmatter(filePath); + + // Validate required fields + if (!frontmatter?.name || !frontmatter?.description) { + console.warn( + `Invalid workflow at ${filePath}: missing name or description in frontmatter` + ); + return null; + } + + // Extract triggers from frontmatter if present + const triggers = frontmatter.triggers || []; + + return { + name: frontmatter.name, + description: frontmatter.description, + triggers, + tags: frontmatter.tags || [], + path: filePath, + }; + }, + filePath, + null + ); +} + /** * Parse a generic YAML file (used for tools.yml and other config files) * @param {string} filePath - Path to the YAML file @@ -276,6 +314,7 @@ export { parseFrontmatter, parseSkillMetadata, parseHookMetadata, + parseWorkflowMetadata, parseYamlFile, safeFileOperation, }; diff --git a/instructions/context7.instructions.md b/instructions/context7.instructions.md new file mode 100644 index 00000000..da377caf --- /dev/null +++ b/instructions/context7.instructions.md @@ -0,0 +1,106 @@ +--- +description: 'Use Context7 for authoritative external docs and API references when local context is insufficient' +applyTo: '**' +--- + +# Context7-aware development + +Use Context7 proactively whenever the task depends on **authoritative, current, version-specific external documentation** that is not present in the workspace context. + +This instruction exists so you **do not require the user to type** β€œuse context7” to get up-to-date docs. + +## When to use Context7 + +Use Context7 before making decisions or writing code when you need any of the following: + +- **Framework/library API details** (method signatures, configuration keys, expected behaviors). +- **Version-sensitive guidance** (breaking changes, deprecations, new defaults). +- **Correctness or security-critical patterns** (auth flows, crypto usage, deserialization rules). +- **Interpreting unfamiliar error messages** that likely come from third-party tools. +- **Best-practice implementation constraints** (rate limits, quotas, required headers, supported formats). + +Also use Context7 when: + +- The user references **a specific framework/library version** (e.g., β€œNext.js 15”, β€œReact 19”, β€œAWS SDK v3”). +- You’re about to recommend **non-trivial configuration** (CLI flags, config files, auth flows). +- You’re unsure whether an API exists, changed names, or got deprecated. + +Skip Context7 for: + +- Purely local refactors, formatting, naming, or logic that is fully derivable from the repo. +- Language fundamentals (no external APIs involved). + +## What to fetch + +When using Context7, prefer **primary sources** and narrow queries: + +- Official docs (vendor/framework documentation) +- Reference/API pages +- Release notes / migration guides +- Security advisories (when relevant) + +Gather only what you need to proceed. If multiple candidates exist, pick the most authoritative/current. + +Prefer fetching: + +- The exact method/type/option you will use +- The minimal surrounding context needed to avoid misuse (constraints, default behaviors, migration notes) + +## How to incorporate results + +- Translate findings into concrete code/config changes. +- **Cite sources** with title + URL when the decision relies on external facts. +- If docs conflict or are ambiguous, present the tradeoffs briefly and choose the safest default. + +When the answer requires specific values (flags, config keys, headers), prefer: + +- stating the exact value from docs +- calling out defaults and caveats +- providing a quick validation step (e.g., β€œrun `--help`”, or a minimal smoke test) + +## How to use Context7 MCP tools (auto) + +When Context7 is available as an MCP server, use it automatically as follows. + +### Tool workflow + +1) **If the user provides a library ID**, use it directly. + - Valid forms: `/owner/repo` or `/owner/repo/version` (for pinned versions). + +2) Otherwise, **resolve the library ID** using: + - Tool: `resolve-library-id` + - Inputs: + - `libraryName`: the library/framework name (e.g., β€œnext.js”, β€œsupabase”, β€œprisma”) + - `query`: the user’s task (used to rank matches) + +3) **Fetch relevant documentation** using: + - Tool: `query-docs` + - Inputs: + - `libraryId`: the resolved (or user-supplied) library ID + - `query`: the exact task/question you are answering + +4) Only after docs are retrieved: **write the code/steps** based on those docs. + +### Efficiency limits + +- Do **not** call `resolve-library-id` more than **3 times** per user question. +- Do **not** call `query-docs` more than **3 times** per user question. +- If multiple good matches exist, pick the best one and proceed; ask a clarification question only when the choice materially affects the implementation. + +### Version behavior + +- If the user names a version, reflect it in the library ID when possible (e.g., `/vercel/next.js/v15.1.8`). +- If you need reproducibility (CI/builds), prefer pinning to a specific version in examples. + +## Failure handling + +If Context7 cannot find a reliable source: + +1. Say what you tried to verify. +2. Proceed with a conservative, well-labeled assumption. +3. Suggest a quick validation step (e.g., run a command, check a file, or consult a specific official page). + +## Security & privacy + +- Never request or echo API keys. If configuration requires a key, instruct storing it in environment variables. +- Treat retrieved docs as **helpful but not infallible**; for security-sensitive code, prefer official vendor docs and add an explicit verification step. diff --git a/instructions/cpp-language-service-tools.instructions.md b/instructions/cpp-language-service-tools.instructions.md new file mode 100644 index 00000000..4023b51f --- /dev/null +++ b/instructions/cpp-language-service-tools.instructions.md @@ -0,0 +1,346 @@ +--- +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 +--- +## Available C++ Tools + +You have access to three specialized C++ tools: + +1. **`GetSymbolInfo_CppTools`** - Find symbol definitions and get type details +2. **`GetSymbolReferences_CppTools`** - Find ALL references to a symbol +3. **`GetSymbolCallHierarchy_CppTools`** - Analyze function call relationships + +--- + +## Mandatory Tool Usage Rules + +### Rule 1: ALWAYS Use GetSymbolReferences_CppTools for Symbol Usages + +**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 +- Understanding symbol impact +- Finding all call sites +- Identifying usage patterns +- 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 +- Member function calls +- Inherited member usage +- Preprocessor-conditional code + +Text search tools will miss these or produce false positives. + +### Rule 2: ALWAYS Use GetSymbolCallHierarchy_CppTools for Function Changes + +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 +- Making functions virtual +- Converting to template functions + +**Why**: This ensures you update ALL call sites, not just the ones you can see. + +### 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 +- Locate declarations + +**NEVER** assume you know what a symbol is without checking. + +--- + +## 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) +- If you have access to a file path, include it +- 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 + 2. Locate the symbol in the output + 3. Note the EXACT line number from the output + 4. VERIFY the line contains the symbol + 5. Only then call the C++ tool with that line number +- **NEVER** guess or estimate line numbers +- 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`) + +--- + +## Common Workflows + +### Renaming a Symbol + +``` +CORRECT workflow: +1. Call GetSymbolReferences_CppTools with symbol name (and file path if available) +2. Review ALL references returned +3. Update symbol at definition location +4. Update symbol at ALL reference locations + +INCORRECT workflow: +❌ Using vscode_listCodeUsages or grep_search to find usages +❌ Manually inspecting a few files +❌ Assuming you know all the usages +``` + +### Changing a Function Signature + +``` +CORRECT workflow: +1. Call GetSymbolInfo_CppTools to locate the function definition +2. Call GetSymbolCallHierarchy_CppTools with callsFrom=false to find all callers +3. Call GetSymbolReferences_CppTools to catch any additional references (function pointers, etc.) +4. Update function definition +5. Update ALL call sites with new signature + +INCORRECT workflow: +❌ Changing the function without finding callers +❌ Only updating visible call sites +❌ Using text search to find calls +``` + +### Understanding Unfamiliar Code + +``` +CORRECT workflow: +1. Call GetSymbolInfo_CppTools on key types/functions to understand definitions +3. Call GetSymbolCallHierarchy_CppTools with callsFrom=true to understand what a function does +4. Call GetSymbolCallHierarchy_CppTools with callsFrom=false to understand where a function is used + +INCORRECT workflow: +❌ Reading code manually without tool assistance +❌ Making assumptions about symbol meanings +❌ Skipping hierarchy analysis +``` + +### Analyzing Function Dependencies + +``` +CORRECT workflow: +1. Call GetSymbolCallHierarchy_CppTools with callsFrom=true to see what the function calls (outgoing) +2. Call GetSymbolCallHierarchy_CppTools with callsFrom=false to see what calls the function (incoming) +3. Use this to understand code flow and dependencies + +INCORRECT workflow: +❌ Manually reading through function body +❌ Guessing at call patterns +``` + +--- + +## Error Handling and Recovery + +### When You Get an Error Message + +**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" + +Recovery: +1. Ensure you provided a non-empty symbol name +2. Check that the symbol name is spelled correctly +3. Retry with valid symbol name +``` + +#### "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." + +Recovery: +1. Convert relative path to absolute path +2. Verify file exists in the workspace +3. Use exact path from user or file system +4. Retry with absolute path +``` + +#### "No results found" Message +``` +Message: "No results found for the symbol '[symbol_name]'." + +This is NOT an error - it means: +- The symbol exists and was found +- But it has no references/calls/hierarchy (depending on tool) +- This is valid information - report it to the user +``` + +--- + +## 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 + +--- + +## 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 +- βœ… Provide absolute file paths when available +- βœ… Follow error message instructions exactly +- βœ… Trust tool results over manual inspection +- βœ… Use minimal parameters first, add more if needed +- βœ… 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 +- ❌ Assume symbol uniqueness without checking +- ❌ Ignore error messages +- ❌ Skip tool usage to save time +- ❌ Use 0-based line numbers +- ❌ Batch multiple unrelated symbol operations +- ❌ Make changes without finding all affected locations + +--- + +## Examples of Correct Usage + +### Example 1: User asks to rename a function +``` +User: "Rename the function ProcessData to HandleData" + +CORRECT response: +1. Call GetSymbolReferences_CppTools("ProcessData") +2. Review all reference locations +3. Update function definition +4. Update all call sites shown in results +5. Confirm all changes made + +INCORRECT response: +❌ Using grep_search to find "ProcessData" +❌ Only updating files the user mentioned +❌ Assuming you found all usages manually +``` + +### Example 2: User asks to add a parameter to a function +``` +User: "Add a parameter 'bool verbose' to the LogMessage function" + +CORRECT response: +1. Call GetSymbolInfo_CppTools("LogMessage") to find definition +2. Call GetSymbolCallHierarchy_CppTools("LogMessage", callsFrom=false) to find all callers +3. Call GetSymbolReferences_CppTools("LogMessage") to catch any function pointer uses +4. Update function definition +5. Update ALL call sites with new parameter + +INCORRECT response: +❌ Only updating the definition +❌ Updating only obvious call sites +❌ Not using call_hierarchy tool +``` + +### Example 3: User asks to understand a function +``` +User: "What does the Initialize function do?" + +CORRECT response: +1. Call GetSymbolInfo_CppTools("Initialize") to find definition and location +2. Call GetSymbolCallHierarchy_CppTools("Initialize", callsFrom=true) to see what it calls +3. Read the function implementation +4. Explain based on code + call hierarchy + +INCORRECT response: +❌ Only reading the function body +❌ Not checking what it calls +❌ Guessing at behavior +``` + +--- + +## 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 + +--- + +## 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 +- **Then** use C++ tools for precise symbol analysis + +--- + +## Summary + +**The golden rule**: When working with C++ code, think "tool first, manual inspection later." + +1. **Symbol usages?** β†’ `GetSymbolReferences_CppTools` +2. **Function calls?** β†’ `GetSymbolCallHierarchy_CppTools` +3. **Symbol definition?** β†’ `GetSymbolInfo_CppTools` + +These tools are your primary interface to C++ code understanding. Use them liberally and often. They are fast, accurate, and understand C++ semantics that text search cannot capture. + +**Your success metric**: Did I use the right C++ tool for every symbol-related task? diff --git a/instructions/markdown-accessibility.instructions.md b/instructions/markdown-accessibility.instructions.md new file mode 100644 index 00000000..ecf645d5 --- /dev/null +++ b/instructions/markdown-accessibility.instructions.md @@ -0,0 +1,71 @@ +--- +description: 'Markdown accessibility guidelines based on GitHub''s 5 best practices for inclusive documentation' +applyTo: '**/*.md' +--- + +# Markdown Accessibility Review Guidelines + +When reviewing markdown files, check for the following accessibility issues 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/). Flag violations and suggest fixes with clear explanations of the accessibility impact. + +## 1. Descriptive Links + +- Flag generic link text such as "click here," "here," "this," "read more," or "link." +- Link text must make sense when read out of context, because assistive technology can present links as an isolated list. +- Flag multiple links on the same page that share identical text but point to different destinations. +- Bare URLs in prose should be converted to descriptive links. + +Bad: `Read my blog post [here](https://example.com)` +Good: `Read my blog post "[Crafting an accessible resume](https://example.com)"` + +## 2. Image Alt Text + +- Flag images with empty alt text (e.g., `![](path/to/image.png)`) unless they are explicitly decorative. +- Flag alt text that is a filename (e.g., `img_1234.jpg`) or generic placeholder (e.g., `screenshot`, `image`). +- Alt text should be succinct and descriptive. Include any text visible in the image. +- Use "screenshot of" where relevant, but do not prefix with "image of" since screen readers announce that automatically. +- For complex images (charts, infographics), suggest summarizing the data in alt text and providing longer descriptions via `
` tags or linked content. +- When suggesting alt text improvements, present them as recommendations for the author to review. Alt text requires understanding of visual content and context that only the author can properly assess. + +## 3. Heading Hierarchy + +- There must be only one H1 (`#`) per document, used as the page title. Note: in projects where H1 is auto-generated from front matter, start content at H2. +- Headings must follow a logical hierarchy and never skip levels (e.g., `##` followed by `####` is a violation). +- Flag bold text (`**text**`) used as a visual substitute for a proper heading. +- Proper heading structure allows assistive technology users to navigate by section and helps sighted users scan content. + +## 4. Plain Language + +- Flag unnecessarily complex or jargon-heavy language that could be simplified. +- Favor short sentences, common words, and active voice. +- Flag long, dense paragraphs that could be broken into smaller sections or lists. +- When suggesting plain language improvements, present them as recommendations for the author to review. Language decisions require understanding of audience, context, and tone. + +## 5. Lists and Emoji Usage + +### Lists + +- Flag emoji or special characters used as bullet points instead of proper markdown list syntax (`-`, `*`, `+`, or `1.`). +- Flag sequential items in plain text that should be structured as a proper list. +- Proper list markup allows screen readers to announce list context (e.g., "item 1 of 3"). + +### Emoji + +- Flag multiple consecutive emoji, which are disruptive to screen reader users since each emoji name is read aloud in full (e.g., "rocket" "sparkles" "fire"). +- Flag emoji used to convey meaning that is not also communicated in text. +- Emoji should be used sparingly and thoughtfully. + +## Review Priority + +When multiple issues exist, prioritize in this order: + +1. Missing or empty alt text on images +2. Skipped heading levels or heading hierarchy issues +3. Non-descriptive link text +4. Emoji used as bullet points or list markers +5. Plain language improvements + +## Review Tone + +- Explain the accessibility impact of each issue, specifying which users are affected (e.g., screen reader users, people with cognitive disabilities, non-native speakers). +- Do not remove personality or voice from the writing. Accessibility and engaging content are not mutually exclusive. +- Keep suggestions actionable and specific. \ No newline at end of file diff --git a/instructions/moodle.instructions.md b/instructions/moodle.instructions.md new file mode 100644 index 00000000..6a82943c --- /dev/null +++ b/instructions/moodle.instructions.md @@ -0,0 +1,57 @@ +--- +applyTo: '**/*.php, **/*.js, **/*.mustache, **/*.xml, **/*.css, **/*.scss' +description: 'Instructions for GitHub Copilot to generate code in a Moodle project context.' +--- + +# Project Context + +This repository contains a Moodle project. Ensure that any generated code is compatible with the specific Moodle version used in this project (for example, Moodle 3.11, 4.1 LTS, or later). + +It includes: +- Plugin development (local, block, mod, auth, enrol, tool, etc.) +- Theme customization +- CLI scripts +- Integrations with external services using the Moodle API + +# Code Standards + +- Follow the official Moodle Coding guidelines: https://moodledev.io/general/development/policies/codingstyle +- PHP must be compatible with the core version (e.g., PHP 7.4 / 8.0 / 8.1). +- Do not use modern syntax that is not supported by core if it breaks compatibility. +- Class naming must use Moodle namespaces. +- Follow Moodle’s standard plugin directory layout (for example: classes/output, classes/form, db/, lang/, templates/…). +- Mandatory use of Moodle security functions: + - `$DB` with SQL placeholders + - `require_login()`, `require_capability()` + - Parameters handled with `required_param()` / `optional_param()` + +# Code Generation Rules + +- When creating new PHP classes in plugins, use the Moodle component (Frankenstyle) namespace that matches the plugin's component name, e.g. `local_myplugin`, `mod_forum`, `block_mycatalog`, `tool_mytool`. +- In plugins, always respect the structure: + - /db + - /lang + - /classes + - /templates + - /version.php + - /settings.php + - /lib.php (only if necessary) + +- Use renderers and Mustache templates for HTML. Do not mix HTML inside PHP. +- In JavaScript code, use AMD modules, not inline scripts. +- Prefer Moodle API functions over manual code whenever possible. +- Do not invent Moodle functions that do not exist. + +# Examples of What Copilot Should Be Able to Answer + +- "Generate a basic local plugin with version.php, settings.php, and lib.php." +- "Create a new table in db/install.xml and an upgrade script in db/upgrade.php." +- "Generate a Moodle form using moodleform." +- "Create a renderer with Mustache to display a table." + +# Expected Style + +- Clear and specific answers in the Moodle context. +- Always include files with full paths. +- If there are multiple ways to do something, use the approach recommended by Moodle. + diff --git a/package.json b/package.json index a2123dc4..fb1ca377 100644 --- a/package.json +++ b/package.json @@ -15,6 +15,7 @@ "plugin:create": "node ./eng/create-plugin.mjs", "skill:validate": "node ./eng/validate-skills.mjs", "skill:create": "node ./eng/create-skill.mjs", + "plugin:clean": "node ./eng/clean-materialized-plugins.mjs", "plugin:generate-marketplace": "node ./eng/generate-marketplace.mjs", "website:data": "node ./eng/generate-website-data.mjs", "website:dev": "npm run website:data && npm run --prefix website dev", diff --git a/prompts/bigquery-pipeline-audit.prompt.md b/prompts/bigquery-pipeline-audit.prompt.md new file mode 100644 index 00000000..5031bee5 --- /dev/null +++ b/prompts/bigquery-pipeline-audit.prompt.md @@ -0,0 +1,130 @@ +--- +agent: 'agent' +tools: ['search/codebase', 'edit/editFiles', 'search'] +description: 'Audits Python + BigQuery pipelines for cost safety, idempotency, and production readiness. Returns a structured report with exact patch locations.' +--- + +# BigQuery Pipeline Audit: Cost, Safety and Production Readiness + +You are a senior data engineer reviewing a Python + BigQuery pipeline script. +Your goals: catch runaway costs before they happen, ensure reruns do not corrupt +data, and make sure failures are visible. + +Analyze the codebase and respond in the structure below (A to F + Final). +Reference exact function names and line locations. Suggest minimal fixes, not +rewrites. + +--- + +## A) COST EXPOSURE: What will actually get billed? + +Locate every BigQuery job trigger (`client.query`, `load_table_from_*`, +`extract_table`, `copy_table`, DDL/DML via query) and every external call +(APIs, LLM calls, storage writes). + +For each, answer: +- Is this inside a loop, retry block, or async gather? +- What is the realistic worst-case call count? +- For each `client.query`, is `QueryJobConfig.maximum_bytes_billed` set? + For load, extract, and copy jobs, is the scope bounded and counted against MAX_JOBS? +- Is the same SQL and params being executed more than once in a single run? + Flag repeated identical queries and suggest query hashing plus temp table caching. + +**Flag immediately if:** +- Any BQ query runs once per date or once per entity in a loop +- Worst-case BQ job count exceeds 20 +- `maximum_bytes_billed` is missing on any `client.query` call + +--- + +## B) DRY RUN AND EXECUTION MODES + +Verify a `--mode` flag exists with at least `dry_run` and `execute` options. + +- `dry_run` must print the plan and estimated scope with zero billed BQ execution + (BigQuery dry-run estimation via job config is allowed) and zero external API or LLM calls +- `execute` requires explicit confirmation for prod (`--env=prod --confirm`) +- Prod must not be the default environment + +If missing, propose a minimal `argparse` patch with safe defaults. + +--- + +## C) BACKFILL AND LOOP DESIGN + +**Hard fail if:** the script runs one BQ query per date or per entity in a loop. + +Check that date-range backfills use one of: +1. A single set-based query with `GENERATE_DATE_ARRAY` +2. A staging table loaded with all dates then one join query +3. Explicit chunks with a hard `MAX_CHUNKS` cap + +Also check: +- Is the date range bounded by default (suggest 14 days max without `--override`)? +- If the script crashes mid-run, is it safe to re-run without double-writing? +- For backdated simulations, verify data is read from time-consistent snapshots + (`FOR SYSTEM_TIME AS OF`, partitioned as-of tables, or dated snapshot tables). + Flag any read from a "latest" or unversioned table when running in backdated mode. + +Suggest a concrete rewrite if the current approach is row-by-row. + +--- + +## D) QUERY SAFETY AND SCAN SIZE + +For each query, check: +- **Partition filter** is on the raw column, not `DATE(ts)`, `CAST(...)`, or + any function that prevents pruning +- **No `SELECT *`**: only columns actually used downstream +- **Joins will not explode**: verify join keys are unique or appropriately scoped + and flag any potential many-to-many +- **Expensive operations** (`REGEXP`, `JSON_EXTRACT`, UDFs) only run after + partition filtering, not on full table scans + +Provide a specific SQL fix for any query that fails these checks. + +--- + +## E) SAFE WRITES AND IDEMPOTENCY + +Identify every write operation. Flag plain `INSERT`/append with no dedup logic. + +Each write should use one of: +1. `MERGE` on a deterministic key (e.g., `entity_id + date + model_version`) +2. Write to a staging table scoped to the run, then swap or merge into final +3. Append-only with a dedupe view: + `QUALIFY ROW_NUMBER() OVER (PARTITION BY ) = 1` + +Also check: +- Will a re-run create duplicate rows? +- Is the write disposition (`WRITE_TRUNCATE` vs `WRITE_APPEND`) intentional + and documented? +- Is `run_id` being used as part of the merge or dedupe key? If so, flag it. + `run_id` should be stored as a metadata column, not as part of the uniqueness + key, unless you explicitly want multi-run history. + +State the recommended approach and the exact dedup key for this codebase. + +--- + +## F) OBSERVABILITY: Can you debug a failure? + +Verify: +- Failures raise exceptions and abort with no silent `except: pass` or warn-only +- Each BQ job logs: job ID, bytes processed or billed when available, + slot milliseconds, and duration +- A run summary is logged or written at the end containing: + `run_id, env, mode, date_range, tables written, total BQ jobs, total bytes` +- `run_id` is present and consistent across all log lines + +If `run_id` is missing, propose a one-line fix: +`run_id = run_id or datetime.utcnow().strftime('%Y%m%dT%H%M%S')` + +--- + +## Final + +**1. PASS / FAIL** with specific reasons per section (A to F). +**2. Patch list** ordered by risk, referencing exact functions to change. +**3. If FAIL: Top 3 cost risks** with a rough worst-case estimate +(e.g., "loop over 90 dates x 3 retries = 270 BQ jobs"). diff --git a/skills/entra-agent-user/SKILL.md b/skills/entra-agent-user/SKILL.md new file mode 100644 index 00000000..06f5cfa0 --- /dev/null +++ b/skills/entra-agent-user/SKILL.md @@ -0,0 +1,270 @@ +--- +name: entra-agent-user +description: '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.' +--- + +# SKILL: Creating Agent Users in Microsoft Entra Agent ID + +## Overview + +An **agent user** is a specialized user identity in Microsoft Entra ID that enables AI agents to act as digital workers. It allows agents to access APIs and services that strictly require user identities (e.g., Exchange mailboxes, Teams, org charts), while maintaining appropriate security boundaries. + +Agent users receive tokens with `idtyp=user`, unlike regular agent identities which receive `idtyp=app`. + +--- + +## Prerequisites + +- A **Microsoft Entra tenant** with Agent ID capabilities +- An **agent identity** (service principal of type `ServiceIdentity`) created from an **agent identity blueprint** +- One of the following **permissions**: + - `AgentIdUser.ReadWrite.IdentityParentedBy` (least privileged) + - `AgentIdUser.ReadWrite.All` + - `User.ReadWrite.All` +- The caller must have at minimum the **Agent ID Administrator** role (in delegated scenarios) + +> **Important:** The `identityParentId` must reference a true agent identity (created via an agent identity blueprint), NOT a regular application service principal. You can verify by checking that the service principal has `@odata.type: #microsoft.graph.agentIdentity` and `servicePrincipalType: ServiceIdentity`. + +--- + +## Architecture + +``` +Agent Identity Blueprint (application template) + β”‚ + β”œβ”€β”€ Agent Identity (service principal - ServiceIdentity) + β”‚ β”‚ + β”‚ └── Agent User (user - agentUser) ← 1:1 relationship + β”‚ + └── Agent Identity Blueprint Principal (service principal in tenant) +``` + +| Component | Type | Token Claim | Purpose | +|---|---|---|---| +| Agent Identity | Service Principal | `idtyp=app` | Backend/API operations | +| Agent User | User (`agentUser`) | `idtyp=user` | Act as a digital worker in M365 | + +--- + +## Step 1: Verify the Agent Identity Exists + +Before creating an agent user, confirm the agent identity is a proper `agentIdentity` type: + +```http +GET https://graph.microsoft.com/beta/servicePrincipals/{agent-identity-id} +Authorization: Bearer +``` + +Verify the response contains: +```json +{ + "@odata.type": "#microsoft.graph.agentIdentity", + "servicePrincipalType": "ServiceIdentity", + "agentIdentityBlueprintId": "" +} +``` + +### PowerShell + +```powershell +Connect-MgGraph -Scopes "Application.Read.All" -TenantId "" -UseDeviceCode -NoWelcome +Invoke-MgGraphRequest -Method GET ` + -Uri "https://graph.microsoft.com/beta/servicePrincipals/" | ConvertTo-Json -Depth 3 +``` + +> **Common mistake:** Using an app registration's `appId` or a regular application service principal's `id` will fail. Only agent identities created from blueprints work. + +--- + +## Step 2: Create the Agent User + +### HTTP Request + +```http +POST https://graph.microsoft.com/beta/users/microsoft.graph.agentUser +Content-Type: application/json +Authorization: Bearer + +{ + "accountEnabled": true, + "displayName": "My Agent User", + "mailNickname": "my-agent-user", + "userPrincipalName": "my-agent-user@yourtenant.onmicrosoft.com", + "identityParentId": "" +} +``` + +### Required Properties + +| Property | Type | Description | +|---|---|---| +| `accountEnabled` | Boolean | `true` to enable the account | +| `displayName` | String | Human-friendly name | +| `mailNickname` | String | Mail alias (no spaces/special chars) | +| `userPrincipalName` | String | UPN β€” must be unique in the tenant (`alias@verified-domain`) | +| `identityParentId` | String | Object ID of the parent agent identity | + +### PowerShell + +```powershell +Connect-MgGraph -Scopes "User.ReadWrite.All" -TenantId "" -UseDeviceCode -NoWelcome + +$body = @{ + accountEnabled = $true + displayName = "My Agent User" + mailNickname = "my-agent-user" + userPrincipalName = "my-agent-user@yourtenant.onmicrosoft.com" + identityParentId = "" +} | ConvertTo-Json + +Invoke-MgGraphRequest -Method POST ` + -Uri "https://graph.microsoft.com/beta/users/microsoft.graph.agentUser" ` + -Body $body -ContentType "application/json" | ConvertTo-Json -Depth 3 +``` + +### Key Notes + +- **No password** β€” agent users cannot have passwords. They authenticate via their parent agent identity's credentials. +- **1:1 relationship** β€” each agent identity can have at most one agent user. Attempting to create a second returns `400 Bad Request`. +- The `userPrincipalName` must be unique. Don't reuse an existing user's UPN. + +--- + +## Step 3: Assign a Manager (Optional) + +Assigning a manager allows the agent user to appear in org charts (e.g., Teams). + +```http +PUT https://graph.microsoft.com/beta/users/{agent-user-id}/manager/$ref +Content-Type: application/json +Authorization: Bearer + +{ + "@odata.id": "https://graph.microsoft.com/beta/users/{manager-user-id}" +} +``` + +### PowerShell + +```powershell +$managerBody = '{"@odata.id":"https://graph.microsoft.com/beta/users/"}' +Invoke-MgGraphRequest -Method PUT ` + -Uri "https://graph.microsoft.com/beta/users//manager/`$ref" ` + -Body $managerBody -ContentType "application/json" +``` + +--- + +## Step 4: Set Usage Location and Assign Licenses (Optional) + +A license is needed for the agent user to have a mailbox, Teams presence, etc. Usage location must be set first. + +### Set Usage Location + +```http +PATCH https://graph.microsoft.com/beta/users/{agent-user-id} +Content-Type: application/json +Authorization: Bearer + +{ + "usageLocation": "US" +} +``` + +### List Available Licenses + +```http +GET https://graph.microsoft.com/beta/subscribedSkus?$select=skuPartNumber,skuId,consumedUnits,prepaidUnits +Authorization: Bearer +``` + +Requires `Organization.Read.All` permission. + +### Assign a License + +```http +POST https://graph.microsoft.com/beta/users/{agent-user-id}/assignLicense +Content-Type: application/json +Authorization: Bearer + +{ + "addLicenses": [ + { "skuId": "" } + ], + "removeLicenses": [] +} +``` + +### PowerShell (all in one) + +```powershell +Connect-MgGraph -Scopes "User.ReadWrite.All","Organization.Read.All" -TenantId "" -NoWelcome + +# Set usage location +Invoke-MgGraphRequest -Method PATCH ` + -Uri "https://graph.microsoft.com/beta/users/" ` + -Body '{"usageLocation":"US"}' -ContentType "application/json" + +# Assign license +$licenseBody = '{"addLicenses":[{"skuId":""}],"removeLicenses":[]}' +Invoke-MgGraphRequest -Method POST ` + -Uri "https://graph.microsoft.com/beta/users//assignLicense" ` + -Body $licenseBody -ContentType "application/json" +``` + +> **Tip:** You can also assign licenses via the **Entra admin center** under Identity β†’ Users β†’ All users β†’ select the agent user β†’ Licenses and apps. + +--- + +## Provisioning Times + +| Service | Estimated Time | +|---|---| +| Exchange mailbox | 5–30 minutes | +| Teams availability | 15 min – 24 hours | +| Org chart / People search | Up to 24–48 hours | +| SharePoint / OneDrive | 5–30 minutes | +| Global Address List | Up to 24 hours | + +--- + +## Agent User Capabilities + +- βœ… Added to Microsoft Entra groups (including dynamic groups) +- βœ… Access user-only APIs (`idtyp=user` tokens) +- βœ… Own a mailbox, calendar, and contacts +- βœ… Participate in Teams chats and channels +- βœ… Appear in org charts and People search +- βœ… Added to administrative units +- βœ… Assigned licenses + +## Agent User Security Constraints + +- ❌ Cannot have passwords, passkeys, or interactive sign-in +- ❌ Cannot be assigned privileged admin roles +- ❌ Cannot be added to role-assignable groups +- ❌ Permissions similar to guest users by default +- ❌ Custom role assignment not available + +--- + +## Troubleshooting + +| Error | Cause | Fix | +|---|---|---| +| `Agent user IdentityParent does not exist` | `identityParentId` points to a non-existent or non-agent-identity object | Verify the ID is an `agentIdentity` service principal, not a regular app | +| `400 Bad Request` (identityParentId already linked) | The agent identity already has an agent user | Each agent identity supports only one agent user | +| `409 Conflict` on UPN | The `userPrincipalName` is already taken | Use a unique UPN | +| License assignment fails | Usage location not set | Set `usageLocation` before assigning licenses | + +--- + +## References + +- [Agent identities](https://learn.microsoft.com/en-us/entra/agent-id/identity-platform/agent-identities) +- [Agent users](https://learn.microsoft.com/en-us/entra/agent-id/identity-platform/agent-users) +- [Agent service principals](https://learn.microsoft.com/en-us/entra/agent-id/identity-platform/agent-service-principals) +- [Create agent identity blueprint](https://learn.microsoft.com/en-us/entra/agent-id/identity-platform/create-blueprint) +- [Create agent identities](https://learn.microsoft.com/en-us/entra/agent-id/identity-platform/create-delete-agent-identities) +- [agentUser resource type (Graph API)](https://learn.microsoft.com/en-us/graph/api/resources/agentuser?view=graph-rest-beta) +- [Create agentUser (Graph API)](https://learn.microsoft.com/en-us/graph/api/agentuser-post?view=graph-rest-beta)