From e3ee37a27450b16199ad4ccc08502c0d58feb6db Mon Sep 17 00:00:00 2001 From: MV Karan Date: Fri, 6 Mar 2026 02:30:52 +0530 Subject: [PATCH 01/37] Add instrumentation script for pageview analytics (#875) * Add instrumentation script for pageview analytics * Only include analytics tags in production builds Wrap hydro-marketing analytics meta tag and script in an import.meta.env.PROD conditional so they are excluded during local development and only rendered in production builds. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Add production-only analytics tags to Starlight Head component Add hydro-marketing analytics meta tag and script to the custom Head.astro component override, gated behind import.meta.env.PROD so they only render in production builds (GitHub Pages deploy). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- website/src/components/Head.astro | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/website/src/components/Head.astro b/website/src/components/Head.astro index bf25df34..73dc360d 100644 --- a/website/src/components/Head.astro +++ b/website/src/components/Head.astro @@ -9,3 +9,16 @@ const basePath = import.meta.env.BASE_URL; document.body.dataset.basePath = basePath; }); +{import.meta.env.PROD && ( + <> + + + +)} From 38aafb1a7282c762ffaa7097530cb73cf4d3f95c Mon Sep 17 00:00:00 2001 From: Tom Meschter Date: Thu, 5 Mar 2026 13:01:58 -0800 Subject: [PATCH 02/37] Add azure-skills as external plugin (#880) * Add azure-skills as external plugin Add microsoft/azure-skills as an external plugin with metadata including author, homepage, keywords, license, and repository fields. Regenerated marketplace.json. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Rename external plugin from azure-skills to azure Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Update azure plugin description Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Swap homepage and repository URLs for azure plugin Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Add source.path to azure external plugin entry Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/plugin/marketplace.json | 25 +++++++++++++++++++++++++ plugins/external.json | 21 ++++++++++++++++++++- 2 files changed, 45 insertions(+), 1 deletion(-) diff --git a/.github/plugin/marketplace.json b/.github/plugin/marketplace.json index 78d31a00..66be4b39 100644 --- a/.github/plugin/marketplace.json +++ b/.github/plugin/marketplace.json @@ -16,6 +16,31 @@ "description": "Meta prompts that help you discover and generate curated GitHub Copilot agents, instructions, prompts, and skills.", "version": "1.0.0" }, + { + "name": "azure", + "description": "Microsoft Azure MCP Server and skills for cloud resource management, deployments, and Azure services. Manage your Azure infrastructure, monitor applications, and deploy resources directly from Copilot.", + "version": "1.0.0", + "author": { + "name": "Microsoft", + "url": "https://www.microsoft.com" + }, + "homepage": "https://github.com/microsoft/azure-skills", + "keywords": [ + "azure", + "cloud", + "infrastructure", + "deployment", + "microsoft", + "devops" + ], + "license": "MIT", + "repository": "https://github.com/microsoft/github-copilot-for-azure", + "source": { + "source": "github", + "repo": "microsoft/azure-skills", + "path": ".github/plugins/azure-skills" + } + }, { "name": "azure-cloud-development", "source": "azure-cloud-development", diff --git a/plugins/external.json b/plugins/external.json index fe51488c..ec8c8073 100644 --- a/plugins/external.json +++ b/plugins/external.json @@ -1 +1,20 @@ -[] +[ + { + "name": "azure", + "description": "Microsoft Azure MCP Server and skills for cloud resource management, deployments, and Azure services. Manage your Azure infrastructure, monitor applications, and deploy resources directly from Copilot.", + "version": "1.0.0", + "author": { + "name": "Microsoft", + "url": "https://www.microsoft.com" + }, + "homepage": "https://github.com/microsoft/azure-skills", + "keywords": ["azure", "cloud", "infrastructure", "deployment", "microsoft", "devops"], + "license": "MIT", + "repository": "https://github.com/microsoft/github-copilot-for-azure", + "source": { + "source": "github", + "repo": "microsoft/azure-skills", + "path": ".github/plugins/azure-skills" + } + } +] From 13970c3275d4474555656a8efca3b91ca9339f9f Mon Sep 17 00:00:00 2001 From: Tadas Labudis Date: Thu, 5 Mar 2026 21:06:55 +0000 Subject: [PATCH 03/37] Add copilot-spaces skill (#889) * Add copilot-spaces skill for loading project-specific context New skill that teaches agents to use Copilot Spaces MCP tools (list_copilot_spaces, get_copilot_space) to discover and load curated project context into conversations. Covers discovery workflow, loading spaces by owner/name, and using space content to ground responses in team-specific docs, code, and standards. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Improve copilot-spaces skill with real-world usage patterns - Add 'Spaces as workflow engines' pattern for multi-step processes - Add 'Follow the breadcrumbs' step for fetching referenced resources - Document read-only API limitation (no create/update/delete) - Add filtering tip for list_copilot_spaces by owner - Add large output handling guidance (20KB+ spaces) - Add Example 4: Space as a workflow engine - Strengthen tips with actionable guidance Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Add Spaces CRUD REST API to copilot-spaces skill - Document full CRUD API endpoints (create, update, delete, collaborators) - Add 'Managing Spaces' workflow section with gh api examples - Add Example 5: updating Space instructions programmatically - Fix incorrect 'read-only' claim - MCP is read-only, REST API is full CRUD - Add scope requirements (user scope for writes) - Add resource management tips (array replacement, _destroy) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/README.skills.md | 1 + skills/copilot-spaces/SKILL.md | 205 +++++++++++++++++++++++++++++++++ 2 files changed, 206 insertions(+) create mode 100644 skills/copilot-spaces/SKILL.md diff --git a/docs/README.skills.md b/docs/README.skills.md index e90a64b7..ca41e425 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -64,6 +64,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [copilot-cli-quickstart](../skills/copilot-cli-quickstart/SKILL.md) | Use this skill when someone wants to learn GitHub Copilot CLI from scratch. Offers interactive step-by-step tutorials with separate Developer and Non-Developer tracks, plus on-demand Q&A. Just say "start tutorial" or ask a question! Note: This skill targets GitHub Copilot CLI specifically and uses CLI-specific tools (ask_user, sql, fetch_copilot_cli_documentation). | None | | [copilot-instructions-blueprint-generator](../skills/copilot-instructions-blueprint-generator/SKILL.md) | Technology-agnostic blueprint generator for creating comprehensive copilot-instructions.md files that guide GitHub Copilot to produce code consistent with project standards, architecture patterns, and exact technology versions by analyzing existing codebase patterns and avoiding assumptions. | None | | [copilot-sdk](../skills/copilot-sdk/SKILL.md) | Build agentic applications with GitHub Copilot SDK. Use when embedding AI agents in apps, creating custom tools, implementing streaming responses, managing sessions, connecting to MCP servers, or creating custom agents. Triggers on Copilot SDK, GitHub SDK, agentic app, embed Copilot, programmable agent, MCP server, custom agent. | None | +| [copilot-spaces](../skills/copilot-spaces/SKILL.md) | Use Copilot Spaces to provide project-specific context to conversations. Use this skill when users mention a "Copilot space", want to load context from a shared knowledge base, discover available spaces, or ask questions grounded in curated project documentation, code, and instructions. | None | | [copilot-usage-metrics](../skills/copilot-usage-metrics/SKILL.md) | Retrieve and display GitHub Copilot usage metrics for organizations and enterprises using the GitHub CLI and REST API. | `get-enterprise-metrics.sh`
`get-enterprise-user-metrics.sh`
`get-org-metrics.sh`
`get-org-user-metrics.sh` | | [cosmosdb-datamodeling](../skills/cosmosdb-datamodeling/SKILL.md) | Step-by-step guide for capturing key application requirements for NoSQL use-case and produce Azure Cosmos DB Data NoSQL Model design using best practices and common patterns, artifacts_produced: "cosmosdb_requirements.md" file and "cosmosdb_data_model.md" file | None | | [create-agentsmd](../skills/create-agentsmd/SKILL.md) | Prompt for generating an AGENTS.md file for a repository | None | diff --git a/skills/copilot-spaces/SKILL.md b/skills/copilot-spaces/SKILL.md new file mode 100644 index 00000000..616952af --- /dev/null +++ b/skills/copilot-spaces/SKILL.md @@ -0,0 +1,205 @@ +--- +name: copilot-spaces +description: 'Use Copilot Spaces to provide project-specific context to conversations. Use this skill when users mention a "Copilot space", want to load context from a shared knowledge base, discover available spaces, or ask questions grounded in curated project documentation, code, and instructions.' +--- + +# Copilot Spaces + +Use Copilot Spaces to bring curated, project-specific context into conversations. A Space is a shared collection of repositories, files, documentation, and instructions that grounds Copilot responses in your team's actual code and knowledge. + +## Available Tools + +### MCP Tools (Read-only) + +| Tool | Purpose | +|------|---------| +| `mcp__github__list_copilot_spaces` | List all spaces accessible to the current user | +| `mcp__github__get_copilot_space` | Load a space's full context by owner and name | + +### REST API via `gh api` (Full CRUD) + +The Spaces REST API supports creating, updating, deleting spaces, and managing collaborators. The MCP server only exposes read operations, so use `gh api` for writes. + +**User Spaces:** + +| Method | Endpoint | Purpose | +|--------|----------|---------| +| `POST` | `/users/{username}/copilot-spaces` | Create a space | +| `GET` | `/users/{username}/copilot-spaces` | List spaces | +| `GET` | `/users/{username}/copilot-spaces/{number}` | Get a space | +| `PUT` | `/users/{username}/copilot-spaces/{number}` | Update a space | +| `DELETE` | `/users/{username}/copilot-spaces/{number}` | Delete a space | + +**Organization Spaces:** Same pattern under `/orgs/{org}/copilot-spaces/...` + +**Collaborators:** Add, list, update, and remove collaborators at `.../collaborators` + +**Scope requirements:** PAT needs `read:user` for reads, `user` for writes. Add with `gh auth refresh -h github.com -s user`. + +**Note:** This API is functional but not yet in the public REST API docs. It may require the `copilot_spaces_api` feature flag. + +## When to Use Spaces + +- User mentions "Copilot space" or asks to "load a space" +- User wants answers grounded in specific project docs, code, or standards +- User asks "what spaces are available?" or "find a space for X" +- User needs onboarding context, architecture docs, or team-specific guidance +- User wants to follow a structured workflow defined in a Space (templates, checklists, multi-step processes) + +## Workflow + +### 1. Discover Spaces + +When a user asks what spaces are available or you need to find the right space: + +``` +Call mcp__github__list_copilot_spaces +``` + +This returns all spaces the user can access, each with a `name` and `owner_login`. Present relevant matches to the user. + +To filter for a specific user's spaces, match `owner_login` against the username (e.g., "show me my spaces"). + +### 2. Load a Space + +When a user names a specific space or you've identified the right one: + +``` +Call mcp__github__get_copilot_space with: + owner: "org-or-user" (the owner_login from the list) + name: "Space Name" (exact space name, case-sensitive) +``` + +This returns the space's full content: attached documentation, code context, custom instructions, and any other curated materials. Use this context to inform your responses. + +### 3. Follow the Breadcrumbs + +Space content often references external resources: GitHub issues, dashboards, repos, discussions, or other tools. Proactively fetch these using other MCP tools to gather complete context. For example: +- A space references an initiative tracking issue. Use `issue_read` to get the latest comments. +- A space links to a project board. Use project tools to check current status. +- A space mentions a repo's masterplan. Use `get_file_contents` to read it. + +### 4. Answer or Execute + +Once loaded, use the space content based on what it contains: + +**If the space contains reference material** (docs, code, standards): +- Answer questions about the project's architecture, patterns, or standards +- Generate code that follows the team's conventions +- Debug issues using project-specific knowledge + +**If the space contains workflow instructions** (templates, step-by-step processes): +- Follow the workflow as defined, step by step +- Gather data from the sources the workflow specifies +- Produce output in the format the workflow defines +- Show progress after each step so the user can steer + +### 5. Manage Spaces (via `gh api`) + +When a user wants to create, update, or delete a space, use `gh api`. First, find the space number from the list endpoint. + +**Update a space's instructions:** +```bash +gh api users/{username}/copilot-spaces/{number} \ + -X PUT \ + -f general_instructions="New instructions here" +``` + +**Update name, description, or instructions together:** +```bash +gh api users/{username}/copilot-spaces/{number} \ + -X PUT \ + -f name="Updated Name" \ + -f description="Updated description" \ + -f general_instructions="Updated instructions" +``` + +**Create a new space:** +```bash +gh api users/{username}/copilot-spaces \ + -X POST \ + -f name="My New Space" \ + -f general_instructions="Help me with..." \ + -f visibility="private" +``` + +**Attach resources (replaces entire resource list):** +```json +{ + "resources_attributes": [ + { "resource_type": "free_text", "metadata": { "name": "Notes", "text": "Content here" } }, + { "resource_type": "github_issue", "metadata": { "repository_id": 12345, "number": 42 } }, + { "resource_type": "github_file", "metadata": { "repository_id": 12345, "file_path": "docs/guide.md" } } + ] +} +``` + +**Delete a space:** +```bash +gh api users/{username}/copilot-spaces/{number} -X DELETE +``` + +**Updatable fields:** `name`, `description`, `general_instructions`, `icon_type`, `icon_color`, `visibility` ("private"/"public"), `base_role` ("no_access"/"reader"), `resources_attributes` + +## Examples + +### Example 1: User Asks for a Space + +**User**: "Load the Accessibility copilot space" + +**Action**: +1. Call `mcp__github__get_copilot_space` with owner `"github"`, name `"Accessibility"` +2. Use the returned context to answer questions about accessibility standards, MAS grades, compliance processes, etc. + +### Example 2: User Wants to Find Spaces + +**User**: "What copilot spaces are available for our team?" + +**Action**: +1. Call `mcp__github__list_copilot_spaces` +2. Filter/present spaces relevant to the user's org or interests +3. Offer to load any space they're interested in + +### Example 3: Context-Grounded Question + +**User**: "Using the security space, what's our policy on secret scanning?" + +**Action**: +1. Call `mcp__github__get_copilot_space` with the appropriate owner and name +2. Find the relevant policy in the space content +3. Answer based on the actual internal documentation + +### Example 4: Space as a Workflow Engine + +**User**: "Write my weekly update using the PM Weekly Updates space" + +**Action**: +1. Call `mcp__github__get_copilot_space` to load the space. It contains a template format and step-by-step instructions. +2. Follow the space's workflow: pull data from attached initiative issues, gather metrics, draft each section. +3. Fetch external resources referenced by the space (tracking issues, dashboards) using other MCP tools. +4. Show the draft after each section so the user can review and fill in gaps. +5. Produce the final output in the format the space defines. + +### Example 5: Update Space Instructions Programmatically + +**User**: "Update my PM Weekly Updates space to include a new writing guideline" + +**Action**: +1. Call `mcp__github__list_copilot_spaces` and find the space number (e.g., 19). +2. Call `mcp__github__get_copilot_space` to read current instructions. +3. Modify the instructions text as requested. +4. Push the update: +```bash +gh api users/labudis/copilot-spaces/19 -X PUT -f general_instructions="updated instructions..." +``` + +## Tips + +- Space names are **case-sensitive**. Use the exact name from `list_copilot_spaces`. +- Spaces can be owned by users or organizations. Always provide both `owner` and `name`. +- Space content can be large (20KB+). If returned as a temp file, use grep or view_range to find relevant sections rather than reading everything at once. +- If a space isn't found, suggest listing available spaces to find the right name. +- Spaces auto-update as underlying repos change, so the context is always current. +- Some spaces contain custom instructions that should guide your behavior (coding standards, preferred patterns, workflows). Treat these as directives, not suggestions. +- **Write operations** (`gh api` for create/update/delete) require the `user` PAT scope. If you get a 404 on write operations, run `gh auth refresh -h github.com -s user`. +- Resource updates **replace the entire array**. To add a resource, include all existing resources plus the new one. To remove one, include `{ "id": 123, "_destroy": true }` in the array. From f9b08a585fb325e72306baf99306d10d9e219592 Mon Sep 17 00:00:00 2001 From: augustus-0 <113288678+augustus-0@users.noreply.github.com> Date: Fri, 6 Mar 2026 05:09:19 +0800 Subject: [PATCH 04/37] Update README.md (#891) Fixed the installation script --- plugins/structured-autonomy/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/structured-autonomy/README.md b/plugins/structured-autonomy/README.md index 2a69e99a..55abe83f 100644 --- a/plugins/structured-autonomy/README.md +++ b/plugins/structured-autonomy/README.md @@ -6,7 +6,7 @@ Premium planning, thrifty implementation ```bash # Using Copilot CLI -copilot plugin install github/awesome-copilot/plugins/structured-autonomy +copilot plugin install structured-autonomy@awesome-copilot ``` ## What's Included From 9239e8e32065c0a5a37ef58c91174e38b98d72e6 Mon Sep 17 00:00:00 2001 From: Muhammad Ubaid Raza Date: Fri, 6 Mar 2026 02:10:34 +0500 Subject: [PATCH 05/37] feat: Support mulitple browser tools envrionment (#893) - Make browser tester generic to support for chrome devotols mcp, playwright, agentic browser tools. - Add Team lead and energetci peronsality to Orchestrator - Add progress updates between phases/ waves --- .github/plugin/marketplace.json | 4 +- agents/gem-browser-tester.agent.md | 51 +++++++++++++-------- agents/gem-devops.agent.md | 2 +- agents/gem-documentation-writer.agent.md | 2 +- agents/gem-implementer.agent.md | 2 +- agents/gem-orchestrator.agent.md | 16 +++++-- agents/gem-reviewer.agent.md | 2 +- docs/README.agents.md | 4 +- docs/README.plugins.md | 2 +- plugins/gem-team/.github/plugin/plugin.json | 4 +- plugins/gem-team/README.md | 4 +- 11 files changed, 57 insertions(+), 36 deletions(-) diff --git a/.github/plugin/marketplace.json b/.github/plugin/marketplace.json index 66be4b39..c89b38a2 100644 --- a/.github/plugin/marketplace.json +++ b/.github/plugin/marketplace.json @@ -122,8 +122,8 @@ { "name": "gem-team", "source": "gem-team", - "description": "A modular multi-agent team for complex project execution with DAG-based planning, parallel execution, TDD verification, and automated testing.", - "version": "1.2.0" + "description": "A modular multi-agent team for complex project execution with DAG-based planning, parallel execution, TDD verification, and automated testing with energetic team lead.", + "version": "1.2.1" }, { "name": "go-mcp-development", diff --git a/agents/gem-browser-tester.agent.md b/agents/gem-browser-tester.agent.md index a2564d08..68a5c322 100644 --- a/agents/gem-browser-tester.agent.md +++ b/agents/gem-browser-tester.agent.md @@ -1,5 +1,5 @@ --- -description: "Automates browser testing, UI/UX validation using browser automation tools and visual verification techniques" +description: "Automates E2E scenarios with Chrome DevTools MCP, Playwright, Agent Browser. UI/UX validation using browser automation tools and visual verification techniques" name: gem-browser-tester disable-model-invocation: false user-invocable: true @@ -7,24 +7,28 @@ user-invocable: true -BROWSER TESTER: Run E2E tests in browser, verify UI/UX, check accessibility. Deliver test results. Never implement. +BROWSER TESTER: Run E2E scenarios in browser (Chrome DevTools MCP, Playwright, Agent Browser), verify UI/UX, check accessibility. Deliver test results. Never implement. -Browser Automation, E2E Testing, UI Verification, Accessibility +Browser Automation (Chrome DevTools MCP, Playwright, Agent Browser), E2E Testing, UI Verification, Accessibility -- Initialize: Identify plan_id, task_def. Map scenarios. -- Execute: Run scenarios iteratively. For each: - - Navigate to target URL - - Observation-First: Navigate → Snapshot → Action - - Use accessibility snapshots over screenshots for element identification - - Verify outcomes against expected results - - On failure: Capture evidence to docs/plan/{plan_id}/evidence/{task_id}/ -- Verify: Console errors, network requests, accessibility audit per plan -- Handle Failure: Apply mitigation from failure_modes if available -- Log Failure: If status=failed, write to docs/plan/{plan_id}/logs/{agent}_{task_id}_{timestamp}.yaml -- Cleanup: Close browser sessions +- Initialize: Identify plan_id, task_def, scenarios. +- Execute: Run scenarios. For each scenario: + - Verify: list pages to confirm browser state + - Navigate: open new page → capture pageId from response + - Wait: wait for content to load + - Snapshot: take snapshot to get element uids + - Interact: click, fill, etc. + - Verify: Validate outcomes against expected results + - On element not found: Retry with fresh snapshot before failing + - On failure: Capture evidence using filePath parameter +- Finalize Verification (per page): + - Console: get console messages + - Network: get network requests + - Accessibility: audit accessibility +- Cleanup: close page for each scenario - Return JSON per @@ -52,6 +56,7 @@ Browser Automation, E2E Testing, UI Verification, Accessibility "console_errors": "number", "network_failures": "number", "accessibility_issues": "number", + "lighthouse_scores": { "accessibility": "number", "seo": "number", "best_practices": "number" }, "evidence_path": "docs/plan/{plan_id}/evidence/{task_id}/", "failures": [ { @@ -82,10 +87,20 @@ Browser Automation, E2E Testing, UI Verification, Accessibility - Execute autonomously. Never pause for confirmation or progress report. -- Observation-First: Navigate → Snapshot → Action -- Use accessibility snapshots over screenshots -- Verify validation matrix (console, network, accessibility) +- Use pageId on ALL page-scoped tool calls - get from opening new page, use for wait for, take snapshot, take screenshot, click, fill, evaluate script, get console, get network, audit accessibility, close page, etc. +- Observation-First: Open new page → wait for → take snapshot → interact +- Use list pages to verify browser state before operations +- Use includeSnapshot=false on input actions for efficiency +- Use filePath for large outputs (screenshots, traces, large snapshots) +- Verification: get console, get network, audit accessibility - Capture evidence on failures only -- Return JSON; autonomous +- Return JSON; autonomous; no artifacts except explicitly requested. +- Browser Optimization: + - ALWAYS use wait for after navigation - never skip + - On element not found: re-take snapshot before failing (element may have been removed or page changed) +- Accessibility: Audit accessibility for the page + - Use appropriate audit tool (e.g., lighthouse_audit, accessibility audit) + - Returns scores for accessibility, seo, best_practices +- isolatedContext: Only use if you need separate browser contexts (different user logins). For most tests, pageId alone is sufficient. diff --git a/agents/gem-devops.agent.md b/agents/gem-devops.agent.md index 37c77779..e8fda9cf 100644 --- a/agents/gem-devops.agent.md +++ b/agents/gem-devops.agent.md @@ -96,6 +96,6 @@ deployment_approval: - Gate production/security changes via approval - Verify health checks and resources - Remove orphaned resources -- Return JSON; autonomous +- Return JSON; autonomous; no artifacts except explicitly requested. diff --git a/agents/gem-documentation-writer.agent.md b/agents/gem-documentation-writer.agent.md index 77628c62..529f45ab 100644 --- a/agents/gem-documentation-writer.agent.md +++ b/agents/gem-documentation-writer.agent.md @@ -95,6 +95,6 @@ Technical Writing, API Documentation, Diagram Generation, Documentation Maintena - Generate docs with absolute code parity - Use coverage matrix; verify diagrams - Never use TBD/TODO as final -- Return JSON; autonomous +- Return JSON; autonomous; no artifacts except explicitly requested. diff --git a/agents/gem-implementer.agent.md b/agents/gem-implementer.agent.md index 351c4d52..965750cc 100644 --- a/agents/gem-implementer.agent.md +++ b/agents/gem-implementer.agent.md @@ -86,6 +86,6 @@ TDD Implementation, Code Writing, Test Coverage, Debugging - Test behavior, not implementation - Enforce YAGNI, KISS, DRY, Functional Programming - No TBD/TODO as final code -- Return JSON; autonomous +- Return JSON; autonomous; no artifacts except explicitly requested. diff --git a/agents/gem-orchestrator.agent.md b/agents/gem-orchestrator.agent.md index f52742ef..5d7f5637 100644 --- a/agents/gem-orchestrator.agent.md +++ b/agents/gem-orchestrator.agent.md @@ -1,5 +1,5 @@ --- -description: "Coordinates multi-agent workflows, delegates tasks, synthesizes results via runSubagent" +description: "Team Lead - Coordinates multi-agent workflows with energetic announcements, delegates tasks, synthesizes results via runSubagent" name: gem-orchestrator disable-model-invocation: true user-invocable: true @@ -7,7 +7,7 @@ user-invocable: true -ORCHESTRATOR: Coordinate workflow by delegating all tasks. Detect phase → Route to agents → Synthesize results. Never execute workspace modifications directly. +ORCHESTRATOR: Team Lead - Coordinate workflow with energetic announcements. Detect phase → Route to agents → Synthesize results. Never execute workspace modifications directly. @@ -103,7 +103,7 @@ gem-researcher, gem-planner, gem-implementer, gem-browser-tester, gem-devops, ge "task_id": "string", "plan_id": "string", "plan_path": "string", - "validation_matrix": "array of test scenarios" + "task_definition": "object (full task from plan.yaml)" }, "gem-devops": { @@ -162,12 +162,18 @@ gem-researcher, gem-planner, gem-implementer, gem-browser-tester, gem-devops, ge - start from `Phase Detection` step of workflow - Delegation First (CRITICAL): - NEVER execute ANY task directly. ALWAYS delegate to an agent. - - Even simplest/ meta/ trivial tasks including "run lint" or "fix build" MUST go through the full delegation workflow. - - Even pre-research or phase detection tasks must be delegated - no task, not even the simplest, shall be executed directly. + - Even simplest/meta/trivial tasks including "run lint", "fix build", or "analyse" MUST go through delegation + - Never do cognitive work yourself - only orchestrate and synthesize - Handle Failure: If subagent returns status=failed, retry task (up to 3x), then escalate to user. - Manage tasks status updates: - in plan.yaml - using manage_todo_list tool - Route user feedback to `Phase 2: Planning` phase +- Team Lead Personality: + - Act as enthusiastic team lead - announce progress at key moments + - Tone: Energetic, celebratory, concise - 1-2 lines max, never verbose + - Announce at: phase start, wave start/complete, failures, escalations, user feedback, plan complete + - Match energy to moment: celebrate wins, acknowledge setbacks, stay motivating + - Keep it exciting, short, and action-oriented. Use formatting, emojis, and energy diff --git a/agents/gem-reviewer.agent.md b/agents/gem-reviewer.agent.md index a14da41e..2808359a 100644 --- a/agents/gem-reviewer.agent.md +++ b/agents/gem-reviewer.agent.md @@ -102,6 +102,6 @@ Security Auditing, OWASP Top 10, Secret Detection, PRD Compliance, Requirements - Depth-based: full/standard/lightweight - OWASP Top 10, secrets/PII detection - Verify logic against specification AND PRD compliance -- Return JSON; autonomous +- Return JSON; autonomous; no artifacts except explicitly requested. diff --git a/docs/README.agents.md b/docs/README.agents.md index 8d9213b0..fe5e94a7 100644 --- a/docs/README.agents.md +++ b/docs/README.agents.md @@ -80,11 +80,11 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-agents) for guidelines on how to | [Expert React Frontend Engineer](../agents/expert-react-frontend-engineer.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fexpert-react-frontend-engineer.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fexpert-react-frontend-engineer.agent.md) | Expert React 19.2 frontend engineer specializing in modern hooks, Server Components, Actions, TypeScript, and performance optimization | | | [Expert Vue.js Frontend Engineer](../agents/vuejs-expert.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fvuejs-expert.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fvuejs-expert.agent.md) | Expert Vue.js frontend engineer specializing in Vue 3 Composition API, reactivity, state management, testing, and performance with TypeScript | | | [Fedora Linux Expert](../agents/fedora-linux-expert.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Ffedora-linux-expert.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Ffedora-linux-expert.agent.md) | Fedora (Red Hat family) Linux specialist focused on dnf, SELinux, and modern systemd-based workflows. | | -| [Gem Browser Tester](../agents/gem-browser-tester.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-browser-tester.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-browser-tester.agent.md) | Automates browser testing, UI/UX validation using browser automation tools and visual verification techniques | | +| [Gem Browser Tester](../agents/gem-browser-tester.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-browser-tester.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-browser-tester.agent.md) | Automates E2E scenarios with Chrome DevTools MCP, Playwright, Agent Browser. UI/UX validation using browser automation tools and visual verification techniques | | | [Gem Devops](../agents/gem-devops.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-devops.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-devops.agent.md) | Manages containers, CI/CD pipelines, and infrastructure deployment | | | [Gem Documentation Writer](../agents/gem-documentation-writer.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-documentation-writer.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-documentation-writer.agent.md) | Generates technical docs, diagrams, maintains code-documentation parity | | | [Gem Implementer](../agents/gem-implementer.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-implementer.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-implementer.agent.md) | Executes TDD code changes, ensures verification, maintains quality | | -| [Gem Orchestrator](../agents/gem-orchestrator.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-orchestrator.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-orchestrator.agent.md) | Coordinates multi-agent workflows, delegates tasks, synthesizes results via runSubagent | | +| [Gem Orchestrator](../agents/gem-orchestrator.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-orchestrator.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-orchestrator.agent.md) | Team Lead - Coordinates multi-agent workflows with energetic announcements, delegates tasks, synthesizes results via runSubagent | | | [Gem Planner](../agents/gem-planner.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-planner.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-planner.agent.md) | Creates DAG-based plans with pre-mortem analysis and task decomposition from research findings | | | [Gem Researcher](../agents/gem-researcher.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-researcher.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-researcher.agent.md) | Research specialist: gathers codebase context, identifies relevant files/patterns, returns structured findings | | | [Gem Reviewer](../agents/gem-reviewer.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-reviewer.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-reviewer.agent.md) | Security gatekeeper for critical tasks—OWASP, secrets, compliance | | diff --git a/docs/README.plugins.md b/docs/README.plugins.md index 095228f8..dd3afb0b 100644 --- a/docs/README.plugins.md +++ b/docs/README.plugins.md @@ -34,7 +34,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-plugins) for guidelines on how t | [devops-oncall](../plugins/devops-oncall/README.md) | A focused set of prompts, instructions, and a chat mode to help triage incidents and respond quickly with DevOps tools and Azure resources. | 3 items | devops, incident-response, oncall, azure | | [edge-ai-tasks](../plugins/edge-ai-tasks/README.md) | Task Researcher and Task Planner for intermediate to expert users and large codebases - Brought to you by microsoft/edge-ai | 2 items | architecture, planning, research, tasks, implementation | | [frontend-web-dev](../plugins/frontend-web-dev/README.md) | Essential prompts, instructions, and chat modes for modern frontend web development including React, Angular, Vue, TypeScript, and CSS frameworks. | 4 items | frontend, web, react, typescript, javascript, css, html, angular, vue | -| [gem-team](../plugins/gem-team/README.md) | A modular multi-agent team for complex project execution with DAG-based planning, parallel execution, TDD verification, and automated testing. | 8 items | multi-agent, orchestration, dag-planning, parallel-execution, tdd, verification, automation, security, prd | +| [gem-team](../plugins/gem-team/README.md) | A modular multi-agent team for complex project execution with DAG-based planning, parallel execution, TDD verification, and automated testing with energetic team lead. | 8 items | multi-agent, orchestration, dag-planning, parallel-execution, tdd, verification, automation, security, prd | | [go-mcp-development](../plugins/go-mcp-development/README.md) | Complete toolkit for building Model Context Protocol (MCP) servers in Go using the official github.com/modelcontextprotocol/go-sdk. Includes instructions for best practices, a prompt for generating servers, and an expert chat mode for guidance. | 2 items | go, golang, mcp, model-context-protocol, server-development, sdk | | [java-development](../plugins/java-development/README.md) | Comprehensive collection of prompts and instructions for Java development including Spring Boot, Quarkus, testing, documentation, and best practices. | 4 items | java, springboot, quarkus, jpa, junit, javadoc | | [java-mcp-development](../plugins/java-mcp-development/README.md) | Complete toolkit for building Model Context Protocol servers in Java using the official MCP Java SDK with reactive streams and Spring Boot integration. | 2 items | java, mcp, model-context-protocol, server-development, sdk, reactive-streams, spring-boot, reactor | diff --git a/plugins/gem-team/.github/plugin/plugin.json b/plugins/gem-team/.github/plugin/plugin.json index 79b32afe..6f756168 100644 --- a/plugins/gem-team/.github/plugin/plugin.json +++ b/plugins/gem-team/.github/plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "gem-team", - "description": "A modular multi-agent team for complex project execution with DAG-based planning, parallel execution, TDD verification, and automated testing.", - "version": "1.2.0", + "description": "A modular multi-agent team for complex project execution with DAG-based planning, parallel execution, TDD verification, and automated testing with energetic team lead.", + "version": "1.2.1", "author": { "name": "Awesome Copilot Community" }, diff --git a/plugins/gem-team/README.md b/plugins/gem-team/README.md index 321c64a9..703437a0 100644 --- a/plugins/gem-team/README.md +++ b/plugins/gem-team/README.md @@ -15,11 +15,11 @@ copilot plugin install gem-team@awesome-copilot | Agent | Description | |-------|-------------| -| `gem-orchestrator` | Coordinates multi-agent workflows, delegates tasks, synthesizes results via runSubagent | +| `gem-orchestrator` | Team Lead - Coordinates multi-agent workflows with energetic announcements, delegates tasks, synthesizes results via runSubagent | | `gem-researcher` | Research specialist: gathers codebase context, identifies relevant files/patterns, returns structured findings | | `gem-planner` | Creates DAG-based plans with pre-mortem analysis and task decomposition from research findings | | `gem-implementer` | Executes TDD code changes, ensures verification, maintains quality | -| `gem-chrome-tester` | Automates browser testing, UI/UX validation via Chrome DevTools | +| `gem-browser-tester` | Automates E2E scenarios with Chrome DevTools MCP, Playwright, Agent Browser. UI/UX validation using browser automation tools and visual verification techniques | | `gem-devops` | Manages containers, CI/CD pipelines, and infrastructure deployment | | `gem-reviewer` | Security gatekeeper for critical tasks—OWASP, secrets, compliance | | `gem-documentation-writer` | Generates technical docs, diagrams, maintains code-documentation parity | From 78e3ea29c2df83640c94924c3816f2d177f83d4b Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Fri, 6 Mar 2026 10:22:25 +1100 Subject: [PATCH 06/37] [WIP] Fix URL path issue in learning hub (#895) * Initial plan * fix: use relative links in learning-hub index to preserve base path Co-authored-by: aaronpowell <434140+aaronpowell@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: aaronpowell <434140+aaronpowell@users.noreply.github.com> --- website/src/content/docs/learning-hub/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/website/src/content/docs/learning-hub/index.md b/website/src/content/docs/learning-hub/index.md index 538e51ec..86f8ac50 100644 --- a/website/src/content/docs/learning-hub/index.md +++ b/website/src/content/docs/learning-hub/index.md @@ -16,17 +16,17 @@ tableOfContents: false ## Fundamentals Essential concepts to tailor GitHub Copilot beyond its default experience. Start with -[What are Agents, Skills, and Instructions](/learning-hub/what-are-agents-skills-instructions/) +[What are Agents, Skills, and Instructions](what-are-agents-skills-instructions/) and work through the full track to master every customization primitive. ## Reference Quick-lookup resources to keep handy while you work. Browse the -[GitHub Copilot Terminology Glossary](/learning-hub/github-copilot-terminology-glossary/) +[GitHub Copilot Terminology Glossary](github-copilot-terminology-glossary/) for definitions of common terms and concepts. ## Hands-on Interactive samples and recipes to learn by doing. Jump into the -[Cookbook](/learning-hub/cookbook/) for code samples, recipes, +[Cookbook](cookbook/) for code samples, recipes, and examples you can use right away. From 4707565c7b50c8ae36adee182e8e86ce56e8ee40 Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Fri, 6 Mar 2026 13:57:39 +1100 Subject: [PATCH 07/37] [WIP] Update text colour for improved navigation readability (#897) * Initial plan * fix: improve readability of active nav item on learning hub pages Co-authored-by: aaronpowell <434140+aaronpowell@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: aaronpowell <434140+aaronpowell@users.noreply.github.com> --- website/src/styles/starlight-overrides.css | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/src/styles/starlight-overrides.css b/website/src/styles/starlight-overrides.css index c1d55cb6..0761c39c 100644 --- a/website/src/styles/starlight-overrides.css +++ b/website/src/styles/starlight-overrides.css @@ -43,7 +43,7 @@ /* ── Sidebar active item ───────────────────────────────────── */ nav[aria-label="Main"] a[aria-current="page"] { - color: var(--sl-color-accent) !important; + color: var(--sl-color-white) !important; font-weight: 600; border-inline-start-color: var(--sl-color-accent) !important; } From f3142d77c15f40fb6910f1093f385df9c4c691e6 Mon Sep 17 00:00:00 2001 From: Catherine Han <123369259+ninihen1@users.noreply.github.com> Date: Fri, 6 Mar 2026 15:16:11 +1100 Subject: [PATCH 08/37] feat: add power-automate-mcp skill (#896) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat: add power-automate-mcp skill Connect to and operate Power Automate cloud flows via a FlowStudio MCP server. Includes tool reference, action types, connection references, and bootstrap guide. * fix: rename skill & address review feedback - Rename power-automate-mcp → flowstudio-power-automate-mcp - Fix list_live_flows docs: returns wrapper object {mode, flows, totalCount, error}, not direct array - Fix next() syntax: add parens for generator with default arg - Add User-Agent header to tools/list discovery example - Standardize User-Agent to FlowStudio-MCP/1.0 (required by Cloudflare) - Add environmentName note for list_live_connections (required despite schema) - Update list_live_flows response shape in tool-reference.md All response shapes verified against live MCP server. --- docs/README.skills.md | 1 + skills/flowstudio-power-automate-mcp/SKILL.md | 450 ++++++++++++++++++ .../references/MCP-BOOTSTRAP.md | 53 +++ .../references/action-types.md | 79 +++ .../references/connection-references.md | 115 +++++ .../references/tool-reference.md | 445 +++++++++++++++++ 6 files changed, 1143 insertions(+) create mode 100644 skills/flowstudio-power-automate-mcp/SKILL.md create mode 100644 skills/flowstudio-power-automate-mcp/references/MCP-BOOTSTRAP.md create mode 100644 skills/flowstudio-power-automate-mcp/references/action-types.md create mode 100644 skills/flowstudio-power-automate-mcp/references/connection-references.md create mode 100644 skills/flowstudio-power-automate-mcp/references/tool-reference.md diff --git a/docs/README.skills.md b/docs/README.skills.md index ca41e425..ef0c8124 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -112,6 +112,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [finalize-agent-prompt](../skills/finalize-agent-prompt/SKILL.md) | Finalize prompt file using the role of an AI agent to polish the prompt for the end user. | None | | [finnish-humanizer](../skills/finnish-humanizer/SKILL.md) | Detect and remove AI-generated markers from Finnish text, making it sound like a native Finnish speaker wrote it. Use when asked to "humanize", "naturalize", or "remove AI feel" from Finnish text, or when editing .md/.txt files containing Finnish content. Identifies 26 patterns (12 Finnish-specific + 14 universal) and 4 style markers. | `references/patterns.md` | | [first-ask](../skills/first-ask/SKILL.md) | Interactive, input-tool powered, task refinement workflow: interrogates scope, deliverables, constraints before carrying out the task; Requires the Joyride extension. | None | +| [flowstudio-power-automate-mcp](../skills/flowstudio-power-automate-mcp/SKILL.md) | Connect to and operate Power Automate cloud flows via a FlowStudio MCP server. Use when asked to: list flows, read a flow definition, check run history, inspect action outputs, resubmit a run, cancel a running flow, view connections, get a trigger URL, validate a definition, monitor flow health, or any task that requires talking to the Power Automate API through an MCP tool. Also use for Power Platform environment discovery and connection management. Requires a FlowStudio MCP subscription or compatible server — see https://mcp.flowstudio.app | `references/MCP-BOOTSTRAP.md`
`references/action-types.md`
`references/connection-references.md`
`references/tool-reference.md` | | [fluentui-blazor](../skills/fluentui-blazor/SKILL.md) | Guide for using the Microsoft Fluent UI Blazor component library (Microsoft.FluentUI.AspNetCore.Components NuGet package) in Blazor applications. Use this when the user is building a Blazor app with Fluent UI components, setting up the library, using FluentUI components like FluentButton, FluentDataGrid, FluentDialog, FluentToast, FluentNavMenu, FluentTextField, FluentSelect, FluentAutocomplete, FluentDesignTheme, or any component prefixed with "Fluent". Also use when troubleshooting missing providers, JS interop issues, or theming. | `references/DATAGRID.md`
`references/LAYOUT-AND-NAVIGATION.md`
`references/SETUP.md`
`references/THEMING.md` | | [folder-structure-blueprint-generator](../skills/folder-structure-blueprint-generator/SKILL.md) | Comprehensive technology-agnostic prompt for analyzing and documenting project folder structures. Auto-detects project types (.NET, Java, React, Angular, Python, Node.js, Flutter), generates detailed blueprints with visualization options, naming conventions, file placement patterns, and extension templates for maintaining consistent code organization across diverse technology stacks. | None | | [game-engine](../skills/game-engine/SKILL.md) | Expert skill for building web-based game engines and games using HTML5, Canvas, WebGL, and JavaScript. Use when asked to create games, build game engines, implement game physics, handle collision detection, set up game loops, manage sprites, add game controls, or work with 2D/3D rendering. Covers techniques for platformers, breakout-style games, maze games, tilemaps, audio, multiplayer via WebRTC, and publishing games. | `assets/2d-maze-game.md`
`assets/2d-platform-game.md`
`assets/gameBase-template-repo.md`
`assets/paddle-game-template.md`
`assets/simple-2d-engine.md`
`references/3d-web-games.md`
`references/algorithms.md`
`references/basics.md`
`references/game-control-mechanisms.md`
`references/game-engine-core-principles.md`
`references/game-publishing.md`
`references/techniques.md`
`references/terminology.md`
`references/web-apis.md` | diff --git a/skills/flowstudio-power-automate-mcp/SKILL.md b/skills/flowstudio-power-automate-mcp/SKILL.md new file mode 100644 index 00000000..7866ed27 --- /dev/null +++ b/skills/flowstudio-power-automate-mcp/SKILL.md @@ -0,0 +1,450 @@ +--- +name: flowstudio-power-automate-mcp +description: >- + Connect to and operate Power Automate cloud flows via a FlowStudio MCP server. + Use when asked to: list flows, read a flow definition, check run history, inspect + action outputs, resubmit a run, cancel a running flow, view connections, get a + trigger URL, validate a definition, monitor flow health, or any task that requires + talking to the Power Automate API through an MCP tool. Also use for Power Platform + environment discovery and connection management. Requires a FlowStudio MCP + subscription or compatible server — see https://mcp.flowstudio.app +--- + +# Power Automate via FlowStudio MCP + +This skill lets AI agents read, monitor, and operate Microsoft Power Automate +cloud flows programmatically through a **FlowStudio MCP server** — no browser, +no UI, no manual steps. + +> **Requires:** A [FlowStudio](https://mcp.flowstudio.app) MCP subscription (or +> compatible Power Automate MCP server). You will need: +> - MCP endpoint: `https://mcp.flowstudio.app/mcp` (same for all subscribers) +> - API key / JWT token (`x-api-key` header — NOT Bearer) +> - Power Platform environment name (e.g. `Default-`) + +--- + +## Source of Truth + +| Priority | Source | Covers | +|----------|--------|--------| +| 1 | **Real API response** | Always trust what the server actually returns | +| 2 | **`tools/list`** | Tool names, parameter names, types, required flags | +| 3 | **SKILL docs & reference files** | Response shapes, behavioral notes, workflow recipes | + +> **Start every new session with `tools/list`.** +> It returns the authoritative, up-to-date schema for every tool — parameter names, +> types, and required flags. The SKILL docs cover what `tools/list` cannot tell you: +> response shapes, non-obvious behaviors, and end-to-end workflow patterns. +> +> If any documentation disagrees with `tools/list` or a real API response, +> the API wins. + +--- + +## Recommended Language: Python or Node.js + +All examples in this skill and the companion build / debug skills use **Python +with `urllib.request`** (stdlib — no `pip install` needed). **Node.js** is an +equally valid choice: `fetch` is built-in from Node 18+, JSON handling is +native, and the async/await model maps cleanly onto the request-response pattern +of MCP tool calls — making it a natural fit for teams already working in a +JavaScript/TypeScript stack. + +| Language | Verdict | Notes | +|---|---|---| +| **Python** | ✅ Recommended | Clean JSON handling, no escaping issues, all skill examples use it | +| **Node.js (≥ 18)** | ✅ Recommended | Native `fetch` + `JSON.stringify`/`JSON.parse`; async/await fits MCP call patterns well; no extra packages needed | +| PowerShell | ⚠️ Avoid for flow operations | `ConvertTo-Json -Depth` silently truncates nested definitions; quoting and escaping break complex payloads. Acceptable for a quick `tools/list` discovery call but not for building or updating flows. | +| cURL / Bash | ⚠️ Possible but fragile | Shell-escaping nested JSON is error-prone; no native JSON parser | + +> **TL;DR — use the Core MCP Helper (Python or Node.js) below.** Both handle +> JSON-RPC framing, auth, and response parsing in a single reusable function. + +--- + +## What You Can Do + +FlowStudio MCP has two access tiers. **FlowStudio for Teams** subscribers get +both the fast Azure-table store (cached snapshot data + governance metadata) and +full live Power Automate API access. **MCP-only subscribers** get the live tools — +more than enough to build, debug, and operate flows. + +### Live Tools — Available to All MCP Subscribers + +| Tool | What it does | +|---|---| +| `list_live_flows` | List flows in an environment directly from the PA API (always current) | +| `list_live_environments` | List all Power Platform environments visible to the service account | +| `list_live_connections` | List all connections in an environment from the PA API | +| `get_live_flow` | Fetch the complete flow definition (triggers, actions, parameters) | +| `get_live_flow_http_schema` | Inspect the JSON body schema and response schemas of an HTTP-triggered flow | +| `get_live_flow_trigger_url` | Get the current signed callback URL for an HTTP-triggered flow | +| `trigger_live_flow` | POST to an HTTP-triggered flow's callback URL (AAD auth handled automatically) | +| `update_live_flow` | Create a new flow or patch an existing definition in one call | +| `add_live_flow_to_solution` | Migrate a non-solution flow into a solution | +| `get_live_flow_runs` | List recent run history with status, start/end times, and errors | +| `get_live_flow_run_error` | Get structured error details (per-action) for a failed run | +| `get_live_flow_run_action_outputs` | Inspect inputs/outputs of any action (or every foreach iteration) in a run | +| `resubmit_live_flow_run` | Re-run a failed or cancelled run using its original trigger payload | +| `cancel_live_flow_run` | Cancel a currently running flow execution | + +### Store Tools — FlowStudio for Teams Subscribers Only + +These tools read from (and write to) the FlowStudio Azure table — a monitored +snapshot of your tenant's flows enriched with governance metadata and run statistics. + +| Tool | What it does | +|---|---| +| `list_store_flows` | Search flows from the cache with governance flags, run failure rates, and owner metadata | +| `get_store_flow` | Get full cached details for a single flow including run stats and governance fields | +| `get_store_flow_trigger_url` | Get the trigger URL from the cache (instant, no PA API call) | +| `get_store_flow_runs` | Cached run history for the last N days with duration and remediation hints | +| `get_store_flow_errors` | Cached failed-only runs with failed action names and remediation hints | +| `get_store_flow_summary` | Aggregated stats: success rate, failure count, avg/max duration | +| `set_store_flow_state` | Start or stop a flow via the PA API and sync the result back to the store | +| `update_store_flow` | Update governance metadata (description, tags, monitor flag, notification rules, business impact) | +| `list_store_environments` | List all environments from the cache | +| `list_store_makers` | List all makers (citizen developers) from the cache | +| `get_store_maker` | Get a maker's flow/app counts and account status | +| `list_store_power_apps` | List all Power Apps canvas apps from the cache | +| `list_store_connections` | List all Power Platform connections from the cache | + +--- + +## Which Tool Tier to Call First + +| Task | Tool | Notes | +|---|---|---| +| List flows | `list_live_flows` | Always current — calls PA API directly | +| Read a definition | `get_live_flow` | Always fetched live — not cached | +| Debug a failure | `get_live_flow_runs` → `get_live_flow_run_error` | Use live run data | + +> ⚠️ **`list_live_flows` returns a wrapper object** with a `flows` array — access via `result["flows"]`. + +> Store tools (`list_store_flows`, `get_store_flow`, etc.) are available to **FlowStudio for Teams** subscribers and provide cached governance metadata. Use live tools when in doubt — they work for all subscription tiers. + +--- + +## Step 0 — Discover Available Tools + +Always start by calling `tools/list` to confirm the server is reachable and see +exactly which tool names are available (names may vary by server version): + +```python +import json, urllib.request + +TOKEN = "" +MCP = "https://mcp.flowstudio.app/mcp" + +def mcp_raw(method, params=None, cid=1): + payload = {"jsonrpc": "2.0", "method": method, "id": cid} + if params: + payload["params"] = params + req = urllib.request.Request(MCP, data=json.dumps(payload).encode(), + headers={"x-api-key": TOKEN, "Content-Type": "application/json", + "User-Agent": "FlowStudio-MCP/1.0"}) + try: + resp = urllib.request.urlopen(req, timeout=30) + except urllib.error.HTTPError as e: + raise RuntimeError(f"MCP HTTP {e.code} — check token and endpoint") from e + return json.loads(resp.read()) + +raw = mcp_raw("tools/list") +if "error" in raw: + print("ERROR:", raw["error"]); raise SystemExit(1) +for t in raw["result"]["tools"]: + print(t["name"], "—", t["description"][:60]) +``` + +--- + +## Core MCP Helper (Python) + +Use this helper throughout all subsequent operations: + +```python +import json, urllib.request + +TOKEN = "" +MCP = "https://mcp.flowstudio.app/mcp" + +def mcp(tool, args, cid=1): + payload = {"jsonrpc": "2.0", "method": "tools/call", "id": cid, + "params": {"name": tool, "arguments": args}} + req = urllib.request.Request(MCP, data=json.dumps(payload).encode(), + headers={"x-api-key": TOKEN, "Content-Type": "application/json", + "User-Agent": "FlowStudio-MCP/1.0"}) + try: + resp = urllib.request.urlopen(req, timeout=120) + except urllib.error.HTTPError as e: + body = e.read().decode("utf-8", errors="replace") + raise RuntimeError(f"MCP HTTP {e.code}: {body[:200]}") from e + raw = json.loads(resp.read()) + if "error" in raw: + raise RuntimeError(f"MCP error: {json.dumps(raw['error'])}") + text = raw["result"]["content"][0]["text"] + return json.loads(text) +``` + +> **Common auth errors:** +> - HTTP 401/403 → token is missing, expired, or malformed. Get a fresh JWT from [mcp.flowstudio.app](https://mcp.flowstudio.app). +> - HTTP 400 → malformed JSON-RPC payload. Check `Content-Type: application/json` and body structure. +> - `MCP error: {"code": -32602, ...}` → wrong or missing tool arguments. + +--- + +## Core MCP Helper (Node.js) + +Equivalent helper for Node.js 18+ (built-in `fetch` — no packages required): + +```js +const TOKEN = ""; +const MCP = "https://mcp.flowstudio.app/mcp"; + +async function mcp(tool, args, cid = 1) { + const payload = { + jsonrpc: "2.0", + method: "tools/call", + id: cid, + params: { name: tool, arguments: args }, + }; + const res = await fetch(MCP, { + method: "POST", + headers: { + "x-api-key": TOKEN, + "Content-Type": "application/json", + "User-Agent": "FlowStudio-MCP/1.0", + }, + body: JSON.stringify(payload), + }); + if (!res.ok) { + const body = await res.text(); + throw new Error(`MCP HTTP ${res.status}: ${body.slice(0, 200)}`); + } + const raw = await res.json(); + if (raw.error) throw new Error(`MCP error: ${JSON.stringify(raw.error)}`); + return JSON.parse(raw.result.content[0].text); +} +``` + +> Requires Node.js 18+. For older Node, replace `fetch` with `https.request` +> from the stdlib or install `node-fetch`. + +--- + +## List Flows + +```python +ENV = "Default-" + +result = mcp("list_live_flows", {"environmentName": ENV}) +# Returns wrapper object: +# {"mode": "owner", "flows": [{"id": "0757041a-...", "displayName": "My Flow", +# "state": "Started", "triggerType": "Request", ...}], "totalCount": 42, "error": null} +for f in result["flows"]: + FLOW_ID = f["id"] # plain UUID — use directly as flowName + print(FLOW_ID, "|", f["displayName"], "|", f["state"]) +``` + +--- + +## Read a Flow Definition + +```python +FLOW = "" + +flow = mcp("get_live_flow", {"environmentName": ENV, "flowName": FLOW}) + +# Display name and state +print(flow["properties"]["displayName"]) +print(flow["properties"]["state"]) + +# List all action names +actions = flow["properties"]["definition"]["actions"] +print("Actions:", list(actions.keys())) + +# Inspect one action's expression +print(actions["Compose_Filter"]["inputs"]) +``` + +--- + +## Check Run History + +```python +# Most recent runs (newest first) +runs = mcp("get_live_flow_runs", {"environmentName": ENV, "flowName": FLOW, "top": 5}) +# Returns direct array: +# [{"name": "08584296068667933411438594643CU15", +# "status": "Failed", +# "startTime": "2026-02-25T06:13:38.6910688Z", +# "endTime": "2026-02-25T06:15:24.1995008Z", +# "triggerName": "manual", +# "error": {"code": "ActionFailed", "message": "An action failed..."}}, +# {"name": "08584296028664130474944675379CU26", +# "status": "Succeeded", "error": null, ...}] + +for r in runs: + print(r["name"], r["status"]) + +# Get the name of the first failed run +run_id = next((r["name"] for r in runs if r["status"] == "Failed"), None) +``` + +--- + +## Inspect an Action's Output + +```python +run_id = runs[0]["name"] + +out = mcp("get_live_flow_run_action_outputs", { + "environmentName": ENV, + "flowName": FLOW, + "runName": run_id, + "actionName": "Get_Customer_Record" # exact action name from the definition +}) +print(json.dumps(out, indent=2)) +``` + +--- + +## Get a Run's Error + +```python +err = mcp("get_live_flow_run_error", { + "environmentName": ENV, + "flowName": FLOW, + "runName": run_id +}) +# Returns: +# {"runName": "08584296068...", +# "failedActions": [ +# {"actionName": "HTTP_find_AD_User_by_Name", "status": "Failed", +# "code": "NotSpecified", "startTime": "...", "endTime": "..."}, +# {"actionName": "Scope_prepare_workers", "status": "Failed", +# "error": {"code": "ActionFailed", "message": "An action failed..."}} +# ], +# "allActions": [ +# {"actionName": "Apply_to_each", "status": "Skipped"}, +# {"actionName": "Compose_WeekEnd", "status": "Succeeded"}, +# ... +# ]} + +# The ROOT cause is usually the deepest entry in failedActions: +root = err["failedActions"][-1] +print(f"Root failure: {root['actionName']} → {root['code']}") +``` + +--- + +## Resubmit a Run + +```python +result = mcp("resubmit_live_flow_run", { + "environmentName": ENV, + "flowName": FLOW, + "runName": run_id +}) +print(result) # {"resubmitted": true, "triggerName": "..."} +``` + +--- + +## Cancel a Running Run + +```python +mcp("cancel_live_flow_run", { + "environmentName": ENV, + "flowName": FLOW, + "runName": run_id +}) +``` + +> ⚠️ **Do NOT cancel a run that shows `Running` because it is waiting for an +> adaptive card response.** That status is normal — the flow is paused waiting +> for a human to respond in Teams. Cancelling it will discard the pending card. + +--- + +## Full Round-Trip Example — Debug and Fix a Failing Flow + +```python +# ── 1. Find the flow ───────────────────────────────────────────────────── +result = mcp("list_live_flows", {"environmentName": ENV}) +target = next(f for f in result["flows"] if "My Flow Name" in f["displayName"]) +FLOW_ID = target["id"] + +# ── 2. Get the most recent failed run ──────────────────────────────────── +runs = mcp("get_live_flow_runs", {"environmentName": ENV, "flowName": FLOW_ID, "top": 5}) +# [{"name": "08584296068...", "status": "Failed", ...}, ...] +RUN_ID = next(r["name"] for r in runs if r["status"] == "Failed") + +# ── 3. Get per-action failure breakdown ────────────────────────────────── +err = mcp("get_live_flow_run_error", {"environmentName": ENV, "flowName": FLOW_ID, "runName": RUN_ID}) +# {"failedActions": [{"actionName": "HTTP_find_AD_User_by_Name", "code": "NotSpecified",...}], ...} +root_action = err["failedActions"][-1]["actionName"] +print(f"Root failure: {root_action}") + +# ── 4. Read the definition and inspect the failing action's expression ─── +defn = mcp("get_live_flow", {"environmentName": ENV, "flowName": FLOW_ID}) +acts = defn["properties"]["definition"]["actions"] +print("Failing action inputs:", acts[root_action]["inputs"]) + +# ── 5. Inspect the prior action's output to find the null ──────────────── +out = mcp("get_live_flow_run_action_outputs", { + "environmentName": ENV, "flowName": FLOW_ID, + "runName": RUN_ID, "actionName": "Compose_Names" +}) +nulls = [x for x in out.get("body", []) if x.get("Name") is None] +print(f"{len(nulls)} records with null Name") + +# ── 6. Apply the fix ───────────────────────────────────────────────────── +acts[root_action]["inputs"]["parameters"]["searchName"] = \ + "@coalesce(item()?['Name'], '')" + +conn_refs = defn["properties"]["connectionReferences"] +result = mcp("update_live_flow", { + "environmentName": ENV, "flowName": FLOW_ID, + "definition": defn["properties"]["definition"], + "connectionReferences": conn_refs +}) +assert result.get("error") is None, f"Deploy failed: {result['error']}" +# ⚠️ error key is always present — only fail if it is NOT None + +# ── 7. Resubmit and verify ─────────────────────────────────────────────── +mcp("resubmit_live_flow_run", {"environmentName": ENV, "flowName": FLOW_ID, "runName": RUN_ID}) + +import time; time.sleep(30) +new_runs = mcp("get_live_flow_runs", {"environmentName": ENV, "flowName": FLOW_ID, "top": 1}) +print(new_runs[0]["status"]) # Succeeded = done +``` + +--- + +## Auth & Connection Notes + +| Field | Value | +|---|---| +| Auth header | `x-api-key: ` — **not** `Authorization: Bearer` | +| Token format | Plain JWT — do not strip, alter, or prefix it | +| Timeout | Use ≥ 120 s for `get_live_flow_run_action_outputs` (large outputs) | +| Environment name | `Default-` (find it via `list_live_environments` or `list_live_flows` response) | + +--- + +## Reference Files + +- [MCP-BOOTSTRAP.md](references/MCP-BOOTSTRAP.md) — endpoint, auth, request/response format (read this first) +- [tool-reference.md](references/tool-reference.md) — response shapes and behavioral notes (parameters are in `tools/list`) +- [action-types.md](references/action-types.md) — Power Automate action type patterns +- [connection-references.md](references/connection-references.md) — connector reference guide + +--- + +## More Capabilities + +For **diagnosing failing flows** end-to-end → load the `power-automate-debug` skill. + +For **building and deploying new flows** → load the `power-automate-build` skill. diff --git a/skills/flowstudio-power-automate-mcp/references/MCP-BOOTSTRAP.md b/skills/flowstudio-power-automate-mcp/references/MCP-BOOTSTRAP.md new file mode 100644 index 00000000..7dc71605 --- /dev/null +++ b/skills/flowstudio-power-automate-mcp/references/MCP-BOOTSTRAP.md @@ -0,0 +1,53 @@ +# MCP Bootstrap — Quick Reference + +Everything an agent needs to start calling the FlowStudio MCP server. + +``` +Endpoint: https://mcp.flowstudio.app/mcp +Protocol: JSON-RPC 2.0 over HTTP POST +Transport: Streamable HTTP — single POST per request, no SSE, no WebSocket +Auth: x-api-key header with JWT token (NOT Bearer) +``` + +## Required Headers + +``` +Content-Type: application/json +x-api-key: +User-Agent: FlowStudio-MCP/1.0 ← required, or Cloudflare blocks you +``` + +## Step 1 — Discover Tools + +```json +POST {"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}} +``` + +Returns all tools with names, descriptions, and input schemas. +Free — not counted against plan limits. + +## Step 2 — Call a Tool + +```json +POST {"jsonrpc":"2.0","id":1,"method":"tools/call", + "params":{"name":"","arguments":{...}}} +``` + +## Response Shape + +``` +Success → {"result":{"content":[{"type":"text","text":""}]}} +Error → {"result":{"content":[{"type":"text","text":"{\"error\":{...}}"}]}} +``` + +Always parse `result.content[0].text` as JSON to get the actual data. + +## Key Tips + +- Tool results are JSON strings inside the text field — **double-parse needed** +- `"error"` field in parsed body: `null` = success, object = failure +- `environmentName` is required for most tools, but **not** for: + `list_live_environments`, `list_live_connections`, `list_store_flows`, + `list_store_environments`, `list_store_makers`, `get_store_maker`, + `list_store_power_apps`, `list_store_connections` +- When in doubt, check the `required` array in each tool's schema from `tools/list` diff --git a/skills/flowstudio-power-automate-mcp/references/action-types.md b/skills/flowstudio-power-automate-mcp/references/action-types.md new file mode 100644 index 00000000..42507ce7 --- /dev/null +++ b/skills/flowstudio-power-automate-mcp/references/action-types.md @@ -0,0 +1,79 @@ +# FlowStudio MCP — Action Types Reference + +Compact lookup for recognising action types returned by `get_live_flow`. +Use this to **read and understand** existing flow definitions. + +> For full copy-paste construction patterns, see the `power-automate-build` skill. + +--- + +## How to Read a Flow Definition + +Every action has `"type"`, `"runAfter"`, and `"inputs"`. The `runAfter` object +declares dependencies: `{"Previous": ["Succeeded"]}`. Valid statuses: +`Succeeded`, `Failed`, `Skipped`, `TimedOut`. + +--- + +## Action Type Quick Reference + +| Type | Purpose | Key fields to inspect | Output reference | +|---|---|---|---| +| `Compose` | Store/transform a value | `inputs` (any expression) | `outputs('Name')` | +| `InitializeVariable` | Declare a variable | `inputs.variables[].{name, type, value}` | `variables('name')` | +| `SetVariable` | Update a variable | `inputs.{name, value}` | `variables('name')` | +| `IncrementVariable` | Increment a numeric variable | `inputs.{name, value}` | `variables('name')` | +| `AppendToArrayVariable` | Push to an array variable | `inputs.{name, value}` | `variables('name')` | +| `If` | Conditional branch | `expression.and/or`, `actions`, `else.actions` | — | +| `Switch` | Multi-way branch | `expression`, `cases.{case, actions}`, `default` | — | +| `Foreach` | Loop over array | `foreach`, `actions`, `operationOptions` | `item()` / `items('Name')` | +| `Until` | Loop until condition | `expression`, `limit.{count, timeout}`, `actions` | — | +| `Wait` | Delay | `inputs.interval.{count, unit}` | — | +| `Scope` | Group / try-catch | `actions` (nested action map) | `result('Name')` | +| `Terminate` | End run | `inputs.{runStatus, runError}` | — | +| `OpenApiConnection` | Connector call (SP, Outlook, Teams…) | `inputs.host.{apiId, connectionName, operationId}`, `inputs.parameters` | `outputs('Name')?['body/...']` | +| `OpenApiConnectionWebhook` | Webhook wait (approvals, adaptive cards) | same as above | `body('Name')?['...']` | +| `Http` | External HTTP call | `inputs.{method, uri, headers, body}` | `outputs('Name')?['body']` | +| `Response` | Return to HTTP caller | `inputs.{statusCode, headers, body}` | — | +| `Query` | Filter array | `inputs.{from, where}` | `body('Name')` (filtered array) | +| `Select` | Reshape/project array | `inputs.{from, select}` | `body('Name')` (projected array) | +| `Table` | Array → CSV/HTML string | `inputs.{from, format, columns}` | `body('Name')` (string) | +| `ParseJson` | Parse JSON with schema | `inputs.{content, schema}` | `body('Name')?['field']` | +| `Expression` | Built-in function (e.g. ConvertTimeZone) | `kind`, `inputs` | `body('Name')` | + +--- + +## Connector Identification + +When you see `type: OpenApiConnection`, identify the connector from `host.apiId`: + +| apiId suffix | Connector | +|---|---| +| `shared_sharepointonline` | SharePoint | +| `shared_office365` | Outlook / Office 365 | +| `shared_teams` | Microsoft Teams | +| `shared_approvals` | Approvals | +| `shared_office365users` | Office 365 Users | +| `shared_flowmanagement` | Flow Management | + +The `operationId` tells you the specific operation (e.g. `GetItems`, `SendEmailV2`, +`PostMessageToConversation`). The `connectionName` maps to a GUID in +`properties.connectionReferences`. + +--- + +## Common Expressions (Reading Cheat Sheet) + +| Expression | Meaning | +|---|---| +| `@outputs('X')?['body/value']` | Array result from connector action X | +| `@body('X')` | Direct body of action X (Query, Select, ParseJson) | +| `@item()?['Field']` | Current loop item's field | +| `@triggerBody()?['Field']` | Trigger payload field | +| `@variables('name')` | Variable value | +| `@coalesce(a, b)` | First non-null of a, b | +| `@first(array)` | First element (null if empty) | +| `@length(array)` | Array count | +| `@empty(value)` | True if null/empty string/empty array | +| `@union(a, b)` | Merge arrays — **first wins** on duplicates | +| `@result('Scope')` | Array of action outcomes inside a Scope | diff --git a/skills/flowstudio-power-automate-mcp/references/connection-references.md b/skills/flowstudio-power-automate-mcp/references/connection-references.md new file mode 100644 index 00000000..08e83984 --- /dev/null +++ b/skills/flowstudio-power-automate-mcp/references/connection-references.md @@ -0,0 +1,115 @@ +# FlowStudio MCP — Connection References + +Connection references wire a flow's connector actions to real authenticated +connections in the Power Platform. They are required whenever you call +`update_live_flow` with a definition that uses connector actions. + +--- + +## Structure in a Flow Definition + +```json +{ + "properties": { + "definition": { ... }, + "connectionReferences": { + "shared_sharepointonline": { + "connectionName": "shared-sharepointonl-62599557c-1f33-4aec-b4c0-a6e4afcae3be", + "id": "/providers/Microsoft.PowerApps/apis/shared_sharepointonline", + "displayName": "SharePoint" + }, + "shared_office365": { + "connectionName": "shared-office365-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "id": "/providers/Microsoft.PowerApps/apis/shared_office365", + "displayName": "Office 365 Outlook" + } + } + } +} +``` + +Keys are **logical reference names** (e.g. `shared_sharepointonline`). +These match the `connectionName` field inside each action's `host` block. + +--- + +## Finding Connection GUIDs + +Call `get_live_flow` on **any existing flow** that uses the same connection +and copy the `connectionReferences` block. The GUID after the connector prefix is +the connection instance owned by the authenticating user. + +```python +flow = mcp("get_live_flow", environmentName=ENV, flowName=EXISTING_FLOW_ID) +conn_refs = flow["properties"]["connectionReferences"] +# conn_refs["shared_sharepointonline"]["connectionName"] +# → "shared-sharepointonl-62599557c-1f33-4aec-b4c0-a6e4afcae3be" +``` + +> ⚠️ Connection references are **user-scoped**. If a connection is owned +> by another account, `update_live_flow` will return 403 +> `ConnectionAuthorizationFailed`. You must use a connection belonging to +> the account whose token is in the `x-api-key` header. + +--- + +## Passing `connectionReferences` to `update_live_flow` + +```python +result = mcp("update_live_flow", + environmentName=ENV, + flowName=FLOW_ID, + definition=modified_definition, + connectionReferences={ + "shared_sharepointonline": { + "connectionName": "shared-sharepointonl-62599557c-1f33-4aec-b4c0-a6e4afcae3be", + "id": "/providers/Microsoft.PowerApps/apis/shared_sharepointonline" + } + } +) +``` + +Only include connections that the definition actually uses. + +--- + +## Common Connector API IDs + +| Service | API ID | +|---|---| +| SharePoint Online | `/providers/Microsoft.PowerApps/apis/shared_sharepointonline` | +| Office 365 Outlook | `/providers/Microsoft.PowerApps/apis/shared_office365` | +| Microsoft Teams | `/providers/Microsoft.PowerApps/apis/shared_teams` | +| OneDrive for Business | `/providers/Microsoft.PowerApps/apis/shared_onedriveforbusiness` | +| Azure AD | `/providers/Microsoft.PowerApps/apis/shared_azuread` | +| HTTP with Azure AD | `/providers/Microsoft.PowerApps/apis/shared_webcontents` | +| SQL Server | `/providers/Microsoft.PowerApps/apis/shared_sql` | +| Dataverse | `/providers/Microsoft.PowerApps/apis/shared_commondataserviceforapps` | +| Azure Blob Storage | `/providers/Microsoft.PowerApps/apis/shared_azureblob` | +| Approvals | `/providers/Microsoft.PowerApps/apis/shared_approvals` | +| Office 365 Users | `/providers/Microsoft.PowerApps/apis/shared_office365users` | +| Flow Management | `/providers/Microsoft.PowerApps/apis/shared_flowmanagement` | + +--- + +## Teams Adaptive Card Dual-Connection Requirement + +Flows that send adaptive cards **and** post follow-up messages require two +separate Teams connections: + +```json +"connectionReferences": { + "shared_teams": { + "connectionName": "shared-teams-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "id": "/providers/Microsoft.PowerApps/apis/shared_teams" + }, + "shared_teams_1": { + "connectionName": "shared-teams-yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy", + "id": "/providers/Microsoft.PowerApps/apis/shared_teams" + } +} +``` + +Both can point to the **same underlying Teams account** but must be registered +as two distinct connection references. The webhook (`OpenApiConnectionWebhook`) +uses `shared_teams` and subsequent message actions use `shared_teams_1`. diff --git a/skills/flowstudio-power-automate-mcp/references/tool-reference.md b/skills/flowstudio-power-automate-mcp/references/tool-reference.md new file mode 100644 index 00000000..b447a9c0 --- /dev/null +++ b/skills/flowstudio-power-automate-mcp/references/tool-reference.md @@ -0,0 +1,445 @@ +# FlowStudio MCP — Tool Response Catalog + +Response shapes and behavioral notes for the FlowStudio Power Automate MCP server. + +> **For tool names and parameters**: Always call `tools/list` on the server. +> It returns the authoritative, up-to-date schema for every tool. +> This document covers what `tools/list` does NOT tell you: **response shapes** +> and **non-obvious behaviors** discovered through real usage. + +--- + +## Source of Truth + +| Priority | Source | Covers | +|----------|--------|--------| +| 1 | **Real API response** | Always trust what the server actually returns | +| 2 | **`tools/list`** | Tool names, parameter names, types, required flags | +| 3 | **This document** | Response shapes, behavioral notes, gotchas | + +> If this document disagrees with `tools/list` or real API behavior, +> the API wins. Update this document accordingly. + +--- + +## Environment & Tenant Discovery + +### `list_live_environments` + +Response: direct array of environments. +```json +[ + { + "id": "Default-26e65220-5561-46ef-9783-ce5f20489241", + "displayName": "FlowStudio (default)", + "sku": "Production", + "location": "australia", + "state": "Enabled", + "isDefault": true, + "isAdmin": true, + "isMember": true, + "createdTime": "2023-08-18T00:41:05Z" + } +] +``` + +> Use the `id` value as `environmentName` in all other tools. + +### `list_store_environments` + +Same shape as `list_live_environments` but read from cache (faster). + +--- + +## Connection Discovery + +### `list_live_connections` + +Response: wrapper object with `connections` array. +```json +{ + "connections": [ + { + "id": "shared-office365-9f9d2c8e-55f1-49c9-9f9c-1c45d1fbbdce", + "displayName": "user@contoso.com", + "connectorName": "shared_office365", + "createdBy": "User Name", + "statuses": [{"status": "Connected"}], + "createdTime": "2024-03-12T21:23:55.206815Z" + } + ], + "totalCount": 56, + "error": null +} +``` + +> **Key field**: `id` is the `connectionName` value used in `connectionReferences`. +> +> **Key field**: `connectorName` maps to apiId: +> `"/providers/Microsoft.PowerApps/apis/" + connectorName` +> +> Filter by status: `statuses[0].status == "Connected"`. +> +> **Note**: `tools/list` marks `environmentName` as optional, but the server +> returns `MissingEnvironmentFilter` (HTTP 400) if you omit it. Always pass +> `environmentName`. + +### `list_store_connections` + +Same connection data from cache. + +--- + +## Flow Discovery & Listing + +### `list_live_flows` + +Response: wrapper object with `flows` array. +```json +{ + "mode": "owner", + "flows": [ + { + "id": "0757041a-8ef2-cf74-ef06-06881916f371", + "displayName": "My Flow", + "state": "Started", + "triggerType": "Request", + "triggerKind": "Http", + "createdTime": "2023-08-18T01:18:17Z", + "lastModifiedTime": "2023-08-18T12:47:42Z", + "owners": "", + "definitionAvailable": true + } + ], + "totalCount": 100, + "error": null +} +``` + +> Access via `result["flows"]`. `id` is a plain UUID --- use directly as `flowName`. +> +> `mode` indicates the access scope used (`"owner"` or `"admin"`). + +### `list_store_flows` + +Response: **direct array** (no wrapper). +```json +[ + { + "id": "3991358a-f603-e49d-b1ed-a9e4f72e2dcb.0757041a-8ef2-cf74-ef06-06881916f371", + "displayName": "Admin | Sync Template v3 (Solutions)", + "state": "Started", + "triggerType": "OpenApiConnectionWebhook", + "environmentName": "3991358a-f603-e49d-b1ed-a9e4f72e2dcb", + "runPeriodTotal": 100, + "createdTime": "2023-08-18T01:18:17Z", + "lastModifiedTime": "2023-08-18T12:47:42Z" + } +] +``` + +> **`id` format**: `envId.flowId` --- split on the first `.` to extract the flow UUID: +> `flow_id = item["id"].split(".", 1)[1]` + +### `get_store_flow` + +Response: single flow metadata from cache (selected fields). +```json +{ + "id": "envId.flowId", + "displayName": "My Flow", + "state": "Started", + "triggerType": "Recurrence", + "runPeriodTotal": 100, + "runPeriodFailRate": 0.1, + "runPeriodSuccessRate": 0.9, + "runPeriodFails": 10, + "runPeriodSuccess": 90, + "runPeriodDurationAverage": 29410.8, + "runPeriodDurationMax": 158900.0, + "runError": "{\"code\": \"EACCES\", ...}", + "description": "Flow description", + "tier": "Premium", + "complexity": "{...}", + "actions": 42, + "connections": ["sharepointonline", "office365"], + "owners": ["user@contoso.com"], + "createdBy": "user@contoso.com" +} +``` + +> `runPeriodDurationAverage` / `runPeriodDurationMax` are in **milliseconds** (divide by 1000). +> `runError` is a **JSON string** --- parse with `json.loads()`. + +--- + +## Flow Definition (Live API) + +### `get_live_flow` + +Response: full flow definition from PA API. +```json +{ + "name": "", + "properties": { + "displayName": "My Flow", + "state": "Started", + "definition": { + "triggers": { "..." }, + "actions": { "..." }, + "parameters": { "..." } + }, + "connectionReferences": { "..." } + } +} +``` + +### `update_live_flow` + +**Create mode**: Omit `flowName` --- creates a new flow. `definition` and `displayName` required. + +**Update mode**: Provide `flowName` --- PATCHes existing flow. + +Response: +```json +{ + "created": false, + "flowKey": "envId.flowId", + "updated": ["definition", "connectionReferences"], + "displayName": "My Flow", + "state": "Started", + "definition": { "...full definition..." }, + "error": null +} +``` + +> `error` is **always present** but may be `null`. Check `result.get("error") is not None`. +> +> On create: `created` is the new flow GUID (string). On update: `created` is `false`. +> +> `description` is **always required** (create and update). + +### `add_live_flow_to_solution` + +Migrates a non-solution flow into a solution. Returns error if already in a solution. + +--- + +## Run History & Monitoring + +### `get_live_flow_runs` + +Response: direct array of runs (newest first). +```json +[{ + "name": "", + "status": "Succeeded|Failed|Running|Cancelled", + "startTime": "2026-02-25T06:13:38Z", + "endTime": "2026-02-25T06:14:02Z", + "triggerName": "Recurrence", + "error": null +}] +``` + +> `top` defaults to **30** and auto-paginates for higher values. Set `top: 300` +> for 24-hour coverage on flows running every 5 minutes. +> +> Run ID field is **`name`** (not `runName`). Use this value as the `runName` +> parameter in other tools. + +### `get_live_flow_run_error` + +Response: structured error breakdown for a failed run. +```json +{ + "runName": "08584296068667933411438594643CU15", + "failedActions": [ + { + "actionName": "Apply_to_each_prepare_workers", + "status": "Failed", + "error": {"code": "ActionFailed", "message": "An action failed."}, + "code": "ActionFailed", + "startTime": "2026-02-25T06:13:52Z", + "endTime": "2026-02-25T06:15:24Z" + }, + { + "actionName": "HTTP_find_AD_User_by_Name", + "status": "Failed", + "code": "NotSpecified", + "startTime": "2026-02-25T06:14:01Z", + "endTime": "2026-02-25T06:14:05Z" + } + ], + "allActions": [ + {"actionName": "Apply_to_each", "status": "Skipped"}, + {"actionName": "Compose_WeekEnd", "status": "Succeeded"}, + {"actionName": "HTTP_find_AD_User_by_Name", "status": "Failed"} + ] +} +``` + +> `failedActions` is ordered outer-to-inner --- the **last entry is the root cause**. +> Use `failedActions[-1]["actionName"]` as the starting point for diagnosis. + +### `get_live_flow_run_action_outputs` + +Response: array of action detail objects. +```json +[ + { + "actionName": "Compose_WeekEnd_now", + "status": "Succeeded", + "startTime": "2026-02-25T06:13:52Z", + "endTime": "2026-02-25T06:13:52Z", + "error": null, + "inputs": "Mon, 25 Feb 2026 06:13:52 GMT", + "outputs": "Mon, 25 Feb 2026 06:13:52 GMT" + } +] +``` + +> **`actionName` is optional**: omit it to return ALL actions in the run; +> provide it to return a single-element array for that action only. +> +> Outputs can be very large (50 MB+) for bulk-data actions. Use 120s+ timeout. + +--- + +## Run Control + +### `resubmit_live_flow_run` + +Response: `{ flowKey, resubmitted: true, runName, triggerName }` + +### `cancel_live_flow_run` + +Cancels a `Running` flow run. + +> Do NOT cancel runs waiting for an adaptive card response --- status `Running` +> is normal while a Teams card is awaiting user input. + +--- + +## HTTP Trigger Tools + +### `get_live_flow_http_schema` + +Response keys: +``` +flowKey - Flow GUID +displayName - Flow display name +triggerName - Trigger action name (e.g. "manual") +triggerType - Trigger type (e.g. "Request") +triggerKind - Trigger kind (e.g. "Http") +requestMethod - HTTP method (e.g. "POST") +relativePath - Relative path configured on the trigger (if any) +requestSchema - JSON schema the trigger expects as POST body +requestHeaders - Headers the trigger expects +responseSchemas - Array of JSON schemas defined on Response action(s) +responseSchemaCount - Number of Response actions that define output schemas +``` + +> The request body schema is in `requestSchema` (not `triggerSchema`). + +### `get_live_flow_trigger_url` + +Returns the signed callback URL for HTTP-triggered flows. Response includes +`flowKey`, `triggerName`, `triggerType`, `triggerKind`, `triggerMethod`, `triggerUrl`. + +### `trigger_live_flow` + +Response keys: `flowKey`, `triggerName`, `triggerUrl`, `requiresAadAuth`, `authType`, +`responseStatus`, `responseBody`. + +> **Only works for `Request` (HTTP) triggers.** Returns an error for Recurrence +> and other trigger types: `"only HTTP Request triggers can be invoked via this tool"`. +> +> `responseStatus` + `responseBody` contain the flow's Response action output. +> AAD-authenticated triggers are handled automatically. + +--- + +## Flow State Management + +### `set_store_flow_state` + +Start or stop a flow. Pass `state: "Started"` or `state: "Stopped"`. + +--- + +## Store Tools --- FlowStudio for Teams Only + +### `get_store_flow_summary` + +Response: aggregated run statistics. +```json +{ + "totalRuns": 100, + "failRuns": 10, + "failRate": 0.1, + "averageDurationSeconds": 29.4, + "maxDurationSeconds": 158.9, + "firstFailRunRemediation": "" +} +``` + +### `get_store_flow_runs` + +Cached run history for the last N days with duration and remediation hints. + +### `get_store_flow_errors` + +Cached failed-only runs with failed action names and remediation hints. + +### `get_store_flow_trigger_url` + +Trigger URL from cache (instant, no PA API call). + +### `update_store_flow` + +Update governance metadata (description, tags, monitor flag, notification rules, business impact). + +### `list_store_makers` / `get_store_maker` + +Maker (citizen developer) discovery and detail. + +### `list_store_power_apps` + +List all Power Apps canvas apps from the cache. + +--- + +## Behavioral Notes + +Non-obvious behaviors discovered through real API usage. These are things +`tools/list` cannot tell you. + +### `get_live_flow_run_action_outputs` +- **`actionName` is optional**: omit to get all actions, provide to get one. + This changes the response from N elements to 1 element (still an array). +- Outputs can be 50 MB+ for bulk-data actions --- always use 120s+ timeout. + +### `update_live_flow` +- `description` is **always required** (create and update modes). +- `error` key is **always present** in response --- `null` means success. + Do NOT check `if "error" in result`; check `result.get("error") is not None`. +- On create, `created` = new flow GUID (string). On update, `created` = `false`. + +### `trigger_live_flow` +- **Only works for HTTP Request triggers.** Returns error for Recurrence, connector, + and other trigger types. +- AAD-authenticated triggers are handled automatically (impersonated Bearer token). + +### `get_live_flow_runs` +- `top` defaults to **30** with automatic pagination for higher values. +- Run ID field is `name`, not `runName`. Use this value as `runName` in other tools. +- Runs are returned newest-first. + +### Teams `PostMessageToConversation` (via `update_live_flow`) +- **"Chat with Flow bot"**: `body/recipient` = `"user@domain.com;"` (string with trailing semicolon). +- **"Channel"**: `body/recipient` = `{"groupId": "...", "channelId": "..."}` (object). +- `poster`: `"Flow bot"` for Workflows bot identity, `"User"` for user identity. + +### `list_live_connections` +- `id` is the value you need for `connectionName` in `connectionReferences`. +- `connectorName` maps to apiId: `"/providers/Microsoft.PowerApps/apis/" + connectorName`. From e6437902d62bd9baf8c227a20615b55aeb98e36e Mon Sep 17 00:00:00 2001 From: Aaron Powell Date: Fri, 6 Mar 2026 16:10:05 +1100 Subject: [PATCH 09/37] Fix sidebar navigation text contrast in light mode (#902) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Fixing the action link * Fix sidebar navigation text contrast in light mode - Use --sl-color-text-invert instead of --sl-color-white for active sidebar item, fixing near-black text on dark purple background (contrast ~2.5:1 → ~7.1:1) - Bump inactive sidebar links to font-weight 500 for better readability Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- website/src/content/docs/learning-hub/index.md | 2 +- website/src/styles/starlight-overrides.css | 10 +++++++--- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/website/src/content/docs/learning-hub/index.md b/website/src/content/docs/learning-hub/index.md index 86f8ac50..d06359d7 100644 --- a/website/src/content/docs/learning-hub/index.md +++ b/website/src/content/docs/learning-hub/index.md @@ -6,7 +6,7 @@ hero: tagline: 'Curated articles, walkthroughs, and reference material to help you unlock everything you can do with GitHub Copilot' actions: - text: Start with Fundamentals - link: /learning-hub/what-are-agents-skills-instructions/ + link: what-are-agents-skills-instructions/ icon: right-arrow sidebar: hidden: true diff --git a/website/src/styles/starlight-overrides.css b/website/src/styles/starlight-overrides.css index 0761c39c..ec6489af 100644 --- a/website/src/styles/starlight-overrides.css +++ b/website/src/styles/starlight-overrides.css @@ -41,10 +41,14 @@ --sl-color-black: #f0f0f5; } -/* ── Sidebar active item ───────────────────────────────────── */ +/* ── Sidebar readability ───────────────────────────────────── */ +nav[aria-label="Main"] a { + font-weight: 500 !important; +} + nav[aria-label="Main"] a[aria-current="page"] { - color: var(--sl-color-white) !important; - font-weight: 600; + color: var(--sl-color-text-invert) !important; + font-weight: 600 !important; border-inline-start-color: var(--sl-color-accent) !important; } From 1b15663c46736d82ad56600d0a0f5dd3842f1a88 Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Fri, 6 Mar 2026 16:26:26 +1100 Subject: [PATCH 10/37] Update docs to reflect awesome-copilot as default plugin marketplace in CLI and VS Code (#901) * Initial plan * docs: update plugin discovery for default marketplace in CLI and VS Code Co-authored-by: aaronpowell <434140+aaronpowell@users.noreply.github.com> * docs: revert README.md changes (covered by #900), update README.plugins.md Co-authored-by: aaronpowell <434140+aaronpowell@users.noreply.github.com> * fix: update plugin template in constants.mjs so README.plugins.md survives rebuilds Co-authored-by: aaronpowell <434140+aaronpowell@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: aaronpowell <434140+aaronpowell@users.noreply.github.com> --- docs/README.plugins.md | 15 +++++--- eng/constants.mjs | 15 +++++--- .../installing-and-using-plugins.md | 19 ++++++++--- website/src/pages/plugins.astro | 34 +++++++++++++++++++ 4 files changed, 69 insertions(+), 14 deletions(-) diff --git a/docs/README.plugins.md b/docs/README.plugins.md index dd3afb0b..284d3c7e 100644 --- a/docs/README.plugins.md +++ b/docs/README.plugins.md @@ -1,6 +1,8 @@ # 🔌 Plugins -Curated plugins of related agents and skills organized around specific themes, workflows, or use cases. Plugins can be installed directly via GitHub Copilot CLI. +Curated plugins of related agents and skills organized around specific themes, workflows, or use cases. Plugins can be installed directly via GitHub Copilot CLI or VS Code. + +> **Awesome Copilot is a default plugin marketplace** — no setup required in either Copilot CLI or VS Code. ### How to Contribute See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-plugins) for guidelines on how to contribute new plugins, improve existing ones, and share your use cases. @@ -13,10 +15,13 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-plugins) for guidelines on how t - Each plugin includes agents and skills for specific workflows - Plugins make it easy to adopt comprehensive toolkits for particular scenarios -**Install Plugins:** -- Use \`copilot plugin install @awesome-copilot\` to install a plugin -- Or browse to the individual files to copy content manually -- Plugins help you discover related customizations you might have missed +**Find & Install in Copilot CLI:** +- Browse the marketplace from within an interactive Copilot session: \`/plugin marketplace browse awesome-copilot\` +- Install a plugin: \`copilot plugin install @awesome-copilot\` + +**Find & Install in VS Code:** +- Open the Extensions search view and type \`@agentPlugins\` to browse available plugins +- Or open the Command Palette and run \`Chat: Plugins\` | Name | Description | Items | Tags | | ---- | ----------- | ----- | ---- | diff --git a/eng/constants.mjs b/eng/constants.mjs index 50f85cb8..21a11053 100644 --- a/eng/constants.mjs +++ b/eng/constants.mjs @@ -27,7 +27,9 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-instructions) for guidelines on pluginsSection: `## 🔌 Plugins -Curated plugins of related agents and skills organized around specific themes, workflows, or use cases. Plugins can be installed directly via GitHub Copilot CLI.`, +Curated plugins of related agents and skills organized around specific themes, workflows, or use cases. Plugins can be installed directly via GitHub Copilot CLI or VS Code. + +> **Awesome Copilot is a default plugin marketplace** — no setup required in either Copilot CLI or VS Code.`, pluginsUsage: `### How to Contribute @@ -41,10 +43,13 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-plugins) for guidelines on how t - Each plugin includes agents and skills for specific workflows - Plugins make it easy to adopt comprehensive toolkits for particular scenarios -**Install Plugins:** -- Use \\\`copilot plugin install @awesome-copilot\\\` to install a plugin -- Or browse to the individual files to copy content manually -- Plugins help you discover related customizations you might have missed`, +**Find & Install in Copilot CLI:** +- Browse the marketplace from within an interactive Copilot session: \\\`/plugin marketplace browse awesome-copilot\\\` +- Install a plugin: \\\`copilot plugin install @awesome-copilot\\\` + +**Find & Install in VS Code:** +- Open the Extensions search view and type \\\`@agentPlugins\\\` to browse available plugins +- Or open the Command Palette and run \\\`Chat: Plugins\\\``, featuredPluginsSection: `## 🌟 Featured Plugins diff --git a/website/src/content/learning-hub/installing-and-using-plugins.md b/website/src/content/learning-hub/installing-and-using-plugins.md index 94eb44d5..28bc8795 100644 --- a/website/src/content/learning-hub/installing-and-using-plugins.md +++ b/website/src/content/learning-hub/installing-and-using-plugins.md @@ -94,12 +94,12 @@ Plugins are especially valuable when you want to: ## Finding Plugins -Plugins are collected in **marketplaces** — registries you can browse and install from. Copilot CLI comes with two marketplaces registered by default: +Plugins are collected in **marketplaces** — registries you can browse and install from. Both Copilot CLI and VS Code come with two marketplaces registered by default — **no setup required**: - **`copilot-plugins`** — Official GitHub Copilot plugins - **`awesome-copilot`** — Community-contributed plugins from this repository -### Browsing a Marketplace +### Browsing in Copilot CLI List your registered marketplaces: @@ -121,6 +121,13 @@ Or from within an interactive Copilot session: > **Tip**: You can also browse plugins on this site's [Plugins Directory](../../plugins/) to see descriptions, included agents, and skills before installing. +### Browsing in VS Code + +Because `awesome-copilot` is a default marketplace in VS Code, you can discover plugins without any configuration: + +- Open the **Extensions** search view and type **`@agentPlugins`** to see all available plugins +- Or open the **Command Palette** (`Ctrl+Shift+P` / `Cmd+Shift+P`) and run **Chat: Plugins** + ### Adding More Marketplaces Register additional marketplaces from GitHub repositories: @@ -137,9 +144,9 @@ copilot plugin marketplace add /path/to/local-marketplace ## Installing Plugins -### From a Registered Marketplace +### From Copilot CLI -The most common way to install a plugin — reference it by name and marketplace: +Reference a plugin by name and marketplace: ```bash copilot plugin install database-data-management@awesome-copilot @@ -151,6 +158,10 @@ Or from an interactive session: /plugin install database-data-management@awesome-copilot ``` +### From VS Code + +Browse to the plugin via `@agentPlugins` in the Extensions search view or via **Chat: Plugins** in the Command Palette, then click **Install**. + ## Managing Plugins Once installed, plugins are managed with a few simple commands: diff --git a/website/src/pages/plugins.astro b/website/src/pages/plugins.astro index 52bff369..c7f49fbf 100644 --- a/website/src/pages/plugins.astro +++ b/website/src/pages/plugins.astro @@ -11,6 +11,15 @@ import PageHeader from '../components/PageHeader.astro';
+
+

Awesome Copilot is a default plugin marketplace — no setup required. Access it directly from your tools:

+
    +
  • GitHub Copilot CLI: Type /plugin marketplace browse awesome-copilot in a Copilot session
    • +
  • VS Code: Type @agentPlugins in the Extensions search view, or open the Command Palette and run Chat: Plugins
    • +
+

Install any plugin with: copilot plugin install <plugin-name>@awesome-copilot

+
+
@@ -44,4 +53,29 @@ import PageHeader from '../components/PageHeader.astro'; + + From fca5de1f6a77a63078bc9988d7e03bacccb242b2 Mon Sep 17 00:00:00 2001 From: Tadas Labudis Date: Fri, 6 Mar 2026 10:20:36 +0000 Subject: [PATCH 11/37] Improve github-issues skill: fix MCP tools, add search reference, fix sub-issues docs (#888) * Add advanced search reference with query syntax guide Covers search qualifiers, boolean logic, date ranges, missing metadata filters, common patterns, and when to use search vs list_issues. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Add issue fields search support to search and issue-fields references - Add Advanced Search Mode section to search.md covering field: qualifier, has:field: syntax, REST advanced_search=true, and GraphQL ISSUE_ADVANCED - Add Searching by Field Values section to issue-fields.md with REST/GraphQL examples and qualifier reference table - Note MCP search_issues limitation (no advanced_search support) - Update SKILL.md capability table to mention issue field filters Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Clarify three search approaches: list_issues vs search_issues vs advanced search Replace the simple two-column comparison with a capability matrix showing what each approach supports (field filters, boolean logic, scope, etc.) and a decision guide for when to use each one. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fix issue field search syntax: use dot notation (field.name:value) The colon notation (field:Name:Value) is silently ignored by the API. The correct syntax is dot notation (field.priority:P0) which works in REST (advanced_search=true), GraphQL (ISSUE_ADVANCED), and web UI. Also supports has:field.name, no:field.name, and date comparisons. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fix github-issues skill: correct MCP tools and add gh api workflows The skill listed 5 MCP tools that don't exist (create_issue, update_issue, get_issue, add_issue_comment, list_issue_types), causing tool-not-found errors when agents tried to follow the skill instructions. Changes: - Split tools table into MCP (read ops) and CLI/API (write ops) - Add gh api commands for creating, updating, commenting on issues - Document that gh issue create doesn't support --type flag - Add GraphQL query for discovering issue types - Remove redundant [Bug]/[Feature] title prefixes (use type param instead) - Update examples to use gh api instead of non-existent MCP tools Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fix sub-issues reference: add gh api examples and integer gotcha The sub_issue_id parameter requires an integer but gh api -f sends strings, causing 422 errors. Updated all REST examples to use --input with raw JSON. Also added: - Recommended two-step workflow (create issue, then link) - Explicit warning about -f vs --input for integer params - Proper gh api command syntax instead of raw HTTP notation Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Address PR review: fix search docs accuracy and broken link - Fix misleading claim about full boolean logic support (implicit AND only) - Remove sort:updated from query example (it's an API param, not a qualifier) - Clarify -linked:pr comment to avoid confusion with authoring status - Fix relative link in issue-fields.md (sibling file, not nested path) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Improve projects reference: scope warning, gh api examples, issue-side queries From hands-on usage: hit INSUFFICIENT_SCOPES trying to update project status because token had read:project but not project write scope. Added: - OAuth scope requirements table with gh auth refresh workaround - How to find an issue's project item ID (query from issue side) - All GraphQL examples now use gh api graphql (copy-paste ready) - End-to-end example: set issue status to In Progress Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Add images-in-issues reference: hosting methods, pitfalls, screenshots Documents three approaches for embedding images in issue comments via CLI: Contents API with github.com/raw/ URLs, browser drag-drop for permanent user-attachments URLs, and gist hosting limitations. Includes puppeteer screenshot recipe and comparison table. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Update README.skills.md with images reference Run npm run build to regenerate skill listing. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fix issue-fields search: add GraphQL bulk query, caveat search syntax The field.name:value search qualifier is unreliable via API (returns 0 results even when matching issues exist). Added a recommended GraphQL approach that fetches issues and filters by issueFieldValues client-side. Documented the correct IssueFieldSingleSelectValue schema (name, not value). Marked search qualifier syntax as experimental with a reliability warning. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs(github-issues): improve project discovery guidance The projectsV2 query param does keyword search, not exact match, and sorts by recency. For large orgs like github, common words like 'issue' return 400+ results and bury the target project. Added a priority-ordered discovery strategy: 1. Direct lookup by number (instant) 2. Reverse lookup from a known issue's projectItems (most reliable) 3. GraphQL name search with client-side jq filtering (fallback) 4. MCP tool (small orgs only) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/README.skills.md | 2 +- skills/github-issues/SKILL.md | 144 +++++++---- skills/github-issues/references/images.md | 116 +++++++++ .../github-issues/references/issue-fields.md | 64 +++++ skills/github-issues/references/projects.md | 211 +++++++++++++--- skills/github-issues/references/search.md | 231 ++++++++++++++++++ skills/github-issues/references/sub-issues.md | 52 ++-- 7 files changed, 721 insertions(+), 99 deletions(-) create mode 100644 skills/github-issues/references/images.md create mode 100644 skills/github-issues/references/search.md diff --git a/docs/README.skills.md b/docs/README.skills.md index ef0c8124..ca513c5f 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -122,7 +122,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [git-commit](../skills/git-commit/SKILL.md) | Execute git commit with conventional commit message analysis, intelligent staging, and message generation. Use when user asks to commit changes, create a git commit, or mentions "/commit". Supports: (1) Auto-detecting type and scope from changes, (2) Generating conventional commit messages from diff, (3) Interactive commit with optional type/scope/description overrides, (4) Intelligent file staging for logical grouping | None | | [git-flow-branch-creator](../skills/git-flow-branch-creator/SKILL.md) | Intelligent Git Flow branch creator that analyzes git status/diff and creates appropriate branches following the nvie Git Flow branching model. | None | | [github-copilot-starter](../skills/github-copilot-starter/SKILL.md) | Set up complete GitHub Copilot configuration for a new project based on technology stack | None | -| [github-issues](../skills/github-issues/SKILL.md) | Create, update, and manage GitHub issues using MCP tools. Use this skill when users want to create bug reports, feature requests, or task issues, update existing issues, add labels/assignees/milestones, set issue fields (dates, priority, custom fields), set issue types, or manage issue workflows. Triggers on requests like "create an issue", "file a bug", "request a feature", "update issue X", "set the priority", "set the start date", or any GitHub issue management task. | `references/dependencies.md`
`references/issue-fields.md`
`references/issue-types.md`
`references/projects.md`
`references/sub-issues.md`
`references/templates.md` | +| [github-issues](../skills/github-issues/SKILL.md) | Create, update, and manage GitHub issues using MCP tools. Use this skill when users want to create bug reports, feature requests, or task issues, update existing issues, add labels/assignees/milestones, set issue fields (dates, priority, custom fields), set issue types, or manage issue workflows. Triggers on requests like "create an issue", "file a bug", "request a feature", "update issue X", "set the priority", "set the start date", or any GitHub issue management task. | `references/dependencies.md`
`references/images.md`
`references/issue-fields.md`
`references/issue-types.md`
`references/projects.md`
`references/search.md`
`references/sub-issues.md`
`references/templates.md` | | [go-mcp-server-generator](../skills/go-mcp-server-generator/SKILL.md) | Generate a complete Go MCP server project with proper structure, dependencies, and implementation using the official github.com/modelcontextprotocol/go-sdk. | None | | [image-manipulation-image-magick](../skills/image-manipulation-image-magick/SKILL.md) | Process and manipulate images using ImageMagick. Supports resizing, format conversion, batch processing, and retrieving image metadata. Use when working with images, creating thumbnails, resizing wallpapers, or performing batch image operations. | None | | [import-infrastructure-as-code](../skills/import-infrastructure-as-code/SKILL.md) | Import existing Azure resources into Terraform using Azure CLI discovery and Azure Verified Modules (AVM). Use when asked to reverse-engineer live Azure infrastructure, generate Infrastructure as Code from existing subscriptions/resource groups/resource IDs, map dependencies, derive exact import addresses from downloaded module source, prevent configuration drift, and produce AVM-based Terraform files ready for validation and planning across any Azure resource type. | None | diff --git a/skills/github-issues/SKILL.md b/skills/github-issues/SKILL.md index 48b41f39..18f2bd66 100644 --- a/skills/github-issues/SKILL.md +++ b/skills/github-issues/SKILL.md @@ -7,63 +7,81 @@ description: 'Create, update, and manage GitHub issues using MCP tools. Use this Manage GitHub issues using the `@modelcontextprotocol/server-github` MCP server. -## Available MCP Tools +## Available Tools + +### MCP Tools (read operations) | Tool | Purpose | |------|---------| -| `mcp__github__create_issue` | Create new issues | -| `mcp__github__update_issue` | Update existing issues | -| `mcp__github__get_issue` | Fetch issue details | -| `mcp__github__search_issues` | Search issues | -| `mcp__github__add_issue_comment` | Add comments | -| `mcp__github__list_issues` | List repository issues | -| `mcp__github__list_issue_types` | List available issue types for an organization | -| `mcp__github__issue_read` | Read issue details, sub-issues, comments, labels | +| `mcp__github__issue_read` | Read issue details, sub-issues, comments, labels (methods: get, get_comments, get_sub_issues, get_labels) | +| `mcp__github__list_issues` | List and filter repository issues by state, labels, date | +| `mcp__github__search_issues` | Search issues across repos using GitHub search syntax | | `mcp__github__projects_list` | List projects, project fields, project items, status updates | | `mcp__github__projects_get` | Get details of a project, field, item, or status update | | `mcp__github__projects_write` | Add/update/delete project items, create status updates | +### CLI / REST API (write operations) + +The MCP server does not currently support creating, updating, or commenting on issues. Use `gh api` for these operations. + +| Operation | Command | +|-----------|---------| +| Create issue | `gh api repos/{owner}/{repo}/issues -X POST -f title=... -f body=...` | +| Update issue | `gh api repos/{owner}/{repo}/issues/{number} -X PATCH -f title=... -f state=...` | +| Add comment | `gh api repos/{owner}/{repo}/issues/{number}/comments -X POST -f body=...` | +| Close issue | `gh api repos/{owner}/{repo}/issues/{number} -X PATCH -f state=closed` | +| Set issue type | Include `-f type=Bug` in the create call (REST API only, not supported by `gh issue create` CLI) | + +**Note:** `gh issue create` works for basic issue creation but does **not** support the `--type` flag. Use `gh api` when you need to set issue types. + ## Workflow 1. **Determine action**: Create, update, or query? 2. **Gather context**: Get repo info, existing labels, milestones if needed 3. **Structure content**: Use appropriate template from [references/templates.md](references/templates.md) -4. **Execute**: Call the appropriate MCP tool +4. **Execute**: Use MCP tools for reads, `gh api` for writes 5. **Confirm**: Report the issue URL to user ## Creating Issues -### Required Parameters +Use `gh api` to create issues. This supports all parameters including issue types. -``` -owner: repository owner (org or user) -repo: repository name -title: clear, actionable title -body: structured markdown content +```bash +gh api repos/{owner}/{repo}/issues \ + -X POST \ + -f title="Issue title" \ + -f body="Issue body in markdown" \ + -f type="Bug" \ + --jq '{number, html_url}' ``` ### Optional Parameters +Add any of these flags to the `gh api` call: + ``` -labels: ["bug", "enhancement", "documentation", ...] -assignees: ["username1", "username2"] -milestone: milestone number (integer) -type: issue type name (e.g., "Bug", "Feature", "Task", "Epic") +-f type="Bug" # Issue type (Bug, Feature, Task, Epic, etc.) +-f labels[]="bug" # Labels (repeat for multiple) +-f assignees[]="username" # Assignees (repeat for multiple) +-f milestone=1 # Milestone number ``` -**Issue types** are organization-level metadata. Before using `type`, call `mcp__github__list_issue_types` with the org name to discover available types. If the org has no issue types configured, omit the parameter. +**Issue types** are organization-level metadata. To discover available types, use: +```bash +gh api graphql -f query='{ organization(login: "ORG") { issueTypes(first: 10) { nodes { name } } } }' --jq '.data.organization.issueTypes.nodes[].name' +``` **Prefer issue types over labels for categorization.** When issue types are available (e.g., Bug, Feature, Task), use the `type` parameter instead of applying equivalent labels like `bug` or `enhancement`. Issue types are the canonical way to categorize issues on GitHub. Only fall back to labels when the org has no issue types configured. ### Title Guidelines -- Start with type prefix when useful: `[Bug]`, `[Feature]`, `[Docs]` - Be specific and actionable - Keep under 72 characters +- When issue types are set, don't add redundant prefixes like `[Bug]` - Examples: - - `[Bug] Login fails with SSO enabled` - - `[Feature] Add dark mode support` - - `Add unit tests for auth module` + - `Login fails with SSO enabled` (with type=Bug) + - `Add dark mode support` (with type=Feature) + - `Add unit tests for auth module` (with type=Task) ### Body Structure @@ -77,14 +95,17 @@ Always use the templates in [references/templates.md](references/templates.md). ## Updating Issues -Use `mcp__github__update_issue` with: +Use `gh api` with PATCH: -``` -owner, repo, issue_number (required) -title, body, state, labels, assignees, milestone (optional - only changed fields) +```bash +gh api repos/{owner}/{repo}/issues/{number} \ + -X PATCH \ + -f state=closed \ + -f title="Updated title" \ + --jq '{number, html_url}' ``` -State values: `open`, `closed` +Only include fields you want to change. Available fields: `title`, `body`, `state` (open/closed), `labels`, `assignees`, `milestone`. ## Examples @@ -92,31 +113,54 @@ State values: `open`, `closed` **User**: "Create a bug issue - the login page crashes when using SSO" -**Action**: Call `mcp__github__create_issue` with: -```json -{ - "owner": "github", - "repo": "awesome-copilot", - "title": "[Bug] Login page crashes when using SSO", - "body": "## Description\nThe login page crashes when users attempt to authenticate using SSO.\n\n## Steps to Reproduce\n1. Navigate to login page\n2. Click 'Sign in with SSO'\n3. Page crashes\n\n## Expected Behavior\nSSO authentication should complete and redirect to dashboard.\n\n## Actual Behavior\nPage becomes unresponsive and displays error.\n\n## Environment\n- Browser: [To be filled]\n- OS: [To be filled]\n\n## Additional Context\nReported by user.", - "type": "Bug" -} +**Action**: +```bash +gh api repos/github/awesome-copilot/issues \ + -X POST \ + -f title="Login page crashes when using SSO" \ + -f type="Bug" \ + -f body="## Description +The login page crashes when users attempt to authenticate using SSO. + +## Steps to Reproduce +1. Navigate to login page +2. Click 'Sign in with SSO' +3. Page crashes + +## Expected Behavior +SSO authentication should complete and redirect to dashboard. + +## Actual Behavior +Page becomes unresponsive and displays error." \ + --jq '{number, html_url}' ``` ### Example 2: Feature Request **User**: "Create a feature request for dark mode with high priority" -**Action**: Call `mcp__github__create_issue` with: -```json -{ - "owner": "github", - "repo": "awesome-copilot", - "title": "[Feature] Add dark mode support", - "body": "## Summary\nAdd dark mode theme option for improved user experience and accessibility.\n\n## Motivation\n- Reduces eye strain in low-light environments\n- Increasingly expected by users\n- Improves accessibility\n\n## Proposed Solution\nImplement theme toggle with system preference detection.\n\n## Acceptance Criteria\n- [ ] Toggle switch in settings\n- [ ] Persists user preference\n- [ ] Respects system preference by default\n- [ ] All UI components support both themes\n\n## Alternatives Considered\nNone specified.\n\n## Additional Context\nHigh priority request.", - "type": "Feature", - "labels": ["high-priority"] -} +**Action**: +```bash +gh api repos/github/awesome-copilot/issues \ + -X POST \ + -f title="Add dark mode support" \ + -f type="Feature" \ + -f labels[]="high-priority" \ + -f body="## Summary +Add dark mode theme option for improved user experience and accessibility. + +## Motivation +- Reduces eye strain in low-light environments +- Increasingly expected by users + +## Proposed Solution +Implement theme toggle with system preference detection. + +## Acceptance Criteria +- [ ] Toggle switch in settings +- [ ] Persists user preference +- [ ] Respects system preference by default" \ + --jq '{number, html_url}' ``` ## Common Labels @@ -148,8 +192,10 @@ The following features require REST or GraphQL APIs beyond the basic MCP tools. | Capability | When to use | Reference | |------------|-------------|-----------| +| Advanced search | Complex queries with boolean logic, date ranges, cross-repo search, issue field filters (`field.name:value`) | [references/search.md](references/search.md) | | Sub-issues & parent issues | Breaking work into hierarchical tasks | [references/sub-issues.md](references/sub-issues.md) | | Issue dependencies | Tracking blocked-by / blocking relationships | [references/dependencies.md](references/dependencies.md) | | Issue types (advanced) | GraphQL operations beyond MCP `list_issue_types` / `type` param | [references/issue-types.md](references/issue-types.md) | | Projects V2 | Project boards, progress reports, field management | [references/projects.md](references/projects.md) | | Issue fields | Custom metadata: dates, priority, text, numbers (private preview) | [references/issue-fields.md](references/issue-fields.md) | +| Images in issues | Embedding images in issue bodies and comments via CLI | [references/images.md](references/images.md) | diff --git a/skills/github-issues/references/images.md b/skills/github-issues/references/images.md new file mode 100644 index 00000000..f6dec631 --- /dev/null +++ b/skills/github-issues/references/images.md @@ -0,0 +1,116 @@ +# Images in Issues and Comments + +How to embed images in GitHub issue bodies and comments programmatically via the CLI. + +## Methods (ranked by reliability) + +### 1. GitHub Contents API (recommended for private repos) + +Push image files to a branch in the same repo, then reference them with a URL that works for authenticated viewers. + +**Step 1: Create a branch** + +```bash +# Get the SHA of the default branch +SHA=$(gh api repos/{owner}/{repo}/git/ref/heads/main --jq '.object.sha') + +# Create a new branch +gh api repos/{owner}/{repo}/git/refs -X POST \ + -f ref="refs/heads/{username}/images" \ + -f sha="$SHA" +``` + +**Step 2: Upload images via Contents API** + +```bash +# Base64-encode the image and upload +BASE64=$(base64 -i /path/to/image.png) + +gh api repos/{owner}/{repo}/contents/docs/images/my-image.png \ + -X PUT \ + -f message="Add image" \ + -f content="$BASE64" \ + -f branch="{username}/images" \ + --jq '.content.path' +``` + +Repeat for each image. The Contents API creates a commit per file. + +**Step 3: Reference in markdown** + +```markdown +![Description](https://github.com/{owner}/{repo}/raw/{username}/images/docs/images/my-image.png) +``` + +> **Important:** Use `github.com/{owner}/{repo}/raw/{branch}/{path}` format, NOT `raw.githubusercontent.com`. The `raw.githubusercontent.com` URLs return 404 for private repos. The `github.com/.../raw/...` format works because the browser sends auth cookies when the viewer is logged in and has repo access. + +**Pros:** Works for any repo the viewer has access to, images live in version control, no expiration. +**Cons:** Creates commits, viewers must be authenticated, images won't render in email notifications or for users without repo access. + +### 2. Gist hosting (public images only) + +Upload images as files in a gist. Only works for images you're comfortable making public. + +```bash +# Create a gist with a placeholder file +gh gist create --public -f description.md <<< "Image hosting gist" + +# Note: gh gist edit does NOT support binary files. +# You must use the API to add binary content to gists. +``` + +> **Limitation:** Gists don't support binary file uploads via the CLI. You'd need to base64-encode and store as text, which won't render as images. Not recommended. + +### 3. Browser upload (most reliable rendering) + +The most reliable way to get permanent image URLs is through the GitHub web UI: + +1. Open the issue/comment in a browser +2. Drag-drop or paste the image into the comment editor +3. GitHub generates a permanent `https://github.com/user-attachments/assets/{UUID}` URL +4. These URLs work for anyone, even without repo access, and render in email notifications + +> **Why the API can't do this:** GitHub's `upload/policies/assets` endpoint requires a browser session (CSRF token + cookies). It returns an HTML error page when called with API tokens. There is no public API for generating `user-attachments` URLs. + +## Taking screenshots programmatically + +Use `puppeteer-core` with local Chrome to screenshot HTML mockups: + +```javascript +const puppeteer = require('puppeteer-core'); + +const browser = await puppeteer.launch({ + executablePath: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', + defaultViewport: { width: 900, height: 600, deviceScaleFactor: 2 } +}); + +const page = await browser.newPage(); +await page.setContent(htmlString); + +// Screenshot specific elements +const elements = await page.$$('.section'); +for (let i = 0; i < elements.length; i++) { + await elements[i].screenshot({ path: `mockup-${i + 1}.png` }); +} + +await browser.close(); +``` + +> **Note:** MCP Playwright may not connect to localhost due to network isolation. Use puppeteer-core with a local Chrome installation instead. + +## Quick reference + +| Method | Private repos | Permanent | No auth needed | API-only | +|--------|:---:|:---:|:---:|:---:| +| Contents API + `github.com/raw/` | ✅ | ✅ | ❌ | ✅ | +| Browser drag-drop (`user-attachments`) | ✅ | ✅ | ✅ | ❌ | +| `raw.githubusercontent.com` | ❌ (404) | ✅ | ❌ | ✅ | +| Gist | Public only | ✅ | ✅ | ❌ (no binary) | + +## Common pitfalls + +- **`raw.githubusercontent.com` returns 404 for private repos** even with a valid token in the URL. GitHub's CDN does not pass auth headers through. +- **API download URLs are temporary.** URLs returned by `gh api repos/.../contents/...` with `download_url` include a token that expires. +- **`upload/policies/assets` requires a browser session.** Do not attempt to call this endpoint from the CLI. +- **Base64 encoding for large files** can hit API payload limits. The Contents API has a ~100MB file size limit but practical limits are lower for base64-encoded payloads. +- **Email notifications** will not render images that require authentication. If email readability matters, use the browser upload method. diff --git a/skills/github-issues/references/issue-fields.md b/skills/github-issues/references/issue-fields.md index d60e4e49..4ab668ce 100644 --- a/skills/github-issues/references/issue-fields.md +++ b/skills/github-issues/references/issue-fields.md @@ -125,3 +125,67 @@ mutation { } }' ``` + +## Searching by field values + +### GraphQL bulk query (recommended) + +The most reliable way to find issues by field value is to fetch issues via GraphQL and filter by `issueFieldValues`. The search qualifier syntax (`field.name:value`) is not yet reliable across all environments. + +```bash +# Find all open P1 issues in a repo +gh api graphql -H "GraphQL-Features: issue_fields" -f query=' +{ + repository(owner: "OWNER", name: "REPO") { + issues(first: 100, states: OPEN) { + nodes { + number + title + updatedAt + assignees(first: 3) { nodes { login } } + issueFieldValues(first: 10) { + nodes { + __typename + ... on IssueFieldSingleSelectValue { + name + field { ... on IssueFieldSingleSelect { name } } + } + } + } + } + } + } +}' --jq ' + [.data.repository.issues.nodes[] | + select(.issueFieldValues.nodes[] | + select(.field.name == "Priority" and .name == "P1") + ) | + {number, title, updatedAt, assignees: [.assignees.nodes[].login]} + ]' +``` + +**Schema notes for `IssueFieldSingleSelectValue`:** +- The selected option's display text is in `.name` (not `.value`) +- Also available: `.color`, `.description`, `.id` +- The parent field reference is in `.field` (use inline fragment to get the field name) + +### Search qualifier syntax (experimental) + +Issue fields may also be searchable using dot notation in search queries. This requires `advanced_search=true` on REST or `ISSUE_ADVANCED` search type on GraphQL, but results are inconsistent and may return 0 results even when matching issues exist. + +``` +field.priority:P0 # Single-select equals value +field.target-date:>=2026-04-01 # Date comparison +has:field.priority # Has any value set +no:field.priority # Has no value set +``` + +Field names use the **slug** (lowercase, hyphens for spaces). For example, "Target Date" becomes `target-date`. + +```bash +# REST API (may not return results in all environments) +gh api "search/issues?q=repo:owner/repo+field.priority:P0+is:open&advanced_search=true" \ + --jq '.items[] | "#\(.number): \(.title)"' +``` + +> **Warning:** The colon notation (`field:Priority:P1`) is silently ignored. If using search qualifiers, always use dot notation (`field.priority:P1`). However, the GraphQL bulk query approach above is more reliable. See [search.md](search.md) for the full search guide. diff --git a/skills/github-issues/references/projects.md b/skills/github-issues/references/projects.md index ce633a18..e373b4e6 100644 --- a/skills/github-issues/references/projects.md +++ b/skills/github-issues/references/projects.md @@ -24,16 +24,69 @@ Call `mcp__github__projects_write` with `method: "delete_project_item"`, `projec ## Workflow for project operations -1. **Find the project** - use `projects_list` with `list_projects` to get the project number and node ID +1. **Find the project** — see [Finding a project by name](#finding-a-project-by-name) below 2. **Discover fields** - use `projects_list` with `list_project_fields` to get field IDs and option IDs 3. **Find items** - use `projects_list` with `list_project_items` to get item IDs 4. **Mutate** - use `projects_write` to add, update, or delete items +## Finding a project by name + +> **⚠️ Known issue:** `projectsV2(query: "…")` does keyword search, not exact name match, and returns results sorted by recency. Common words like "issue" or "bug" return hundreds of false positives. The actual project may be buried dozens of pages deep. + +Use this priority order: + +### 1. Direct lookup (if you know the number) +```bash +gh api graphql -f query='{ + organization(login: "ORG") { + projectV2(number: 42) { id title } + } +}' --jq '.data.organization.projectV2' +``` + +### 2. Reverse lookup from a known issue (most reliable) +If the user mentions an issue, epic, or milestone that's in the project, query that issue's `projectItems` to discover the project: + +```bash +gh api graphql -f query='{ + repository(owner: "OWNER", name: "REPO") { + issue(number: 123) { + projectItems(first: 10) { + nodes { + id + project { number title id } + } + } + } + } +}' --jq '.data.repository.issue.projectItems.nodes[] | {number: .project.number, title: .project.title, id: .project.id}' +``` + +This is the most reliable approach for large orgs where name search fails. + +### 3. GraphQL name search with client-side filtering (fallback) +Query a large page and filter client-side for an exact title match: + +```bash +gh api graphql -f query='{ + organization(login: "ORG") { + projectsV2(first: 100, query: "search term") { + nodes { number title id } + } + } +}' --jq '.data.organization.projectsV2.nodes[] | select(.title | test("(?i)^exact name$"))' +``` + +If this returns nothing, paginate with `after` cursor or broaden the regex. Results are sorted by recency so older projects require pagination. + +### 4. MCP tool (small orgs only) +Call `mcp__github__projects_list` with `method: "list_projects"`. This works well for orgs with <50 projects but has no name filter, so you must scan all results. + ## Project discovery for progress reports When a user asks for a progress update on a project (e.g., "Give me a progress update for Project X"), follow this workflow: -1. **Search by name** - call `projects_list` with `list_projects` and scan results for a title matching the user's query. Project names are often informal, so match flexibly (e.g., "issue fields" matches "Issue fields" or "Issue Fields and Types"). +1. **Find the project** — use the [finding a project](#finding-a-project-by-name) strategies above. Ask the user for a known issue number if name search fails. 2. **Discover fields** - call `projects_list` with `list_project_fields` to find the Status field (its options tell you the workflow stages) and any Iteration field (to scope to the current sprint). @@ -53,23 +106,77 @@ When a user asks for a progress update on a project (e.g., "Give me a progress u 5. **Add context** - if items have sub-issues, include `subIssuesSummary` counts. If items have dependencies, note blocked items and what blocks them. -**Tip:** For org-level projects, use GraphQL with `organization.projectsV2(first: 20, query: "search term")` to search by name directly, which is faster than listing all projects. +## OAuth Scope Requirements -## Using GraphQL directly (advanced) +| Operation | Required scope | +|-----------|---------------| +| Read projects, fields, items | `read:project` | +| Add/update/delete items, change field values | `project` | -Required scope: `read:project` for queries, `project` for mutations. +**Common pitfall:** The default `gh auth` token often only has `read:project`. Mutations will fail with `INSUFFICIENT_SCOPES`. To add the write scope: -**Find a project:** -```graphql -{ - organization(login: "ORG") { - projectV2(number: 5) { id title } - } -} +```bash +gh auth refresh -h github.com -s project ``` -**List fields (including single-select options):** -```graphql +This triggers a browser-based OAuth flow. You must complete it before mutations will work. + +## Finding an Issue's Project Item ID + +When you know the issue but need its project item ID (e.g., to update its Status), query from the issue side: + +```bash +gh api graphql -f query=' +{ + repository(owner: "OWNER", name: "REPO") { + issue(number: 123) { + projectItems(first: 5) { + nodes { + id + project { title number } + fieldValues(first: 10) { + nodes { + ... on ProjectV2ItemFieldSingleSelectValue { + name + field { ... on ProjectV2SingleSelectField { name } } + } + } + } + } + } + } + } +}' --jq '.data.repository.issue.projectItems.nodes' +``` + +This returns the item ID, project info, and current field values in one query. + +## Using GraphQL via gh api (recommended) + +Use `gh api graphql` to run GraphQL queries and mutations. This is more reliable than MCP tools for write operations. + +**Find a project and its Status field options:** +```bash +gh api graphql -f query=' +{ + organization(login: "ORG") { + projectV2(number: 5) { + id + title + field(name: "Status") { + ... on ProjectV2SingleSelectField { + id + options { id name } + } + } + } + } +}' --jq '.data.organization.projectV2' +``` + +**List all fields (including iterations):** +```bash +gh api graphql -f query=' { node(id: "PROJECT_ID") { ... on ProjectV2 { @@ -82,23 +189,12 @@ Required scope: `read:project` for queries, `project` for mutations. } } } -} +}' --jq '.data.node.fields.nodes' ``` -**Add an item:** -```graphql -mutation { - addProjectV2ItemById(input: { - projectId: "PROJECT_ID" - contentId: "ISSUE_OR_PR_NODE_ID" - }) { - item { id } - } -} -``` - -**Update a field value:** -```graphql +**Update a field value (e.g., set Status to "In Progress"):** +```bash +gh api graphql -f query=' mutation { updateProjectV2ItemFieldValue(input: { projectId: "PROJECT_ID" @@ -108,13 +204,27 @@ mutation { }) { projectV2Item { id } } -} +}' ``` Value accepts one of: `text`, `number`, `date`, `singleSelectOptionId`, `iterationId`. +**Add an item:** +```bash +gh api graphql -f query=' +mutation { + addProjectV2ItemById(input: { + projectId: "PROJECT_ID" + contentId: "ISSUE_OR_PR_NODE_ID" + }) { + item { id } + } +}' +``` + **Delete an item:** -```graphql +```bash +gh api graphql -f query=' mutation { deleteProjectV2Item(input: { projectId: "PROJECT_ID" @@ -122,5 +232,42 @@ mutation { }) { deletedItemId } -} +}' +``` + +## End-to-End Example: Set Issue Status to "In Progress" + +```bash +# 1. Get the issue's project item ID, project ID, and current status +gh api graphql -f query='{ + repository(owner: "github", name: "planning-tracking") { + issue(number: 2574) { + projectItems(first: 1) { + nodes { id project { id title } } + } + } + } +}' --jq '.data.repository.issue.projectItems.nodes[0]' + +# 2. Get the Status field ID and "In Progress" option ID +gh api graphql -f query='{ + node(id: "PROJECT_ID") { + ... on ProjectV2 { + field(name: "Status") { + ... on ProjectV2SingleSelectField { id options { id name } } + } + } + } +}' --jq '.data.node.field' + +# 3. Update the status +gh api graphql -f query='mutation { + updateProjectV2ItemFieldValue(input: { + projectId: "PROJECT_ID" + itemId: "ITEM_ID" + fieldId: "FIELD_ID" + value: { singleSelectOptionId: "IN_PROGRESS_OPTION_ID" } + }) { projectV2Item { id } } +}' +``` ``` diff --git a/skills/github-issues/references/search.md b/skills/github-issues/references/search.md new file mode 100644 index 00000000..9e08efaf --- /dev/null +++ b/skills/github-issues/references/search.md @@ -0,0 +1,231 @@ +# Advanced Issue Search + +The `search_issues` MCP tool uses GitHub's issue search query format for cross-repo searches, supporting implicit-AND queries, date ranges, and metadata filters (but not explicit OR/NOT operators). + +## When to Use Search vs List vs Advanced Search + +There are three ways to find issues, each with different capabilities: + +| Capability | `list_issues` (MCP) | `search_issues` (MCP) | Advanced search (`gh api`) | +|-----------|---------------------|----------------------|---------------------------| +| **Scope** | Single repo only | Cross-repo, cross-org | Cross-repo, cross-org | +| **Issue field filters** (`field.priority:P0`) | No | No | **Yes** (dot notation) | +| **Issue type filter** (`type:Bug`) | No | Yes | Yes | +| **Boolean logic** (AND/OR/NOT, nesting) | No | Yes (implicit AND only) | **Yes** (explicit AND/OR/NOT) | +| **Label/state/date filters** | Yes | Yes | Yes | +| **Assignee/author/mentions** | No | Yes | Yes | +| **Negation** (`-label:x`, `no:label`) | No | Yes | Yes | +| **Text search** (title/body/comments) | No | Yes | Yes | +| **`since` filter** | Yes | No | No | +| **Result limit** | No cap (paginate all) | 1,000 max | 1,000 max | +| **How to call** | MCP tool directly | MCP tool directly | `gh api` with `advanced_search=true` | + +**Decision guide:** +- **Single repo, simple filters (state, labels, recent updates):** use `list_issues` +- **Cross-repo, text search, author/assignee, issue types:** use `search_issues` +- **Issue field values (Priority, dates, custom fields) or complex boolean logic:** use `gh api` with `advanced_search=true` + +## Query Syntax + +The `query` parameter is a string of search terms and qualifiers. A space between terms is implicit AND. + +### Scoping + +``` +repo:owner/repo # Single repo (auto-added if you pass owner+repo params) +org:github # All repos in an org +user:octocat # All repos owned by user +in:title # Search only in title +in:body # Search only in body +in:comments # Search only in comments +``` + +### State & Close Reason + +``` +is:open # Open issues (auto-added: is:issue) +is:closed # Closed issues +reason:completed # Closed as completed +reason:"not planned" # Closed as not planned +``` + +### People + +``` +author:username # Created by +assignee:username # Assigned to +mentions:username # Mentions user +commenter:username # Has comment from +involves:username # Author OR assignee OR mentioned OR commenter +author:@me # Current authenticated user +team:org/team # Team mentioned +``` + +### Labels, Milestones, Projects, Types + +``` +label:"bug" # Has label (quote multi-word labels) +label:bug label:priority # Has BOTH labels (AND) +label:bug,enhancement # Has EITHER label (OR) +-label:wontfix # Does NOT have label +milestone:"v2.0" # In milestone +project:github/57 # In project board +type:"Bug" # Issue type +``` + +### Missing Metadata + +``` +no:label # No labels assigned +no:milestone # No milestone +no:assignee # Unassigned +no:project # Not in any project +``` + +### Dates + +All date qualifiers support `>`, `<`, `>=`, `<=`, and range (`..`) operators with ISO 8601 format: + +``` +created:>2026-01-01 # Created after Jan 1 +updated:>=2026-03-01 # Updated since Mar 1 +closed:2026-01-01..2026-02-01 # Closed in January +created:<2026-01-01 # Created before Jan 1 +``` + +### Linked Content + +``` +linked:pr # Issue has a linked PR +-linked:pr # Issues not yet linked to any PR +linked:issue # PR is linked to an issue +``` + +### Numeric Filters + +``` +comments:>10 # More than 10 comments +comments:0 # No comments +interactions:>100 # Reactions + comments > 100 +reactions:>50 # More than 50 reactions +``` + +### Boolean Logic & Nesting + +Use `AND`, `OR`, and parentheses (up to 5 levels deep, max 5 operators): + +``` +label:bug AND assignee:octocat +assignee:octocat OR assignee:hubot +(type:"Bug" AND label:P1) OR (type:"Feature" AND label:P1) +-author:app/dependabot # Exclude bot issues +``` + +A space between terms without an explicit operator is treated as AND. + +## Common Query Patterns + +**Unassigned bugs:** +``` +repo:owner/repo type:"Bug" no:assignee is:open +``` + +**Issues closed this week:** +``` +repo:owner/repo is:closed closed:>=2026-03-01 +``` + +**Stale open issues (no updates in 90 days):** +``` +repo:owner/repo is:open updated:<2026-01-01 +``` + +**Open issues without a linked PR (needs work):** +``` +repo:owner/repo is:open -linked:pr +``` + +**Issues I'm involved in across an org:** +``` +org:github involves:@me is:open +``` + +**High-activity issues:** +``` +repo:owner/repo is:open comments:>20 +``` + +**Issues by type and priority label:** +``` +repo:owner/repo type:"Epic" label:P1 is:open +``` + +## Issue Field Search + +> **Reliability warning:** The `field.name:value` search qualifier syntax is experimental and may return 0 results even when matching issues exist. For reliable filtering by field values, use the GraphQL bulk query approach documented in [issue-fields.md](issue-fields.md#searching-by-field-values). + +Issue fields can theoretically be searched via the `field.name:value` qualifier using **advanced search mode**. This works in the web UI but results from the API are inconsistent. + +### REST API + +Add `advanced_search=true` as a query parameter: + +```bash +gh api "search/issues?q=org:github+field.priority:P0+type:Epic+is:open&advanced_search=true" \ + --jq '.items[] | "#\(.number): \(.title)"' +``` + +### GraphQL + +Use `type: ISSUE_ADVANCED` instead of `type: ISSUE`: + +```graphql +{ + search(query: "org:github field.priority:P0 type:Epic is:open", type: ISSUE_ADVANCED, first: 10) { + issueCount + nodes { + ... on Issue { number title } + } + } +} +``` + +### Issue Field Qualifiers + +The syntax uses **dot notation** with the field's slug name (lowercase, hyphens for spaces): + +``` +field.priority:P0 # Single-select field equals value +field.priority:P1 # Different option value +field.target-date:>=2026-04-01 # Date comparison +has:field.priority # Has any value set +no:field.priority # Has no value set +``` + +**MCP limitation:** The `search_issues` MCP tool does not pass `advanced_search=true`. You must use `gh api` directly for issue field searches. + +### Common Field Search Patterns + +**P0 epics across an org:** +``` +org:github field.priority:P0 type:Epic is:open +``` + +**Issues with a target date this quarter:** +``` +org:github field.target-date:>=2026-04-01 field.target-date:<=2026-06-30 is:open +``` + +**Open bugs missing priority:** +``` +org:github no:field.priority type:Bug is:open +``` + +## Limitations + +- Query text: max **256 characters** (excluding operators/qualifiers) +- Boolean operators: max **5** AND/OR/NOT per query +- Results: max **1,000** total (use `list_issues` if you need all issues) +- Repo scan: searches up to **4,000** matching repositories +- Rate limit: **30 requests/minute** for authenticated search +- Issue field search requires `advanced_search=true` (REST) or `ISSUE_ADVANCED` (GraphQL); not available through MCP `search_issues` diff --git a/skills/github-issues/references/sub-issues.md b/skills/github-issues/references/sub-issues.md index 96577f9d..aac288e6 100644 --- a/skills/github-issues/references/sub-issues.md +++ b/skills/github-issues/references/sub-issues.md @@ -2,46 +2,64 @@ Sub-issues let you break down work into hierarchical tasks. Each parent issue can have up to 100 sub-issues, nested up to 8 levels deep. Sub-issues can span repositories within the same owner. +## Recommended Workflow + +The simplest way to create a sub-issue is **two steps**: create the issue, then link it. + +```bash +# Step 1: Create the issue and capture its numeric ID +ISSUE_ID=$(gh api repos/{owner}/{repo}/issues \ + -X POST \ + -f title="Sub-task title" \ + -f body="Description" \ + --jq '.id') + +# Step 2: Link it as a sub-issue of the parent +# IMPORTANT: sub_issue_id must be an integer. Use --input (not -f) to send JSON. +echo "{\"sub_issue_id\": $ISSUE_ID}" | gh api repos/{owner}/{repo}/issues/{parent_number}/sub_issues -X POST --input - +``` + +**Why `--input` instead of `-f`?** The `gh api -f` flag sends all values as strings, but the API requires `sub_issue_id` as an integer. Using `-f sub_issue_id=12345` will return a 422 error. + +Alternatively, use GraphQL `createIssue` with `parentIssueId` to do it in one step (see GraphQL section below). + ## Using MCP tools **List sub-issues:** Call `mcp__github__issue_read` with `method: "get_sub_issues"`, `owner`, `repo`, and `issue_number`. **Create an issue as a sub-issue:** -There is no MCP tool for creating sub-issues directly. Use REST or GraphQL (see below). +There is no MCP tool for creating sub-issues directly. Use the workflow above or GraphQL. ## Using REST API **List sub-issues:** -``` -GET /repos/{owner}/{repo}/issues/{issue_number}/sub_issues +```bash +gh api repos/{owner}/{repo}/issues/{issue_number}/sub_issues ``` **Get parent issue:** -``` -GET /repos/{owner}/{repo}/issues/{issue_number}/parent +```bash +gh api repos/{owner}/{repo}/issues/{issue_number}/parent ``` **Add an existing issue as a sub-issue:** -``` -POST /repos/{owner}/{repo}/issues/{issue_number}/sub_issues -Body: { "sub_issue_id": 12345 } +```bash +# sub_issue_id is the numeric issue ID (not the issue number) +# Get it from the .id field when creating or fetching an issue +echo '{"sub_issue_id": 12345}' | gh api repos/{owner}/{repo}/issues/{parent_number}/sub_issues -X POST --input - ``` -The `sub_issue_id` is the numeric issue **ID** (not the issue number). Get it from the issue's `id` field in any API response. - -To move a sub-issue that already has a parent, add `"replace_parent": true`. +To move a sub-issue that already has a parent, add `"replace_parent": true` to the JSON body. **Remove a sub-issue:** -``` -DELETE /repos/{owner}/{repo}/issues/{issue_number}/sub_issue -Body: { "sub_issue_id": 12345 } +```bash +echo '{"sub_issue_id": 12345}' | gh api repos/{owner}/{repo}/issues/{parent_number}/sub_issue -X DELETE --input - ``` **Reprioritize a sub-issue:** -``` -PATCH /repos/{owner}/{repo}/issues/{issue_number}/sub_issues/priority -Body: { "sub_issue_id": 6, "after_id": 5 } +```bash +echo '{"sub_issue_id": 6, "after_id": 5}' | gh api repos/{owner}/{repo}/issues/{parent_number}/sub_issues/priority -X PATCH --input - ``` Use `after_id` or `before_id` to position the sub-issue relative to another. From a61d7bf9c1ddea5ac60b09f39fa8dbb953f73fa8 Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Mon, 9 Mar 2026 09:13:47 +1100 Subject: [PATCH 12/37] Update Astro site URL to awesome-copilot.github.com with root base path (#925) * Initial plan * chore: update Astro site URL to awesome-copilot.github.com with root base path Co-authored-by: aaronpowell <434140+aaronpowell@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: aaronpowell <434140+aaronpowell@users.noreply.github.com> --- website/astro.config.mjs | 4 ++-- website/src/integrations/pagefind-resources.ts | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/website/astro.config.mjs b/website/astro.config.mjs index 76a8d50a..e6e3866f 100644 --- a/website/astro.config.mjs +++ b/website/astro.config.mjs @@ -5,8 +5,8 @@ import pagefindResources from "./src/integrations/pagefind-resources"; // https://astro.build/config export default defineConfig({ - site: "https://github.github.com/", - base: "/awesome-copilot/", + site: "https://awesome-copilot.github.com/", + base: "/", output: "static", integrations: [ starlight({ diff --git a/website/src/integrations/pagefind-resources.ts b/website/src/integrations/pagefind-resources.ts index 1a7efab5..95a56335 100644 --- a/website/src/integrations/pagefind-resources.ts +++ b/website/src/integrations/pagefind-resources.ts @@ -86,7 +86,7 @@ export default function pagefindResources(): AstroIntegration { records = []; } - // Use the base path from Astro config (e.g. "/awesome-copilot/") + // Use the base path from Astro config (e.g. "/") const base = siteBase.endsWith("/") ? siteBase : `${siteBase}/`; let added = 0; From 0a16fe42850e72f5c5c7c93c0a2bcc89f6d13772 Mon Sep 17 00:00:00 2001 From: Catherine Han <123369259+ninihen1@users.noreply.github.com> Date: Mon, 9 Mar 2026 09:58:31 +1100 Subject: [PATCH 13/37] feat: add flowstudio-power-automate-debug and flowstudio-power-automate-build skills (#899) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat: add flowstudio-power-automate-debug and flowstudio-power-automate-build skills Two companion skills for the FlowStudio Power Automate MCP server: - flowstudio-power-automate-debug: Debug workflow for failed Power Automate cloud flow runs - flowstudio-power-automate-build: Build & deploy flows from natural language descriptions Both require a FlowStudio MCP subscription: https://flowstudio.app These complement the existing flowstudio-power-automate-mcp skill (merged in PR #896). * fix: address all review comments — README, cross-refs, response shapes, step numbering - Add skills to docs/README.skills.md (fixes validate-readme CI check) - Update cross-skill references to use flowstudio- prefix (#1, #4, #7, #9) - Fix get_live_flow_run_action_outputs: returns array, index [0] (#2, #3) - Renumber Step 6→5, Step 7→6 — remove gap in build workflow (#8) - Fix connectionName note: it's the key, not the GUID (#10) - Remove invalid arrow function from Filter array expression (#11) * feat: add flowstudio-power-automate plugin bundling all 3 skills Plugin bundles: - flowstudio-power-automate-mcp (core connection & CRUD) - flowstudio-power-automate-debug (debug failed runs) - flowstudio-power-automate-build (build & deploy flows) Install: copilot plugin install flowstudio-power-automate@awesome-copilot Per @aaronpowell's suggestion in review. --- .github/plugin/marketplace.json | 6 + docs/README.plugins.md | 1 + docs/README.skills.md | 2 + .../.github/plugin/plugin.json | 24 + plugins/flowstudio-power-automate/README.md | 37 + .../flowstudio-power-automate-build/SKILL.md | 460 +++++++++++ .../references/action-patterns-connectors.md | 542 +++++++++++++ .../references/action-patterns-core.md | 542 +++++++++++++ .../references/action-patterns-data.md | 735 ++++++++++++++++++ .../references/build-patterns.md | 108 +++ .../references/flow-schema.md | 225 ++++++ .../references/trigger-types.md | 211 +++++ .../flowstudio-power-automate-debug/SKILL.md | 322 ++++++++ .../references/common-errors.md | 188 +++++ .../references/debug-workflow.md | 157 ++++ 15 files changed, 3560 insertions(+) create mode 100644 plugins/flowstudio-power-automate/.github/plugin/plugin.json create mode 100644 plugins/flowstudio-power-automate/README.md create mode 100644 skills/flowstudio-power-automate-build/SKILL.md create mode 100644 skills/flowstudio-power-automate-build/references/action-patterns-connectors.md create mode 100644 skills/flowstudio-power-automate-build/references/action-patterns-core.md create mode 100644 skills/flowstudio-power-automate-build/references/action-patterns-data.md create mode 100644 skills/flowstudio-power-automate-build/references/build-patterns.md create mode 100644 skills/flowstudio-power-automate-build/references/flow-schema.md create mode 100644 skills/flowstudio-power-automate-build/references/trigger-types.md create mode 100644 skills/flowstudio-power-automate-debug/SKILL.md create mode 100644 skills/flowstudio-power-automate-debug/references/common-errors.md create mode 100644 skills/flowstudio-power-automate-debug/references/debug-workflow.md diff --git a/.github/plugin/marketplace.json b/.github/plugin/marketplace.json index c89b38a2..cf4d6a8e 100644 --- a/.github/plugin/marketplace.json +++ b/.github/plugin/marketplace.json @@ -113,6 +113,12 @@ "description": "Task Researcher and Task Planner for intermediate to expert users and large codebases - Brought to you by microsoft/edge-ai", "version": "1.0.0" }, + { + "name": "flowstudio-power-automate", + "source": "flowstudio-power-automate", + "description": "Complete toolkit for managing Power Automate cloud flows via the FlowStudio MCP server. Includes skills for connecting to the MCP server, debugging failed flow runs, and building/deploying flows from natural language.", + "version": "1.0.0" + }, { "name": "frontend-web-dev", "source": "frontend-web-dev", diff --git a/docs/README.plugins.md b/docs/README.plugins.md index 284d3c7e..cca2d1b9 100644 --- a/docs/README.plugins.md +++ b/docs/README.plugins.md @@ -38,6 +38,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-plugins) for guidelines on how t | [dataverse-sdk-for-python](../plugins/dataverse-sdk-for-python/README.md) | Comprehensive collection for building production-ready Python integrations with Microsoft Dataverse. Includes official documentation, best practices, advanced features, file operations, and code generation prompts. | 4 items | dataverse, python, integration, sdk | | [devops-oncall](../plugins/devops-oncall/README.md) | A focused set of prompts, instructions, and a chat mode to help triage incidents and respond quickly with DevOps tools and Azure resources. | 3 items | devops, incident-response, oncall, azure | | [edge-ai-tasks](../plugins/edge-ai-tasks/README.md) | Task Researcher and Task Planner for intermediate to expert users and large codebases - Brought to you by microsoft/edge-ai | 2 items | architecture, planning, research, tasks, implementation | +| [flowstudio-power-automate](../plugins/flowstudio-power-automate/README.md) | Complete toolkit for managing Power Automate cloud flows via the FlowStudio MCP server. Includes skills for connecting to the MCP server, debugging failed flow runs, and building/deploying flows from natural language. | 3 items | power-automate, power-platform, flowstudio, mcp, model-context-protocol, cloud-flows, workflow-automation | | [frontend-web-dev](../plugins/frontend-web-dev/README.md) | Essential prompts, instructions, and chat modes for modern frontend web development including React, Angular, Vue, TypeScript, and CSS frameworks. | 4 items | frontend, web, react, typescript, javascript, css, html, angular, vue | | [gem-team](../plugins/gem-team/README.md) | A modular multi-agent team for complex project execution with DAG-based planning, parallel execution, TDD verification, and automated testing with energetic team lead. | 8 items | multi-agent, orchestration, dag-planning, parallel-execution, tdd, verification, automation, security, prd | | [go-mcp-development](../plugins/go-mcp-development/README.md) | Complete toolkit for building Model Context Protocol (MCP) servers in Go using the official github.com/modelcontextprotocol/go-sdk. Includes instructions for best practices, a prompt for generating servers, and an expert chat mode for guidance. | 2 items | go, golang, mcp, model-context-protocol, server-development, sdk | diff --git a/docs/README.skills.md b/docs/README.skills.md index ca513c5f..3ac73000 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -112,6 +112,8 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [finalize-agent-prompt](../skills/finalize-agent-prompt/SKILL.md) | Finalize prompt file using the role of an AI agent to polish the prompt for the end user. | None | | [finnish-humanizer](../skills/finnish-humanizer/SKILL.md) | Detect and remove AI-generated markers from Finnish text, making it sound like a native Finnish speaker wrote it. Use when asked to "humanize", "naturalize", or "remove AI feel" from Finnish text, or when editing .md/.txt files containing Finnish content. Identifies 26 patterns (12 Finnish-specific + 14 universal) and 4 style markers. | `references/patterns.md` | | [first-ask](../skills/first-ask/SKILL.md) | Interactive, input-tool powered, task refinement workflow: interrogates scope, deliverables, constraints before carrying out the task; Requires the Joyride extension. | None | +| [flowstudio-power-automate-build](../skills/flowstudio-power-automate-build/SKILL.md) | Build, scaffold, and deploy Power Automate cloud flows using the FlowStudio MCP server. Load this skill when asked to: create a flow, build a new flow, deploy a flow definition, scaffold a Power Automate workflow, construct a flow JSON, update an existing flow's actions, patch a flow definition, add actions to a flow, wire up connections, or generate a workflow definition from scratch. Requires a FlowStudio MCP subscription — see https://mcp.flowstudio.app | `references/action-patterns-connectors.md`
`references/action-patterns-core.md`
`references/action-patterns-data.md`
`references/build-patterns.md`
`references/flow-schema.md`
`references/trigger-types.md` | +| [flowstudio-power-automate-debug](../skills/flowstudio-power-automate-debug/SKILL.md) | Debug failing Power Automate cloud flows using the FlowStudio MCP server. Load this skill when asked to: debug a flow, investigate a failed run, why is this flow failing, inspect action outputs, find the root cause of a flow error, fix a broken Power Automate flow, diagnose a timeout, trace a DynamicOperationRequestFailure, check connector auth errors, read error details from a run, or troubleshoot expression failures. Requires a FlowStudio MCP subscription — see https://mcp.flowstudio.app | `references/common-errors.md`
`references/debug-workflow.md` | | [flowstudio-power-automate-mcp](../skills/flowstudio-power-automate-mcp/SKILL.md) | Connect to and operate Power Automate cloud flows via a FlowStudio MCP server. Use when asked to: list flows, read a flow definition, check run history, inspect action outputs, resubmit a run, cancel a running flow, view connections, get a trigger URL, validate a definition, monitor flow health, or any task that requires talking to the Power Automate API through an MCP tool. Also use for Power Platform environment discovery and connection management. Requires a FlowStudio MCP subscription or compatible server — see https://mcp.flowstudio.app | `references/MCP-BOOTSTRAP.md`
`references/action-types.md`
`references/connection-references.md`
`references/tool-reference.md` | | [fluentui-blazor](../skills/fluentui-blazor/SKILL.md) | Guide for using the Microsoft Fluent UI Blazor component library (Microsoft.FluentUI.AspNetCore.Components NuGet package) in Blazor applications. Use this when the user is building a Blazor app with Fluent UI components, setting up the library, using FluentUI components like FluentButton, FluentDataGrid, FluentDialog, FluentToast, FluentNavMenu, FluentTextField, FluentSelect, FluentAutocomplete, FluentDesignTheme, or any component prefixed with "Fluent". Also use when troubleshooting missing providers, JS interop issues, or theming. | `references/DATAGRID.md`
`references/LAYOUT-AND-NAVIGATION.md`
`references/SETUP.md`
`references/THEMING.md` | | [folder-structure-blueprint-generator](../skills/folder-structure-blueprint-generator/SKILL.md) | Comprehensive technology-agnostic prompt for analyzing and documenting project folder structures. Auto-detects project types (.NET, Java, React, Angular, Python, Node.js, Flutter), generates detailed blueprints with visualization options, naming conventions, file placement patterns, and extension templates for maintaining consistent code organization across diverse technology stacks. | None | diff --git a/plugins/flowstudio-power-automate/.github/plugin/plugin.json b/plugins/flowstudio-power-automate/.github/plugin/plugin.json new file mode 100644 index 00000000..7c025d78 --- /dev/null +++ b/plugins/flowstudio-power-automate/.github/plugin/plugin.json @@ -0,0 +1,24 @@ +{ + "name": "flowstudio-power-automate", + "description": "Complete toolkit for managing Power Automate cloud flows via the FlowStudio MCP server. Includes skills for connecting to the MCP server, debugging failed flow runs, and building/deploying flows from natural language.", + "version": "1.0.0", + "author": { + "name": "Awesome Copilot Community" + }, + "repository": "https://github.com/github/awesome-copilot", + "license": "MIT", + "keywords": [ + "power-automate", + "power-platform", + "flowstudio", + "mcp", + "model-context-protocol", + "cloud-flows", + "workflow-automation" + ], + "skills": [ + "./skills/flowstudio-power-automate-mcp/", + "./skills/flowstudio-power-automate-debug/", + "./skills/flowstudio-power-automate-build/" + ] +} diff --git a/plugins/flowstudio-power-automate/README.md b/plugins/flowstudio-power-automate/README.md new file mode 100644 index 00000000..4924c658 --- /dev/null +++ b/plugins/flowstudio-power-automate/README.md @@ -0,0 +1,37 @@ +# FlowStudio Power Automate Plugin + +Complete toolkit for managing Power Automate cloud flows via the FlowStudio MCP server. Connect, debug, and build/deploy flows using AI agents. + +Requires a FlowStudio MCP subscription — see https://flowstudio.app + +## Installation + +```bash +# Using Copilot CLI +copilot plugin install flowstudio-power-automate@awesome-copilot +``` + +## What's Included + +### Skills + +| Skill | Description | +|-------|-------------| +| `flowstudio-power-automate-mcp` | Core connection setup, tool discovery, and CRUD operations for Power Automate cloud flows via the FlowStudio MCP server. | +| `flowstudio-power-automate-debug` | Step-by-step diagnostic workflow for investigating and fixing failing Power Automate cloud flow runs. | +| `flowstudio-power-automate-build` | Build, scaffold, and deploy Power Automate cloud flows from natural language descriptions with bundled action pattern templates. | + +## Getting Started + +1. Install the plugin +2. Subscribe to FlowStudio MCP at https://flowstudio.app +3. Configure your MCP connection with the JWT from your workspace +4. Ask Copilot to list your flows, debug a failure, or build a new flow + +## Source + +This plugin is part of [Awesome Copilot](https://github.com/github/awesome-copilot), a community-driven collection of GitHub Copilot extensions. + +## License + +MIT diff --git a/skills/flowstudio-power-automate-build/SKILL.md b/skills/flowstudio-power-automate-build/SKILL.md new file mode 100644 index 00000000..25112118 --- /dev/null +++ b/skills/flowstudio-power-automate-build/SKILL.md @@ -0,0 +1,460 @@ +--- +name: flowstudio-power-automate-build +description: >- + Build, scaffold, and deploy Power Automate cloud flows using the FlowStudio + MCP server. Load this skill when asked to: create a flow, build a new flow, + deploy a flow definition, scaffold a Power Automate workflow, construct a flow + JSON, update an existing flow's actions, patch a flow definition, add actions + to a flow, wire up connections, or generate a workflow definition from scratch. + Requires a FlowStudio MCP subscription — see https://mcp.flowstudio.app +--- + +# Build & Deploy Power Automate Flows with FlowStudio MCP + +Step-by-step guide for constructing and deploying Power Automate cloud flows +programmatically through the FlowStudio MCP server. + +**Prerequisite**: A FlowStudio MCP server must be reachable with a valid JWT. +See the `flowstudio-power-automate-mcp` skill for connection setup. +Subscribe at https://mcp.flowstudio.app + +--- + +## Source of Truth + +> **Always call `tools/list` first** to confirm available tool names and their +> parameter schemas. Tool names and parameters may change between server versions. +> This skill covers response shapes, behavioral notes, and build patterns — +> things `tools/list` cannot tell you. If this document disagrees with `tools/list` +> or a real API response, the API wins. + +--- + +## Python Helper + +```python +import json, urllib.request + +MCP_URL = "https://mcp.flowstudio.app/mcp" +MCP_TOKEN = "" + +def mcp(tool, **kwargs): + payload = json.dumps({"jsonrpc": "2.0", "id": 1, "method": "tools/call", + "params": {"name": tool, "arguments": kwargs}}).encode() + req = urllib.request.Request(MCP_URL, data=payload, + headers={"x-api-key": MCP_TOKEN, "Content-Type": "application/json", + "User-Agent": "FlowStudio-MCP/1.0"}) + try: + resp = urllib.request.urlopen(req, timeout=120) + except urllib.error.HTTPError as e: + body = e.read().decode("utf-8", errors="replace") + raise RuntimeError(f"MCP HTTP {e.code}: {body[:200]}") from e + raw = json.loads(resp.read()) + if "error" in raw: + raise RuntimeError(f"MCP error: {json.dumps(raw['error'])}") + return json.loads(raw["result"]["content"][0]["text"]) + +ENV = "" # e.g. Default-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx +``` + +--- + +## Step 1 — Safety Check: Does the Flow Already Exist? + +Always look before you build to avoid duplicates: + +```python +results = mcp("list_store_flows", + environmentName=ENV, searchTerm="My New Flow") + +# list_store_flows returns a direct array (no wrapper object) +if len(results) > 0: + # Flow exists — modify rather than create + # id format is "envId.flowId" — split to get the flow UUID + FLOW_ID = results[0]["id"].split(".", 1)[1] + print(f"Existing flow: {FLOW_ID}") + defn = mcp("get_live_flow", environmentName=ENV, flowName=FLOW_ID) +else: + print("Flow not found — building from scratch") + FLOW_ID = None +``` + +--- + +## Step 2 — Obtain Connection References + +Every connector action needs a `connectionName` that points to a key in the +flow's `connectionReferences` map. That key links to an authenticated connection +in the environment. + +> **MANDATORY**: You MUST call `list_live_connections` first — do NOT ask the +> user for connection names or GUIDs. The API returns the exact values you need. +> Only prompt the user if the API confirms that required connections are missing. + +### 2a — Always call `list_live_connections` first + +```python +conns = mcp("list_live_connections", environmentName=ENV) + +# Filter to connected (authenticated) connections only +active = [c for c in conns["connections"] + if c["statuses"][0]["status"] == "Connected"] + +# Build a lookup: connectorName → connectionName (id) +conn_map = {} +for c in active: + conn_map[c["connectorName"]] = c["id"] + +print(f"Found {len(active)} active connections") +print("Available connectors:", list(conn_map.keys())) +``` + +### 2b — Determine which connectors the flow needs + +Based on the flow you are building, identify which connectors are required. +Common connector API names: + +| Connector | API name | +|---|---| +| SharePoint | `shared_sharepointonline` | +| Outlook / Office 365 | `shared_office365` | +| Teams | `shared_teams` | +| Approvals | `shared_approvals` | +| OneDrive for Business | `shared_onedriveforbusiness` | +| Excel Online (Business) | `shared_excelonlinebusiness` | +| Dataverse | `shared_commondataserviceforapps` | +| Microsoft Forms | `shared_microsoftforms` | + +> **Flows that need NO connections** (e.g. Recurrence + Compose + HTTP only) +> can skip the rest of Step 2 — omit `connectionReferences` from the deploy call. + +### 2c — If connections are missing, guide the user + +```python +connectors_needed = ["shared_sharepointonline", "shared_office365"] # adjust per flow + +missing = [c for c in connectors_needed if c not in conn_map] + +if not missing: + print("✅ All required connections are available — proceeding to build") +else: + # ── STOP: connections must be created interactively ── + # Connections require OAuth consent in a browser — no API can create them. + print("⚠️ The following connectors have no active connection in this environment:") + for c in missing: + friendly = c.replace("shared_", "").replace("onlinebusiness", " Online (Business)") + print(f" • {friendly} (API name: {c})") + print() + print("Please create the missing connections:") + print(" 1. Open https://make.powerautomate.com/connections") + print(" 2. Select the correct environment from the top-right picker") + print(" 3. Click '+ New connection' for each missing connector listed above") + print(" 4. Sign in and authorize when prompted") + print(" 5. Tell me when done — I will re-check and continue building") + # DO NOT proceed to Step 3 until the user confirms. + # After user confirms, re-run Step 2a to refresh conn_map. +``` + +### 2d — Build the connectionReferences block + +Only execute this after 2c confirms no missing connectors: + +```python +connection_references = {} +for connector in connectors_needed: + connection_references[connector] = { + "connectionName": conn_map[connector], # the GUID from list_live_connections + "source": "Invoker", + "id": f"/providers/Microsoft.PowerApps/apis/{connector}" + } +``` + +> **IMPORTANT — `host.connectionName` in actions**: When building actions in +> Step 3, set `host.connectionName` to the **key** from this map (e.g. +> `shared_teams`), NOT the connection GUID. The GUID only goes inside the +> `connectionReferences` entry. The engine matches the action's +> `host.connectionName` to the key to find the right connection. + +> **Alternative** — if you already have a flow using the same connectors, +> you can extract `connectionReferences` from its definition: +> ```python +> ref_flow = mcp("get_live_flow", environmentName=ENV, flowName="") +> connection_references = ref_flow["properties"]["connectionReferences"] +> ``` + +See the `power-automate-mcp` skill's **connection-references.md** reference +for the full connection reference structure. + +--- + +## Step 3 — Build the Flow Definition + +Construct the definition object. See [flow-schema.md](references/flow-schema.md) +for the full schema and these action pattern references for copy-paste templates: +- [action-patterns-core.md](references/action-patterns-core.md) — Variables, control flow, expressions +- [action-patterns-data.md](references/action-patterns-data.md) — Array transforms, HTTP, parsing +- [action-patterns-connectors.md](references/action-patterns-connectors.md) — SharePoint, Outlook, Teams, Approvals + +```python +definition = { + "$schema": "https://schema.management.azure.com/providers/Microsoft.Logic/schemas/2016-06-01/workflowdefinition.json#", + "contentVersion": "1.0.0.0", + "triggers": { ... }, # see trigger-types.md / build-patterns.md + "actions": { ... } # see ACTION-PATTERNS-*.md / build-patterns.md +} +``` + +> See [build-patterns.md](references/build-patterns.md) for complete, ready-to-use +> flow definitions covering Recurrence+SharePoint+Teams, HTTP triggers, and more. + +--- + +## Step 4 — Deploy (Create or Update) + +`update_live_flow` handles both creation and updates in a single tool. + +### Create a new flow (no existing flow) + +Omit `flowName` — the server generates a new GUID and creates via PUT: + +```python +result = mcp("update_live_flow", + environmentName=ENV, + # flowName omitted → creates a new flow + definition=definition, + connectionReferences=connection_references, + displayName="Overdue Invoice Notifications", + description="Weekly SharePoint → Teams notification flow, built by agent" +) + +if result.get("error") is not None: + print("Create failed:", result["error"]) +else: + # Capture the new flow ID for subsequent steps + FLOW_ID = result["created"] + print(f"✅ Flow created: {FLOW_ID}") +``` + +### Update an existing flow + +Provide `flowName` to PATCH: + +```python +result = mcp("update_live_flow", + environmentName=ENV, + flowName=FLOW_ID, + definition=definition, + connectionReferences=connection_references, + displayName="My Updated Flow", + description="Updated by agent on " + __import__('datetime').datetime.utcnow().isoformat() +) + +if result.get("error") is not None: + print("Update failed:", result["error"]) +else: + print("Update succeeded:", result) +``` + +> ⚠️ `update_live_flow` always returns an `error` key. +> `null` (Python `None`) means success — do not treat the presence of the key as failure. +> +> ⚠️ `description` is required for both create and update. + +### Common deployment errors + +| Error message (contains) | Cause | Fix | +|---|---|---| +| `missing from connectionReferences` | An action's `host.connectionName` references a key that doesn't exist in the `connectionReferences` map | Ensure `host.connectionName` uses the **key** from `connectionReferences` (e.g. `shared_teams`), not the raw GUID | +| `ConnectionAuthorizationFailed` / 403 | The connection GUID belongs to another user or is not authorized | Re-run Step 2a and use a connection owned by the current `x-api-key` user | +| `InvalidTemplate` / `InvalidDefinition` | Syntax error in the definition JSON | Check `runAfter` chains, expression syntax, and action type spelling | +| `ConnectionNotConfigured` | A connector action exists but the connection GUID is invalid or expired | Re-check `list_live_connections` for a fresh GUID | + +--- + +## Step 5 — Verify the Deployment + +```python +check = mcp("get_live_flow", environmentName=ENV, flowName=FLOW_ID) + +# Confirm state +print("State:", check["properties"]["state"]) # Should be "Started" + +# Confirm the action we added is there +acts = check["properties"]["definition"]["actions"] +print("Actions:", list(acts.keys())) +``` + +--- + +## Step 6 — Test the Flow + +> **MANDATORY**: Before triggering any test run, **ask the user for confirmation**. +> Running a flow has real side effects — it may send emails, post Teams messages, +> write to SharePoint, start approvals, or call external APIs. Explain what the +> flow will do and wait for explicit approval before calling `trigger_live_flow` +> or `resubmit_live_flow_run`. + +### Updated flows (have prior runs) + +The fastest path — resubmit the most recent run: + +```python +runs = mcp("get_live_flow_runs", environmentName=ENV, flowName=FLOW_ID, top=1) +if runs: + result = mcp("resubmit_live_flow_run", + environmentName=ENV, flowName=FLOW_ID, runName=runs[0]["name"]) + print(result) +``` + +### Flows already using an HTTP trigger + +Fire directly with a test payload: + +```python +schema = mcp("get_live_flow_http_schema", + environmentName=ENV, flowName=FLOW_ID) +print("Expected body:", schema.get("triggerSchema")) + +result = mcp("trigger_live_flow", + environmentName=ENV, flowName=FLOW_ID, + body={"name": "Test", "value": 1}) +print(f"Status: {result['status']}") +``` + +### Brand-new non-HTTP flows (Recurrence, connector triggers, etc.) + +A brand-new Recurrence or connector-triggered flow has no runs to resubmit +and no HTTP endpoint to call. **Deploy with a temporary HTTP trigger first, +test the actions, then swap to the production trigger.** + +#### 7a — Save the real trigger, deploy with a temporary HTTP trigger + +```python +# Save the production trigger you built in Step 3 +production_trigger = definition["triggers"] + +# Replace with a temporary HTTP trigger +definition["triggers"] = { + "manual": { + "type": "Request", + "kind": "Http", + "inputs": { + "schema": {} + } + } +} + +# Deploy (create or update) with the temp trigger +result = mcp("update_live_flow", + environmentName=ENV, + flowName=FLOW_ID, # omit if creating new + definition=definition, + connectionReferences=connection_references, + displayName="Overdue Invoice Notifications", + description="Deployed with temp HTTP trigger for testing") + +if result.get("error") is not None: + print("Deploy failed:", result["error"]) +else: + if not FLOW_ID: + FLOW_ID = result["created"] + print(f"✅ Deployed with temp HTTP trigger: {FLOW_ID}") +``` + +#### 7b — Fire the flow and check the result + +```python +# Trigger the flow +test = mcp("trigger_live_flow", + environmentName=ENV, flowName=FLOW_ID) +print(f"Trigger response status: {test['status']}") + +# Wait for the run to complete +import time; time.sleep(15) + +# Check the run result +runs = mcp("get_live_flow_runs", + environmentName=ENV, flowName=FLOW_ID, top=1) +run = runs[0] +print(f"Run {run['name']}: {run['status']}") + +if run["status"] == "Failed": + err = mcp("get_live_flow_run_error", + environmentName=ENV, flowName=FLOW_ID, runName=run["name"]) + root = err["failedActions"][-1] + print(f"Root cause: {root['actionName']} → {root.get('code')}") + # Debug and fix the definition before proceeding + # See power-automate-debug skill for full diagnosis workflow +``` + +#### 7c — Swap to the production trigger + +Once the test run succeeds, replace the temporary HTTP trigger with the real one: + +```python +# Restore the production trigger +definition["triggers"] = production_trigger + +result = mcp("update_live_flow", + environmentName=ENV, + flowName=FLOW_ID, + definition=definition, + connectionReferences=connection_references, + description="Swapped to production trigger after successful test") + +if result.get("error") is not None: + print("Trigger swap failed:", result["error"]) +else: + print("✅ Production trigger deployed — flow is live") +``` + +> **Why this works**: The trigger is just the entry point — the actions are +> identical regardless of how the flow starts. Testing via HTTP trigger +> exercises all the same Compose, SharePoint, Teams, etc. actions. +> +> **Connector triggers** (e.g. "When an item is created in SharePoint"): +> If actions reference `triggerBody()` or `triggerOutputs()`, pass a +> representative test payload in `trigger_live_flow`'s `body` parameter +> that matches the shape the connector trigger would produce. + +--- + +## Gotchas + +| Mistake | Consequence | Prevention | +|---|---|---| +| Missing `connectionReferences` in deploy | 400 "Supply connectionReferences" | Always call `list_live_connections` first | +| `"operationOptions"` missing on Foreach | Parallel execution, race conditions on writes | Always add `"Sequential"` | +| `union(old_data, new_data)` | Old values override new (first-wins) | Use `union(new_data, old_data)` | +| `split()` on potentially-null string | `InvalidTemplate` crash | Wrap with `coalesce(field, '')` | +| Checking `result["error"]` exists | Always present; true error is `!= null` | Use `result.get("error") is not None` | +| Flow deployed but state is "Stopped" | Flow won't run on schedule | Check connection auth; re-enable | +| Teams "Chat with Flow bot" recipient as object | 400 `GraphUserDetailNotFound` | Use plain string with trailing semicolon (see below) | + +### Teams `PostMessageToConversation` — Recipient Formats + +The `body/recipient` parameter format depends on the `location` value: + +| Location | `body/recipient` format | Example | +|---|---|---| +| **Chat with Flow bot** | Plain email string with **trailing semicolon** | `"user@contoso.com;"` | +| **Channel** | Object with `groupId` and `channelId` | `{"groupId": "...", "channelId": "..."}` | + +> **Common mistake**: passing `{"to": "user@contoso.com"}` for "Chat with Flow bot" +> returns a 400 `GraphUserDetailNotFound` error. The API expects a plain string. + +--- + +## Reference Files + +- [flow-schema.md](references/flow-schema.md) — Full flow definition JSON schema +- [trigger-types.md](references/trigger-types.md) — Trigger type templates +- [action-patterns-core.md](references/action-patterns-core.md) — Variables, control flow, expressions +- [action-patterns-data.md](references/action-patterns-data.md) — Array transforms, HTTP, parsing +- [action-patterns-connectors.md](references/action-patterns-connectors.md) — SharePoint, Outlook, Teams, Approvals +- [build-patterns.md](references/build-patterns.md) — Complete flow definition templates (Recurrence+SP+Teams, HTTP trigger) + +## Related Skills + +- `flowstudio-power-automate-mcp` — Core connection setup and tool reference +- `flowstudio-power-automate-debug` — Debug failing flows after deployment diff --git a/skills/flowstudio-power-automate-build/references/action-patterns-connectors.md b/skills/flowstudio-power-automate-build/references/action-patterns-connectors.md new file mode 100644 index 00000000..d9102d6d --- /dev/null +++ b/skills/flowstudio-power-automate-build/references/action-patterns-connectors.md @@ -0,0 +1,542 @@ +# FlowStudio MCP — Action Patterns: Connectors + +SharePoint, Outlook, Teams, and Approvals connector action patterns. + +> All examples assume `"runAfter"` is set appropriately. +> Replace `` with the **key** you used in `connectionReferences` +> (e.g. `shared_sharepointonline`, `shared_teams`). This is NOT the connection +> GUID — it is the logical reference name that links the action to its entry in +> the `connectionReferences` map. + +--- + +## SharePoint + +### SharePoint — Get Items + +```json +"Get_SP_Items": { + "type": "OpenApiConnection", + "runAfter": {}, + "inputs": { + "host": { + "apiId": "/providers/Microsoft.PowerApps/apis/shared_sharepointonline", + "connectionName": "", + "operationId": "GetItems" + }, + "parameters": { + "dataset": "https://mytenant.sharepoint.com/sites/mysite", + "table": "MyList", + "$filter": "Status eq 'Active'", + "$top": 500 + } + } +} +``` + +Result reference: `@outputs('Get_SP_Items')?['body/value']` + +> **Dynamic OData filter with string interpolation**: inject a runtime value +> directly into the `$filter` string using `@{...}` syntax: +> ``` +> "$filter": "Title eq '@{outputs('ConfirmationCode')}'" +> ``` +> Note the single-quotes inside double-quotes — correct OData string literal +> syntax. Avoids a separate variable action. + +> **Pagination for large lists**: by default, GetItems stops at `$top`. To auto-paginate +> beyond that, enable the pagination policy on the action. In the flow definition this +> appears as: +> ```json +> "paginationPolicy": { "minimumItemCount": 10000 } +> ``` +> Set `minimumItemCount` to the maximum number of items you expect. The connector will +> keep fetching pages until that count is reached or the list is exhausted. Without this, +> flows silently return a capped result on lists with >5,000 items. + +--- + +### SharePoint — Get Item (Single Row by ID) + +```json +"Get_SP_Item": { + "type": "OpenApiConnection", + "runAfter": {}, + "inputs": { + "host": { + "apiId": "/providers/Microsoft.PowerApps/apis/shared_sharepointonline", + "connectionName": "", + "operationId": "GetItem" + }, + "parameters": { + "dataset": "https://mytenant.sharepoint.com/sites/mysite", + "table": "MyList", + "id": "@triggerBody()?['ID']" + } + } +} +``` + +Result reference: `@body('Get_SP_Item')?['FieldName']` + +> Use `GetItem` (not `GetItems` with a filter) when you already have the ID. +> Re-fetching after a trigger gives you the **current** row state, not the +> snapshot captured at trigger time — important if another process may have +> modified the item since the flow started. + +--- + +### SharePoint — Create Item + +```json +"Create_SP_Item": { + "type": "OpenApiConnection", + "runAfter": {}, + "inputs": { + "host": { + "apiId": "/providers/Microsoft.PowerApps/apis/shared_sharepointonline", + "connectionName": "", + "operationId": "PostItem" + }, + "parameters": { + "dataset": "https://mytenant.sharepoint.com/sites/mysite", + "table": "MyList", + "item/Title": "@variables('myTitle')", + "item/Status": "Active" + } + } +} +``` + +--- + +### SharePoint — Update Item + +```json +"Update_SP_Item": { + "type": "OpenApiConnection", + "runAfter": {}, + "inputs": { + "host": { + "apiId": "/providers/Microsoft.PowerApps/apis/shared_sharepointonline", + "connectionName": "", + "operationId": "PatchItem" + }, + "parameters": { + "dataset": "https://mytenant.sharepoint.com/sites/mysite", + "table": "MyList", + "id": "@item()?['ID']", + "item/Status": "Processed" + } + } +} +``` + +--- + +### SharePoint — File Upsert (Create or Overwrite in Document Library) + +SharePoint's `CreateFile` fails if the file already exists. To upsert (create or overwrite) +without a prior existence check, use `GetFileMetadataByPath` on **both Succeeded and Failed** +from `CreateFile` — if create failed because the file exists, the metadata call still +returns its ID, which `UpdateFile` can then overwrite: + +```json +"Create_File": { + "type": "OpenApiConnection", + "inputs": { + "host": { "apiId": "/providers/Microsoft.PowerApps/apis/shared_sharepointonline", + "connectionName": "", "operationId": "CreateFile" }, + "parameters": { + "dataset": "https://mytenant.sharepoint.com/sites/mysite", + "folderPath": "/My Library/Subfolder", + "name": "@{variables('filename')}", + "body": "@outputs('Compose_File_Content')" + } + } +}, +"Get_File_Metadata_By_Path": { + "type": "OpenApiConnection", + "runAfter": { "Create_File": ["Succeeded", "Failed"] }, + "inputs": { + "host": { "apiId": "/providers/Microsoft.PowerApps/apis/shared_sharepointonline", + "connectionName": "", "operationId": "GetFileMetadataByPath" }, + "parameters": { + "dataset": "https://mytenant.sharepoint.com/sites/mysite", + "path": "/My Library/Subfolder/@{variables('filename')}" + } + } +}, +"Update_File": { + "type": "OpenApiConnection", + "runAfter": { "Get_File_Metadata_By_Path": ["Succeeded", "Skipped"] }, + "inputs": { + "host": { "apiId": "/providers/Microsoft.PowerApps/apis/shared_sharepointonline", + "connectionName": "", "operationId": "UpdateFile" }, + "parameters": { + "dataset": "https://mytenant.sharepoint.com/sites/mysite", + "id": "@outputs('Get_File_Metadata_By_Path')?['body/{Identifier}']", + "body": "@outputs('Compose_File_Content')" + } + } +} +``` + +> If `Create_File` succeeds, `Get_File_Metadata_By_Path` is `Skipped` and `Update_File` +> still fires (accepting `Skipped`), harmlessly overwriting the file just created. +> If `Create_File` fails (file exists), the metadata call retrieves the existing file's ID +> and `Update_File` overwrites it. Either way you end with the latest content. +> +> **Document library system properties** — when iterating a file library result (e.g. +> from `ListFolder` or `GetFilesV2`), use curly-brace property names to access +> SharePoint's built-in file metadata. These are different from list field names: +> ``` +> @item()?['{Name}'] — filename without path (e.g. "report.csv") +> @item()?['{FilenameWithExtension}'] — same as {Name} in most connectors +> @item()?['{Identifier}'] — internal file ID for use in UpdateFile/DeleteFile +> @item()?['{FullPath}'] — full server-relative path +> @item()?['{IsFolder}'] — boolean, true for folder entries +> ``` + +--- + +### SharePoint — GetItemChanges Column Gate + +When a SharePoint "item modified" trigger fires, it doesn't tell you WHICH +column changed. Use `GetItemChanges` to get per-column change flags, then gate +downstream logic on specific columns: + +```json +"Get_Changes": { + "type": "OpenApiConnection", + "runAfter": {}, + "inputs": { + "host": { + "apiId": "/providers/Microsoft.PowerApps/apis/shared_sharepointonline", + "connectionName": "", + "operationId": "GetItemChanges" + }, + "parameters": { + "dataset": "https://mytenant.sharepoint.com/sites/mysite", + "table": "", + "id": "@triggerBody()?['ID']", + "since": "@triggerBody()?['Modified']", + "includeDrafts": false + } + } +} +``` + +Gate on a specific column: + +```json +"expression": { + "and": [{ + "equals": [ + "@body('Get_Changes')?['Column']?['hasChanged']", + true + ] + }] +} +``` + +> **New-item detection:** On the very first modification (version 1.0), +> `GetItemChanges` may report no prior version. Check +> `@equals(triggerBody()?['OData__UIVersionString'], '1.0')` to detect +> newly created items and skip change-gate logic for those. + +--- + +### SharePoint — REST MERGE via HttpRequest + +For cross-list updates or advanced operations not supported by the standard +Update Item connector (e.g., updating a list in a different site), use the +SharePoint REST API via the `HttpRequest` operation: + +```json +"Update_Cross_List_Item": { + "type": "OpenApiConnection", + "runAfter": {}, + "inputs": { + "host": { + "apiId": "/providers/Microsoft.PowerApps/apis/shared_sharepointonline", + "connectionName": "", + "operationId": "HttpRequest" + }, + "parameters": { + "dataset": "https://mytenant.sharepoint.com/sites/target-site", + "parameters/method": "POST", + "parameters/uri": "/_api/web/lists(guid'')/items(@{variables('ItemId')})", + "parameters/headers": { + "Accept": "application/json;odata=nometadata", + "Content-Type": "application/json;odata=nometadata", + "X-HTTP-Method": "MERGE", + "IF-MATCH": "*" + }, + "parameters/body": "{ \"Title\": \"@{variables('NewTitle')}\", \"Status\": \"@{variables('NewStatus')}\" }" + } + } +} +``` + +> **Key headers:** +> - `X-HTTP-Method: MERGE` — tells SharePoint to do a partial update (PATCH semantics) +> - `IF-MATCH: *` — overwrites regardless of current ETag (no conflict check) +> +> The `HttpRequest` operation reuses the existing SharePoint connection — no extra +> authentication needed. Use this when the standard Update Item connector can't +> reach the target list (different site collection, or you need raw REST control). + +--- + +### SharePoint — File as JSON Database (Read + Parse) + +Use a SharePoint document library JSON file as a queryable "database" of +last-known-state records. A separate process (e.g., Power BI dataflow) maintains +the file; the flow downloads and filters it for before/after comparisons. + +```json +"Get_File": { + "type": "OpenApiConnection", + "runAfter": {}, + "inputs": { + "host": { + "apiId": "/providers/Microsoft.PowerApps/apis/shared_sharepointonline", + "connectionName": "", + "operationId": "GetFileContent" + }, + "parameters": { + "dataset": "https://mytenant.sharepoint.com/sites/mysite", + "id": "%252fShared%2bDocuments%252fdata.json", + "inferContentType": false + } + } +}, +"Parse_JSON_File": { + "type": "Compose", + "runAfter": { "Get_File": ["Succeeded"] }, + "inputs": "@json(decodeBase64(body('Get_File')?['$content']))" +}, +"Find_Record": { + "type": "Query", + "runAfter": { "Parse_JSON_File": ["Succeeded"] }, + "inputs": { + "from": "@outputs('Parse_JSON_File')", + "where": "@equals(item()?['id'], variables('RecordId'))" + } +} +``` + +> **Decode chain:** `GetFileContent` returns base64-encoded content in +> `body(...)?['$content']`. Apply `decodeBase64()` then `json()` to get a +> usable array. `Filter Array` then acts as a WHERE clause. +> +> **When to use:** When you need a lightweight "before" snapshot to detect field +> changes from a webhook payload (the "after" state). Simpler than maintaining +> a full SharePoint list mirror — works well for up to ~10K records. +> +> **File path encoding:** In the `id` parameter, SharePoint URL-encodes paths +> twice. Spaces become `%2b` (plus sign), slashes become `%252f`. + +--- + +## Outlook + +### Outlook — Send Email + +```json +"Send_Email": { + "type": "OpenApiConnection", + "runAfter": {}, + "inputs": { + "host": { + "apiId": "/providers/Microsoft.PowerApps/apis/shared_office365", + "connectionName": "", + "operationId": "SendEmailV2" + }, + "parameters": { + "emailMessage/To": "recipient@contoso.com", + "emailMessage/Subject": "Automated notification", + "emailMessage/Body": "

@{outputs('Compose_Message')}

", + "emailMessage/IsHtml": true + } + } +} +``` + +--- + +### Outlook — Get Emails (Read Template from Folder) + +```json +"Get_Email_Template": { + "type": "OpenApiConnection", + "runAfter": {}, + "inputs": { + "host": { + "apiId": "/providers/Microsoft.PowerApps/apis/shared_office365", + "connectionName": "", + "operationId": "GetEmailsV3" + }, + "parameters": { + "folderPath": "Id::", + "fetchOnlyUnread": false, + "includeAttachments": false, + "top": 1, + "importance": "Any", + "fetchOnlyWithAttachment": false, + "subjectFilter": "My Email Template Subject" + } + } +} +``` + +Access subject and body: +``` +@first(outputs('Get_Email_Template')?['body/value'])?['subject'] +@first(outputs('Get_Email_Template')?['body/value'])?['body'] +``` + +> **Outlook-as-CMS pattern**: store a template email in a dedicated Outlook folder. +> Set `fetchOnlyUnread: false` so the template persists after first use. +> Non-technical users can update subject and body by editing that email — +> no flow changes required. Pass subject and body directly into `SendEmailV2`. +> +> To get a folder ID: in Outlook on the web, right-click the folder → open in +> new tab — the folder GUID is in the URL. Prefix it with `Id::` in `folderPath`. + +--- + +## Teams + +### Teams — Post Message + +```json +"Post_Teams_Message": { + "type": "OpenApiConnection", + "runAfter": {}, + "inputs": { + "host": { + "apiId": "/providers/Microsoft.PowerApps/apis/shared_teams", + "connectionName": "", + "operationId": "PostMessageToConversation" + }, + "parameters": { + "poster": "Flow bot", + "location": "Channel", + "body/recipient": { + "groupId": "", + "channelId": "" + }, + "body/messageBody": "@outputs('Compose_Message')" + } + } +} +``` + +#### Variant: Group Chat (1:1 or Multi-Person) + +To post to a group chat instead of a channel, use `"location": "Group chat"` with +a thread ID as the recipient: + +```json +"Post_To_Group_Chat": { + "type": "OpenApiConnection", + "runAfter": {}, + "inputs": { + "host": { + "apiId": "/providers/Microsoft.PowerApps/apis/shared_teams", + "connectionName": "", + "operationId": "PostMessageToConversation" + }, + "parameters": { + "poster": "Flow bot", + "location": "Group chat", + "body/recipient": "19:@thread.v2", + "body/messageBody": "@outputs('Compose_Message')" + } + } +} +``` + +For 1:1 ("Chat with Flow bot"), use `"location": "Chat with Flow bot"` and set +`body/recipient` to the user's email address. + +> **Active-user gate:** When sending notifications in a loop, check the recipient's +> Azure AD account is enabled before posting — avoids failed deliveries to departed +> staff: +> ```json +> "Check_User_Active": { +> "type": "OpenApiConnection", +> "inputs": { +> "host": { "apiId": "/providers/Microsoft.PowerApps/apis/shared_office365users", +> "operationId": "UserProfile_V2" }, +> "parameters": { "id": "@{item()?['Email']}" } +> } +> } +> ``` +> Then gate: `@equals(body('Check_User_Active')?['accountEnabled'], true)` + +--- + +## Approvals + +### Split Approval (Create → Wait) + +The standard "Start and wait for an approval" is a single blocking action. +For more control (e.g., posting the approval link in Teams, or adding a timeout +scope), split it into two actions: `CreateAnApproval` (fire-and-forget) then +`WaitForAnApproval` (webhook pause). + +```json +"Create_Approval": { + "type": "OpenApiConnection", + "runAfter": {}, + "inputs": { + "host": { + "apiId": "/providers/Microsoft.PowerApps/apis/shared_approvals", + "connectionName": "", + "operationId": "CreateAnApproval" + }, + "parameters": { + "approvalType": "CustomResponse/Result", + "ApprovalCreationInput/title": "Review: @{variables('ItemTitle')}", + "ApprovalCreationInput/assignedTo": "approver@contoso.com", + "ApprovalCreationInput/details": "Please review and select an option.", + "ApprovalCreationInput/responseOptions": ["Approve", "Reject", "Defer"], + "ApprovalCreationInput/enableNotifications": true, + "ApprovalCreationInput/enableReassignment": true + } + } +}, +"Wait_For_Approval": { + "type": "OpenApiConnectionWebhook", + "runAfter": { "Create_Approval": ["Succeeded"] }, + "inputs": { + "host": { + "apiId": "/providers/Microsoft.PowerApps/apis/shared_approvals", + "connectionName": "", + "operationId": "WaitForAnApproval" + }, + "parameters": { + "approvalName": "@body('Create_Approval')?['name']" + } + } +} +``` + +> **`approvalType` options:** +> - `"Approve/Reject - First to respond"` — binary, first responder wins +> - `"Approve/Reject - Everyone must approve"` — requires all assignees +> - `"CustomResponse/Result"` — define your own response buttons +> +> After `Wait_For_Approval`, read the outcome: +> ``` +> @body('Wait_For_Approval')?['outcome'] → "Approve", "Reject", or custom +> @body('Wait_For_Approval')?['responses'][0]?['responder']?['displayName'] +> @body('Wait_For_Approval')?['responses'][0]?['comments'] +> ``` +> +> The split pattern lets you insert actions between create and wait — e.g., +> posting the approval link to Teams, starting a timeout scope, or logging +> the pending approval to a tracking list. diff --git a/skills/flowstudio-power-automate-build/references/action-patterns-core.md b/skills/flowstudio-power-automate-build/references/action-patterns-core.md new file mode 100644 index 00000000..74221ba8 --- /dev/null +++ b/skills/flowstudio-power-automate-build/references/action-patterns-core.md @@ -0,0 +1,542 @@ +# FlowStudio MCP — Action Patterns: Core + +Variables, control flow, and expression patterns for Power Automate flow definitions. + +> All examples assume `"runAfter"` is set appropriately. +> Replace `` with the **key** you used in your `connectionReferences` map +> (e.g. `shared_teams`, `shared_office365`) — NOT the connection GUID. + +--- + +## Data & Variables + +### Compose (Store a Value) + +```json +"Compose_My_Value": { + "type": "Compose", + "runAfter": {}, + "inputs": "@variables('myVar')" +} +``` + +Reference: `@outputs('Compose_My_Value')` + +--- + +### Initialize Variable + +```json +"Init_Counter": { + "type": "InitializeVariable", + "runAfter": {}, + "inputs": { + "variables": [{ + "name": "counter", + "type": "Integer", + "value": 0 + }] + } +} +``` + +Types: `"Integer"`, `"Float"`, `"Boolean"`, `"String"`, `"Array"`, `"Object"` + +--- + +### Set Variable + +```json +"Set_Counter": { + "type": "SetVariable", + "runAfter": {}, + "inputs": { + "name": "counter", + "value": "@add(variables('counter'), 1)" + } +} +``` + +--- + +### Append to Array Variable + +```json +"Collect_Item": { + "type": "AppendToArrayVariable", + "runAfter": {}, + "inputs": { + "name": "resultArray", + "value": "@item()" + } +} +``` + +--- + +### Increment Variable + +```json +"Increment_Counter": { + "type": "IncrementVariable", + "runAfter": {}, + "inputs": { + "name": "counter", + "value": 1 + } +} +``` + +> Use `IncrementVariable` (not `SetVariable` with `add()`) for counters inside loops — +> it is atomic and avoids expression errors when the variable is used elsewhere in the +> same iteration. `value` can be any integer or expression, e.g. `@mul(item()?['Interval'], 60)` +> to advance a Unix timestamp cursor by N minutes. + +--- + +## Control Flow + +### Condition (If/Else) + +```json +"Check_Status": { + "type": "If", + "runAfter": {}, + "expression": { + "and": [{ "equals": ["@item()?['Status']", "Active"] }] + }, + "actions": { + "Handle_Active": { + "type": "Compose", + "runAfter": {}, + "inputs": "Active user: @{item()?['Name']}" + } + }, + "else": { + "actions": { + "Handle_Inactive": { + "type": "Compose", + "runAfter": {}, + "inputs": "Inactive user" + } + } + } +} +``` + +Comparison operators: `equals`, `not`, `greater`, `greaterOrEquals`, `less`, `lessOrEquals`, `contains` +Logical: `and: [...]`, `or: [...]` + +--- + +### Switch + +```json +"Route_By_Type": { + "type": "Switch", + "runAfter": {}, + "expression": "@triggerBody()?['type']", + "cases": { + "Case_Email": { + "case": "email", + "actions": { "Process_Email": { "type": "Compose", "runAfter": {}, "inputs": "email" } } + }, + "Case_Teams": { + "case": "teams", + "actions": { "Process_Teams": { "type": "Compose", "runAfter": {}, "inputs": "teams" } } + } + }, + "default": { + "actions": { "Unknown_Type": { "type": "Compose", "runAfter": {}, "inputs": "unknown" } } + } +} +``` + +--- + +### Scope (Grouping / Try-Catch) + +Wrap related actions in a Scope to give them a shared name, collapse them in the +designer, and — most importantly — handle their errors as a unit. + +```json +"Scope_Get_Customer": { + "type": "Scope", + "runAfter": {}, + "actions": { + "HTTP_Get_Customer": { + "type": "Http", + "runAfter": {}, + "inputs": { + "method": "GET", + "uri": "https://api.example.com/customers/@{variables('customerId')}" + } + }, + "Compose_Email": { + "type": "Compose", + "runAfter": { "HTTP_Get_Customer": ["Succeeded"] }, + "inputs": "@outputs('HTTP_Get_Customer')?['body/email']" + } + } +}, +"Handle_Scope_Error": { + "type": "Compose", + "runAfter": { "Scope_Get_Customer": ["Failed", "TimedOut"] }, + "inputs": "Scope failed: @{result('Scope_Get_Customer')?[0]?['error']?['message']}" +} +``` + +> Reference scope results: `@result('Scope_Get_Customer')` returns an array of action +> outcomes. Use `runAfter: {"MyScope": ["Failed", "TimedOut"]}` on a follow-up action +> to create try/catch semantics without a Terminate. + +--- + +### Foreach (Sequential) + +```json +"Process_Each_Item": { + "type": "Foreach", + "runAfter": {}, + "foreach": "@outputs('Get_Items')?['body/value']", + "operationOptions": "Sequential", + "actions": { + "Handle_Item": { + "type": "Compose", + "runAfter": {}, + "inputs": "@item()?['Title']" + } + } +} +``` + +> Always include `"operationOptions": "Sequential"` unless parallel is intentional. + +--- + +### Foreach (Parallel with Concurrency Limit) + +```json +"Process_Each_Item_Parallel": { + "type": "Foreach", + "runAfter": {}, + "foreach": "@body('Get_SP_Items')?['value']", + "runtimeConfiguration": { + "concurrency": { + "repetitions": 20 + } + }, + "actions": { + "HTTP_Upsert": { + "type": "Http", + "runAfter": {}, + "inputs": { + "method": "POST", + "uri": "https://api.example.com/contacts/@{item()?['Email']}" + } + } + } +} +``` + +> Set `repetitions` to control how many items are processed simultaneously. +> Practical values: `5–10` for external API calls (respect rate limits), +> `20–50` for internal/fast operations. +> Omit `runtimeConfiguration.concurrency` entirely for the platform default +> (currently 50). Do NOT use `"operationOptions": "Sequential"` and concurrency together. + +--- + +### Wait (Delay) + +```json +"Delay_10_Minutes": { + "type": "Wait", + "runAfter": {}, + "inputs": { + "interval": { + "count": 10, + "unit": "Minute" + } + } +} +``` + +Valid `unit` values: `"Second"`, `"Minute"`, `"Hour"`, `"Day"` + +> Use a Delay + re-fetch as a deduplication guard: wait for any competing process +> to complete, then re-read the record before acting. This avoids double-processing +> when multiple triggers or manual edits can race on the same item. + +--- + +### Terminate (Success or Failure) + +```json +"Terminate_Success": { + "type": "Terminate", + "runAfter": {}, + "inputs": { + "runStatus": "Succeeded" + } +}, +"Terminate_Failure": { + "type": "Terminate", + "runAfter": { "Risky_Action": ["Failed"] }, + "inputs": { + "runStatus": "Failed", + "runError": { + "code": "StepFailed", + "message": "@{outputs('Get_Error_Message')}" + } + } +} +``` + +--- + +### Do Until (Loop Until Condition) + +Repeats a block of actions until an exit condition becomes true. +Use when the number of iterations is not known upfront (e.g. paginating an API, +walking a time range, polling until a status changes). + +```json +"Do_Until_Done": { + "type": "Until", + "runAfter": {}, + "expression": "@greaterOrEquals(variables('cursor'), variables('endValue'))", + "limit": { + "count": 5000, + "timeout": "PT5H" + }, + "actions": { + "Do_Work": { + "type": "Compose", + "runAfter": {}, + "inputs": "@variables('cursor')" + }, + "Advance_Cursor": { + "type": "IncrementVariable", + "runAfter": { "Do_Work": ["Succeeded"] }, + "inputs": { + "name": "cursor", + "value": 1 + } + } + } +} +``` + +> Always set `limit.count` and `limit.timeout` explicitly — the platform defaults are +> low (60 iterations, 1 hour). For time-range walkers use `limit.count: 5000` and +> `limit.timeout: "PT5H"` (ISO 8601 duration). +> +> The exit condition is evaluated **before** each iteration. Initialise your cursor +> variable before the loop so the condition can evaluate correctly on the first pass. + +--- + +### Async Polling with RequestId Correlation + +When an API starts a long-running job asynchronously (e.g. Power BI dataset refresh, +report generation, batch export), the trigger call returns a request ID. Capture it +from the **response header**, then poll a status endpoint filtering by that exact ID: + +```json +"Start_Job": { + "type": "Http", + "inputs": { "method": "POST", "uri": "https://api.example.com/jobs" } +}, +"Capture_Request_ID": { + "type": "Compose", + "runAfter": { "Start_Job": ["Succeeded"] }, + "inputs": "@outputs('Start_Job')?['headers/X-Request-Id']" +}, +"Initialize_Status": { + "type": "InitializeVariable", + "inputs": { "variables": [{ "name": "jobStatus", "type": "String", "value": "Running" }] } +}, +"Poll_Until_Done": { + "type": "Until", + "expression": "@not(equals(variables('jobStatus'), 'Running'))", + "limit": { "count": 60, "timeout": "PT30M" }, + "actions": { + "Delay": { "type": "Wait", "inputs": { "interval": { "count": 20, "unit": "Second" } } }, + "Get_History": { + "type": "Http", + "runAfter": { "Delay": ["Succeeded"] }, + "inputs": { "method": "GET", "uri": "https://api.example.com/jobs/history" } + }, + "Filter_This_Job": { + "type": "Query", + "runAfter": { "Get_History": ["Succeeded"] }, + "inputs": { + "from": "@outputs('Get_History')?['body/items']", + "where": "@equals(item()?['requestId'], outputs('Capture_Request_ID'))" + } + }, + "Set_Status": { + "type": "SetVariable", + "runAfter": { "Filter_This_Job": ["Succeeded"] }, + "inputs": { + "name": "jobStatus", + "value": "@first(body('Filter_This_Job'))?['status']" + } + } + } +}, +"Handle_Failure": { + "type": "If", + "runAfter": { "Poll_Until_Done": ["Succeeded"] }, + "expression": { "equals": ["@variables('jobStatus')", "Failed"] }, + "actions": { "Terminate_Failed": { "type": "Terminate", "inputs": { "runStatus": "Failed" } } }, + "else": { "actions": {} } +} +``` + +Access response headers: `@outputs('Start_Job')?['headers/X-Request-Id']` + +> **Status variable initialisation**: set a sentinel value (`"Running"`, `"Unknown"`) before +> the loop. The exit condition tests for any value other than the sentinel. +> This way an empty poll result (job not yet in history) leaves the variable unchanged +> and the loop continues — it doesn't accidentally exit on null. +> +> **Filter before extracting**: always `Filter Array` the history to your specific +> request ID before calling `first()`. History endpoints return all jobs; without +> filtering, status from a different concurrent job can corrupt your poll. + +--- + +### runAfter Fallback (Failed → Alternative Action) + +Route to a fallback action when a primary action fails — without a Condition block. +Simply set `runAfter` on the fallback to accept `["Failed"]` from the primary: + +```json +"HTTP_Get_Hi_Res": { + "type": "Http", + "runAfter": {}, + "inputs": { "method": "GET", "uri": "https://api.example.com/data?resolution=hi-res" } +}, +"HTTP_Get_Low_Res": { + "type": "Http", + "runAfter": { "HTTP_Get_Hi_Res": ["Failed"] }, + "inputs": { "method": "GET", "uri": "https://api.example.com/data?resolution=low-res" } +} +``` + +> Actions that follow can use `runAfter` accepting both `["Succeeded", "Skipped"]` to +> handle either path — see **Fan-In Join Gate** below. + +--- + +### Fan-In Join Gate (Merge Two Mutually Exclusive Branches) + +When two branches are mutually exclusive (only one can succeed per run), use a single +downstream action that accepts `["Succeeded", "Skipped"]` from **both** branches. +The gate fires exactly once regardless of which branch ran: + +```json +"Increment_Count": { + "type": "IncrementVariable", + "runAfter": { + "Update_Hi_Res_Metadata": ["Succeeded", "Skipped"], + "Update_Low_Res_Metadata": ["Succeeded", "Skipped"] + }, + "inputs": { "name": "LoopCount", "value": 1 } +} +``` + +> This avoids duplicating the downstream action in each branch. The key insight: +> whichever branch was skipped reports `Skipped` — the gate accepts that state and +> fires once. Only works cleanly when the two branches are truly mutually exclusive +> (e.g. one is `runAfter: [...Failed]` of the other). + +--- + +## Expressions + +### Common Expression Patterns + +``` +Null-safe field access: @item()?['FieldName'] +Null guard: @coalesce(item()?['Name'], 'Unknown') +String format: @{variables('firstName')} @{variables('lastName')} +Date today: @utcNow() +Formatted date: @formatDateTime(utcNow(), 'dd/MM/yyyy') +Add days: @addDays(utcNow(), 7) +Array length: @length(variables('myArray')) +Filter array: Use the "Filter array" action (no inline filter expression exists in PA) +Union (new wins): @union(body('New_Data'), outputs('Old_Data')) +Sort: @sort(variables('myArray'), 'Date') +Unix timestamp → date: @formatDateTime(addseconds('1970-1-1', triggerBody()?['created']), 'yyyy-MM-dd') +Date → Unix milliseconds: @div(sub(ticks(startOfDay(item()?['Created'])), ticks(formatDateTime('1970-01-01Z','o'))), 10000) +Date → Unix seconds: @div(sub(ticks(item()?['Start']), ticks('1970-01-01T00:00:00Z')), 10000000) +Unix seconds → datetime: @addSeconds('1970-01-01T00:00:00Z', int(variables('Unix'))) +Coalesce as no-else: @coalesce(outputs('Optional_Step'), outputs('Default_Step')) +Flow elapsed minutes: @div(float(sub(ticks(utcNow()), ticks(outputs('Flow_Start')))), 600000000) +HH:mm time string: @formatDateTime(outputs('Local_Datetime'), 'HH:mm') +Response header: @outputs('HTTP_Action')?['headers/X-Request-Id'] +Array max (by field): @reverse(sort(body('Select_Items'), 'Date'))[0] +Integer day span: @int(split(dateDifference(outputs('Start'), outputs('End')), '.')[0]) +ISO week number: @div(add(dayofyear(addDays(subtractFromTime(date, sub(dayofweek(date),1), 'Day'), 3)), 6), 7) +Join errors to string: @if(equals(length(variables('Errors')),0), null, concat(join(variables('Errors'),', '),' not found.')) +Normalize before compare: @replace(coalesce(outputs('Value'),''),'_',' ') +Robust non-empty check: @greater(length(trim(coalesce(string(outputs('Val')), ''))), 0) +``` + +### Newlines in Expressions + +> **`\n` does NOT produce a newline inside Power Automate expressions.** It is +> treated as a literal backslash + `n` and will either appear verbatim or cause +> a validation error. + +Use `decodeUriComponent('%0a')` wherever you need a newline character: + +``` +Newline (LF): decodeUriComponent('%0a') +CRLF: decodeUriComponent('%0d%0a') +``` + +Example — multi-line Teams or email body via `concat()`: +```json +"Compose_Message": { + "type": "Compose", + "inputs": "@concat('Hi ', outputs('Get_User')?['body/displayName'], ',', decodeUriComponent('%0a%0a'), 'Your report is ready.', decodeUriComponent('%0a'), '- The Team')" +} +``` + +Example — `join()` with newline separator: +```json +"Compose_List": { + "type": "Compose", + "inputs": "@join(body('Select_Names'), decodeUriComponent('%0a'))" +} +``` + +> This is the only reliable way to embed newlines in dynamically built strings +> in Power Automate flow definitions (confirmed against Logic Apps runtime). + +--- + +### Sum an array (XPath trick) + +Power Automate has no native `sum()` function. Use XPath on XML instead: + +```json +"Prepare_For_Sum": { + "type": "Compose", + "runAfter": {}, + "inputs": { "root": { "numbers": "@body('Select_Amounts')" } } +}, +"Sum": { + "type": "Compose", + "runAfter": { "Prepare_For_Sum": ["Succeeded"] }, + "inputs": "@xpath(xml(outputs('Prepare_For_Sum')), 'sum(/root/numbers)')" +} +``` + +`Select_Amounts` must output a flat array of numbers (use a **Select** action to extract a single numeric field first). The result is a number you can use directly in conditions or calculations. + +> This is the only way to aggregate (sum/min/max) an array without a loop in Power Automate. diff --git a/skills/flowstudio-power-automate-build/references/action-patterns-data.md b/skills/flowstudio-power-automate-build/references/action-patterns-data.md new file mode 100644 index 00000000..d1c652f2 --- /dev/null +++ b/skills/flowstudio-power-automate-build/references/action-patterns-data.md @@ -0,0 +1,735 @@ +# FlowStudio MCP — Action Patterns: Data Transforms + +Array operations, HTTP calls, parsing, and data transformation patterns. + +> All examples assume `"runAfter"` is set appropriately. +> `` is the **key** in `connectionReferences` (e.g. `shared_sharepointonline`), not the GUID. +> The GUID goes in the map value's `connectionName` property. + +--- + +## Array Operations + +### Select (Reshape / Project an Array) + +Transforms each item in an array, keeping only the columns you need or renaming them. +Avoids carrying large objects through the rest of the flow. + +```json +"Select_Needed_Columns": { + "type": "Select", + "runAfter": {}, + "inputs": { + "from": "@outputs('HTTP_Get_Subscriptions')?['body/data']", + "select": { + "id": "@item()?['id']", + "status": "@item()?['status']", + "trial_end": "@item()?['trial_end']", + "cancel_at": "@item()?['cancel_at']", + "interval": "@item()?['plan']?['interval']" + } + } +} +``` + +Result reference: `@body('Select_Needed_Columns')` — returns a direct array of reshaped objects. + +> Use Select before looping or filtering to reduce payload size and simplify +> downstream expressions. Works on any array — SP results, HTTP responses, variables. +> +> **Tips:** +> - **Single-to-array coercion:** When an API returns a single object but you need +> Select (which requires an array), wrap it: `@array(body('Get_Employee')?['data'])`. +> The output is a 1-element array — access results via `?[0]?['field']`. +> - **Null-normalize optional fields:** Use `@if(empty(item()?['field']), null, item()?['field'])` +> on every optional field to normalize empty strings, missing properties, and empty +> objects to explicit `null`. Ensures consistent downstream `@equals(..., @null)` checks. +> - **Flatten nested objects:** Project nested properties into flat fields: +> ``` +> "manager_name": "@if(empty(item()?['manager']?['name']), null, item()?['manager']?['name'])" +> ``` +> This enables direct field-level comparison with a flat schema from another source. + +--- + +### Filter Array (Query) + +Filters an array to items matching a condition. Use the action form (not the `filter()` +expression) for complex multi-condition logic — it's clearer and easier to maintain. + +```json +"Filter_Active_Subscriptions": { + "type": "Query", + "runAfter": {}, + "inputs": { + "from": "@body('Select_Needed_Columns')", + "where": "@and(or(equals(item().status, 'trialing'), equals(item().status, 'active')), equals(item().cancel_at, null))" + } +} +``` + +Result reference: `@body('Filter_Active_Subscriptions')` — direct filtered array. + +> Tip: run multiple Filter Array actions on the same source array to create +> named buckets (e.g. active, being-canceled, fully-canceled), then use +> `coalesce(first(body('Filter_A')), first(body('Filter_B')), ...)` to pick +> the highest-priority match without any loops. + +--- + +### Create CSV Table (Array → CSV String) + +Converts an array of objects into a CSV-formatted string — no connector call, no code. +Use after a `Select` or `Filter Array` to export data or pass it to a file-write action. + +```json +"Create_CSV": { + "type": "Table", + "runAfter": {}, + "inputs": { + "from": "@body('Select_Output_Columns')", + "format": "CSV" + } +} +``` + +Result reference: `@body('Create_CSV')` — a plain string with header row + data rows. + +```json +// Custom column order / renamed headers: +"Create_CSV_Custom": { + "type": "Table", + "inputs": { + "from": "@body('Select_Output_Columns')", + "format": "CSV", + "columns": [ + { "header": "Date", "value": "@item()?['transactionDate']" }, + { "header": "Amount", "value": "@item()?['amount']" }, + { "header": "Description", "value": "@item()?['description']" } + ] + } +} +``` + +> Without `columns`, headers are taken from the object property names in the source array. +> With `columns`, you control header names and column order explicitly. +> +> The output is a raw string. Write it to a file with `CreateFile` or `UpdateFile` +> (set `body` to `@body('Create_CSV')`), or store in a variable with `SetVariable`. +> +> If source data came from Power BI's `ExecuteDatasetQuery`, column names will be +> wrapped in square brackets (e.g. `[Amount]`). Strip them before writing: +> `@replace(replace(body('Create_CSV'),'[',''),']','')` + +--- + +### range() + Select for Array Generation + +`range(0, N)` produces an integer sequence `[0, 1, 2, …, N-1]`. Pipe it through +a Select action to generate date series, index grids, or any computed array +without a loop: + +```json +// Generate 14 consecutive dates starting from a base date +"Generate_Date_Series": { + "type": "Select", + "inputs": { + "from": "@range(0, 14)", + "select": "@addDays(outputs('Base_Date'), item(), 'yyyy-MM-dd')" + } +} +``` + +Result: `@body('Generate_Date_Series')` → `["2025-01-06", "2025-01-07", …, "2025-01-19"]` + +```json +// Flatten a 2D array (rows × cols) into 1D using arithmetic indexing +"Flatten_Grid": { + "type": "Select", + "inputs": { + "from": "@range(0, mul(length(outputs('Rows')), length(outputs('Cols'))))", + "select": { + "row": "@outputs('Rows')[div(item(), length(outputs('Cols')))]", + "col": "@outputs('Cols')[mod(item(), length(outputs('Cols')))]" + } + } +} +``` + +> `range()` is zero-based. The Cartesian product pattern above uses `div(i, cols)` +> for the row index and `mod(i, cols)` for the column index — equivalent to a +> nested for-loop flattened into a single pass. Useful for generating time-slot × +> date grids, shift × location assignments, etc. + +--- + +### Dynamic Dictionary via json(concat(join())) + +When you need O(1) key→value lookups at runtime and Power Automate has no native +dictionary type, build one from an array using Select + join + json: + +```json +"Build_Key_Value_Pairs": { + "type": "Select", + "inputs": { + "from": "@body('Get_Lookup_Items')?['value']", + "select": "@concat('\"', item()?['Key'], '\":\"', item()?['Value'], '\"')" + } +}, +"Assemble_Dictionary": { + "type": "Compose", + "inputs": "@json(concat('{', join(body('Build_Key_Value_Pairs'), ','), '}'))" +} +``` + +Lookup: `@outputs('Assemble_Dictionary')?['myKey']` + +```json +// Practical example: date → rate-code lookup for business rules +"Build_Holiday_Rates": { + "type": "Select", + "inputs": { + "from": "@body('Get_Holidays')?['value']", + "select": "@concat('\"', formatDateTime(item()?['Date'], 'yyyy-MM-dd'), '\":\"', item()?['RateCode'], '\"')" + } +}, +"Holiday_Dict": { + "type": "Compose", + "inputs": "@json(concat('{', join(body('Build_Holiday_Rates'), ','), '}'))" +} +``` + +Then inside a loop: `@coalesce(outputs('Holiday_Dict')?[item()?['Date']], 'Standard')` + +> The `json(concat('{', join(...), '}'))` pattern works for string values. For numeric +> or boolean values, omit the inner escaped quotes around the value portion. +> Keys must be unique — duplicate keys silently overwrite earlier ones. +> This replaces deeply nested `if(equals(key,'A'),'X', if(equals(key,'B'),'Y', ...))` chains. + +--- + +### union() for Changed-Field Detection + +When you need to find records where *any* of several fields has changed, run one +`Filter Array` per field and `union()` the results. This avoids a complex +multi-condition filter and produces a clean deduplicated set: + +```json +"Filter_Name_Changed": { + "type": "Query", + "inputs": { "from": "@body('Existing_Records')", + "where": "@not(equals(item()?['name'], item()?['dest_name']))" } +}, +"Filter_Status_Changed": { + "type": "Query", + "inputs": { "from": "@body('Existing_Records')", + "where": "@not(equals(item()?['status'], item()?['dest_status']))" } +}, +"All_Changed": { + "type": "Compose", + "inputs": "@union(body('Filter_Name_Changed'), body('Filter_Status_Changed'))" +} +``` + +Reference: `@outputs('All_Changed')` — deduplicated array of rows where anything changed. + +> `union()` deduplicates by object identity, so a row that changed in both fields +> appears once. Add more `Filter_*_Changed` inputs to `union()` as needed: +> `@union(body('F1'), body('F2'), body('F3'))` + +--- + +### File-Content Change Gate + +Before running expensive processing on a file or blob, compare its current content +to a stored baseline. Skip entirely if nothing has changed — makes sync flows +idempotent and safe to re-run or schedule aggressively. + +```json +"Get_File_From_Source": { ... }, +"Get_Stored_Baseline": { ... }, +"Condition_File_Changed": { + "type": "If", + "expression": { + "not": { + "equals": [ + "@base64(body('Get_File_From_Source'))", + "@body('Get_Stored_Baseline')" + ] + } + }, + "actions": { + "Update_Baseline": { "...": "overwrite stored copy with new content" }, + "Process_File": { "...": "all expensive work goes here" } + }, + "else": { "actions": {} } +} +``` + +> Store the baseline as a file in SharePoint or blob storage — `base64()`-encode the +> live content before comparing so binary and text files are handled uniformly. +> Write the new baseline **before** processing so a re-run after a partial failure +> does not re-process the same file again. + +--- + +### Set-Join for Sync (Update Detection without Nested Loops) + +When syncing a source collection into a destination (e.g. API response → SharePoint list, +CSV → database), avoid nested `Apply to each` loops to find changed records. +Instead, **project flat key arrays** and use `contains()` to perform set operations — +zero nested loops, and the final loop only touches changed items. + +**Full insert/update/delete sync pattern:** + +```json +// Step 1 — Project a flat key array from the DESTINATION (e.g. SharePoint) +"Select_Dest_Keys": { + "type": "Select", + "inputs": { + "from": "@outputs('Get_Dest_Items')?['body/value']", + "select": "@item()?['Title']" + } +} +// → ["KEY1", "KEY2", "KEY3", ...] + +// Step 2 — INSERT: source rows whose key is NOT in destination +"Filter_To_Insert": { + "type": "Query", + "inputs": { + "from": "@body('Source_Array')", + "where": "@not(contains(body('Select_Dest_Keys'), item()?['key']))" + } +} +// → Apply to each Filter_To_Insert → CreateItem + +// Step 3 — INNER JOIN: source rows that exist in destination +"Filter_Already_Exists": { + "type": "Query", + "inputs": { + "from": "@body('Source_Array')", + "where": "@contains(body('Select_Dest_Keys'), item()?['key'])" + } +} + +// Step 4 — UPDATE: one Filter per tracked field, then union them +"Filter_Field1_Changed": { + "type": "Query", + "inputs": { + "from": "@body('Filter_Already_Exists')", + "where": "@not(equals(item()?['field1'], item()?['dest_field1']))" + } +} +"Filter_Field2_Changed": { + "type": "Query", + "inputs": { + "from": "@body('Filter_Already_Exists')", + "where": "@not(equals(item()?['field2'], item()?['dest_field2']))" + } +} +"Union_Changed": { + "type": "Compose", + "inputs": "@union(body('Filter_Field1_Changed'), body('Filter_Field2_Changed'))" +} +// → rows where ANY tracked field differs + +// Step 5 — Resolve destination IDs for changed rows (no nested loop) +"Select_Changed_Keys": { + "type": "Select", + "inputs": { "from": "@outputs('Union_Changed')", "select": "@item()?['key']" } +} +"Filter_Dest_Items_To_Update": { + "type": "Query", + "inputs": { + "from": "@outputs('Get_Dest_Items')?['body/value']", + "where": "@contains(body('Select_Changed_Keys'), item()?['Title'])" + } +} +// Step 6 — Single loop over changed items only +"Apply_to_each_Update": { + "type": "Foreach", + "foreach": "@body('Filter_Dest_Items_To_Update')", + "actions": { + "Get_Source_Row": { + "type": "Query", + "inputs": { + "from": "@outputs('Union_Changed')", + "where": "@equals(item()?['key'], items('Apply_to_each_Update')?['Title'])" + } + }, + "Update_Item": { + "...": "...", + "id": "@items('Apply_to_each_Update')?['ID']", + "item/field1": "@first(body('Get_Source_Row'))?['field1']" + } + } +} + +// Step 7 — DELETE: destination keys NOT in source +"Select_Source_Keys": { + "type": "Select", + "inputs": { "from": "@body('Source_Array')", "select": "@item()?['key']" } +} +"Filter_To_Delete": { + "type": "Query", + "inputs": { + "from": "@outputs('Get_Dest_Items')?['body/value']", + "where": "@not(contains(body('Select_Source_Keys'), item()?['Title']))" + } +} +// → Apply to each Filter_To_Delete → DeleteItem +``` + +> **Why this beats nested loops**: the naive approach (for each dest item, scan source) +> is O(n × m) and hits Power Automate's 100k-action run limit fast on large lists. +> This pattern is O(n + m): one pass to build key arrays, one pass per filter. +> The update loop in Step 6 only iterates *changed* records — often a tiny fraction +> of the full collection. Run Steps 2/4/7 in **parallel Scopes** for further speed. + +--- + +### First-or-Null Single-Row Lookup + +Use `first()` on the result array to extract one record without a loop. +Then null-check the output to guard downstream actions. + +```json +"Get_First_Match": { + "type": "Compose", + "runAfter": { "Get_SP_Items": ["Succeeded"] }, + "inputs": "@first(outputs('Get_SP_Items')?['body/value'])" +} +``` + +In a Condition, test for no-match with the **`@null` literal** (not `empty()`): + +```json +"Condition": { + "type": "If", + "expression": { + "not": { + "equals": [ + "@outputs('Get_First_Match')", + "@null" + ] + } + } +} +``` + +Access fields on the matched row: `@outputs('Get_First_Match')?['FieldName']` + +> Use this instead of `Apply to each` when you only need one matching record. +> `first()` on an empty array returns `null`; `empty()` is for arrays/strings, +> not scalars — using it on a `first()` result causes a runtime error. + +--- + +## HTTP & Parsing + +### HTTP Action (External API) + +```json +"Call_External_API": { + "type": "Http", + "runAfter": {}, + "inputs": { + "method": "POST", + "uri": "https://api.example.com/endpoint", + "headers": { + "Content-Type": "application/json", + "Authorization": "Bearer @{variables('apiToken')}" + }, + "body": { + "data": "@outputs('Compose_Payload')" + }, + "retryPolicy": { + "type": "Fixed", + "count": 3, + "interval": "PT10S" + } + } +} +``` + +Response reference: `@outputs('Call_External_API')?['body']` + +#### Variant: ActiveDirectoryOAuth (Service-to-Service) + +For calling APIs that require Azure AD client-credentials (e.g., Microsoft Graph), +use in-line OAuth instead of a Bearer token variable: + +```json +"Call_Graph_API": { + "type": "Http", + "runAfter": {}, + "inputs": { + "method": "GET", + "uri": "https://graph.microsoft.com/v1.0/users?$search=\"employeeId:@{variables('Code')}\"&$select=id,displayName", + "headers": { + "Content-Type": "application/json", + "ConsistencyLevel": "eventual" + }, + "authentication": { + "type": "ActiveDirectoryOAuth", + "authority": "https://login.microsoftonline.com", + "tenant": "", + "audience": "https://graph.microsoft.com", + "clientId": "", + "secret": "@parameters('graphClientSecret')" + } + } +} +``` + +> **When to use:** Calling Microsoft Graph, Azure Resource Manager, or any +> Azure AD-protected API from a flow without a premium connector. +> +> The `authentication` block handles the entire OAuth client-credentials flow +> transparently — no manual token acquisition step needed. +> +> `ConsistencyLevel: eventual` is required for Graph `$search` queries. +> Without it, `$search` returns 400. +> +> For PATCH/PUT writes, the same `authentication` block works — just change +> `method` and add a `body`. +> +> ⚠️ **Never hardcode `secret` inline.** Use `@parameters('graphClientSecret')` +> and declare it in the flow's `parameters` block (type `securestring`). This +> prevents the secret from appearing in run history or being readable via +> `get_live_flow`. Declare the parameter like: +> ```json +> "parameters": { +> "graphClientSecret": { "type": "securestring", "defaultValue": "" } +> } +> ``` +> Then pass the real value via the flow's connections or environment variables +> — never commit it to source control. + +--- + +### HTTP Response (Return to Caller) + +Used in HTTP-triggered flows to send a structured reply back to the caller. +Must run before the flow times out (default 2 min for synchronous HTTP). + +```json +"Response": { + "type": "Response", + "runAfter": {}, + "inputs": { + "statusCode": 200, + "headers": { + "Content-Type": "application/json" + }, + "body": { + "status": "success", + "message": "@{outputs('Compose_Result')}" + } + } +} +``` + +> **PowerApps / low-code caller pattern**: always return `statusCode: 200` with a +> `status` field in the body (`"success"` / `"error"`). PowerApps HTTP actions +> do not handle non-2xx responses gracefully — the caller should inspect +> `body.status` rather than the HTTP status code. +> +> Use multiple Response actions — one per branch — so each path returns +> an appropriate message. Only one will execute per run. + +--- + +### Child Flow Call (Parent→Child via HTTP POST) + +Power Automate supports parent→child orchestration by calling a child flow's +HTTP trigger URL directly. The parent sends an HTTP POST and blocks until the +child returns a `Response` action. The child flow uses a `manual` (Request) trigger. + +```json +// PARENT — call child flow and wait for its response +"Call_Child_Flow": { + "type": "Http", + "inputs": { + "method": "POST", + "uri": "https://prod-XX.australiasoutheast.logic.azure.com:443/workflows//triggers/manual/paths/invoke?api-version=2016-06-01&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig=", + "headers": { "Content-Type": "application/json" }, + "body": { + "ID": "@triggerBody()?['ID']", + "WeekEnd": "@triggerBody()?['WeekEnd']", + "Payload": "@variables('dataArray')" + }, + "retryPolicy": { "type": "none" } + }, + "operationOptions": "DisableAsyncPattern", + "runtimeConfiguration": { + "contentTransfer": { "transferMode": "Chunked" } + }, + "limit": { "timeout": "PT2H" } +} +``` + +```json +// CHILD — manual trigger receives the JSON body +// (trigger definition) +"manual": { + "type": "Request", + "kind": "Http", + "inputs": { + "schema": { + "type": "object", + "properties": { + "ID": { "type": "string" }, + "WeekEnd": { "type": "string" }, + "Payload": { "type": "array" } + } + } + } +} + +// CHILD — return result to parent +"Response_Success": { + "type": "Response", + "inputs": { + "statusCode": 200, + "headers": { "Content-Type": "application/json" }, + "body": { "Result": "Success", "Count": "@length(variables('processed'))" } + } +} +``` + +> **`retryPolicy: none`** — critical on the parent's HTTP call. Without it, a child +> flow timeout triggers retries, spawning duplicate child runs. +> +> **`DisableAsyncPattern`** — prevents the parent from treating a 202 Accepted as +> completion. The parent will block until the child sends its `Response`. +> +> **`transferMode: Chunked`** — enable when passing large arrays (>100 KB) to the child; +> avoids request-size limits. +> +> **`limit.timeout: PT2H`** — raise the default 2-minute HTTP timeout for long-running +> children. Max is PT24H. +> +> The child flow's trigger URL contains a SAS token (`sig=...`) that authenticates +> the call. Copy it from the child flow's trigger properties panel. The URL changes +> if the trigger is deleted and re-created. + +--- + +### Parse JSON + +```json +"Parse_Response": { + "type": "ParseJson", + "runAfter": {}, + "inputs": { + "content": "@outputs('Call_External_API')?['body']", + "schema": { + "type": "object", + "properties": { + "id": { "type": "integer" }, + "name": { "type": "string" }, + "items": { + "type": "array", + "items": { "type": "object" } + } + } + } + } +} +``` + +Access parsed values: `@body('Parse_Response')?['name']` + +--- + +### Manual CSV → JSON (No Premium Action) + +Parse a raw CSV string into an array of objects using only built-in expressions. +Avoids the premium "Parse CSV" connector action. + +```json +"Delimiter": { + "type": "Compose", + "inputs": "," +}, +"Strip_Quotes": { + "type": "Compose", + "inputs": "@replace(body('Get_File_Content'), '\"', '')" +}, +"Detect_Line_Ending": { + "type": "Compose", + "inputs": "@if(equals(indexOf(outputs('Strip_Quotes'), decodeUriComponent('%0D%0A')), -1), if(equals(indexOf(outputs('Strip_Quotes'), decodeUriComponent('%0A')), -1), decodeUriComponent('%0D'), decodeUriComponent('%0A')), decodeUriComponent('%0D%0A'))" +}, +"Headers": { + "type": "Compose", + "inputs": "@split(first(split(outputs('Strip_Quotes'), outputs('Detect_Line_Ending'))), outputs('Delimiter'))" +}, +"Data_Rows": { + "type": "Compose", + "inputs": "@skip(split(outputs('Strip_Quotes'), outputs('Detect_Line_Ending')), 1)" +}, +"Select_CSV_Body": { + "type": "Select", + "inputs": { + "from": "@outputs('Data_Rows')", + "select": { + "@{outputs('Headers')[0]}": "@split(item(), outputs('Delimiter'))[0]", + "@{outputs('Headers')[1]}": "@split(item(), outputs('Delimiter'))[1]", + "@{outputs('Headers')[2]}": "@split(item(), outputs('Delimiter'))[2]" + } + } +}, +"Filter_Empty_Rows": { + "type": "Query", + "inputs": { + "from": "@body('Select_CSV_Body')", + "where": "@not(equals(item()?[outputs('Headers')[0]], null))" + } +} +``` + +Result: `@body('Filter_Empty_Rows')` — array of objects with header names as keys. + +> **`Detect_Line_Ending`** handles CRLF (Windows), LF (Unix), and CR (old Mac) automatically +> using `indexOf()` with `decodeUriComponent('%0D%0A' / '%0A' / '%0D')`. +> +> **Dynamic key names in `Select`**: `@{outputs('Headers')[0]}` as a JSON key in a +> `Select` shape sets the output property name at runtime from the header row — +> this works as long as the expression is in `@{...}` interpolation syntax. +> +> **Columns with embedded commas**: if field values can contain the delimiter, +> use `length(split(row, ','))` in a Switch to detect the column count and manually +> reassemble the split fragments: `@concat(split(item(),',')[1],',',split(item(),',')[2])` + +--- + +### ConvertTimeZone (Built-in, No Connector) + +Converts a timestamp between timezones with no API call or connector licence cost. +Format string `"g"` produces short locale date+time (`M/d/yyyy h:mm tt`). + +```json +"Convert_to_Local_Time": { + "type": "Expression", + "kind": "ConvertTimeZone", + "runAfter": {}, + "inputs": { + "baseTime": "@{outputs('UTC_Timestamp')}", + "sourceTimeZone": "UTC", + "destinationTimeZone": "Taipei Standard Time", + "formatString": "g" + } +} +``` + +Result reference: `@body('Convert_to_Local_Time')` — **not** `outputs()`, unlike most actions. + +Common `formatString` values: `"g"` (short), `"f"` (full), `"yyyy-MM-dd"`, `"HH:mm"` + +Common timezone strings: `"UTC"`, `"AUS Eastern Standard Time"`, `"Taipei Standard Time"`, +`"Singapore Standard Time"`, `"GMT Standard Time"` + +> This is `type: Expression, kind: ConvertTimeZone` — a built-in Logic Apps action, +> not a connector. No connection reference needed. Reference the output via +> `body()` (not `outputs()`), otherwise the expression returns null. diff --git a/skills/flowstudio-power-automate-build/references/build-patterns.md b/skills/flowstudio-power-automate-build/references/build-patterns.md new file mode 100644 index 00000000..b50b10af --- /dev/null +++ b/skills/flowstudio-power-automate-build/references/build-patterns.md @@ -0,0 +1,108 @@ +# Common Build Patterns + +Complete flow definition templates ready to copy and customize. + +--- + +## Pattern: Recurrence + SharePoint list read + Teams notification + +```json +{ + "triggers": { + "Recurrence": { + "type": "Recurrence", + "recurrence": { "frequency": "Day", "interval": 1, + "startTime": "2026-01-01T08:00:00Z", + "timeZone": "AUS Eastern Standard Time" } + } + }, + "actions": { + "Get_SP_Items": { + "type": "OpenApiConnection", + "runAfter": {}, + "inputs": { + "host": { + "apiId": "/providers/Microsoft.PowerApps/apis/shared_sharepointonline", + "connectionName": "shared_sharepointonline", + "operationId": "GetItems" + }, + "parameters": { + "dataset": "https://mytenant.sharepoint.com/sites/mysite", + "table": "MyList", + "$filter": "Status eq 'Active'", + "$top": 500 + } + } + }, + "Apply_To_Each": { + "type": "Foreach", + "runAfter": { "Get_SP_Items": ["Succeeded"] }, + "foreach": "@outputs('Get_SP_Items')?['body/value']", + "actions": { + "Post_Teams_Message": { + "type": "OpenApiConnection", + "runAfter": {}, + "inputs": { + "host": { + "apiId": "/providers/Microsoft.PowerApps/apis/shared_teams", + "connectionName": "shared_teams", + "operationId": "PostMessageToConversation" + }, + "parameters": { + "poster": "Flow bot", + "location": "Channel", + "body/recipient": { + "groupId": "", + "channelId": "" + }, + "body/messageBody": "Item: @{items('Apply_To_Each')?['Title']}" + } + } + } + }, + "operationOptions": "Sequential" + } + } +} +``` + +--- + +## Pattern: HTTP trigger (webhook / Power App call) + +```json +{ + "triggers": { + "manual": { + "type": "Request", + "kind": "Http", + "inputs": { + "schema": { + "type": "object", + "properties": { + "name": { "type": "string" }, + "value": { "type": "number" } + } + } + } + } + }, + "actions": { + "Compose_Response": { + "type": "Compose", + "runAfter": {}, + "inputs": "Received: @{triggerBody()?['name']} = @{triggerBody()?['value']}" + }, + "Response": { + "type": "Response", + "runAfter": { "Compose_Response": ["Succeeded"] }, + "inputs": { + "statusCode": 200, + "body": { "status": "ok", "message": "@{outputs('Compose_Response')}" } + } + } + } +} +``` + +Access body values: `@triggerBody()?['name']` diff --git a/skills/flowstudio-power-automate-build/references/flow-schema.md b/skills/flowstudio-power-automate-build/references/flow-schema.md new file mode 100644 index 00000000..02210e0a --- /dev/null +++ b/skills/flowstudio-power-automate-build/references/flow-schema.md @@ -0,0 +1,225 @@ +# FlowStudio MCP — Flow Definition Schema + +The full JSON structure expected by `update_live_flow` (and returned by `get_live_flow`). + +--- + +## Top-Level Shape + +```json +{ + "$schema": "https://schema.management.azure.com/providers/Microsoft.Logic/schemas/2016-06-01/workflowdefinition.json#", + "contentVersion": "1.0.0.0", + "parameters": { + "$connections": { + "defaultValue": {}, + "type": "Object" + } + }, + "triggers": { + "": { ... } + }, + "actions": { + "": { ... } + }, + "outputs": {} +} +``` + +--- + +## `triggers` + +Exactly one trigger per flow definition. The key name is arbitrary but +conventional names are used (e.g. `Recurrence`, `manual`, `When_a_new_email_arrives`). + +See [trigger-types.md](trigger-types.md) for all trigger templates. + +--- + +## `actions` + +Dictionary of action definitions keyed by unique action name. +Key names may not contain spaces — use underscores. + +Each action must include: +- `type` — action type identifier +- `runAfter` — map of upstream action names → status conditions array +- `inputs` — action-specific input configuration + +See [action-patterns-core.md](action-patterns-core.md), [action-patterns-data.md](action-patterns-data.md), +and [action-patterns-connectors.md](action-patterns-connectors.md) for templates. + +### Optional Action Properties + +Beyond the required `type`, `runAfter`, and `inputs`, actions can include: + +| Property | Purpose | +|---|---| +| `runtimeConfiguration` | Pagination, concurrency, secure data, chunked transfer | +| `operationOptions` | `"Sequential"` for Foreach, `"DisableAsyncPattern"` for HTTP | +| `limit` | Timeout override (e.g. `{"timeout": "PT2H"}`) | + +#### `runtimeConfiguration` Variants + +**Pagination** (SharePoint Get Items with large lists): +```json +"runtimeConfiguration": { + "paginationPolicy": { + "minimumItemCount": 5000 + } +} +``` +> Without this, Get Items silently caps at 256 results. Set `minimumItemCount` +> to the maximum rows you expect. Required for any SharePoint list over 256 items. + +**Concurrency** (parallel Foreach): +```json +"runtimeConfiguration": { + "concurrency": { + "repetitions": 20 + } +} +``` + +**Secure inputs/outputs** (mask values in run history): +```json +"runtimeConfiguration": { + "secureData": { + "properties": ["inputs", "outputs"] + } +} +``` +> Use on actions that handle credentials, tokens, or PII. Masked values show +> as `""` in the flow run history UI and API responses. + +**Chunked transfer** (large HTTP payloads): +```json +"runtimeConfiguration": { + "contentTransfer": { + "transferMode": "Chunked" + } +} +``` +> Enable on HTTP actions sending or receiving bodies >100 KB (e.g. parent→child +> flow calls with large arrays). + +--- + +## `runAfter` Rules + +The first action in a branch has `"runAfter": {}` (empty — runs after trigger). + +Subsequent actions declare their dependency: + +```json +"My_Action": { + "runAfter": { + "Previous_Action": ["Succeeded"] + } +} +``` + +Multiple upstream dependencies: +```json +"runAfter": { + "Action_A": ["Succeeded"], + "Action_B": ["Succeeded", "Skipped"] +} +``` + +Error-handling action (runs when upstream failed): +```json +"Log_Error": { + "runAfter": { + "Risky_Action": ["Failed"] + } +} +``` + +--- + +## `parameters` (Flow-Level Input Parameters) + +Optional. Define reusable values at the flow level: + +```json +"parameters": { + "listName": { + "type": "string", + "defaultValue": "MyList" + }, + "maxItems": { + "type": "integer", + "defaultValue": 100 + } +} +``` + +Reference: `@parameters('listName')` in expression strings. + +--- + +## `outputs` + +Rarely used in cloud flows. Leave as `{}` unless the flow is called +as a child flow and needs to return values. + +For child flows that return data: + +```json +"outputs": { + "resultData": { + "type": "object", + "value": "@outputs('Compose_Result')" + } +} +``` + +--- + +## Scoped Actions (Inside Scope Block) + +Actions that need to be grouped for error handling or clarity: + +```json +"Scope_Main_Process": { + "type": "Scope", + "runAfter": {}, + "actions": { + "Step_One": { ... }, + "Step_Two": { "runAfter": { "Step_One": ["Succeeded"] }, ... } + } +} +``` + +--- + +## Full Minimal Example + +```json +{ + "$schema": "https://schema.management.azure.com/providers/Microsoft.Logic/schemas/2016-06-01/workflowdefinition.json#", + "contentVersion": "1.0.0.0", + "triggers": { + "Recurrence": { + "type": "Recurrence", + "recurrence": { + "frequency": "Week", + "interval": 1, + "schedule": { "weekDays": ["Monday"] }, + "startTime": "2026-01-05T09:00:00Z", + "timeZone": "AUS Eastern Standard Time" + } + } + }, + "actions": { + "Compose_Greeting": { + "type": "Compose", + "runAfter": {}, + "inputs": "Good Monday!" + } + }, + "outputs": {} +} +``` diff --git a/skills/flowstudio-power-automate-build/references/trigger-types.md b/skills/flowstudio-power-automate-build/references/trigger-types.md new file mode 100644 index 00000000..6065f1fa --- /dev/null +++ b/skills/flowstudio-power-automate-build/references/trigger-types.md @@ -0,0 +1,211 @@ +# FlowStudio MCP — Trigger Types + +Copy-paste trigger definitions for Power Automate flow definitions. + +--- + +## Recurrence + +Run on a schedule. + +```json +"Recurrence": { + "type": "Recurrence", + "recurrence": { + "frequency": "Day", + "interval": 1, + "startTime": "2026-01-01T08:00:00Z", + "timeZone": "AUS Eastern Standard Time" + } +} +``` + +Weekly on specific days: +```json +"Recurrence": { + "type": "Recurrence", + "recurrence": { + "frequency": "Week", + "interval": 1, + "schedule": { + "weekDays": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"] + }, + "startTime": "2026-01-05T09:00:00Z", + "timeZone": "AUS Eastern Standard Time" + } +} +``` + +Common `timeZone` values: +- `"AUS Eastern Standard Time"` — Sydney/Melbourne (UTC+10/+11) +- `"UTC"` — Universal time +- `"E. Australia Standard Time"` — Brisbane (UTC+10 no DST) +- `"New Zealand Standard Time"` — Auckland (UTC+12/+13) +- `"Pacific Standard Time"` — Los Angeles (UTC-8/-7) +- `"GMT Standard Time"` — London (UTC+0/+1) + +--- + +## Manual (HTTP Request / Power Apps) + +Receive an HTTP POST with a JSON body. + +```json +"manual": { + "type": "Request", + "kind": "Http", + "inputs": { + "schema": { + "type": "object", + "properties": { + "name": { "type": "string" }, + "value": { "type": "integer" } + }, + "required": ["name"] + } + } +} +``` + +Access values: `@triggerBody()?['name']` +Trigger URL available after saving: `@listCallbackUrl()` + +#### No-Schema Variant (Accept Arbitrary JSON) + +When the incoming payload structure is unknown or varies, omit the schema +to accept any valid JSON body without validation: + +```json +"manual": { + "type": "Request", + "kind": "Http", + "inputs": { + "schema": {} + } +} +``` + +Access any field dynamically: `@triggerBody()?['anyField']` + +> Use this for external webhooks (Stripe, GitHub, Employment Hero, etc.) where the +> payload shape may change or is not fully documented. The flow accepts any +> JSON without returning 400 for unexpected properties. + +--- + +## Automated (SharePoint Item Created) + +```json +"When_an_item_is_created": { + "type": "OpenApiConnectionNotification", + "inputs": { + "host": { + "apiId": "/providers/Microsoft.PowerApps/apis/shared_sharepointonline", + "connectionName": "", + "operationId": "OnNewItem" + }, + "parameters": { + "dataset": "https://mytenant.sharepoint.com/sites/mysite", + "table": "MyList" + }, + "subscribe": { + "body": { "notificationUrl": "@listCallbackUrl()" }, + "queries": { + "dataset": "https://mytenant.sharepoint.com/sites/mysite", + "table": "MyList" + } + } + } +} +``` + +Access trigger data: `@triggerBody()?['ID']`, `@triggerBody()?['Title']`, etc. + +--- + +## Automated (SharePoint Item Modified) + +```json +"When_an_existing_item_is_modified": { + "type": "OpenApiConnectionNotification", + "inputs": { + "host": { + "apiId": "/providers/Microsoft.PowerApps/apis/shared_sharepointonline", + "connectionName": "", + "operationId": "OnUpdatedItem" + }, + "parameters": { + "dataset": "https://mytenant.sharepoint.com/sites/mysite", + "table": "MyList" + }, + "subscribe": { + "body": { "notificationUrl": "@listCallbackUrl()" }, + "queries": { + "dataset": "https://mytenant.sharepoint.com/sites/mysite", + "table": "MyList" + } + } + } +} +``` + +--- + +## Automated (Outlook: When New Email Arrives) + +```json +"When_a_new_email_arrives": { + "type": "OpenApiConnectionNotification", + "inputs": { + "host": { + "apiId": "/providers/Microsoft.PowerApps/apis/shared_office365", + "connectionName": "", + "operationId": "OnNewEmail" + }, + "parameters": { + "folderId": "Inbox", + "to": "monitored@contoso.com", + "isHTML": true + }, + "subscribe": { + "body": { "notificationUrl": "@listCallbackUrl()" } + } + } +} +``` + +--- + +## Child Flow (Called by Another Flow) + +```json +"manual": { + "type": "Request", + "kind": "Button", + "inputs": { + "schema": { + "type": "object", + "properties": { + "items": { + "type": "array", + "items": { "type": "object" } + } + } + } + } +} +``` + +Access parent-supplied data: `@triggerBody()?['items']` + +To return data to the parent, add a `Response` action: +```json +"Respond_to_Parent": { + "type": "Response", + "runAfter": { "Compose_Result": ["Succeeded"] }, + "inputs": { + "statusCode": 200, + "body": "@outputs('Compose_Result')" + } +} +``` diff --git a/skills/flowstudio-power-automate-debug/SKILL.md b/skills/flowstudio-power-automate-debug/SKILL.md new file mode 100644 index 00000000..964ca349 --- /dev/null +++ b/skills/flowstudio-power-automate-debug/SKILL.md @@ -0,0 +1,322 @@ +--- +name: flowstudio-power-automate-debug +description: >- + Debug failing Power Automate cloud flows using the FlowStudio MCP server. + Load this skill when asked to: debug a flow, investigate a failed run, why is + this flow failing, inspect action outputs, find the root cause of a flow error, + fix a broken Power Automate flow, diagnose a timeout, trace a DynamicOperationRequestFailure, + check connector auth errors, read error details from a run, or troubleshoot + expression failures. Requires a FlowStudio MCP subscription — see https://mcp.flowstudio.app +--- + +# Power Automate Debugging with FlowStudio MCP + +A step-by-step diagnostic process for investigating failing Power Automate +cloud flows through the FlowStudio MCP server. + +**Prerequisite**: A FlowStudio MCP server must be reachable with a valid JWT. +See the `flowstudio-power-automate-mcp` skill for connection setup. +Subscribe at https://mcp.flowstudio.app + +--- + +## Source of Truth + +> **Always call `tools/list` first** to confirm available tool names and their +> parameter schemas. Tool names and parameters may change between server versions. +> This skill covers response shapes, behavioral notes, and diagnostic patterns — +> things `tools/list` cannot tell you. If this document disagrees with `tools/list` +> or a real API response, the API wins. + +--- + +## Python Helper + +```python +import json, urllib.request + +MCP_URL = "https://mcp.flowstudio.app/mcp" +MCP_TOKEN = "" + +def mcp(tool, **kwargs): + payload = json.dumps({"jsonrpc": "2.0", "id": 1, "method": "tools/call", + "params": {"name": tool, "arguments": kwargs}}).encode() + req = urllib.request.Request(MCP_URL, data=payload, + headers={"x-api-key": MCP_TOKEN, "Content-Type": "application/json", + "User-Agent": "FlowStudio-MCP/1.0"}) + try: + resp = urllib.request.urlopen(req, timeout=120) + except urllib.error.HTTPError as e: + body = e.read().decode("utf-8", errors="replace") + raise RuntimeError(f"MCP HTTP {e.code}: {body[:200]}") from e + raw = json.loads(resp.read()) + if "error" in raw: + raise RuntimeError(f"MCP error: {json.dumps(raw['error'])}") + return json.loads(raw["result"]["content"][0]["text"]) + +ENV = "" # e.g. Default-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx +``` + +--- + +## FlowStudio for Teams: Fast-Path Diagnosis (Skip Steps 2–4) + +If you have a FlowStudio for Teams subscription, `get_store_flow_errors` +returns per-run failure data including action names and remediation hints +in a single call — no need to walk through live API steps. + +```python +# Quick failure summary +summary = mcp("get_store_flow_summary", environmentName=ENV, flowName=FLOW_ID) +# {"totalRuns": 100, "failRuns": 10, "failRate": 0.1, +# "averageDurationSeconds": 29.4, "maxDurationSeconds": 158.9, +# "firstFailRunRemediation": ""} +print(f"Fail rate: {summary['failRate']:.0%} over {summary['totalRuns']} runs") + +# Per-run error details (requires active monitoring to be configured) +errors = mcp("get_store_flow_errors", environmentName=ENV, flowName=FLOW_ID) +if errors: + for r in errors[:3]: + print(r["startTime"], "|", r.get("failedActions"), "|", r.get("remediationHint")) + # If errors confirms the failing action → jump to Step 6 (apply fix) +else: + # Store doesn't have run-level detail for this flow — use live tools (Steps 2–5) + pass +``` + +For the full governance record (description, complexity, tier, connector list): +```python +record = mcp("get_store_flow", environmentName=ENV, flowName=FLOW_ID) +# {"displayName": "My Flow", "state": "Started", +# "runPeriodTotal": 100, "runPeriodFailRate": 0.1, "runPeriodFails": 10, +# "runPeriodDurationAverage": 29410.8, ← milliseconds +# "runError": "{\"code\": \"EACCES\", ...}", ← JSON string, parse it +# "description": "...", "tier": "Premium", "complexity": "{...}"} +if record.get("runError"): + last_err = json.loads(record["runError"]) + print("Last run error:", last_err) +``` + +--- + +## Step 1 — Locate the Flow + +```python +result = mcp("list_live_flows", environmentName=ENV) +# Returns a wrapper object: {mode, flows, totalCount, error} +target = next(f for f in result["flows"] if "My Flow Name" in f["displayName"]) +FLOW_ID = target["id"] # plain UUID — use directly as flowName +print(FLOW_ID) +``` + +--- + +## Step 2 — Find the Failing Run + +```python +runs = mcp("get_live_flow_runs", environmentName=ENV, flowName=FLOW_ID, top=5) +# Returns direct array (newest first): +# [{"name": "08584296068667933411438594643CU15", +# "status": "Failed", +# "startTime": "2026-02-25T06:13:38.6910688Z", +# "endTime": "2026-02-25T06:15:24.1995008Z", +# "triggerName": "manual", +# "error": {"code": "ActionFailed", "message": "An action failed..."}}, +# {"name": "...", "status": "Succeeded", "error": null, ...}] + +for r in runs: + print(r["name"], r["status"], r["startTime"]) + +RUN_ID = next(r["name"] for r in runs if r["status"] == "Failed") +``` + +--- + +## Step 3 — Get the Top-Level Error + +```python +err = mcp("get_live_flow_run_error", + environmentName=ENV, flowName=FLOW_ID, runName=RUN_ID) +# Returns: +# { +# "runName": "08584296068667933411438594643CU15", +# "failedActions": [ +# {"actionName": "Apply_to_each_prepare_workers", "status": "Failed", +# "error": {"code": "ActionFailed", "message": "An action failed..."}, +# "startTime": "...", "endTime": "..."}, +# {"actionName": "HTTP_find_AD_User_by_Name", "status": "Failed", +# "code": "NotSpecified", "startTime": "...", "endTime": "..."} +# ], +# "allActions": [ +# {"actionName": "Apply_to_each", "status": "Skipped"}, +# {"actionName": "Compose_WeekEnd", "status": "Succeeded"}, +# ... +# ] +# } + +# failedActions is ordered outer-to-inner. The ROOT cause is the LAST entry: +root = err["failedActions"][-1] +print(f"Root action: {root['actionName']} → code: {root.get('code')}") + +# allActions shows every action's status — useful for spotting what was Skipped +# See common-errors.md to decode the error code. +``` + +--- + +## Step 4 — Read the Flow Definition + +```python +defn = mcp("get_live_flow", environmentName=ENV, flowName=FLOW_ID) +actions = defn["properties"]["definition"]["actions"] +print(list(actions.keys())) +``` + +Find the failing action in the definition. Inspect its `inputs` expression +to understand what data it expects. + +--- + +## Step 5 — Inspect Action Outputs (Walk Back from Failure) + +For each action **leading up to** the failure, inspect its runtime output: + +```python +for action_name in ["Compose_WeekEnd", "HTTP_Get_Data", "Parse_JSON"]: + result = mcp("get_live_flow_run_action_outputs", + environmentName=ENV, + flowName=FLOW_ID, + runName=RUN_ID, + actionName=action_name) + # Returns an array — single-element when actionName is provided + out = result[0] if result else {} + print(action_name, out.get("status")) + print(json.dumps(out.get("outputs", {}), indent=2)[:500]) +``` + +> ⚠️ Output payloads from array-processing actions can be very large. +> Always slice (e.g. `[:500]`) before printing. + +--- + +## Step 6 — Pinpoint the Root Cause + +### Expression Errors (e.g. `split` on null) +If the error mentions `InvalidTemplate` or a function name: +1. Find the action in the definition +2. Check what upstream action/expression it reads +3. Inspect that upstream action's output for null / missing fields + +```python +# Example: action uses split(item()?['Name'], ' ') +# → null Name in the source data +result = mcp("get_live_flow_run_action_outputs", ..., actionName="Compose_Names") +# Returns a single-element array; index [0] to get the action object +if not result: + print("No outputs returned for Compose_Names") + names = [] +else: + names = result[0].get("outputs", {}).get("body") or [] +nulls = [x for x in names if x.get("Name") is None] +print(f"{len(nulls)} records with null Name") +``` + +### Wrong Field Path +Expression `triggerBody()?['fieldName']` returns null → `fieldName` is wrong. +Check the trigger output shape with: +```python +mcp("get_live_flow_run_action_outputs", ..., actionName="") +``` + +### Connection / Auth Failures +Look for `ConnectionAuthorizationFailed` — the connection owner must match the +service account running the flow. Cannot fix via API; fix in PA designer. + +--- + +## Step 7 — Apply the Fix + +**For expression/data issues**: +```python +defn = mcp("get_live_flow", environmentName=ENV, flowName=FLOW_ID) +acts = defn["properties"]["definition"]["actions"] + +# Example: fix split on potentially-null Name +acts["Compose_Names"]["inputs"] = \ + "@coalesce(item()?['Name'], 'Unknown')" + +conn_refs = defn["properties"]["connectionReferences"] +result = mcp("update_live_flow", + environmentName=ENV, + flowName=FLOW_ID, + definition=defn["properties"]["definition"], + connectionReferences=conn_refs) + +print(result.get("error")) # None = success +``` + +> ⚠️ `update_live_flow` always returns an `error` key. +> A value of `null` (Python `None`) means success. + +--- + +## Step 8 — Verify the Fix + +```python +# Resubmit the failed run +resubmit = mcp("resubmit_live_flow_run", + environmentName=ENV, flowName=FLOW_ID, runName=RUN_ID) +print(resubmit) + +# Wait ~30 s then check +import time; time.sleep(30) +new_runs = mcp("get_live_flow_runs", environmentName=ENV, flowName=FLOW_ID, top=3) +print(new_runs[0]["status"]) # Succeeded = done +``` + +### Testing HTTP-Triggered Flows + +For flows with a `Request` (HTTP) trigger, use `trigger_live_flow` instead +of `resubmit_live_flow_run` to test with custom payloads: + +```python +# First inspect what the trigger expects +schema = mcp("get_live_flow_http_schema", + environmentName=ENV, flowName=FLOW_ID) +print("Expected body schema:", schema.get("triggerSchema")) +print("Response schemas:", schema.get("responseSchemas")) + +# Trigger with a test payload +result = mcp("trigger_live_flow", + environmentName=ENV, + flowName=FLOW_ID, + body={"name": "Test User", "value": 42}) +print(f"Status: {result['status']}, Body: {result.get('body')}") +``` + +> `trigger_live_flow` handles AAD-authenticated triggers automatically. +> Only works for flows with a `Request` (HTTP) trigger type. + +--- + +## Quick-Reference Diagnostic Decision Tree + +| Symptom | First Tool to Call | What to Look For | +|---|---|---| +| Flow shows as Failed | `get_live_flow_run_error` | `failedActions[-1]["actionName"]` = root cause | +| Expression crash | `get_live_flow_run_action_outputs` on prior action | null / wrong-type fields in output body | +| Flow never starts | `get_live_flow` | check `properties.state` = "Started" | +| Action returns wrong data | `get_live_flow_run_action_outputs` | actual output body vs expected | +| Fix applied but still fails | `get_live_flow_runs` after resubmit | new run `status` field | + +--- + +## Reference Files + +- [common-errors.md](references/common-errors.md) — Error codes, likely causes, and fixes +- [debug-workflow.md](references/debug-workflow.md) — Full decision tree for complex failures + +## Related Skills + +- `flowstudio-power-automate-mcp` — Core connection setup and operation reference +- `flowstudio-power-automate-build` — Build and deploy new flows diff --git a/skills/flowstudio-power-automate-debug/references/common-errors.md b/skills/flowstudio-power-automate-debug/references/common-errors.md new file mode 100644 index 00000000..bd879b4f --- /dev/null +++ b/skills/flowstudio-power-automate-debug/references/common-errors.md @@ -0,0 +1,188 @@ +# FlowStudio MCP — Common Power Automate Errors + +Reference for error codes, likely causes, and recommended fixes when debugging +Power Automate flows via the FlowStudio MCP server. + +--- + +## Expression / Template Errors + +### `InvalidTemplate` — Function Applied to Null + +**Full message pattern**: `"Unable to process template language expressions... function 'split' expects its first argument 'text' to be of type string"` + +**Root cause**: An expression like `@split(item()?['Name'], ' ')` received a null value. + +**Diagnosis**: +1. Note the action name in the error message +2. Call `get_live_flow_run_action_outputs` on the action that produces the array +3. Find items where `Name` (or the referenced field) is `null` + +**Fixes**: +``` +Before: @split(item()?['Name'], ' ') +After: @split(coalesce(item()?['Name'], ''), ' ') + +Or guard the whole foreach body with a condition: + expression: "@not(empty(item()?['Name']))" +``` + +--- + +### `InvalidTemplate` — Wrong Expression Path + +**Full message pattern**: `"Unable to process template language expressions... 'triggerBody()?['FieldName']' is of type 'Null'"` + +**Root cause**: The field name in the expression doesn't match the actual payload schema. + +**Diagnosis**: +```python +# Check trigger output shape +mcp("get_live_flow_run_action_outputs", + environmentName=ENV, flowName=FLOW_ID, runName=RUN_ID, + actionName="") +# Compare actual keys vs expression +``` + +**Fix**: Update expression to use the correct key name. Common mismatches: +- `triggerBody()?['body']` vs `triggerBody()?['Body']` (case-sensitive) +- `triggerBody()?['Subject']` vs `triggerOutputs()?['body/Subject']` + +--- + +### `InvalidTemplate` — Type Mismatch + +**Full message pattern**: `"... expected type 'Array' but got type 'Object'"` + +**Root cause**: Passing an object where the expression expects an array (e.g. a single item HTTP response vs a list response). + +**Fix**: +``` +Before: @outputs('HTTP')?['body'] +After: @outputs('HTTP')?['body/value'] ← for OData list responses + @createArray(outputs('HTTP')?['body']) ← wrap single object in array +``` + +--- + +## Connection / Auth Errors + +### `ConnectionAuthorizationFailed` + +**Full message**: `"The API connection ... is not authorized."` + +**Root cause**: The connection referenced in the flow is owned by a different +user/service account than the one whose JWT is being used. + +**Diagnosis**: Check `properties.connectionReferences` — the `connectionName` GUID +identifies the owner. Cannot be fixed via API. + +**Fix options**: +1. Open flow in Power Automate designer → re-authenticate the connection +2. Use a connection owned by the service account whose token you hold +3. Share the connection with the service account in PA admin + +--- + +### `InvalidConnectionCredentials` + +**Root cause**: The underlying OAuth token for the connection has expired or +the user's credentials changed. + +**Fix**: Owner must sign in to Power Automate and refresh the connection. + +--- + +## HTTP Action Errors + +### `ActionFailed` — HTTP 4xx/5xx + +**Full message pattern**: `"An HTTP request to... failed with status code '400'"` + +**Diagnosis**: +```python +actions_out = mcp("get_live_flow_run_action_outputs", ..., actionName="HTTP_My_Call") +item = actions_out[0] # first entry in the returned array +print(item["outputs"]["statusCode"]) # 400, 401, 403, 500... +print(item["outputs"]["body"]) # error details from target API +``` + +**Common causes**: +- 401 — missing or expired auth header +- 403 — permission denied on target resource +- 404 — wrong URL / resource deleted +- 400 — malformed JSON body (check expression that builds the body) + +--- + +### `ActionFailed` — HTTP Timeout + +**Root cause**: Target endpoint did not respond within the connector's timeout +(default 90 s for HTTP action). + +**Fix**: Add retry policy to the HTTP action, or split the payload into smaller +batches to reduce per-request processing time. + +--- + +## Control Flow Errors + +### `ActionSkipped` Instead of Running + +**Root cause**: The `runAfter` condition wasn't met. E.g. an action set to +`runAfter: { "Prev": ["Succeeded"] }` won't run if `Prev` failed or was skipped. + +**Diagnosis**: Check the preceding action's status. Deliberately skipped +(e.g. inside a false branch) is intentional — unexpected skip is a logic gap. + +**Fix**: Add `"Failed"` or `"Skipped"` to the `runAfter` status array if the +action should run on those outcomes too. + +--- + +### Foreach Runs in Wrong Order / Race Condition + +**Root cause**: `Foreach` without `operationOptions: "Sequential"` runs +iterations in parallel, causing write conflicts or undefined ordering. + +**Fix**: Add `"operationOptions": "Sequential"` to the Foreach action. + +--- + +## Update / Deploy Errors + +### `update_live_flow` Returns No-Op + +**Symptom**: `result["updated"]` is empty list or `result["created"]` is empty. + +**Likely cause**: Passing wrong parameter name. The required key is `definition` +(object), not `flowDefinition` or `body`. + +--- + +### `update_live_flow` — `"Supply connectionReferences"` + +**Root cause**: The definition contains `OpenApiConnection` or +`OpenApiConnectionWebhook` actions but `connectionReferences` was not passed. + +**Fix**: Fetch the existing connection references with `get_live_flow` and pass +them as the `connectionReferences` argument. + +--- + +## Data Logic Errors + +### `union()` Overriding Correct Records with Nulls + +**Symptom**: After merging two arrays, some records have null fields that existed +in one of the source arrays. + +**Root cause**: `union(old_data, new_data)` — `union()` first-wins, so old_data +values override new_data for matching records. + +**Fix**: Swap argument order: `union(new_data, old_data)` + +``` +Before: @sort(union(outputs('Old_Array'), body('New_Array')), 'Date') +After: @sort(union(body('New_Array'), outputs('Old_Array')), 'Date') +``` diff --git a/skills/flowstudio-power-automate-debug/references/debug-workflow.md b/skills/flowstudio-power-automate-debug/references/debug-workflow.md new file mode 100644 index 00000000..c28d86d1 --- /dev/null +++ b/skills/flowstudio-power-automate-debug/references/debug-workflow.md @@ -0,0 +1,157 @@ +# FlowStudio MCP — Debug Workflow + +End-to-end decision tree for diagnosing Power Automate flow failures. + +--- + +## Top-Level Decision Tree + +``` +Flow is failing +│ +├── Flow never starts / no runs appear +│ └── ► Check flow State: get_live_flow → properties.state +│ ├── "Stopped" → flow is disabled; enable in PA designer +│ └── "Started" + no runs → trigger condition not met (check trigger config) +│ +├── Flow run shows "Failed" +│ ├── Step A: get_live_flow_run_error → read error.code + error.message +│ │ +│ ├── error.code = "InvalidTemplate" +│ │ └── ► Expression error (null value, wrong type, bad path) +│ │ └── See: Expression Error Workflow below +│ │ +│ ├── error.code = "ConnectionAuthorizationFailed" +│ │ └── ► Connection owned by different user; fix in PA designer +│ │ +│ ├── error.code = "ActionFailed" + message mentions HTTP +│ │ └── ► See: HTTP Action Workflow below +│ │ +│ └── Unknown / generic error +│ └── ► Walk actions backwards (Step B below) +│ +└── Flow Succeeds but output is wrong + └── ► Inspect intermediate actions with get_live_flow_run_action_outputs + └── See: Data Quality Workflow below +``` + +--- + +## Expression Error Workflow + +``` +InvalidTemplate error +│ +├── 1. Read error.message — identifies the action name and function +│ +├── 2. Get flow definition: get_live_flow +│ └── Find that action in definition["actions"][action_name]["inputs"] +│ └── Identify what upstream value the expression reads +│ +├── 3. get_live_flow_run_action_outputs for the action BEFORE the failing one +│ └── Look for null / wrong type in that action's output +│ ├── Null string field → wrap with coalesce(): @coalesce(field, '') +│ ├── Null object → add empty check condition before the action +│ └── Wrong field name → correct the key (case-sensitive) +│ +└── 4. Apply fix with update_live_flow, then resubmit +``` + +--- + +## HTTP Action Workflow + +``` +ActionFailed on HTTP action +│ +├── 1. get_live_flow_run_action_outputs on the HTTP action +│ └── Read: outputs.statusCode, outputs.body +│ +├── statusCode = 401 +│ └── ► Auth header missing or expired OAuth token +│ Check: action inputs.authentication block +│ +├── statusCode = 403 +│ └── ► Insufficient permission on target resource +│ Check: service principal / user has access +│ +├── statusCode = 400 +│ └── ► Malformed request body +│ Check: action inputs.body expression; parse errors often in nested JSON +│ +├── statusCode = 404 +│ └── ► Wrong URL or resource deleted/renamed +│ Check: action inputs.uri expression +│ +└── statusCode = 500 / timeout + └── ► Target system error; retry policy may help + Add: "retryPolicy": {"type": "Fixed", "count": 3, "interval": "PT10S"} +``` + +--- + +## Data Quality Workflow + +``` +Flow succeeds but output data is wrong +│ +├── 1. Identify the first "wrong" output — which action produces it? +│ +├── 2. get_live_flow_run_action_outputs on that action +│ └── Compare actual output body vs expected +│ +├── Source array has nulls / unexpected values +│ ├── Check the trigger data — get_live_flow_run_action_outputs on trigger +│ └── Trace forward action by action until the value corrupts +│ +├── Merge/union has wrong values +│ └── Check union argument order: +│ union(NEW, old) = new wins ✓ +│ union(OLD, new) = old wins ← common bug +│ +├── Foreach output missing items +│ ├── Check foreach condition — filter may be too strict +│ └── Check if parallel foreach caused race condition (add Sequential) +│ +└── Date/time values wrong timezone + └── Use convertTimeZone() — utcNow() is always UTC +``` + +--- + +## Walk-Back Analysis (Unknown Failure) + +When the error message doesn't clearly name a root cause: + +```python +# 1. Get all action names from definition +defn = mcp("get_live_flow", environmentName=ENV, flowName=FLOW_ID) +actions = list(defn["properties"]["definition"]["actions"].keys()) + +# 2. Check status of each action in the failed run +for action in actions: + actions_out = mcp("get_live_flow_run_action_outputs", + environmentName=ENV, flowName=FLOW_ID, runName=RUN_ID, + actionName=action) + # Returns an array of action objects + item = actions_out[0] if actions_out else {} + status = item.get("status", "unknown") + print(f"{action}: {status}") + +# 3. Find the boundary between Succeeded and Failed/Skipped +# The first Failed action is likely the root cause (unless skipped by design) +``` + +Actions inside Foreach / Condition branches may appear nested — +check the parent action first to confirm the branch ran at all. + +--- + +## Post-Fix Verification Checklist + +1. `update_live_flow` returns `error: null` — definition accepted +2. `resubmit_live_flow_run` confirms new run started +3. Wait for run completion (poll `get_live_flow_runs` every 15 s) +4. Confirm new run `status = "Succeeded"` +5. If flow has downstream consumers (child flows, emails, SharePoint writes), + spot-check those too From e05c82c43f38d4850507075ede56d9ff1d7cfe0e Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Mon, 9 Mar 2026 11:15:02 +1100 Subject: [PATCH 14/37] Remove suggest-awesome-github-copilot-prompts skill (dead references) (#926) * Initial plan * Remove suggest-awesome-github-copilot-prompts skill (references non-existent prompts/ directory) Co-authored-by: aaronpowell <434140+aaronpowell@users.noreply.github.com> * Bump awesome-copilot plugin version to 1.1.0 Co-authored-by: aaronpowell <434140+aaronpowell@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: aaronpowell <434140+aaronpowell@users.noreply.github.com> --- .github/plugin/marketplace.json | 2 +- docs/README.plugins.md | 2 +- docs/README.skills.md | 1 - .../.github/plugin/plugin.json | 3 +- plugins/awesome-copilot/README.md | 1 - .../SKILL.md | 106 ------------------ 6 files changed, 3 insertions(+), 112 deletions(-) delete mode 100644 skills/suggest-awesome-github-copilot-prompts/SKILL.md diff --git a/.github/plugin/marketplace.json b/.github/plugin/marketplace.json index cf4d6a8e..ec42b570 100644 --- a/.github/plugin/marketplace.json +++ b/.github/plugin/marketplace.json @@ -14,7 +14,7 @@ "name": "awesome-copilot", "source": "awesome-copilot", "description": "Meta prompts that help you discover and generate curated GitHub Copilot agents, instructions, prompts, and skills.", - "version": "1.0.0" + "version": "1.1.0" }, { "name": "azure", diff --git a/docs/README.plugins.md b/docs/README.plugins.md index cca2d1b9..f7d76bdb 100644 --- a/docs/README.plugins.md +++ b/docs/README.plugins.md @@ -25,7 +25,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-plugins) for guidelines on how t | Name | Description | Items | Tags | | ---- | ----------- | ----- | ---- | -| [awesome-copilot](../plugins/awesome-copilot/README.md) | Meta prompts that help you discover and generate curated GitHub Copilot agents, instructions, prompts, and skills. | 5 items | github-copilot, discovery, meta, prompt-engineering, agents | +| [awesome-copilot](../plugins/awesome-copilot/README.md) | Meta prompts that help you discover and generate curated GitHub Copilot agents, instructions, prompts, and skills. | 4 items | github-copilot, discovery, meta, prompt-engineering, agents | | [azure-cloud-development](../plugins/azure-cloud-development/README.md) | Comprehensive Azure cloud development tools including Infrastructure as Code, serverless functions, architecture patterns, and cost optimization for building scalable cloud applications. | 11 items | azure, cloud, infrastructure, bicep, terraform, serverless, architecture, devops | | [cast-imaging](../plugins/cast-imaging/README.md) | A comprehensive collection of specialized agents for software analysis, impact assessment, structural quality advisories, and architectural review using CAST Imaging. | 3 items | cast-imaging, software-analysis, architecture, quality, impact-analysis, devops | | [clojure-interactive-programming](../plugins/clojure-interactive-programming/README.md) | Tools for REPL-first Clojure workflows featuring Clojure instructions, the interactive programming chat mode and supporting guidance. | 2 items | clojure, repl, interactive-programming | diff --git a/docs/README.skills.md b/docs/README.skills.md index 3ac73000..57c42161 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -209,7 +209,6 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [structured-autonomy-plan](../skills/structured-autonomy-plan/SKILL.md) | Structured Autonomy Planning Prompt | None | | [suggest-awesome-github-copilot-agents](../skills/suggest-awesome-github-copilot-agents/SKILL.md) | Suggest relevant GitHub Copilot Custom Agents files from the awesome-copilot repository based on current repository context and chat history, avoiding duplicates with existing custom agents in this repository, and identifying outdated agents that need updates. | None | | [suggest-awesome-github-copilot-instructions](../skills/suggest-awesome-github-copilot-instructions/SKILL.md) | Suggest relevant GitHub Copilot instruction files from the awesome-copilot repository based on current repository context and chat history, avoiding duplicates with existing instructions in this repository, and identifying outdated instructions that need updates. | None | -| [suggest-awesome-github-copilot-prompts](../skills/suggest-awesome-github-copilot-prompts/SKILL.md) | Suggest relevant GitHub Copilot prompt files from the awesome-copilot repository based on current repository context and chat history, avoiding duplicates with existing prompts in this repository, and identifying outdated prompts that need updates. | None | | [suggest-awesome-github-copilot-skills](../skills/suggest-awesome-github-copilot-skills/SKILL.md) | Suggest relevant GitHub Copilot skills from the awesome-copilot repository based on current repository context and chat history, avoiding duplicates with existing skills in this repository, and identifying outdated skills that need updates. | None | | [swift-mcp-server-generator](../skills/swift-mcp-server-generator/SKILL.md) | Generate a complete Model Context Protocol server project in Swift using the official MCP Swift SDK package. | None | | [technology-stack-blueprint-generator](../skills/technology-stack-blueprint-generator/SKILL.md) | Comprehensive technology stack blueprint generator that analyzes codebases to create detailed architectural documentation. Automatically detects technology stacks, programming languages, and implementation patterns across multiple platforms (.NET, Java, JavaScript, React, Python). Generates configurable blueprints with version information, licensing details, usage patterns, coding conventions, and visual diagrams. Provides implementation-ready templates and maintains architectural consistency for guided development. | None | diff --git a/plugins/awesome-copilot/.github/plugin/plugin.json b/plugins/awesome-copilot/.github/plugin/plugin.json index 94f73969..3ebd4b48 100644 --- a/plugins/awesome-copilot/.github/plugin/plugin.json +++ b/plugins/awesome-copilot/.github/plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "awesome-copilot", "description": "Meta prompts that help you discover and generate curated GitHub Copilot agents, instructions, prompts, and skills.", - "version": "1.0.0", + "version": "1.1.0", "author": { "name": "Awesome Copilot Community" }, @@ -20,7 +20,6 @@ "skills": [ "./skills/suggest-awesome-github-copilot-skills/", "./skills/suggest-awesome-github-copilot-instructions/", - "./skills/suggest-awesome-github-copilot-prompts/", "./skills/suggest-awesome-github-copilot-agents/" ] } diff --git a/plugins/awesome-copilot/README.md b/plugins/awesome-copilot/README.md index a61c7043..421e98f1 100644 --- a/plugins/awesome-copilot/README.md +++ b/plugins/awesome-copilot/README.md @@ -17,7 +17,6 @@ copilot plugin install awesome-copilot@awesome-copilot |---------|-------------| | `/awesome-copilot:suggest-awesome-github-copilot-collections` | Suggest relevant GitHub Copilot collections from the awesome-copilot repository based on current repository context and chat history, providing automatic download and installation of collection assets, and identifying outdated collection assets that need updates. | | `/awesome-copilot:suggest-awesome-github-copilot-instructions` | Suggest relevant GitHub Copilot instruction files from the awesome-copilot repository based on current repository context and chat history, avoiding duplicates with existing instructions in this repository, and identifying outdated instructions that need updates. | -| `/awesome-copilot:suggest-awesome-github-copilot-prompts` | Suggest relevant GitHub Copilot prompt files from the awesome-copilot repository based on current repository context and chat history, avoiding duplicates with existing prompts in this repository, and identifying outdated prompts that need updates. | | `/awesome-copilot:suggest-awesome-github-copilot-agents` | Suggest relevant GitHub Copilot Custom Agents files from the awesome-copilot repository based on current repository context and chat history, avoiding duplicates with existing custom agents in this repository, and identifying outdated agents that need updates. | | `/awesome-copilot:suggest-awesome-github-copilot-skills` | Suggest relevant GitHub Copilot skills from the awesome-copilot repository based on current repository context and chat history, avoiding duplicates with existing skills in this repository, and identifying outdated skills that need updates. | diff --git a/skills/suggest-awesome-github-copilot-prompts/SKILL.md b/skills/suggest-awesome-github-copilot-prompts/SKILL.md deleted file mode 100644 index efe487c8..00000000 --- a/skills/suggest-awesome-github-copilot-prompts/SKILL.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -name: suggest-awesome-github-copilot-prompts -description: 'Suggest relevant GitHub Copilot prompt files from the awesome-copilot repository based on current repository context and chat history, avoiding duplicates with existing prompts in this repository, and identifying outdated prompts that need updates.' ---- - -# Suggest Awesome GitHub Copilot Prompts - -Analyze current repository context and suggest relevant prompt files from the [GitHub awesome-copilot repository](https://github.com/github/awesome-copilot/blob/main/docs/README.prompts.md) that are not already available in this repository. - -## Process - -1. **Fetch Available Prompts**: Extract prompt list and descriptions from [awesome-copilot README.prompts.md](https://github.com/github/awesome-copilot/blob/main/docs/README.prompts.md). Must use `#fetch` tool. -2. **Scan Local Prompts**: Discover existing prompt files in `.github/prompts/` folder -3. **Extract Descriptions**: Read front matter from local prompt files to get descriptions -4. **Fetch Remote Versions**: For each local prompt, fetch the corresponding version from awesome-copilot repository using raw GitHub URLs (e.g., `https://raw.githubusercontent.com/github/awesome-copilot/main/prompts/`) -5. **Compare Versions**: Compare local prompt content with remote versions to identify: - - Prompts that are up-to-date (exact match) - - Prompts that are outdated (content differs) - - Key differences in outdated prompts (tools, description, content) -6. **Analyze Context**: Review chat history, repository files, and current project needs -7. **Compare Existing**: Check against prompts already available in this repository -8. **Match Relevance**: Compare available prompts against identified patterns and requirements -9. **Present Options**: Display relevant prompts with descriptions, rationale, and availability status including outdated prompts -10. **Validate**: Ensure suggested prompts would add value not already covered by existing prompts -11. **Output**: Provide structured table with suggestions, descriptions, and links to both awesome-copilot prompts and similar local prompts - **AWAIT** user request to proceed with installation or updates of specific prompts. DO NOT INSTALL OR UPDATE UNLESS DIRECTED TO DO SO. -12. **Download/Update Assets**: For requested prompts, automatically: - - Download new prompts to `.github/prompts/` folder - - Update outdated prompts by replacing with latest version from awesome-copilot - - Do NOT adjust content of the files - - Use `#fetch` tool to download assets, but may use `curl` using `#runInTerminal` tool to ensure all content is retrieved - - Use `#todos` tool to track progress - -## Context Analysis Criteria - -🔍 **Repository Patterns**: -- Programming languages used (.cs, .js, .py, etc.) -- Framework indicators (ASP.NET, React, Azure, etc.) -- Project types (web apps, APIs, libraries, tools) -- Documentation needs (README, specs, ADRs) - -🗨️ **Chat History Context**: -- Recent discussions and pain points -- Feature requests or implementation needs -- Code review patterns -- Development workflow requirements - -## Output Format - -Display analysis results in structured table comparing awesome-copilot prompts with existing repository prompts: - -| Awesome-Copilot Prompt | Description | Already Installed | Similar Local Prompt | Suggestion Rationale | -|-------------------------|-------------|-------------------|---------------------|---------------------| -| [code-review.prompt.md](https://github.com/github/awesome-copilot/blob/main/prompts/code-review.prompt.md) | Automated code review prompts | ❌ No | None | Would enhance development workflow with standardized code review processes | -| [documentation.prompt.md](https://github.com/github/awesome-copilot/blob/main/prompts/documentation.prompt.md) | Generate project documentation | ✅ Yes | create_oo_component_documentation.prompt.md | Already covered by existing documentation prompts | -| [debugging.prompt.md](https://github.com/github/awesome-copilot/blob/main/prompts/debugging.prompt.md) | Debug assistance prompts | ⚠️ Outdated | debugging.prompt.md | Tools configuration differs: remote uses `'codebase'` vs local missing - Update recommended | - -## Local Prompts Discovery Process - -1. List all `*.prompt.md` files in `.github/prompts/` directory -2. For each discovered file, read front matter to extract `description` -3. Build comprehensive inventory of existing prompts -4. Use this inventory to avoid suggesting duplicates - -## Version Comparison Process - -1. For each local prompt file, construct the raw GitHub URL to fetch the remote version: - - Pattern: `https://raw.githubusercontent.com/github/awesome-copilot/main/prompts/` -2. Fetch the remote version using the `#fetch` tool -3. Compare entire file content (including front matter and body) -4. Identify specific differences: - - **Front matter changes** (description, tools, mode) - - **Tools array modifications** (added, removed, or renamed tools) - - **Content updates** (instructions, examples, guidelines) -5. Document key differences for outdated prompts -6. Calculate similarity to determine if update is needed - -## Requirements - -- Use `githubRepo` tool to get content from awesome-copilot repository prompts folder -- Scan local file system for existing prompts in `.github/prompts/` directory -- Read YAML front matter from local prompt files to extract descriptions -- Compare local prompts with remote versions to detect outdated prompts -- Compare against existing prompts in this repository to avoid duplicates -- Focus on gaps in current prompt library coverage -- Validate that suggested prompts align with repository's purpose and standards -- Provide clear rationale for each suggestion -- Include links to both awesome-copilot prompts and similar local prompts -- Clearly identify outdated prompts with specific differences noted -- Don't provide any additional information or context beyond the table and the analysis - - -## Icons Reference - -- ✅ Already installed and up-to-date -- ⚠️ Installed but outdated (update available) -- ❌ Not installed in repo - -## Update Handling - -When outdated prompts are identified: -1. Include them in the output table with ⚠️ status -2. Document specific differences in the "Suggestion Rationale" column -3. Provide recommendation to update with key changes noted -4. When user requests update, replace entire local file with remote version -5. Preserve file location in `.github/prompts/` directory From 5bed97868a60bc4dadff1119fbd44fd071153c6f Mon Sep 17 00:00:00 2001 From: Dan Velton <48307985+dvelton@users.noreply.github.com> Date: Sun, 8 Mar 2026 20:46:32 -0700 Subject: [PATCH 15/37] Add automate-this plugin: screen recording to automation scripts (#930) * Add automate-this plugin: screen recording to automation scripts New plugin that analyzes screen recordings of manual processes and proposes working automation scripts at multiple complexity tiers. Features: - Frame extraction via ffmpeg for visual process reconstruction - Optional audio transcription via Whisper for narrated recordings - Environment fingerprinting to constrain proposals to installed tools - Application-specific automation strategies (browser, spreadsheet, email, terminal, file management, macOS-native) - Three-tier proposal system (quick win, full script, scheduled automation) - Dry-run support for safe testing of all proposals Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Update skills/automate-this/SKILL.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Address code review feedback on automate-this plugin - Fix privacy section: clarify that frames/audio are processed locally but sent to the Copilot model for analysis (not purely local) - Replace 'which' with 'command -v' for reliable tool detection with explicit NO_FFMPEG/NO_WHISPER sentinels - Use per-run secure temp directory (mktemp -d, mode 0700) instead of fixed /tmp/ paths to prevent other users reading extracted frames - Add -y flag and -loglevel warning to ffmpeg calls to prevent overwrite prompts and avoid piping hiding exit codes - Add whisper-cpp CLI invocation path so users who install only whisper-cpp get working transcription - Fix grouped command syntax in environment fingerprint to prevent false 'not installed' fallthrough Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .github/plugin/marketplace.json | 6 + docs/README.plugins.md | 1 + docs/README.skills.md | 1 + .../automate-this/.github/plugin/plugin.json | 23 ++ plugins/automate-this/README.md | 87 +++++++ skills/automate-this/SKILL.md | 244 ++++++++++++++++++ 6 files changed, 362 insertions(+) create mode 100644 plugins/automate-this/.github/plugin/plugin.json create mode 100644 plugins/automate-this/README.md create mode 100644 skills/automate-this/SKILL.md diff --git a/.github/plugin/marketplace.json b/.github/plugin/marketplace.json index ec42b570..e6be3ec4 100644 --- a/.github/plugin/marketplace.json +++ b/.github/plugin/marketplace.json @@ -10,6 +10,12 @@ "email": "copilot@github.com" }, "plugins": [ + { + "name": "automate-this", + "source": "automate-this", + "description": "Record your screen doing a manual process, drop the video on your Desktop, and let Copilot CLI analyze it frame-by-frame to build working automation scripts. Supports narrated recordings with audio transcription.", + "version": "1.0.0" + }, { "name": "awesome-copilot", "source": "awesome-copilot", diff --git a/docs/README.plugins.md b/docs/README.plugins.md index f7d76bdb..a520b04e 100644 --- a/docs/README.plugins.md +++ b/docs/README.plugins.md @@ -25,6 +25,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-plugins) for guidelines on how t | Name | Description | Items | Tags | | ---- | ----------- | ----- | ---- | +| [automate-this](../plugins/automate-this/README.md) | Record your screen doing a manual process, drop the video on your Desktop, and let Copilot CLI analyze it frame-by-frame to build working automation scripts. Supports narrated recordings with audio transcription. | 1 items | automation, screen-recording, workflow, video-analysis, process-automation, scripting, productivity, copilot-cli | | [awesome-copilot](../plugins/awesome-copilot/README.md) | Meta prompts that help you discover and generate curated GitHub Copilot agents, instructions, prompts, and skills. | 4 items | github-copilot, discovery, meta, prompt-engineering, agents | | [azure-cloud-development](../plugins/azure-cloud-development/README.md) | Comprehensive Azure cloud development tools including Infrastructure as Code, serverless functions, architecture patterns, and cost optimization for building scalable cloud applications. | 11 items | azure, cloud, infrastructure, bicep, terraform, serverless, architecture, devops | | [cast-imaging](../plugins/cast-imaging/README.md) | A comprehensive collection of specialized agents for software analysis, impact assessment, structural quality advisories, and architectural review using CAST Imaging. | 3 items | cast-imaging, software-analysis, architecture, quality, impact-analysis, devops | diff --git a/docs/README.skills.md b/docs/README.skills.md index 57c42161..9bb32167 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -36,6 +36,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [architecture-blueprint-generator](../skills/architecture-blueprint-generator/SKILL.md) | Comprehensive project architecture blueprint generator that analyzes codebases to create detailed architectural documentation. Automatically detects technology stacks and architectural patterns, generates visual diagrams, documents implementation patterns, and provides extensible blueprints for maintaining architectural consistency and guiding new development. | None | | [aspire](../skills/aspire/SKILL.md) | Aspire skill covering the Aspire CLI, AppHost orchestration, service discovery, integrations, MCP server, VS Code extension, Dev Containers, GitHub Codespaces, templates, dashboard, and deployment. Use when the user asks to create, run, debug, configure, deploy, or troubleshoot an Aspire distributed application. | `references/architecture.md`
`references/cli-reference.md`
`references/dashboard.md`
`references/deployment.md`
`references/integrations-catalog.md`
`references/mcp-server.md`
`references/polyglot-apis.md`
`references/testing.md`
`references/troubleshooting.md` | | [aspnet-minimal-api-openapi](../skills/aspnet-minimal-api-openapi/SKILL.md) | Create ASP.NET Minimal API endpoints with proper OpenAPI documentation | None | +| [automate-this](../skills/automate-this/SKILL.md) | Analyze a screen recording of a manual process and produce targeted, working automation scripts. Extracts frames and audio narration from video files, reconstructs the step-by-step workflow, and proposes automation at multiple complexity levels using tools already installed on the user machine. | None | | [az-cost-optimize](../skills/az-cost-optimize/SKILL.md) | Analyze Azure resources used in the app (IaC files and/or resources in a target rg) and optimize costs - creating GitHub issues for identified optimizations. | None | | [azure-deployment-preflight](../skills/azure-deployment-preflight/SKILL.md) | Performs comprehensive preflight validation of Bicep deployments to Azure, including template syntax validation, what-if analysis, and permission checks. Use this skill before any deployment to Azure to preview changes, identify potential issues, and ensure the deployment will succeed. Activate when users mention deploying to Azure, validating Bicep files, checking deployment permissions, previewing infrastructure changes, running what-if, or preparing for azd provision. | `references/ERROR-HANDLING.md`
`references/REPORT-TEMPLATE.md`
`references/VALIDATION-COMMANDS.md` | | [azure-devops-cli](../skills/azure-devops-cli/SKILL.md) | Manage Azure DevOps resources via CLI including projects, repos, pipelines, builds, pull requests, work items, artifacts, and service endpoints. Use when working with Azure DevOps, az commands, devops automation, CI/CD, or when user mentions Azure DevOps CLI. | `references/advanced-usage.md`
`references/boards-and-iterations.md`
`references/org-and-security.md`
`references/pipelines-and-builds.md`
`references/repos-and-prs.md`
`references/variables-and-agents.md`
`references/workflows-and-patterns.md` | diff --git a/plugins/automate-this/.github/plugin/plugin.json b/plugins/automate-this/.github/plugin/plugin.json new file mode 100644 index 00000000..0824ae3d --- /dev/null +++ b/plugins/automate-this/.github/plugin/plugin.json @@ -0,0 +1,23 @@ +{ + "name": "automate-this", + "description": "Record your screen doing a manual process, drop the video on your Desktop, and let Copilot CLI analyze it frame-by-frame to build working automation scripts. Supports narrated recordings with audio transcription.", + "version": "1.0.0", + "author": { + "name": "Awesome Copilot Community" + }, + "repository": "https://github.com/github/awesome-copilot", + "license": "MIT", + "keywords": [ + "automation", + "screen-recording", + "workflow", + "video-analysis", + "process-automation", + "scripting", + "productivity", + "copilot-cli" + ], + "skills": [ + "./skills/automate-this/" + ] +} diff --git a/plugins/automate-this/README.md b/plugins/automate-this/README.md new file mode 100644 index 00000000..bbeb81cd --- /dev/null +++ b/plugins/automate-this/README.md @@ -0,0 +1,87 @@ +# Automate This + +You know that thing you do every week — the fifteen-click, four-app, copy-paste-into-spreadsheet-and-email-it process that makes you want to throw your laptop into the ocean? Record yourself doing it once, hand the video to Copilot CLI, and let it write the script that does it for you. + +## How It Works + +1. **Record your screen.** Use QuickTime, OBS, Loom, or whatever you already have. Do the process exactly the way you normally do. If you want to talk through it while you record ("now I'm downloading this report because finance needs it every Monday"), even better — the plugin transcribes your narration and uses it to understand *why* you're doing each step, not just *what* you're clicking. + +2. **Drop the recording on your Desktop** (or anywhere — it just needs a file path). + +3. **Tell Copilot CLI to analyze it:** + ``` + copilot + > /skills + > (select automate-this) + > Analyze ~/Desktop/weekly-report-process.mov and automate it + ``` + +4. **Review what it found.** The plugin extracts frames from your video every couple of seconds, transcribes any narration, and reconstructs your process as a numbered step list. It asks you to confirm it got it right before proposing anything. + +5. **Pick your automation level.** You'll get up to three proposals ranging from "here's a one-liner that handles the worst part" to "here's a full script with scheduling and error handling." Each one uses tools you already have installed — no surprise dependency chains. + +## What Happens Under the Hood + +The plugin uses `ffmpeg` to pull frames and audio from your recording. If you narrated, it uses OpenAI's Whisper (running locally on your machine, not in the cloud) to transcribe what you said. The frames go to the AI model, which can read text on screen, identify applications, see what you're clicking, and follow the flow of your process. + +Before proposing automation, the plugin checks your environment — what's installed, what shell you use, what scripting languages are available — so it only suggests things you can actually run without spending an hour on setup. + +## Prerequisites + +- **ffmpeg** (required) — for extracting frames and audio from your recording + ```bash + brew install ffmpeg + ``` + +- **Whisper** (optional) — only needed if your recording has narration + ```bash + pip install openai-whisper + ``` + Or the C++ version: `brew install whisper-cpp` + +If Whisper isn't installed and your recording has audio, the plugin will let you know and offer to proceed with visual-only analysis. + +## Installation + +```bash +copilot plugin install automate-this@awesome-copilot +``` + +## What Gets Analyzed Well + +The plugin works best when your recording clearly shows what you're doing. Some examples of processes people automate with this: + +- **Report generation** — downloading data from a dashboard, filtering it, formatting it, sending it to someone +- **File organization** — sorting downloads into folders, renaming files by date, cleaning up duplicates +- **Data entry** — copying information from one app and entering it into another +- **Dev environment setup** — the sequence of commands and config changes you run every time you start a new project +- **Repetitive terminal workflows** — running the same sequence of commands with different inputs +- **Email-based workflows** — pulling data from emails, processing it, replying with results + +## What Stays Manual + +The plugin proposes automation for mechanical steps. It preserves human judgment — if your recording shows you pausing to review something or making a decision based on what you see, that step stays manual in the automation with a prompt for your input. + +## Example + +Say you record yourself doing a weekly task: you open a browser, navigate to an internal dashboard, download three CSV exports, open each in Excel, filter for rows marked "pending," combine them into one sheet, and email it to your manager. + +The plugin would reconstruct that process, confirm it with you, and propose something like: + +- **Tier 1:** A `curl` command that downloads all three CSVs in one shot (if the dashboard has direct download URLs), skipping the browser entirely. +- **Tier 2:** A Python script that downloads the CSVs, filters for "pending" rows using pandas, merges them, and saves the result — ready to attach to an email. +- **Tier 3:** The same script, plus it sends the email automatically via your mail client and runs every Monday at 8am via `launchd`. + +Each tier includes the working code, instructions to test it with a dry run, and how to undo anything if it goes sideways. + +## Privacy + +Frame extraction (ffmpeg) and audio transcription (Whisper) run entirely on your machine. Extracted frames and audio are written to a secure temporary directory and deleted when analysis is complete. The extracted frames and transcript are sent to the AI model powering your Copilot CLI session for analysis — this is the same model and data pipeline used by all Copilot interactions. No data is sent to additional third-party services beyond what Copilot already uses. + +## Source + +This plugin is part of [Awesome Copilot](https://github.com/github/awesome-copilot), a community-driven collection of GitHub Copilot extensions. + +## License + +MIT diff --git a/skills/automate-this/SKILL.md b/skills/automate-this/SKILL.md new file mode 100644 index 00000000..3d0cac53 --- /dev/null +++ b/skills/automate-this/SKILL.md @@ -0,0 +1,244 @@ +--- +name: automate-this +description: 'Analyze a screen recording of a manual process and produce targeted, working automation scripts. Extracts frames and audio narration from video files, reconstructs the step-by-step workflow, and proposes automation at multiple complexity levels using tools already installed on the user machine.' +--- + +# Automate This + +Analyze a screen recording of a manual process and build working automation for it. + +The user records themselves doing something repetitive or tedious, hands you the video file, and you figure out what they're doing, why, and how to script it away. + +## Prerequisites Check + +Before analyzing any recording, verify the required tools are available. Run these checks silently and only surface problems: + +```bash +command -v ffmpeg >/dev/null 2>&1 && ffmpeg -version 2>/dev/null | head -1 || echo "NO_FFMPEG" +command -v whisper >/dev/null 2>&1 || command -v whisper-cpp >/dev/null 2>&1 || echo "NO_WHISPER" +``` + +- **ffmpeg is required.** If missing, tell the user: `brew install ffmpeg` (macOS) or the equivalent for their OS. +- **Whisper is optional.** Only needed if the recording has narration. If missing AND the recording has an audio track, suggest: `pip install openai-whisper` or `brew install whisper-cpp`. If the user declines, proceed with visual analysis only. + +## Phase 1: Extract Content from the Recording + +Given a video file path (typically on `~/Desktop/`), extract both visual frames and audio: + +### Frame Extraction + +Extract frames at one frame every 2 seconds. This balances coverage with context window limits. + +```bash +WORK_DIR=$(mktemp -d "${TMPDIR:-/tmp}/automate-this-XXXXXX") +chmod 700 "$WORK_DIR" +mkdir -p "$WORK_DIR/frames" +ffmpeg -y -i "" -vf "fps=0.5" -q:v 2 -loglevel warning "$WORK_DIR/frames/frame_%04d.jpg" +ls "$WORK_DIR/frames/" | wc -l +``` + +Use `$WORK_DIR` for all subsequent temp file paths in the session. The per-run directory with mode 0700 ensures extracted frames are only readable by the current user. + +If the recording is longer than 5 minutes (more than 150 frames), increase the interval to one frame every 4 seconds to stay within context limits. Tell the user you're sampling less frequently for longer recordings. + +### Audio Extraction and Transcription + +Check if the video has an audio track: + +```bash +ffprobe -i "" -show_streams -select_streams a -loglevel error | head -5 +``` + +If audio exists: + +```bash +ffmpeg -y -i "" -ac 1 -ar 16000 -loglevel warning "$WORK_DIR/audio.wav" + +# Use whichever whisper binary is available +if command -v whisper >/dev/null 2>&1; then + whisper "$WORK_DIR/audio.wav" --model small --language en --output_format txt --output_dir "$WORK_DIR/" + cat "$WORK_DIR/audio.txt" +elif command -v whisper-cpp >/dev/null 2>&1; then + whisper-cpp -m "$(brew --prefix 2>/dev/null)/share/whisper-cpp/models/ggml-small.bin" -l en -f "$WORK_DIR/audio.wav" -otxt -of "$WORK_DIR/audio" + cat "$WORK_DIR/audio.txt" +else + echo "NO_WHISPER" +fi +``` + +If neither whisper binary is available and the recording has audio, inform the user they're missing narration context and ask if they want to install Whisper (`pip install openai-whisper` or `brew install whisper-cpp`) or proceed with visual-only analysis. + +## Phase 2: Reconstruct the Process + +Analyze the extracted frames (and transcript, if available) to build a structured understanding of what the user did. Work through the frames sequentially and identify: + +1. **Applications used** — Which apps appear in the recording? (browser, terminal, Finder, mail client, spreadsheet, IDE, etc.) +2. **Sequence of actions** — What did the user do, in order? Click-by-click, step-by-step. +3. **Data flow** — What information moved between steps? (copied text, downloaded files, form inputs, etc.) +4. **Decision points** — Were there moments where the user paused, checked something, or made a choice? +5. **Repetition patterns** — Did the user do the same thing multiple times with different inputs? +6. **Pain points** — Where did the process look slow, error-prone, or tedious? The narration often reveals this directly ("I hate this part," "this always takes forever," "I have to do this for every single one"). + +Present this reconstruction to the user as a numbered step list and ask them to confirm it's accurate before proposing automation. This is critical — a wrong understanding leads to useless automation. + +Format: + +``` +Here's what I see you doing in this recording: + +1. Open Chrome and navigate to [specific URL] +2. Log in with credentials +3. Click through to the reporting dashboard +4. Download a CSV export +5. Open the CSV in Excel +6. Filter rows where column B is "pending" +7. Copy those rows into a new spreadsheet +8. Email the new spreadsheet to [recipient] + +You repeated steps 3-8 three times for different report types. + +[If narration was present]: You mentioned that the export step is the slowest +part and that you do this every Monday morning. + +Does this match what you were doing? Anything I got wrong or missed? +``` + +Do NOT proceed to Phase 3 until the user confirms the reconstruction is accurate. + +## Phase 3: Environment Fingerprint + +Before proposing automation, understand what the user actually has to work with. Run these checks: + +```bash +echo "=== OS ===" && uname -a +echo "=== Shell ===" && echo $SHELL +echo "=== Python ===" && { command -v python3 && python3 --version 2>&1; } || echo "not installed" +echo "=== Node ===" && { command -v node && node --version 2>&1; } || echo "not installed" +echo "=== Homebrew ===" && { command -v brew && echo "installed"; } || echo "not installed" +echo "=== Common Tools ===" && for cmd in curl jq playwright selenium osascript automator crontab; do command -v $cmd >/dev/null 2>&1 && echo "$cmd: yes" || echo "$cmd: no"; done +``` + +Use this to constrain proposals to tools the user already has. Never propose automation that requires installing five new things unless the simpler path genuinely doesn't work. + +## Phase 4: Propose Automation + +Based on the reconstructed process and the user's environment, propose automation at up to three tiers. Not every process needs three tiers — use judgment. + +### Tier Structure + +**Tier 1 — Quick Win (under 5 minutes to set up)** +The smallest useful automation. A shell alias, a one-liner, a keyboard shortcut, an AppleScript snippet. Automates the single most painful step, not the whole process. + +**Tier 2 — Script (under 30 minutes to set up)** +A standalone script (bash, Python, or Node — whichever the user has) that automates the full process end-to-end. Handles common errors. Can be run manually when needed. + +**Tier 3 — Full Automation (under 2 hours to set up)** +The script from Tier 2, plus: scheduled execution (cron, launchd, or GitHub Actions), logging, error notifications, and any necessary integration scaffolding (API keys, auth tokens, etc.). + +### Proposal Format + +For each tier, provide: + +``` +## Tier [N]: [Name] + +**What it automates:** [Which steps from the reconstruction] +**What stays manual:** [Which steps still need a human] +**Time savings:** [Estimated time saved per run, based on the recording length and repetition count] +**Prerequisites:** [Anything needed that isn't already installed — ideally nothing] + +**How it works:** +[2-3 sentence plain-English explanation] + +**The code:** +[Complete, working, commented code — not pseudocode] + +**How to test it:** +[Exact steps to verify it works, starting with a dry run if possible] + +**How to undo:** +[How to reverse any changes if something goes wrong] +``` + +### Application-Specific Automation Strategies + +Use these strategies based on which applications appear in the recording: + +**Browser-based workflows:** +- First choice: Check if the website has a public API. API calls are 10x more reliable than browser automation. Search for API documentation. +- Second choice: `curl` or `wget` for simple HTTP requests with known endpoints. +- Third choice: Playwright or Selenium for workflows that require clicking through UI. Prefer Playwright — it's faster and less flaky. +- Look for patterns: if the user is downloading the same report from a dashboard repeatedly, it's almost certainly available via API or direct URL with query parameters. + +**Spreadsheet and data workflows:** +- Python with pandas for data filtering, transformation, and aggregation. +- If the user is doing simple column operations in Excel, a 5-line Python script replaces the entire manual process. +- `csvkit` for quick command-line CSV manipulation without writing code. +- If the output needs to stay in Excel format, use openpyxl. + +**Email workflows:** +- macOS: `osascript` can control Mail.app to send emails with attachments. +- Cross-platform: Python `smtplib` for sending, `imaplib` for reading. +- If the email follows a template, generate the body from a template file with variable substitution. + +**File management workflows:** +- Shell scripts for move/copy/rename patterns. +- `find` + `xargs` for batch operations. +- `fswatch` or `watchman` for triggered-on-change automation. +- If the user is organizing files into folders by date or type, that's a 3-line shell script. + +**Terminal/CLI workflows:** +- Shell aliases for frequently typed commands. +- Shell functions for multi-step sequences. +- Makefiles for project-specific task sets. +- If the user ran the same command with different arguments, that's a loop. + +**macOS-specific workflows:** +- AppleScript/JXA for controlling native apps (Mail, Calendar, Finder, Preview, etc.). +- Shortcuts.app for simple multi-app workflows that don't need code. +- `automator` for file-based workflows. +- `launchd` plist files for scheduled tasks (prefer over cron on macOS). + +**Cross-application workflows (data moves between apps):** +- Identify the data transfer points. Each transfer is an automation opportunity. +- Clipboard-based transfers in the recording suggest the apps don't talk to each other — look for APIs, file-based handoffs, or direct integrations instead. +- If the user copies from App A and pastes into App B, the automation should read from A's data source and write to B's input format directly. + +### Making Proposals Targeted + +Apply these principles to every proposal: + +1. **Automate the bottleneck first.** The narration and timing in the recording reveal which step is actually painful. A 30-second automation of the worst step beats a 2-hour automation of the whole process. + +2. **Match the user's skill level.** If the recording shows someone comfortable in a terminal, propose shell scripts. If it shows someone navigating GUIs, propose something with a simple trigger (double-click a script, run a Shortcut, or type one command). + +3. **Estimate real time savings.** Count the recording duration and multiply by how often they do it. "This recording is 4 minutes. You said you do this daily. That's 17 hours per year. Tier 1 cuts it to 30 seconds each time — you get 16 hours back." + +4. **Handle the 80% case.** The first version of the automation should cover the common path perfectly. Edge cases can be handled in Tier 3 or flagged for manual intervention. + +5. **Preserve human checkpoints.** If the recording shows the user reviewing or approving something mid-process, keep that as a manual step. Don't automate judgment calls. + +6. **Propose dry runs.** Every script should have a mode where it shows what it *would* do without doing it. `--dry-run` flags, preview output, or confirmation prompts before destructive actions. + +7. **Account for auth and secrets.** If the process involves logging in or using credentials, never hardcode them. Use environment variables, keychain access (macOS `security` command), or prompt for them at runtime. + +8. **Consider failure modes.** What happens if the website is down? If the file doesn't exist? If the format changes? Good proposals mention this and handle it. + +## Phase 5: Build and Test + +When the user picks a tier: + +1. Write the complete automation code to a file (suggest a sensible location — the user's project directory if one exists, or `~/Desktop/` otherwise). +2. Walk through a dry run or test with the user watching. +3. If the test works, show how to run it for real. +4. If it fails, diagnose and fix — don't give up after one attempt. + +## Cleanup + +After analysis is complete (regardless of outcome), clean up extracted frames and audio: + +```bash +rm -rf "$WORK_DIR" +``` + +Tell the user you're cleaning up temporary files so they know nothing is left behind. From cf2a5470a22fe14ff51128d456ba04e87cc302e7 Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Mon, 9 Mar 2026 14:47:20 +1100 Subject: [PATCH 16/37] feat: add contributors page to website (#928) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Initial plan * feat: add contributors page to website Co-authored-by: aaronpowell <434140+aaronpowell@users.noreply.github.com> * feat: add footer with contributors link and fix emoji-only display - Add custom Starlight Footer component with 'Made with ❤️ by our amazing contributors' linking to /contributors/ - Filter out contribution types without emoji mappings in the contributor data generation so only emojis (🎭🎁🧭⌨️🧰) are shown on the contributors page, not text labels like 'code' or 'doc' Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * feat: use all-contributors HTML output for contributors page - Restyle all-contributors generated table as a responsive card grid using CSS grid on tbody with card-styled td cells - Remove old custom JS search/filter UI and contributors.ts script - Remove generateContributorsData from data pipeline (no longer needed) - Keep all-contributors markers for bot regeneration - Include updated contributor data from .all-contributorsrc Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix: CSS fixes for contributors page Starlight compatibility - Override Starlight table width/overflow to prevent clipping - Force td width: 100% to counteract HTML width="14.28%" attribute - Set emoji links to display: inline to prevent vertical stacking - Improve border visibility with lighter gray color Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: aaronpowell <434140+aaronpowell@users.noreply.github.com> Co-authored-by: Aaron Powell Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .all-contributorsrc | 5 +- README.md | 82 ++--- eng/generate-website-data.mjs | 7 + website/astro.config.mjs | 2 + website/src/components/Footer.astro | 30 ++ website/src/pages/contributors.astro | 458 +++++++++++++++++++++++++++ 6 files changed, 542 insertions(+), 42 deletions(-) create mode 100644 website/src/components/Footer.astro create mode 100644 website/src/pages/contributors.astro diff --git a/.all-contributorsrc b/.all-contributorsrc index 84f421f3..5f8f1607 100644 --- a/.all-contributorsrc +++ b/.all-contributorsrc @@ -4,8 +4,11 @@ "repoType": "github", "repoHost": "https://github.com", "files": [ - "README.md" + "README.md", + "website/src/pages/contributors.astro" ], + "contributorTemplate": "\">\" width=\"<%= options.imageSize %>px;\" alt=\"\"/>
<%= contributor.name %>", + "imageSize": 100, "commit": false, "commitConvention": "none", diff --git a/README.md b/README.md index 9c374261..cc63b867 100644 --- a/README.md +++ b/README.md @@ -178,41 +178,41 @@ Thanks goes to these wonderful people ([emoji key](./CONTRIBUTING.md#contributor Harald Kirschner
Harald Kirschner
💻 📖 🚧 Muhammad Ubaid Raza
Muhammad Ubaid Raza
🎭 🧭 Tom Meschter
Tom Meschter
💻 - Aung Myo Kyaw
Aung Myo Kyaw
🎭 + Aung Myo Kyaw
Aung Myo Kyaw
🎭 ⌨️ JasonYeMSFT
JasonYeMSFT
💻 - Jon Corbin
Jon Corbin
🎭 + Jon Corbin
Jon Corbin
🎭 ⌨️ troytaylor-msft
troytaylor-msft
💻 Emerson Delatorre
Emerson Delatorre
🧭 - Burke Holland
Burke Holland
🎭 🚇 🧭 - Kent Yao
Kent Yao
🧭 - Daniel Meppiel
Daniel Meppiel
+ Burke Holland
Burke Holland
🎭 🚇 🧭 ⌨️ + Kent Yao
Kent Yao
🧭 ⌨️ + Daniel Meppiel
Daniel Meppiel
⌨️ Gordon Lam
Gordon Lam
🧭 Mads Kristensen
Mads Kristensen
🧭 Shinji Takenaka
Shinji Takenaka
💻 spectatora
spectatora
🎭 💻 🚧 - Yohan Lasorsa
Yohan Lasorsa
🧭 - Vamshi Verma
Vamshi Verma
🧭 - James Montemagno
James Montemagno
🎭 📖 🧭 + Yohan Lasorsa
Yohan Lasorsa
🧭 ⌨️ + Vamshi Verma
Vamshi Verma
🧭 ⌨️ + James Montemagno
James Montemagno
🎭 📖 🧭 ⌨️ Alessandro Fragnani
Alessandro Fragnani
💻 Ambily
Ambily
🎭 🧭 - krushideep
krushideep
+ krushideep
krushideep
⌨️ devopsfan
devopsfan
🎭 - Tugdual Grall
Tugdual Grall
🧭 + Tugdual Grall
Tugdual Grall
🧭 ⌨️ Oren Me
Oren Me
🎭 🧭 - Mike Rousos
Mike Rousos
🧭 + Mike Rousos
Mike Rousos
🧭 ⌨️ Justin Yoo
Justin Yoo
🧭 Guilherme do Amaral Alves
Guilherme do Amaral Alves
🧭 Griffin Ashe
Griffin Ashe
🎭 🎁 Ashley Childress
Ashley Childress
🎭 📖 🧭 🚇 💻 - Adrien Clerbois
Adrien Clerbois
🎭 📖 + Adrien Clerbois
Adrien Clerbois
🎭 📖 ⌨️ ANGELELLI David
ANGELELLI David
🎭 Mark Davis
Mark Davis
🧭 Matt Vevang
Matt Vevang
🧭 @@ -220,12 +220,12 @@ Thanks goes to these wonderful people ([emoji key](./CONTRIBUTING.md#contributor NULLchimp
NULLchimp
🎭 - Peter Karda
Peter Karda
- Saul Dolgin
Saul Dolgin
🎭 🧭 - Shubham Gaikwad
Shubham Gaikwad
🎭 🧭 + Peter Karda
Peter Karda
⌨️ + Saul Dolgin
Saul Dolgin
🎭 🧭 ⌨️ + Shubham Gaikwad
Shubham Gaikwad
🎭 🧭 ⌨️ Theo van Kraay
Theo van Kraay
🧭 Tianqi Zhang
Tianqi Zhang
🎭 - Will 保哥
Will 保哥
🎭 + Will 保哥
Will 保哥
🎭 ⌨️ Yuta Matsumura
Yuta Matsumura
🧭 @@ -247,11 +247,11 @@ Thanks goes to these wonderful people ([emoji key](./CONTRIBUTING.md#contributor Dan Wahlin
Dan Wahlin
🎭 - Debbie O'Brien
Debbie O'Brien
🎭 🧭 - Ed Harrod
Ed Harrod
- Genevieve Warren
Genevieve Warren
- Guillaume
Guillaume
🎭 - Henrique Nunes
Henrique Nunes
+ Debbie O'Brien
Debbie O'Brien
🎭 🧭 ⌨️ + Ed Harrod
Ed Harrod
⌨️ + Genevieve Warren
Genevieve Warren
⌨️ + Guillaume
Guillaume
🎭 ⌨️ + Henrique Nunes
Henrique Nunes
⌨️ Jeremiah Snee
Jeremiah Snee
💻 @@ -269,7 +269,7 @@ Thanks goes to these wonderful people ([emoji key](./CONTRIBUTING.md#contributor Salih
Salih
🧭 Sebastian Gräf
Sebastian Gräf
🎭 🧭 Sebastien DEGODEZ
Sebastien DEGODEZ
🧭 - Sergiy Smyrnov
Sergiy Smyrnov
+ Sergiy Smyrnov
Sergiy Smyrnov
⌨️ SomeSolutionsArchitect
SomeSolutionsArchitect
🎭 @@ -277,9 +277,9 @@ Thanks goes to these wonderful people ([emoji key](./CONTRIBUTING.md#contributor Søren Trudsø Mahon
Søren Trudsø Mahon
🧭 Tj Vita
Tj Vita
🎭 Peli de Halleux
Peli de Halleux
💻 - Paulo Morgado
Paulo Morgado
+ Paulo Morgado
Paulo Morgado
⌨️ Paul Crane
Paul Crane
🎭 - Pamela Fox
Pamela Fox
+ Pamela Fox
Pamela Fox
⌨️ Oskar Thornblad
Oskar Thornblad
🧭 @@ -293,10 +293,10 @@ Thanks goes to these wonderful people ([emoji key](./CONTRIBUTING.md#contributor Máté Barabás
Máté Barabás
🧭 Mike Parker
Mike Parker
🧭 - Mike Kistler
Mike Kistler
+ Mike Kistler
Mike Kistler
⌨️ Giovanni de Almeida Martins
Giovanni de Almeida Martins
🧭 이상현
이상현
🧭 - Ankur Sharma
Ankur Sharma
+ Ankur Sharma
Ankur Sharma
⌨️ Wendy Breiding
Wendy Breiding
💻 @@ -304,7 +304,7 @@ Thanks goes to these wonderful people ([emoji key](./CONTRIBUTING.md#contributor shane lee
shane lee
🧭 sdanzo-hrb
sdanzo-hrb
🎭 sauran
sauran
🧭 - samqbush
samqbush
+ samqbush
samqbush
⌨️ pareenaverma
pareenaverma
🎭 oleksiyyurchyna
oleksiyyurchyna
🎁 ⌨️ @@ -315,7 +315,7 @@ Thanks goes to these wonderful people ([emoji key](./CONTRIBUTING.md#contributor factory-davidgu
factory-davidgu
💻 dangelov-qa
dangelov-qa
🎭 BenoitMaucotel
BenoitMaucotel
💻 - benjisho-aidome
benjisho-aidome
🎭 🧭 + benjisho-aidome
benjisho-aidome
🎭 🧭 ⌨️ Yuki Omoto
Yuki Omoto
🧭 @@ -328,26 +328,26 @@ Thanks goes to these wonderful people ([emoji key](./CONTRIBUTING.md#contributor Udaya Veeramreddygari
Udaya Veeramreddygari
🧭 - Tài Lê
Tài Lê
+ Tài Lê
Tài Lê
⌨️ Tsubasa Ogawa
Tsubasa Ogawa
💻 Troy Witthoeft (glsauto)
Troy Witthoeft (glsauto)
🧭 Gerald Versluis
Gerald Versluis
🧭 - George Dernikos
George Dernikos
+ George Dernikos
George Dernikos
⌨️ Gautam
Gautam
🎭 Furkan Enes
Furkan Enes
🧭 Florian Mücke
Florian Mücke
🎭 Felix Arjuna
Felix Arjuna
🧭 - Eldrick Wega
Eldrick Wega
- Dobri Danchev
Dobri Danchev
- Diego Gamboa
Diego Gamboa
- Derek Clair
Derek Clair
🎭 + Eldrick Wega
Eldrick Wega
⌨️ + Dobri Danchev
Dobri Danchev
⌨️ + Diego Gamboa
Diego Gamboa
⌨️ + Derek Clair
Derek Clair
🎭 ⌨️ David Ortinau
David Ortinau
💻 Daniel Abbatt
Daniel Abbatt
🧭 - CypherHK
CypherHK
🎭 + CypherHK
CypherHK
🎭 ⌨️ Craig Bekker
Craig Bekker
💻 Christophe Peugnet
Christophe Peugnet
🧭 Christian Lechner
Christian Lechner
🧭 @@ -355,7 +355,7 @@ Thanks goes to these wonderful people ([emoji key](./CONTRIBUTING.md#contributor Artem Saveliev
Artem Saveliev
🧭 - Antoine Rey
Antoine Rey
+ Antoine Rey
Antoine Rey
⌨️ Ankit Das
Ankit Das
🧭 Aline Ávila
Aline Ávila
🧭 Alexander Martinkevich
Alexander Martinkevich
🎭 @@ -369,7 +369,7 @@ Thanks goes to these wonderful people ([emoji key](./CONTRIBUTING.md#contributor 4regab
4regab
🧭 Miguel P Z
Miguel P Z
📖 Michael Fairchild
Michael Fairchild
🧭 - Michael A. Volz (Flynn)
Michael A. Volz (Flynn)
+ Michael A. Volz (Flynn)
Michael A. Volz (Flynn)
⌨️ Michael
Michael
🧭 @@ -386,24 +386,24 @@ Thanks goes to these wonderful people ([emoji key](./CONTRIBUTING.md#contributor Kenny White
Kenny White
🧭 KaloyanGenev
KaloyanGenev
🎭 Kim Skov Rasmussen
Kim Skov Rasmussen
💻 - Julien Dubois
Julien Dubois
+ Julien Dubois
Julien Dubois
⌨️ José Antonio Garrido
José Antonio Garrido
🧭 - Joseph Gonzales
Joseph Gonzales
🧭 + Joseph Gonzales
Joseph Gonzales
🧭 ⌨️ Jorge Balderas
Jorge Balderas
🧭 John Papa
John Papa
💻 John
John
🎭 Joe Watkins
Joe Watkins
🧭 Jan de Vries
Jan de Vries
🎭 - Jakub Jareš
Jakub Jareš
+ Jakub Jareš
Jakub Jareš
⌨️ Jackson Miller
Jackson Miller
🧭 Ioana A
Ioana A
🧭 Hunter Hogan
Hunter Hogan
🎭 Hashim Warren
Hashim Warren
🎭 - Gonzalo
Gonzalo
+ Gonzalo
Gonzalo
⌨️ Gisela Torres
Gisela Torres
🎭 Shibi Ramachandran
Shibi Ramachandran
💻 diff --git a/eng/generate-website-data.mjs b/eng/generate-website-data.mjs index 79b28a1f..b4d3e13f 100644 --- a/eng/generate-website-data.mjs +++ b/eng/generate-website-data.mjs @@ -900,6 +900,12 @@ async function main() { `✓ Generated ${samplesData.totalRecipes} recipes in ${samplesData.totalCookbooks} cookbooks (${samplesData.filters.languages.length} languages, ${samplesData.filters.tags.length} tags)` ); + // Count contributors from .all-contributorsrc for manifest stats + const contributorsRcPath = path.join(ROOT_FOLDER, ".all-contributorsrc"); + const contributorCount = fs.existsSync(contributorsRcPath) + ? (JSON.parse(fs.readFileSync(contributorsRcPath, "utf-8")).contributors || []).length + : 0; + const searchIndex = generateSearchIndex( agents, instructions, @@ -967,6 +973,7 @@ async function main() { workflows: workflows.length, plugins: plugins.length, tools: tools.length, + contributors: contributorCount, samples: samplesData.totalRecipes, total: searchIndex.length, }, diff --git a/website/astro.config.mjs b/website/astro.config.mjs index e6e3866f..663a7d32 100644 --- a/website/astro.config.mjs +++ b/website/astro.config.mjs @@ -35,6 +35,7 @@ export default defineConfig({ { label: "Workflows", link: "/workflows/" }, { label: "Plugins", link: "/plugins/" }, { label: "Tools", link: "/tools/" }, + { label: "Contributors", link: "/contributors/" }, ], }, { @@ -75,6 +76,7 @@ export default defineConfig({ tableOfContents: { minHeadingLevel: 2, maxHeadingLevel: 3 }, components: { Head: "./src/components/Head.astro", + Footer: "./src/components/Footer.astro", }, }), sitemap(), diff --git a/website/src/components/Footer.astro b/website/src/components/Footer.astro new file mode 100644 index 00000000..b46600a6 --- /dev/null +++ b/website/src/components/Footer.astro @@ -0,0 +1,30 @@ +--- +import type { Props } from '@astrojs/starlight/props'; +import Default from '@astrojs/starlight/components/Footer.astro'; +--- + + + +
+

Made with ❤️ by our amazing contributors

+
+ + diff --git a/website/src/pages/contributors.astro b/website/src/pages/contributors.astro new file mode 100644 index 00000000..38b13b47 --- /dev/null +++ b/website/src/pages/contributors.astro @@ -0,0 +1,458 @@ +--- +import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro'; +import PageHeader from '../components/PageHeader.astro'; +--- + + +
+ + +
+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Aaron Powell
Aaron Powell
🎭 💻 🎁 📖 🚇 🧭 🚧 ⌨️		Matt Soucoup
Matt Soucoup
🚇		Troy Simeon Taylor
Troy Simeon Taylor
🎭 🎁 🧭 ⌨️		Abbas
Abbas
🎭 🧭		Peter Strömberg
Peter Strömberg
🎭 🎁 🧭 ⌨️		Daniel Scott-Raynsford
Daniel Scott-Raynsford
🎭 🎁 🧭 ⌨️		John Haugabook
John Haugabook
🧭 ⌨️
Pavel Simsa
Pavel Simsa
💻		Harald Kirschner
Harald Kirschner
💻 📖 🚧		Muhammad Ubaid Raza
Muhammad Ubaid Raza
🎭 🧭		Tom Meschter
Tom Meschter
💻		Aung Myo Kyaw
Aung Myo Kyaw
🎭 ⌨️		JasonYeMSFT
JasonYeMSFT
💻		Jon Corbin
Jon Corbin
🎭 ⌨️
troytaylor-msft
troytaylor-msft
💻		Emerson Delatorre
Emerson Delatorre
🧭		Burke Holland
Burke Holland
🎭 🚇 🧭 ⌨️		Kent Yao
Kent Yao
🧭 ⌨️		Daniel Meppiel
Daniel Meppiel
⌨️		Gordon Lam
Gordon Lam
🧭		Mads Kristensen
Mads Kristensen
🧭
Shinji Takenaka
Shinji Takenaka
💻		spectatora
spectatora
🎭 💻 🚧		Yohan Lasorsa
Yohan Lasorsa
🧭 ⌨️		Vamshi Verma
Vamshi Verma
🧭 ⌨️		James Montemagno
James Montemagno
🎭 📖 🧭 ⌨️		Alessandro Fragnani
Alessandro Fragnani
💻		Ambily
Ambily
🎭 🧭
krushideep
krushideep
⌨️		devopsfan
devopsfan
🎭		Tugdual Grall
Tugdual Grall
🧭 ⌨️		Oren Me
Oren Me
🎭 🧭		Mike Rousos
Mike Rousos
🧭 ⌨️		Justin Yoo
Justin Yoo
🧭		Guilherme do Amaral Alves
Guilherme do Amaral Alves
🧭
Griffin Ashe
Griffin Ashe
🎭 🎁		Ashley Childress
Ashley Childress
🎭 📖 🧭 🚇 💻		Adrien Clerbois
Adrien Clerbois
🎭 📖 ⌨️		ANGELELLI David
ANGELELLI David
🎭		Mark Davis
Mark Davis
🧭		Matt Vevang
Matt Vevang
🧭		Maximilian Irro
Maximilian Irro
🧭
NULLchimp
NULLchimp
🎭		Peter Karda
Peter Karda
⌨️		Saul Dolgin
Saul Dolgin
🎭 🧭 ⌨️		Shubham Gaikwad
Shubham Gaikwad
🎭 🧭 ⌨️		Theo van Kraay
Theo van Kraay
🧭		Tianqi Zhang
Tianqi Zhang
🎭		Will 保哥
Will 保哥
🎭 ⌨️
Yuta Matsumura
Yuta Matsumura
🧭		anschnapp
anschnapp
🎭		hizahizi-hizumi
hizahizi-hizumi
🧭		黃健旻 Vincent Huang
黃健旻 Vincent Huang
⌨️		Bruno Borges
Bruno Borges
🎁 🧭		Steve Magne
Steve Magne
📖 🧭		Shane Neuville
Shane Neuville
🎭 🧭
André Silva
André Silva
🎭 🧭		Allen Greaves
Allen Greaves
🎭 🧭		Amelia Payne
Amelia Payne
🎭		BBoyBen
BBoyBen
🧭		Brooke Hamilton
Brooke Hamilton
🧭		Christopher Harrison
Christopher Harrison
🧭		Dan
Dan
🧭
Dan Wahlin
Dan Wahlin
🎭		Debbie O'Brien
Debbie O'Brien
🎭 🧭 ⌨️		Ed Harrod
Ed Harrod
⌨️		Genevieve Warren
Genevieve Warren
⌨️		Guillaume
Guillaume
🎭 ⌨️		Henrique Nunes
Henrique Nunes
⌨️		Jeremiah Snee
Jeremiah Snee
💻
Kartik Dhiman
Kartik Dhiman
🧭		Kristiyan Velkov
Kristiyan Velkov
🎭		msalaman
msalaman
💻		Per Søderlind
Per Søderlind
🧭		Peter Smulovics
Peter Smulovics
🧭		Ravish Rathod
Ravish Rathod
🧭		Rick Smit
Rick Smit
🎭
Rob Simpson
Rob Simpson
🧭		Robert Altman
Robert Altman
🧭		Salih
Salih
🧭		Sebastian Gräf
Sebastian Gräf
🎭 🧭		Sebastien DEGODEZ
Sebastien DEGODEZ
🧭		Sergiy Smyrnov
Sergiy Smyrnov
⌨️		SomeSolutionsArchitect
SomeSolutionsArchitect
🎭
Stu Mace
Stu Mace
🎭 🎁 🧭		Søren Trudsø Mahon
Søren Trudsø Mahon
🧭		Tj Vita
Tj Vita
🎭		Peli de Halleux
Peli de Halleux
💻		Paulo Morgado
Paulo Morgado
⌨️		Paul Crane
Paul Crane
🎭		Pamela Fox
Pamela Fox
⌨️
Oskar Thornblad
Oskar Thornblad
🧭		Nischay Sharma
Nischay Sharma
🎭		Nikolay Marinov
Nikolay Marinov
🎭		Nik Sachdeva
Nik Sachdeva
🎭 🎁		Nick Taylor
Nick Taylor
💻		Nick Brady
Nick Brady
🎭		Nathan Stanford Sr
Nathan Stanford Sr
🧭
Máté Barabás
Máté Barabás
🧭		Mike Parker
Mike Parker
🧭		Mike Kistler
Mike Kistler
⌨️		Giovanni de Almeida Martins
Giovanni de Almeida Martins
🧭		이상현
이상현
🧭		Ankur Sharma
Ankur Sharma
⌨️		Wendy Breiding
Wendy Breiding
💻
voidfnc
voidfnc
🎭		shane lee
shane lee
🧭		sdanzo-hrb
sdanzo-hrb
🎭		sauran
sauran
🧭		samqbush
samqbush
⌨️		pareenaverma
pareenaverma
🎭		oleksiyyurchyna
oleksiyyurchyna
🎁 ⌨️
oceans-of-time
oceans-of-time
🧭		kshashank57
kshashank57
🎭 🧭		Meii
Meii
🎭		factory-davidgu
factory-davidgu
💻		dangelov-qa
dangelov-qa
🎭		BenoitMaucotel
BenoitMaucotel
💻		benjisho-aidome
benjisho-aidome
🎭 🧭 ⌨️
Yuki Omoto
Yuki Omoto
🧭		Will Schultz
Will Schultz
🎭		Waren Gonzaga
Waren Gonzaga
🎭		Vincent Koc
Vincent Koc
🎭		Victor Williams
Victor Williams
🎭		Ve Sharma
Ve Sharma
🎭		Vasileios Lahanas
Vasileios Lahanas
🧭
Udaya Veeramreddygari
Udaya Veeramreddygari
🧭		Tài Lê
Tài Lê
⌨️		Tsubasa Ogawa
Tsubasa Ogawa
💻		Troy Witthoeft (glsauto)
Troy Witthoeft (glsauto)
🧭		Gerald Versluis
Gerald Versluis
🧭		George Dernikos
George Dernikos
⌨️		Gautam
Gautam
🎭
Furkan Enes
Furkan Enes
🧭		Florian Mücke
Florian Mücke
🎭		Felix Arjuna
Felix Arjuna
🧭		Eldrick Wega
Eldrick Wega
⌨️		Dobri Danchev
Dobri Danchev
⌨️		Diego Gamboa
Diego Gamboa
⌨️		Derek Clair
Derek Clair
🎭 ⌨️
David Ortinau
David Ortinau
💻		Daniel Abbatt
Daniel Abbatt
🧭		CypherHK
CypherHK
🎭 ⌨️		Craig Bekker
Craig Bekker
💻		Christophe Peugnet
Christophe Peugnet
🧭		Christian Lechner
Christian Lechner
🧭		Chris Harris
Chris Harris
🎭
Artem Saveliev
Artem Saveliev
🧭		Antoine Rey
Antoine Rey
⌨️		Ankit Das
Ankit Das
🧭		Aline Ávila
Aline Ávila
🧭		Alexander Martinkevich
Alexander Martinkevich
🎭		Aleksandar Dunchev
Aleksandar Dunchev
🎭		Alan Sprecacenere
Alan Sprecacenere
🧭
Akash Kumar Shaw
Akash Kumar Shaw
🧭		Abdi Daud
Abdi Daud
🎭		AIAlchemyForge
AIAlchemyForge
🧭		4regab
4regab
🧭		Miguel P Z
Miguel P Z
📖		Michael Fairchild
Michael Fairchild
🧭		Michael A. Volz (Flynn)
Michael A. Volz (Flynn)
⌨️
Michael
Michael
🧭		Mehmet Ali EROL
Mehmet Ali EROL
🎭		Max Prilutskiy
Max Prilutskiy
🎭		Matteo Bianchi
Matteo Bianchi
🎭		Mark Noble
Mark Noble
🎭		Manish Jayaswal
Manish Jayaswal
🎭		Luke Murray
Luke Murray
🎭
Louella Creemers
Louella Creemers
🧭		Sai Koumudi Kaluvakolanu
Sai Koumudi Kaluvakolanu
🎭		Kenny White
Kenny White
🧭		KaloyanGenev
KaloyanGenev
🎭		Kim Skov Rasmussen
Kim Skov Rasmussen
💻		Julien Dubois
Julien Dubois
⌨️		José Antonio Garrido
José Antonio Garrido
🧭
Joseph Gonzales
Joseph Gonzales
🧭 ⌨️		Jorge Balderas
Jorge Balderas
🧭		John Papa
John Papa
💻		John
John
🎭		Joe Watkins
Joe Watkins
🧭		Jan de Vries
Jan de Vries
🎭		Jakub Jareš
Jakub Jareš
⌨️
Jackson Miller
Jackson Miller
🧭		Ioana A
Ioana A
🧭		Hunter Hogan
Hunter Hogan
🎭		Hashim Warren
Hashim Warren
🎭		Gonzalo
Gonzalo
⌨️		Gisela Torres
Gisela Torres
🎭		Shibi Ramachandran
Shibi Ramachandran
💻
lupritz
lupritz
🔌		Héctor Benedicte
Héctor Benedicte
💻
+ + Add your contributions + +
+ + + + + +
+
+
+
+ + + + From 169e4f9c9eea5283620b5796c41447e0ea30e3d4 Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Mon, 9 Mar 2026 15:47:42 +1100 Subject: [PATCH 17/37] [WIP] Update comment in PR #930 (#932) * Initial plan * Update CODEOWNERS for PR #930 - add automate-this ownership to @dvelton Co-authored-by: aaronpowell <434140+aaronpowell@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: aaronpowell <434140+aaronpowell@users.noreply.github.com> --- CODEOWNERS | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CODEOWNERS b/CODEOWNERS index 263d34c5..d48721cf 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -4,3 +4,7 @@ # Agentic Workflows /workflows/ @brunoborges /.github/workflows/validate-agentic-workflows-pr.yml @brunoborges + +# Added via #codeowner from PR #930 +/plugins/automate-this/ @dvelton +/skills/automate-this/ @dvelton From febaf64d94d4a56c5485579780dd0b73fcaf3cbd Mon Sep 17 00:00:00 2001 From: Gregg Cochran <158339470+DUBSOpenHub@users.noreply.github.com> Date: Sun, 8 Mar 2026 21:49:23 -0700 Subject: [PATCH 18/37] =?UTF-8?q?feat:=20add=20cli-mastery=20skill=20?= =?UTF-8?q?=E2=80=94=20interactive=20Copilot=20CLI=20training=20(#915)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat: add cli-mastery skill — interactive Copilot CLI training Adds cli-mastery, an interactive training system for the GitHub Copilot CLI. 8 modules covering slash commands, keyboard shortcuts, modes, agents, skills, MCP, configuration, and advanced techniques. Includes scenario challenges, a final exam, XP/leveling system, and SQL-based progress tracking. Source: https://github.com/DUBSOpenHub/copilot-cli-mastery (MIT) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix: address review feedback on frontmatter and consistency - Switch description from folded block scalar (>) to single-quoted string per AGENTS.md documented format - Fix Module 7 heading: backtick-wrap @ separately from 'file mentions' to avoid implying '@ file mentions' is a literal command - Fix Final Exam Q6: change '@ + filename' to '@filename' with example to match the @src/auth.ts syntax taught in modules - Fix Final Exam Q7: add GEMINI.md to match Module 7 precedence list Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix: rename curriculum/ to references/ per agentskills.io spec Addresses review feedback from @aaronpowell on PR #915. The Agent Skills specification defines references/ as the standard directory for supplementary documentation that agents read on demand. - Renamed skills/cli-mastery/curriculum/ → references/ - Updated all path references in SKILL.md - Updated asset paths in docs/README.skills.md Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: DUBSOpenHub Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/README.skills.md | 1 + skills/cli-mastery/SKILL.md | 43 +++++++++ skills/cli-mastery/references/final-exam.md | 24 +++++ .../references/module-1-slash-commands.md | 88 +++++++++++++++++++ .../references/module-2-keyboard-shortcuts.md | 38 ++++++++ .../cli-mastery/references/module-3-modes.md | 33 +++++++ .../cli-mastery/references/module-4-agents.md | 42 +++++++++ .../cli-mastery/references/module-5-skills.md | 33 +++++++ skills/cli-mastery/references/module-6-mcp.md | 50 +++++++++++ .../references/module-7-advanced.md | 38 ++++++++ .../references/module-8-configuration.md | 34 +++++++ skills/cli-mastery/references/scenarios.md | 44 ++++++++++ 12 files changed, 468 insertions(+) create mode 100644 skills/cli-mastery/SKILL.md create mode 100644 skills/cli-mastery/references/final-exam.md create mode 100644 skills/cli-mastery/references/module-1-slash-commands.md create mode 100644 skills/cli-mastery/references/module-2-keyboard-shortcuts.md create mode 100644 skills/cli-mastery/references/module-3-modes.md create mode 100644 skills/cli-mastery/references/module-4-agents.md create mode 100644 skills/cli-mastery/references/module-5-skills.md create mode 100644 skills/cli-mastery/references/module-6-mcp.md create mode 100644 skills/cli-mastery/references/module-7-advanced.md create mode 100644 skills/cli-mastery/references/module-8-configuration.md create mode 100644 skills/cli-mastery/references/scenarios.md diff --git a/docs/README.skills.md b/docs/README.skills.md index 9bb32167..51455a69 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -55,6 +55,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [breakdown-test](../skills/breakdown-test/SKILL.md) | Test Planning and Quality Assurance prompt that generates comprehensive test strategies, task breakdowns, and quality validation plans for GitHub projects. | None | | [centos-linux-triage](../skills/centos-linux-triage/SKILL.md) | Triage and resolve CentOS issues using RHEL-compatible tooling, SELinux-aware practices, and firewalld. | None | | [chrome-devtools](../skills/chrome-devtools/SKILL.md) | Expert-level browser automation, debugging, and performance analysis using Chrome DevTools MCP. Use for interacting with web pages, capturing screenshots, analyzing network traffic, and profiling performance. | None | +| [cli-mastery](../skills/cli-mastery/SKILL.md) | Interactive training for the GitHub Copilot CLI. Guided lessons, quizzes, scenario challenges, and a full reference covering slash commands, shortcuts, modes, agents, skills, MCP, and configuration. Say "cliexpert" to start. | `references/final-exam.md`
`references/module-1-slash-commands.md`
`references/module-2-keyboard-shortcuts.md`
`references/module-3-modes.md`
`references/module-4-agents.md`
`references/module-5-skills.md`
`references/module-6-mcp.md`
`references/module-7-advanced.md`
`references/module-8-configuration.md`
`references/scenarios.md` | | [code-exemplars-blueprint-generator](../skills/code-exemplars-blueprint-generator/SKILL.md) | Technology-agnostic prompt generator that creates customizable AI prompts for scanning codebases and identifying high-quality code exemplars. Supports multiple programming languages (.NET, Java, JavaScript, TypeScript, React, Angular, Python) with configurable analysis depth, categorization methods, and documentation formats to establish coding standards and maintain consistency across development teams. | None | | [comment-code-generate-a-tutorial](../skills/comment-code-generate-a-tutorial/SKILL.md) | Transform this Python script into a polished, beginner-friendly project by refactoring the code, adding clear instructional comments, and generating a complete markdown tutorial. | None | | [containerize-aspnet-framework](../skills/containerize-aspnet-framework/SKILL.md) | Containerize an ASP.NET .NET Framework project by creating Dockerfile and .dockerfile files customized for the project. | None | diff --git a/skills/cli-mastery/SKILL.md b/skills/cli-mastery/SKILL.md new file mode 100644 index 00000000..5a6efc72 --- /dev/null +++ b/skills/cli-mastery/SKILL.md @@ -0,0 +1,43 @@ +--- +name: cli-mastery +description: 'Interactive training for the GitHub Copilot CLI. Guided lessons, quizzes, scenario challenges, and a full reference covering slash commands, shortcuts, modes, agents, skills, MCP, and configuration. Say "cliexpert" to start.' +metadata: + version: 1.2.0 +license: MIT +--- + +# Copilot CLI Mastery + +**UTILITY SKILL** — interactive Copilot CLI trainer. +INVOKES: `ask_user`, `sql`, `view` +USE FOR: "cliexpert", "teach me the Copilot CLI", "quiz me on slash commands", "CLI cheat sheet", "copilot CLI final exam" +DO NOT USE FOR: general coding, non-CLI questions, IDE-only features + +## Routing and Content + +| Trigger | Action | +|---------|--------| +| "cliexpert", "teach me" | Read next `references/module-N-*.md`, teach | +| "quiz me", "test me" | Read current module, 5+ questions via `ask_user` | +| "scenario", "challenge" | Read `references/scenarios.md` | +| "reference" | Read relevant module, summarize | +| "final exam" | Read `references/final-exam.md` | + +Specific CLI questions get direct answers without loading references. +Reference files in `references/` dir. Read on demand with `view`. + +## Behavior + +On first interaction, initialize progress tracking: +```sql +CREATE TABLE IF NOT EXISTS mastery_progress (key TEXT PRIMARY KEY, value TEXT); +CREATE TABLE IF NOT EXISTS mastery_completed (module TEXT PRIMARY KEY, completed_at TEXT DEFAULT (datetime('now'))); +INSERT OR IGNORE INTO mastery_progress (key,value) VALUES ('xp','0'),('level','Newcomer'),('module','0'); +``` +XP: lesson +20, correct +15, perfect quiz +50, scenario +30. +Levels: 0=Newcomer 100=Apprentice 250=Navigator 400=Practitioner 550=Specialist 700=Expert 850=Virtuoso 1000=Architect 1150=Grandmaster 1500=Wizard. +Max XP from all content: 1600 (8 modules × 145 + 8 scenarios × 30 + final exam 200). + +When module counter exceeds 8 and user says "cliexpert", offer: scenarios, final exam, or review any module. + +Rules: `ask_user` with `choices` for ALL quizzes/scenarios. Show XP after correct answers. One concept at a time; offer quiz or review after each lesson. diff --git a/skills/cli-mastery/references/final-exam.md b/skills/cli-mastery/references/final-exam.md new file mode 100644 index 00000000..1a9f470f --- /dev/null +++ b/skills/cli-mastery/references/final-exam.md @@ -0,0 +1,24 @@ +# Final Exam + +Present a 10-question comprehensive exam using `ask_user` with 4 choices each. Require 80%+ to pass. Vary the selection each time. + +## Question Bank + +1. Which command initializes Copilot CLI in a new project? → `/init` +2. What shortcut cycles through modes? → `Shift+Tab` +3. Where are repo-level custom agents stored? → `.github/agents/*.md` +4. What does MCP stand for? → Model Context Protocol +5. Which agent is safe to run in parallel? → `explore` +6. How do you add a file to AI context? → `@filename` (e.g. `@src/auth.ts`) +7. What file has the highest instruction precedence? → `CLAUDE.md` / `GEMINI.md` / `AGENTS.md` (git root + cwd) +8. Which command compresses conversation history? → `/compact` +9. Where is MCP configured at project level? → `.github/mcp-config.json` +10. What does `--yolo` do? → Same as `--allow-all` (skip all confirmations) +11. What does `/research` do? → Run a deep research investigation with sources +12. Which shortcut opens input in $EDITOR? → `Ctrl+G` +13. What does `/reset-allowed-tools` do? → Re-enables confirmation prompts +14. Which command copies the last AI response to your clipboard? → `/copy` +15. What does `/compact` do? → Summarizes conversation to free context + +On pass (80%+): Award "CLI Wizard" title, congratulate enthusiastically! +On fail: Show which they got wrong, encourage retry. diff --git a/skills/cli-mastery/references/module-1-slash-commands.md b/skills/cli-mastery/references/module-1-slash-commands.md new file mode 100644 index 00000000..38b546d5 --- /dev/null +++ b/skills/cli-mastery/references/module-1-slash-commands.md @@ -0,0 +1,88 @@ +# Module 1: Slash Commands + +Teach these categories one at a time, with examples and "when to use" guidance. + +## Getting Started + +| Command | What it does | When to use | +|---------|-------------|-------------| +| `/login` | Authenticate with GitHub | First launch or expired session | +| `/logout` | Sign out | Switching accounts | +| `/help` | Show all commands | When lost | +| `/exit` `/quit` | Exit CLI | Done working | +| `/init` | Bootstrap copilot-instructions.md | New repo setup | +| `/terminal-setup` | Configure multiline input | First-time setup | + +## Models & Agents + +| Command | What it does | When to use | +|---------|-------------|-------------| +| `/model` | Switch AI model | Need different capability/speed | +| `/agent` | Browse/select agents | Delegate to specialist | +| `/fleet` | Enable parallel subagents | Complex multi-part tasks | +| `/tasks` | View background tasks | Check on running subagents | + +## Code & Review + +| Command | What it does | When to use | +|---------|-------------|-------------| +| `/diff` | Review changes in current dir | Before committing | +| `/review` | Run code review agent | Get feedback on changes | +| `/lsp` | Manage language servers | Need go-to-def, diagnostics | +| `/ide` | Connect to IDE workspace | Want IDE integration | + +## Session & Context + +| Command | What it does | When to use | +|---------|-------------|-------------| +| `/context` | Show token usage visualization | Context getting large | +| `/usage` | Display session metrics | Check premium request count | +| `/compact` | Compress conversation history | Near context limit | +| `/session` | Show session info | Need session details | +| `/resume` | Switch to different session | Continue previous work | +| `/rename` | Rename current session | Better organization | +| `/share` | Export session to markdown/gist | Share with team | +| `/copy` | Copy last response to clipboard | Grab AI output quickly | +| `/clear` | Clear conversation history | Fresh start | + +## Permissions & Directories + +| Command | What it does | When to use | +|---------|-------------|-------------| +| `/allow-all` | Enable all permissions | Trusted environment, move fast | +| `/add-dir` | Add trusted directory | Working across projects | +| `/list-dirs` | Show allowed directories | Check access scope | +| `/cwd` | Change working directory | Switch project context | +| `/reset-allowed-tools` | Revoke tool approvals | Tighten security | + +## Configuration & Customization + +| Command | What it does | When to use | +|---------|-------------|-------------| +| `/instructions` | View active instruction files | Debug custom behavior | +| `/experimental` | Toggle experimental features | Try autopilot mode | +| `/theme` | Change terminal theme | Personalize | +| `/streamer-mode` | Hide sensitive info | Livestreaming/demos | +| `/changelog` | Show release notes | After update | +| `/update` | Update CLI | New version available | +| `/feedback` | Submit feedback | Report bug or request | + +## Extensibility + +| Command | What it does | When to use | +|---------|-------------|-------------| +| `/skills` | Manage skills | Browse/enable capabilities | +| `/mcp` | Manage MCP servers | Add external tools | +| `/plugin` | Manage plugins | Extend functionality | + +## Workflows & Research + +| Command | What it does | When to use | +|---------|-------------|-------------| +| `/plan` | Create implementation plan | Before complex changes | +| `/research` | Run deep research investigation | Need thorough analysis with sources | +| `/user` | Manage GitHub user list | Team context | + +## Quiz (5+ questions, use ask_user with 4 choices each) + +Ask "Which command would you use to [scenario]?" style questions. diff --git a/skills/cli-mastery/references/module-2-keyboard-shortcuts.md b/skills/cli-mastery/references/module-2-keyboard-shortcuts.md new file mode 100644 index 00000000..173232b5 --- /dev/null +++ b/skills/cli-mastery/references/module-2-keyboard-shortcuts.md @@ -0,0 +1,38 @@ +# Module 2: Keyboard Shortcuts + +## Navigation & Editing + +| Shortcut | Action | +|----------|--------| +| `@` | Mention files — include their contents as context | +| `Ctrl+S` | Submit prompt while preserving input text | +| `Shift+Tab` | Cycle modes: Interactive → Plan | +| `Ctrl+T` | Toggle model reasoning display | +| `Ctrl+O` | Expand recent timeline (when no input) | +| `Ctrl+E` | Expand all timeline (when no input) / move to end of line (when typing) | +| `↑` `↓` | Navigate command history | +| `!` | Execute shell command directly (bypass AI) | +| `Esc` | Cancel current operation | +| `Ctrl+C` | Cancel operation / clear input / exit | +| `Ctrl+D` | Shutdown session | +| `Ctrl+L` | Clear the screen | +| `Ctrl+G` | Edit prompt in external editor ($EDITOR) | + +## Line Editing + +| Shortcut | Action | +|----------|--------| +| `Ctrl+A` | Move to beginning of line | +| `Ctrl+H` | Delete previous character | +| `Ctrl+W` | Delete previous word | +| `Ctrl+U` | Delete from cursor to beginning of line | +| `Ctrl+K` | Delete from cursor to end of line | +| `Meta+←` `Meta+→` | Move cursor by word | + +## Pro tips to teach + +- `@` is THE most important shortcut — it's how you give precise context +- `!git status` runs git directly without AI processing +- `Shift+Tab` into Plan mode BEFORE complex tasks +- `Ctrl+G` opens your $EDITOR for long prompts — game changer +- `Ctrl+S` lets you iterate on a prompt without retyping diff --git a/skills/cli-mastery/references/module-3-modes.md b/skills/cli-mastery/references/module-3-modes.md new file mode 100644 index 00000000..93241f71 --- /dev/null +++ b/skills/cli-mastery/references/module-3-modes.md @@ -0,0 +1,33 @@ +# Module 3: Interaction Modes + +## Interactive Mode (default) + +- AI acts immediately on your prompts +- Asks permission for risky operations +- Best for: quick tasks, debugging, exploring code +- 80% of your time will be here + +## Plan Mode (`Shift+Tab` or `/plan`) + +- AI creates a step-by-step plan FIRST +- You review and approve before execution +- Best for: complex refactoring, architecture changes, risky operations +- Key insight: Use this when mistakes are expensive + +## Autopilot Mode (experimental, `/experimental`) + +- AI acts without asking for confirmation +- Best for: trusted environments, long-running tasks +- Use with caution — pair with `/allow-all` or `--yolo` + +## Mode Comparison + +| Feature | Interactive | Plan | Autopilot | +|---------|------------|------|-----------| +| Speed | Fast | Slower | Fastest | +| Safety | Medium | Highest | Lowest | +| Control | You approve each action | You approve the plan | Full AI autonomy | +| Best for | Daily tasks | Complex changes | Repetitive/trusted work | +| Switch | Default | Shift+Tab or /plan | /experimental (enables), then Shift+Tab | + +Teaching point: The right mode at the right time = 10x productivity. diff --git a/skills/cli-mastery/references/module-4-agents.md b/skills/cli-mastery/references/module-4-agents.md new file mode 100644 index 00000000..5c037cbb --- /dev/null +++ b/skills/cli-mastery/references/module-4-agents.md @@ -0,0 +1,42 @@ +# Module 4: Agent System + +## Built-in Agents + +| Agent | Model | Best For | Key Trait | +|-------|-------|----------|-----------| +| `explore` | Haiku | Fast codebase Q&A | Read-only, <300 words, safe to parallelize | +| `task` | Haiku | Running commands (tests, builds, lints) | Brief on success, verbose on failure | +| `general-purpose` | Sonnet | Complex multi-step tasks | Full toolset, separate context window | +| `code-review` | Sonnet | Analyzing code changes | Never modifies code, high signal-to-noise | + +## Custom Agents — define your own in Markdown + +| Level | Location | Scope | +|-------|----------|-------| +| Personal | `~/.copilot/agents/*.md` | All your projects | +| Project | `.github/agents/*.md` | Everyone on this repo | +| Organization | `.github-private/agents/` in org repo | Entire org | + +## Agent file anatomy + +```markdown +--- +name: my-agent +description: What this agent does +tools: + - bash + - edit + - view +--- + +# Agent Instructions +Your detailed behavior instructions here. +``` + +## Agent orchestration patterns + +1. **Fan-out exploration** — Launch multiple `explore` agents in parallel to answer different questions simultaneously +2. **Pipeline** — `explore` → understand → `general-purpose` → implement → `code-review` → verify +3. **Specialist handoff** — Identify task → `/agent` to pick specialist → review with `/fleet` or `/tasks` + +Key insight: The AI automatically delegates to subagents when appropriate. diff --git a/skills/cli-mastery/references/module-5-skills.md b/skills/cli-mastery/references/module-5-skills.md new file mode 100644 index 00000000..b9f920f0 --- /dev/null +++ b/skills/cli-mastery/references/module-5-skills.md @@ -0,0 +1,33 @@ +# Module 5: Skills System + +## What are skills? + +- Specialized capability packages the AI can invoke +- Think of them as "expert modes" with domain-specific knowledge +- Managed via `/skills` command + +## Skill locations + +| Level | Location | +|-------|----------| +| User | `~/.copilot/skills//SKILL.md` | +| Repo | `.github/skills//SKILL.md` | +| Org | Shared via org-level config | + +## Creating a custom skill + +1. Create the directory: `mkdir -p ~/.copilot/skills/my-skill/` +2. Create `SKILL.md` with YAML frontmatter (`name`, `description`, optional `tools`) +3. Write detailed instructions for the AI's behavior +4. Verify with `/skills` + +## Skill design best practices + +- **Clear description** — helps the AI match tasks to your skill automatically +- **Focused scope** — each skill should do ONE thing well +- **Include instructions** — specify exactly how the skill should operate +- **Test thoroughly** — use `/skills` to verify, then invoke and check results + +## Auto-matching + +When you describe a task, the AI checks if any skill matches and suggests using it. diff --git a/skills/cli-mastery/references/module-6-mcp.md b/skills/cli-mastery/references/module-6-mcp.md new file mode 100644 index 00000000..76675451 --- /dev/null +++ b/skills/cli-mastery/references/module-6-mcp.md @@ -0,0 +1,50 @@ +# Module 6: MCP Integration + +## What is MCP? + +- Model Context Protocol — a standard for connecting AI to external tools +- Think of it as "USB ports for AI" — plug in any compatible tool +- The GitHub MCP server is **built-in** (search repos, issues, PRs, actions) + +## Key commands + +| Command | What it does | +|---------|-------------| +| `/mcp` | List connected MCP servers | +| `/mcp add ` | Add a new MCP server | + +## Popular MCP servers + +- `@modelcontextprotocol/server-postgres` — Query PostgreSQL databases +- `@modelcontextprotocol/server-sqlite` — Query SQLite databases +- `@modelcontextprotocol/server-filesystem` — Access local files with permissions +- `@modelcontextprotocol/server-memory` — Persistent knowledge graph +- `@modelcontextprotocol/server-puppeteer` — Browser automation + +## Configuration + +| Level | File | +|-------|------| +| User | `~/.copilot/mcp-config.json` | +| Project | `.github/mcp-config.json` | + +## Config file format + +```json +{ + "mcpServers": { + "my-server": { + "command": "npx", + "args": ["@modelcontextprotocol/server-postgres", "{{env.DATABASE_URL}}"], + "env": { "NODE_ENV": "development" } + } + } +} +``` + +## Security best practices + +- Never put credentials directly in config files +- Use environment variable references: `{{env.SECRET}}` +- Review MCP server source before using +- Only connect servers you actually need diff --git a/skills/cli-mastery/references/module-7-advanced.md b/skills/cli-mastery/references/module-7-advanced.md new file mode 100644 index 00000000..22355dc8 --- /dev/null +++ b/skills/cli-mastery/references/module-7-advanced.md @@ -0,0 +1,38 @@ +# Module 7: Advanced Techniques + +1. **`@` file mentions** — Always give precise context, don't rely on the AI finding files + - `@src/auth.ts` — single file + - `@src/components/` — directory listing + - "Fix @src/auth.ts to match @tests/auth.test.ts" — multi-file context + +2. **`! shell bypass`** — `!git log --oneline -5` runs instantly, no AI overhead + +3. **`/research`** — Run a deep research investigation using GitHub search and web sources + +4. **`/resume` + `--continue`** — Session continuity across CLI launches + +5. **`/compact`** — Compress history when context gets large (auto at 95%) + - Check with `/context` first + - Best used at natural task boundaries + - Warning signs: AI contradicting earlier statements, token usage >80% + +6. **`/context`** — Visualize what's eating your token budget + +7. **Custom instructions precedence** (highest to lowest): + - `CLAUDE.md` / `GEMINI.md` / `AGENTS.md` (git root + cwd) + - `.github/instructions/**/*.instructions.md` (path-specific!) + - `.github/copilot-instructions.md` + - `~/.copilot/copilot-instructions.md` + - `COPILOT_CUSTOM_INSTRUCTIONS_DIRS` (additional directories via env var) + +8. **Path-specific instructions:** + - `.github/instructions/backend.instructions.md` with `applyTo: "src/api/**"` + - Different coding standards for different parts of the codebase + +9. **LSP config** — `~/.copilot/lsp-config.json` or `.github/lsp.json` + +10. **`/review`** — Get code review without leaving terminal + +11. **`--allow-all` / `--yolo`** — Full trust mode (use responsibly!) + +12. **`Ctrl+T`** — Watch the AI think (learn its reasoning patterns) diff --git a/skills/cli-mastery/references/module-8-configuration.md b/skills/cli-mastery/references/module-8-configuration.md new file mode 100644 index 00000000..27025797 --- /dev/null +++ b/skills/cli-mastery/references/module-8-configuration.md @@ -0,0 +1,34 @@ +# Module 8: Configuration + +## Key files + +| File | Purpose | +|------|---------| +| `~/.copilot/config.json` | Main settings (model, theme, logging, experimental flags) | +| `~/.copilot/mcp-config.json` | MCP servers | +| `~/.copilot/lsp-config.json` | Language servers (user-level) | +| `.github/lsp.json` | Language servers (repo-level) | +| `~/.copilot/copilot-instructions.md` | Global custom instructions | +| `.github/copilot-instructions.md` | Repo-level custom instructions | + +## Environment variables + +| Variable | Purpose | +|----------|---------| +| `EDITOR` | Text editor for `Ctrl+G` (edit prompt in external editor) | +| `COPILOT_LOG_LEVEL` | Logging verbosity (error/warn/info/debug/trace) | +| `GH_TOKEN` / `GITHUB_TOKEN` | GitHub authentication token (checked in order) | +| `COPILOT_CUSTOM_INSTRUCTIONS_DIRS` | Additional directories for custom instructions | + +## Permissions model + +- Default: confirmation required for edits, creates, shell commands +- `/allow-all` or `--yolo`: skip all confirmations for the session +- `/reset-allowed-tools`: re-enable confirmations +- Directory allowlists, tool approval gates, MCP server trust + +## Logging levels + +error, warn, info, debug, trace (`COPILOT_LOG_LEVEL=debug copilot`) + +Use debug/trace for: MCP connection issues, tool failures, unexpected behavior, bug reports diff --git a/skills/cli-mastery/references/scenarios.md b/skills/cli-mastery/references/scenarios.md new file mode 100644 index 00000000..5a649c69 --- /dev/null +++ b/skills/cli-mastery/references/scenarios.md @@ -0,0 +1,44 @@ +# Scenario Challenges + +Present these as real-world situations. Ask the user what commands/shortcuts they'd use. +Use `ask_user` with choices for each step. + +## Scenario 1: Hotfix Review Under Pressure +> A production bug fix is ready. You need to inspect the diff, run code review, and keep sensitive data hidden because you're on a livestream. + +**Answer:** `/streamer-mode` → `/diff` → `/review @src/payment.ts` + +## Scenario 2: Context Window Rescue +> Your session is huge and model quality is dropping. Keep continuity while shrinking noise. + +**Answer:** `/context` → `/compact` → `/resume` (or restart with `--continue`) + +## Scenario 3: Autonomous Refactor Sprint +> You want an agent to execute a refactor with minimal prompts, but only after reviewing a plan and setting permissions. + +**Answer:** `Shift+Tab` (Plan mode) → validate plan → `/allow-all` → execute in Autopilot mode + +## Scenario 4: Enterprise Onboarding +> Set up custom agents, repo instructions, and MCP integration for a new team repository. + +**Answer:** Add agent profiles to `.github/agents/`, verify `/instructions`, then `/mcp add` + +## Scenario 5: Power Editing Session +> You're crafting a long prompt and need to edit quickly without losing context. + +**Answer:** `Ctrl+G` (open in editor), `Ctrl+A` (jump to start), `Ctrl+K` (trim) + +## Scenario 6: Agent Orchestration +> You're leading a complex project: understand code, run tests, refactor, then review. + +**Answer:** `explore` agent (understand) → `task` agent (tests) → `general-purpose` (refactor) → `code-review` (verify) + +## Scenario 7: New Project Setup +> You cloned a new repo and need to set up Copilot CLI for max productivity. + +**Answer:** `/init` → `/model` → `/mcp add` (if needed) → `Shift+Tab` to Plan mode for first task + +## Scenario 8: Production Safety +> Switching from boilerplate work to production deployment scripts. + +**Answer:** `/reset-allowed-tools` → Plan mode → `/review` before every commit From a4938e2aa7d14421b18ef99ada86abe4819017a7 Mon Sep 17 00:00:00 2001 From: Dan Velton <48307985+dvelton@users.noreply.github.com> Date: Sun, 8 Mar 2026 21:50:20 -0700 Subject: [PATCH 19/37] Add napkin plugin: visual whiteboard collaboration for Copilot CLI (#929) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Add napkin plugin: visual whiteboard collaboration for Copilot CLI Napkin opens an interactive HTML whiteboard in the user's browser where they can draw, sketch, and add sticky notes. When ready, they click 'Share with Copilot' which exports a PNG snapshot. The Copilot CLI agent reads the PNG via the view tool, and the multimodal AI model interprets the drawings, spatial layout, and text content — responding conversationally as a collaborator. Built for non-technical users: lawyers, PMs, business stakeholders, designers, and anyone who thinks better visually. Includes: - Self-contained HTML whiteboard (zero external dependencies) - Shape recognition (wobbly shapes snap to clean versions) - Freehand drawing, sticky notes, arrows, text labels - Auto-save to localStorage - SKILL.md with agent instructions - SVG visual guides for step-by-step README documentation - Plugin manifest for Copilot CLI installation Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fix review feedback: roundRect compat, cross-platform shortcuts, eraser undo - Add safeRoundRect() fallback for browsers without CanvasRenderingContext2D.roundRect() - Update undo/redo button titles to show Ctrl/Cmd instead of Mac-only Cmd - Fix eraser undo by capturing state before first erase mutation per gesture Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Update skills/napkin/templates/napkin.html Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update plugins/napkin/README.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update skills/napkin/templates/napkin.html Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update skills/napkin/templates/napkin.html Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update skills/napkin/templates/napkin.html Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Add missing Line (L) and Eraser (E) keyboard shortcuts to README The in-app shortcuts panel and keyMap handler both support L for Line and E for Eraser, but the README keyboard shortcuts table was missing both entries. Adds them to match the actual implementation. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Combine docs/ and templates/ into assets/ per agentskills.io spec Moves skills/napkin/docs/*.svg and skills/napkin/templates/napkin.html into skills/napkin/assets/ to align with the Agent Skills specification. Updates all path references in SKILL.md, README.md, and generated docs. Addresses review feedback from PR #929. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Dan Velton Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .github/plugin/marketplace.json | 6 + docs/README.plugins.md | 1 + docs/README.skills.md | 1 + plugins/napkin/.github/plugin/plugin.json | 25 + plugins/napkin/README.md | 163 ++ skills/napkin/SKILL.md | 154 ++ skills/napkin/assets/napkin.html | 2019 +++++++++++++++++++++ skills/napkin/assets/step1-activate.svg | 107 ++ skills/napkin/assets/step2-whiteboard.svg | 157 ++ skills/napkin/assets/step3-draw.svg | 143 ++ skills/napkin/assets/step4-share.svg | 98 + skills/napkin/assets/step5-response.svg | 112 ++ 12 files changed, 2986 insertions(+) create mode 100644 plugins/napkin/.github/plugin/plugin.json create mode 100644 plugins/napkin/README.md create mode 100644 skills/napkin/SKILL.md create mode 100644 skills/napkin/assets/napkin.html create mode 100644 skills/napkin/assets/step1-activate.svg create mode 100644 skills/napkin/assets/step2-whiteboard.svg create mode 100644 skills/napkin/assets/step3-draw.svg create mode 100644 skills/napkin/assets/step4-share.svg create mode 100644 skills/napkin/assets/step5-response.svg diff --git a/.github/plugin/marketplace.json b/.github/plugin/marketplace.json index e6be3ec4..fc09eab1 100644 --- a/.github/plugin/marketplace.json +++ b/.github/plugin/marketplace.json @@ -167,6 +167,12 @@ "description": "Comprehensive collection for building declarative agents with Model Context Protocol integration for Microsoft 365 Copilot", "version": "1.0.0" }, + { + "name": "napkin", + "source": "napkin", + "description": "Visual whiteboard collaboration for Copilot CLI. Opens an interactive whiteboard in your browser where you can draw, sketch, and add sticky notes — then share everything back with Copilot. Copilot sees your drawings and responds with analysis, suggestions, and ideas.", + "version": "1.0.0" + }, { "name": "noob-mode", "source": "noob-mode", diff --git a/docs/README.plugins.md b/docs/README.plugins.md index a520b04e..143272f8 100644 --- a/docs/README.plugins.md +++ b/docs/README.plugins.md @@ -47,6 +47,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-plugins) for guidelines on how t | [java-mcp-development](../plugins/java-mcp-development/README.md) | Complete toolkit for building Model Context Protocol servers in Java using the official MCP Java SDK with reactive streams and Spring Boot integration. | 2 items | java, mcp, model-context-protocol, server-development, sdk, reactive-streams, spring-boot, reactor | | [kotlin-mcp-development](../plugins/kotlin-mcp-development/README.md) | Complete toolkit for building Model Context Protocol (MCP) servers in Kotlin using the official io.modelcontextprotocol:kotlin-sdk library. Includes instructions for best practices, a prompt for generating servers, and an expert chat mode for guidance. | 2 items | kotlin, mcp, model-context-protocol, kotlin-multiplatform, server-development, ktor | | [mcp-m365-copilot](../plugins/mcp-m365-copilot/README.md) | Comprehensive collection for building declarative agents with Model Context Protocol integration for Microsoft 365 Copilot | 4 items | mcp, m365-copilot, declarative-agents, api-plugins, model-context-protocol, adaptive-cards | +| [napkin](../plugins/napkin/README.md) | Visual whiteboard collaboration for Copilot CLI. Opens an interactive whiteboard in your browser where you can draw, sketch, and add sticky notes — then share everything back with Copilot. Copilot sees your drawings and responds with analysis, suggestions, and ideas. | 1 items | whiteboard, visual, collaboration, brainstorming, non-technical, drawing, sticky-notes, accessibility, copilot-cli, ux | | [noob-mode](../plugins/noob-mode/README.md) | Plain-English translation layer for non-technical Copilot CLI users. Translates every approval prompt, error message, and technical output into clear, jargon-free English with color-coded risk indicators. | 1 items | accessibility, plain-english, non-technical, beginner, translation, copilot-cli, ux | | [openapi-to-application-csharp-dotnet](../plugins/openapi-to-application-csharp-dotnet/README.md) | Generate production-ready .NET applications from OpenAPI specifications. Includes ASP.NET Core project scaffolding, controller generation, entity framework integration, and C# best practices. | 2 items | openapi, code-generation, api, csharp, dotnet, aspnet | | [openapi-to-application-go](../plugins/openapi-to-application-go/README.md) | Generate production-ready Go applications from OpenAPI specifications. Includes project scaffolding, handler generation, middleware setup, and Go best practices for REST APIs. | 2 items | openapi, code-generation, api, go, golang | diff --git a/docs/README.skills.md b/docs/README.skills.md index 51455a69..c5d3fdc1 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -163,6 +163,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [my-issues](../skills/my-issues/SKILL.md) | List my issues in the current repository | None | | [my-pull-requests](../skills/my-pull-requests/SKILL.md) | List my pull requests in the current repository | None | | [nano-banana-pro-openrouter](../skills/nano-banana-pro-openrouter/SKILL.md) | Generate or edit images via OpenRouter with the Gemini 3 Pro Image model. Use for prompt-only image generation, image edits, and multi-image compositing; supports 1K/2K/4K output. | `assets/SYSTEM_TEMPLATE`
`scripts/generate_image.py` | +| [napkin](../skills/napkin/SKILL.md) | Visual whiteboard collaboration for Copilot CLI. Creates an interactive whiteboard that opens in your browser — draw, sketch, add sticky notes, then share everything back with Copilot. Copilot sees your drawings and text, and responds with analysis, suggestions, and ideas. | `assets/napkin.html`
`assets/step1-activate.svg`
`assets/step2-whiteboard.svg`
`assets/step3-draw.svg`
`assets/step4-share.svg`
`assets/step5-response.svg` | | [next-intl-add-language](../skills/next-intl-add-language/SKILL.md) | Add new language to a Next.js + next-intl application | None | | [noob-mode](../skills/noob-mode/SKILL.md) | Plain-English translation layer for non-technical Copilot CLI users. Translates every approval prompt, error message, and technical output into clear, jargon-free English with color-coded risk indicators. | `references/examples.md`
`references/glossary.md` | | [nuget-manager](../skills/nuget-manager/SKILL.md) | Manage NuGet packages in .NET projects/solutions. Use this skill when adding, removing, or updating NuGet package versions. It enforces using `dotnet` CLI for package management and provides strict procedures for direct file edits only when updating versions. | None | diff --git a/plugins/napkin/.github/plugin/plugin.json b/plugins/napkin/.github/plugin/plugin.json new file mode 100644 index 00000000..2114c178 --- /dev/null +++ b/plugins/napkin/.github/plugin/plugin.json @@ -0,0 +1,25 @@ +{ + "name": "napkin", + "description": "Visual whiteboard collaboration for Copilot CLI. Opens an interactive whiteboard in your browser where you can draw, sketch, and add sticky notes — then share everything back with Copilot. Copilot sees your drawings and responds with analysis, suggestions, and ideas.", + "version": "1.0.0", + "author": { + "name": "Awesome Copilot Community" + }, + "repository": "https://github.com/github/awesome-copilot", + "license": "MIT", + "keywords": [ + "whiteboard", + "visual", + "collaboration", + "brainstorming", + "non-technical", + "drawing", + "sticky-notes", + "accessibility", + "copilot-cli", + "ux" + ], + "skills": [ + "./skills/napkin/" + ] +} diff --git a/plugins/napkin/README.md b/plugins/napkin/README.md new file mode 100644 index 00000000..4c8cb5c7 --- /dev/null +++ b/plugins/napkin/README.md @@ -0,0 +1,163 @@ +# Napkin — Visual Whiteboard for Copilot CLI + +A whiteboard that opens in your browser and connects to Copilot CLI. Draw, sketch, add sticky notes — then share everything back with Copilot. Copilot sees your drawings and responds with analysis, suggestions, and ideas. + +Built for people who aren't software developers: lawyers, PMs, business stakeholders, designers, writers — anyone who thinks better visually. + +## Installation + +Install the plugin directly from Copilot CLI: + +```bash +copilot plugin install napkin@awesome-copilot +``` + +That's it. No other software, accounts, or setup required. + +### Verify It's Installed + +Run this in Copilot CLI to confirm the plugin is available: + +``` +/skills +``` + +You should see **napkin** in the list of available skills. + +## How to Use It + +### Step 1: Say "let's napkin" + +Open Copilot CLI and type `let's napkin` (or "open a napkin" or "start a whiteboard"). Copilot creates a whiteboard and opens it in your browser. + +![Step 1 — Activate the napkin](../../skills/napkin/assets/step1-activate.svg) + +### Step 2: Your whiteboard opens + +A clean whiteboard appears in your browser with simple drawing tools. If it's your first time, a quick welcome message explains how everything works. + +![Step 2 — The whiteboard opens](../../skills/napkin/assets/step2-whiteboard.svg) + +### Step 3: Draw and brainstorm + +Use the tools to sketch ideas, add sticky notes, draw arrows between concepts — whatever helps you think. This is your space. + +![Step 3 — Draw and brainstorm](../../skills/napkin/assets/step3-draw.svg) + +### Step 4: Share with Copilot + +When you're ready for Copilot's input, click the green **Share with Copilot** button. It saves a screenshot and copies your notes. + +![Step 4 — Share with Copilot](../../skills/napkin/assets/step4-share.svg) + +### Step 5: Copilot responds + +Go back to your terminal and say `check the napkin`. Copilot looks at your whiteboard — including your drawings — and responds. + +![Step 5 — Copilot responds](../../skills/napkin/assets/step5-response.svg) + +## What's Included + +### Skill + +| Skill | Description | +|-------|-------------| +| `napkin` | Visual whiteboard collaboration — creates a whiteboard, interprets your drawings and notes, and responds conversationally | + +### Bundled Assets + +| Asset | Description | +|-------|-------------| +| `assets/napkin.html` | The whiteboard application — a single HTML file that opens in any browser, no installation needed | + +## Whiteboard Features + +| Feature | What it does | +|---------|-------------| +| **Freehand drawing** | Draw with a pen tool, just like on paper | +| **Shapes** | Rectangles, circles, lines, and arrows — wobbly shapes snap to clean versions | +| **Sticky notes** | Draggable, resizable, color-coded notes (yellow, pink, blue, green) | +| **Text labels** | Click anywhere to type text directly on the canvas | +| **Pan and zoom** | Hold spacebar and drag to move around; scroll to zoom | +| **Undo/Redo** | Made a mistake? Ctrl+Z to undo, Ctrl+Shift+Z to redo | +| **Auto-save** | Your work saves automatically — close the tab, come back later, it's still there | +| **Share with Copilot** | One button exports a screenshot and copies your text content | + +## How Copilot Understands Your Drawings + +When you click "Share with Copilot," two things happen: + +1. **A screenshot is saved** (`napkin-snapshot.png` in your Downloads or Desktop folder). Copilot reads this image and can see everything — sketches, arrows, groupings, annotations, sticky notes, spatial layout. + +2. **Your text is copied to clipboard.** This gives Copilot the exact text from your sticky notes and labels, so nothing gets misread from the image. + +Copilot uses both to understand what you're thinking and respond as a collaborator — not a computer analyzing data, but a colleague looking at your whiteboard sketch. + +## What Can You Draw? + +Anything. But here are some things Copilot is especially good at interpreting: + +| What you draw | What Copilot understands | +|---------------|------------------------| +| Boxes connected by arrows | A process flow or workflow | +| Items circled together | A group of related ideas | +| Sticky notes in different colors | Categories or priorities | +| Text with a line through it | Something rejected or deprioritized | +| Stars or exclamation marks | High-priority items | +| Items on opposite sides | A comparison or contrast | +| A rough org chart | Reporting structure or team layout | + +## Keyboard Shortcuts + +You don't need these — everything works with mouse clicks. But if you want to work faster: + +| Key | Tool | +|-----|------| +| V | Select / move | +| P | Pen (draw) | +| R | Rectangle | +| C | Circle | +| A | Arrow | +| L | Line | +| T | Text | +| N | New sticky note | +| E | Eraser | +| Delete | Delete selected item (not yet supported) | +| Ctrl+Z | Undo | +| Ctrl+Shift+Z | Redo | +| Space + drag | Pan the canvas | +| ? | Show help | + +## FAQ + +**Do I need to install anything besides the plugin?** +No. The whiteboard is a single HTML file that opens in your browser. No apps, no accounts, no setup. + +**Does it work offline?** +Yes. Everything runs locally in your browser. No internet connection needed for the whiteboard itself. + +**What browsers work?** +Any modern browser — Chrome, Safari, Edge, Firefox. Chrome works best for the "copy to clipboard" feature. + +**Can I save my work?** +Yes, automatically. The whiteboard saves to your browser's local storage every few seconds. Close the tab, come back later, your work is still there. + +**Can Copilot really understand my drawings?** +Yes. The AI models powering Copilot CLI (Claude, GPT) can interpret images. They can see your sketches, read your handwriting-style text, understand spatial relationships, and interpret common visual patterns like flowcharts, groupings, and annotations. + +**What if I'm not a good artist?** +Doesn't matter. The whiteboard snaps wobbly shapes to clean versions, and Copilot is trained to interpret rough sketches. Stick figures and messy arrows work just fine. + +**How do I start over?** +Say "let's napkin" again in the CLI. Copilot will ask if you want to keep the existing whiteboard or start fresh. + +**What platforms are supported?** +macOS, Linux, and Windows. The whiteboard runs in any browser. Clipboard integration uses platform-native tools (`pbpaste` on macOS, `xclip` on Linux, PowerShell on Windows). + +## Source + +This plugin is part of [Awesome Copilot](https://github.com/github/awesome-copilot), a community-driven collection of GitHub Copilot extensions. + +## License + +MIT diff --git a/skills/napkin/SKILL.md b/skills/napkin/SKILL.md new file mode 100644 index 00000000..aab90cbe --- /dev/null +++ b/skills/napkin/SKILL.md @@ -0,0 +1,154 @@ +--- +name: napkin +description: 'Visual whiteboard collaboration for Copilot CLI. Creates an interactive whiteboard that opens in your browser — draw, sketch, add sticky notes, then share everything back with Copilot. Copilot sees your drawings and text, and responds with analysis, suggestions, and ideas.' +--- + +# Napkin — Visual Whiteboard for Copilot CLI + +Napkin gives users a browser-based whiteboard where they can draw, sketch, and add sticky notes to think through ideas visually. The agent reads back the whiteboard contents (via a PNG snapshot and optional JSON data) and responds conversationally with analysis, suggestions, and next steps. + +The target audience is lawyers, PMs, and business stakeholders — not software developers. Keep everything approachable and jargon-free. + +--- + +## Activation + +When the user invokes this skill — saying things like "let's napkin," "open a napkin," "start a whiteboard," or using the slash command — do the following: + +1. **Copy the bundled HTML template** from the skill assets to the user's Desktop. + - The template lives at `assets/napkin.html` relative to this SKILL.md file. + - Copy it to `~/Desktop/napkin.html`. + - If `~/Desktop/napkin.html` already exists, ask the user whether they want to open the existing one or start fresh before overwriting. + +2. **Open it in the default browser:** + - macOS: `open ~/Desktop/napkin.html` + - Linux: `xdg-open ~/Desktop/napkin.html` + - Windows: `start ~/Desktop/napkin.html` + +3. **Tell the user what to do next.** Say something warm and simple: + + ``` + Your napkin is open in your browser! + + Draw, sketch, or add sticky notes — whatever helps you think through your idea. + + When you're ready for my input, click the green "Share with Copilot" button on the whiteboard, then come back here and say "check the napkin." + ``` + +--- + +## Reading the Napkin + +When the user says "check the napkin," "look at the napkin," "what do you think," "read my napkin," or anything similar, follow these steps: + +### Step 1 — Read the PNG snapshot (primary) + +Look for a PNG file called `napkin-snapshot.png`. Check these locations in order (the browser saves it to the user's default download folder, which varies): + +1. `~/Downloads/napkin-snapshot.png` +2. `~/Desktop/napkin-snapshot.png` + +Use the `view` tool to read the PNG. This sends the image as base64-encoded data to the model, which can visually interpret it. The PNG is the **primary** way the agent understands what the user drew — it captures freehand sketches, arrows, spatial layout, annotations, circled or crossed-out items, and anything else on the canvas. + +If the PNG is not found in either location, do NOT silently skip it. Instead, tell the user: + +``` +I don't see a snapshot from your napkin yet. Here's what to do: + +1. Go to your whiteboard in the browser +2. Click the green "Share with Copilot" button +3. Come back here and say "check the napkin" again + +The button saves a screenshot that I can look at. +``` + +### Step 2 — Read the clipboard for structured JSON (supplementary) + +Also try to grab structured JSON data from the system clipboard. The whiteboard copies this automatically alongside the PNG. + +- macOS: `pbpaste` +- Linux: `xclip -selection clipboard -o` +- Windows: `powershell -command "Get-Clipboard"` + +The JSON contains the exact text content of sticky notes and text labels, their positions, and their colors. This supplements the PNG by giving you precise text that might be hard to read from a screenshot. + +If the clipboard doesn't contain JSON data, that's fine — the PNG alone gives the model plenty to work with. Do not treat a missing clipboard as an error. + +### Step 3 — Interpret both sources together + +Synthesize the visual snapshot and the structured text into a coherent understanding of what the user is thinking or planning: + +- **From the PNG:** Describe what you see — sketches, diagrams, flowcharts, groupings, arrows, spatial layout, annotations, circled items, crossed-out items, emphasis marks. +- **From the JSON:** Read the exact text content of sticky notes and labels, noting their positions and colors. +- **Combine both** into a single, conversational interpretation. + +### Step 4 — Respond conversationally + +Do not dump raw data or a technical summary. Respond as a collaborator who looked at someone's whiteboard sketch. Examples: + +- "I can see you've sketched out a three-stage process — it looks like you're thinking about [X] flowing into [Y] and then [Z]. The sticky note in the corner says '[text]' — is that a concern you want me to address?" +- "It looks like you've grouped these four ideas together on the left side and separated them from the two items on the right. Are you thinking of these as two different categories?" +- "I see you drew arrows connecting [A] to [B] to [C] — is this the workflow you're envisioning?" + +### Step 5 — Ask what's next + +Always end by offering a next step: + +- "Want me to build on this?" +- "Should I turn this into a structured document?" +- "Want me to add my suggestions to the napkin?" + +--- + +## Responding on the Napkin + +When the user wants the agent to add content back to the whiteboard: + +- The agent **cannot** directly modify the HTML file's canvas state — that's managed by JavaScript running in the browser. +- Instead, offer practical alternatives: + - Provide the response right here in the CLI, and suggest the user add it to the napkin manually. + - Offer to create a separate document (markdown, memo, checklist, etc.) based on what was interpreted from the napkin. + - If it makes sense, create an updated copy of `napkin.html` with pre-loaded content. + +--- + +## Tone and Style + +- Use the same approachable, non-technical tone as the noob-mode skill. +- Never use developer jargon without explaining it in plain English. +- Treat the napkin as a creative, collaborative space — not a formal input mechanism. +- Be encouraging about the user's sketches regardless of artistic quality. +- Frame responses as "building on your thinking," not "analyzing your input." + +--- + +## Error Handling + +**PNG snapshot not found:** + +``` +I don't see a snapshot from your napkin yet. Here's what to do: + +1. Go to your whiteboard in the browser +2. Click the green "Share with Copilot" button +3. Come back here and say "check the napkin" again + +The button saves a screenshot that I can look at. +``` + +**Whiteboard file doesn't exist on Desktop:** + +``` +It looks like we haven't started a napkin yet. Want me to open one for you? +``` + +--- + +## Important Notes + +- The PNG interpretation is the **primary** channel. Multimodal models can read and interpret the base64 image data returned by the `view` tool. +- The JSON clipboard data is **supplementary** — it provides precise text but does not capture freehand drawings. +- Always check for the PNG first. If it isn't found, prompt the user to click "Share with Copilot." +- If the clipboard doesn't have JSON data, proceed with the PNG alone. +- The HTML template is located at `assets/napkin.html` relative to this SKILL.md file. +- If the noob-mode skill is also active, use its risk indicator format (green/yellow/red) when requesting file or bash permissions. diff --git a/skills/napkin/assets/napkin.html b/skills/napkin/assets/napkin.html new file mode 100644 index 00000000..8a934ecb --- /dev/null +++ b/skills/napkin/assets/napkin.html @@ -0,0 +1,2019 @@ + + + + + +Napkin — Whiteboard for Copilot + + + + + +
+ +
+ + + + + + + +
+ + +
+ + +
+
+
+
+
+
+
+ + +
+
+
+
+
+
+
+
+
+
+ +
+ + + +
+ + +
+ + +
+ + + + + + +
+ + +
+ +
+ + +
+
+

Welcome to Napkin!

+

Your whiteboard for brainstorming with Copilot.

+
+
+
1
+
Draw, sketch, or add sticky notes — whatever helps you think
+
+
+
2
+
When you're ready, click "Share with Copilot" (the green button)
+
+
+
3
+
Go back to your terminal and say "check the napkin"
+
+
+
4
+
Copilot will look at your whiteboard and respond
+
+
+

That's it. Let's go!

+ +
+
+ + + + + +
+ +

Keyboard Shortcuts

+
Select / MoveV
+
PenP
+
RectangleR
+
CircleC
+
ArrowA
+
LineL
+
TextT
+
Sticky NoteN
+
EraserE
+
UndoCtrl/Cmd+Z
+
RedoCtrl/Cmd+Shift+Z
+
Pan canvasSpace+Drag
+
+ + +
+ + 100% + + +
+ + +
+ + + + diff --git a/skills/napkin/assets/step1-activate.svg b/skills/napkin/assets/step1-activate.svg new file mode 100644 index 00000000..548ac4a5 --- /dev/null +++ b/skills/napkin/assets/step1-activate.svg @@ -0,0 +1,107 @@ + + + + + + + + + + + + + + + + + + 1 + Type "let's napkin" to start + + + + + + + + + + + + + + Terminal + + + + ~/Projects + $ + copilot + + + ❯ + let's napkin + + + ✓ + Opening your napkin whiteboard... + + + Copilot + Your napkin is open in your browser! + Sketch your ideas, then click + "Share with Copilot" + when ready. + + + + + + + + + + + + + + + + + + + napkin.html + + + + + + + + Share + + + + + + + + + + + + + + + + + + Browser opens + automatically + + + + How it works: + Type "let's napkin" (or "open the napkin") in your Copilot CLI session. + A whiteboard will open in your default browser — no setup needed. + \ No newline at end of file diff --git a/skills/napkin/assets/step2-whiteboard.svg b/skills/napkin/assets/step2-whiteboard.svg new file mode 100644 index 00000000..e8ca67e6 --- /dev/null +++ b/skills/napkin/assets/step2-whiteboard.svg @@ -0,0 +1,157 @@ + + + + + + + + + + + + + + 2 + The whiteboard opens in your browser + + + + + + + + + + + + + + + + file:///Users/.../napkin.html + + + + + + + + + + + + + + + Pen + + + + + + Shapes + + + + + + + Arrow + + + + + + Sticky Note + + + + + + Eraser + + + + + Share with Copilot + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Welcome to your Napkin! + Sketch your ideas here — draw, write, add sticky notes. + When you're done, click "Share with Copilot" + to send your sketch back to the CLI. + + + + Got it! + + + + + + Drawing tools + + + + + + + + Send to Copilot + \ No newline at end of file diff --git a/skills/napkin/assets/step3-draw.svg b/skills/napkin/assets/step3-draw.svg new file mode 100644 index 00000000..ef836dfc --- /dev/null +++ b/skills/napkin/assets/step3-draw.svg @@ -0,0 +1,143 @@ + + + + + + + + + + + + + + + + + + + + + + 3 + Sketch your ideas on the whiteboard + + + + + + + + + + + + + napkin.html + + + + + + + + + + + + Pen + + + + + + Shapes + + + + + + Arrow + + + + + Sticky Note + + + + + Eraser + + + + + + + Draft + proposal + + + + + + + + Review + with team + + + + + + + + Ship + to customer + + + + + Need legal + review + before shipping! + + + + + + Q2 deadline + June 30th + + + + + + Check with + Sarah + re: compliance + + + + + + + + + + * + important! + + + ? + ? + + + + Share with Copilot + + + + + Draw, sketch, and add notes — whatever helps you think + \ No newline at end of file diff --git a/skills/napkin/assets/step4-share.svg b/skills/napkin/assets/step4-share.svg new file mode 100644 index 00000000..b24b854b --- /dev/null +++ b/skills/napkin/assets/step4-share.svg @@ -0,0 +1,98 @@ + + + + + + + + + + + + + + 4 + Share your sketch with Copilot + + + + + + + + + + + + + napkin.html + + + + + + + + Draft + + + + Review + + + + Ship + + + + + + + + + + Share with Copilot + + + + + + + + + + + + + Shared with Copilot! + A screenshot was saved and your text was copied. + Go back to your terminal to continue. + + + PNG + + TEXT + + ✓ + ✓ + + + + + + Click when you're ready + + + + + + + + + + _ + Next: Go back to your terminal and say: + + check the napkin + + \ No newline at end of file diff --git a/skills/napkin/assets/step5-response.svg b/skills/napkin/assets/step5-response.svg new file mode 100644 index 00000000..8fa643b8 --- /dev/null +++ b/skills/napkin/assets/step5-response.svg @@ -0,0 +1,112 @@ + + + + + + + + + + + + + + 5 + Copilot reads your napkin and responds + + + + + + + + + + + + + Terminal + + + ❯ + check the napkin + + + ✓ + Reading your napkin... + + + Copilot + + + I can see your sketch! Here's what I'm picking up: + + + You've drawn a three-stage workflow: + Draft + → + Review + → + Ship + + Your sticky notes highlight some key items: + + + ■ + "Need legal review" — before the Ship phase + ■ + "Q2 deadline" — June 30th + ■ + "Check with Sarah" — re: compliance + + It looks like you're planning a review workflow + with a legal gate. Would you like me to help you + turn this into a checklist or project plan? + + + + + + + + + Copilot sees your + drawings and text, + then responds in + plain English + + + + + + + + + What Copilot understood: + + + + + 3-stage workflow + + + + Legal review needed + + + + Q2 deadline (June 30) + + + + Follow up with Sarah + + + + Review step = priority + + + Everything from your + napkin — captured! + + \ No newline at end of file From 5e4c13d6d68fcf78529ad35798e03e74bef937a0 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Mon, 9 Mar 2026 16:03:00 +1100 Subject: [PATCH 20/37] Update CODEOWNERS for PR #929 (#933) Assigns ownership of napkin plugin and skill to @dvelton Co-authored-by: github-actions[bot] Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- CODEOWNERS | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CODEOWNERS b/CODEOWNERS index d48721cf..4b774fe6 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -8,3 +8,7 @@ # Added via #codeowner from PR #930 /plugins/automate-this/ @dvelton /skills/automate-this/ @dvelton + +# Added via #codeowner from PR #929 +/plugins/napkin/ @dvelton +/skills/napkin/ @dvelton From 58566ff8e53de914fff6fe598f224b51b742f8e8 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Mon, 9 Mar 2026 16:11:33 +1100 Subject: [PATCH 21/37] Update CODEOWNERS for PR #915 (#934) Co-authored-by: github-actions[bot] Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Aaron Powell --- CODEOWNERS | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CODEOWNERS b/CODEOWNERS index 4b774fe6..a17bf951 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -9,6 +9,9 @@ /plugins/automate-this/ @dvelton /skills/automate-this/ @dvelton +# Added via #codeowner from PR #915 +/skills/cli-mastery/ @DUBSOpenHub + # Added via #codeowner from PR #929 /plugins/napkin/ @dvelton /skills/napkin/ @dvelton From bc1202f00c31c3eae0d2b36e7b293c02bbff115a Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Mon, 9 Mar 2026 16:56:26 +1100 Subject: [PATCH 22/37] Update CODEOWNERS for PR #888 (#936) Add @labudis as owner of /skills/github-issues/ Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- CODEOWNERS | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CODEOWNERS b/CODEOWNERS index a17bf951..e6397af6 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -15,3 +15,6 @@ # Added via #codeowner from PR #929 /plugins/napkin/ @dvelton /skills/napkin/ @dvelton + +# Added via #codeowner from PR #888 +/skills/github-issues/ @labudis From 299033c7dc542ecf67262d4755f001ac734ae128 Mon Sep 17 00:00:00 2001 From: Aaron Powell Date: Mon, 9 Mar 2026 17:00:01 +1100 Subject: [PATCH 23/37] manually updating codeowners field (#939) --- CODEOWNERS | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/CODEOWNERS b/CODEOWNERS index e6397af6..2600aefd 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -18,3 +18,9 @@ # Added via #codeowner from PR #888 /skills/github-issues/ @labudis + +# Added via #codeowner from PR #884 +/skills/github-issues/ @labudis + +# Added via #codeowner from PR #889 +/skills/copilot-spaces/ @labudis From 7172ebfb8b12e74f7dc3be1b7ac69de74b5aaa16 Mon Sep 17 00:00:00 2001 From: Aaron Powell Date: Mon, 9 Mar 2026 17:01:30 +1100 Subject: [PATCH 24/37] a few style tweaks (#938) --- website/src/styles/global.css | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/website/src/styles/global.css b/website/src/styles/global.css index 782a4f34..640b99bd 100644 --- a/website/src/styles/global.css +++ b/website/src/styles/global.css @@ -562,7 +562,7 @@ body:has(#main-content) { .btn-primary { background: var(--color-accent); - color: white; + color: var(--sl-color-text-invert) !important; border-color: transparent; font-weight: 600; } @@ -1237,17 +1237,19 @@ body:has(#main-content) { background: var(--gradient-primary); border-radius: var(--border-radius-lg) 0 0 var(--border-radius-lg); opacity: 0; - transition: opacity var(--transition); + transition: opacity var(--transition), left var(--transition); } .resource-item:hover { background: var(--color-card-hover); transform: translateX(4px); box-shadow: var(--shadow); + border-radius: 0px var(--border-radius-lg) var(--border-radius-lg) 0px; } .resource-item:hover::before { opacity: 1; + left: -4px; } .resource-info { From b91369d1b5d76a83f63f394ec43c1530d93d99f4 Mon Sep 17 00:00:00 2001 From: tagedeep <43116939+tagedeep@users.noreply.github.com> Date: Tue, 10 Mar 2026 00:10:35 +0100 Subject: [PATCH 25/37] Fix outdated Copilot skill references for agents and skills in github-copilot-starter (#918) * Fix outdated Copilot skill references for agents, skills, and workflows * Fix example format and typos * replace incorrect formatter references with frontmatter * Add engineer agent, file templates, and start-minimal philosophy to github-copilot-starter * removed unspecific references to docs folder. * revert changes to workflow setup * revise templates * simplify agent creation * implement review changes * make GitHub Actions workflow generation optional and clean up templates --- skills/github-copilot-starter/SKILL.md | 216 ++++++++++++++----------- 1 file changed, 124 insertions(+), 92 deletions(-) diff --git a/skills/github-copilot-starter/SKILL.md b/skills/github-copilot-starter/SKILL.md index ba196b0f..f3c687eb 100644 --- a/skills/github-copilot-starter/SKILL.md +++ b/skills/github-copilot-starter/SKILL.md @@ -12,51 +12,82 @@ Ask the user for the following information if not provided: 1. **Primary Language/Framework**: (e.g., JavaScript/React, Python/Django, Java/Spring Boot, etc.) 2. **Project Type**: (e.g., web app, API, mobile app, desktop app, library, etc.) 3. **Additional Technologies**: (e.g., database, cloud provider, testing frameworks, etc.) -4. **Team Size**: (solo, small team, enterprise) -5. **Development Style**: (strict standards, flexible, specific patterns) +4. **Development Style**: (strict standards, flexible, specific patterns) +5. **GitHub Actions / Coding Agent**: Does the project use GitHub Actions? (yes/no — determines whether to generate `copilot-setup-steps.yml`) ## Configuration Files to Create Based on the provided stack, create the following files in the appropriate directories: ### 1. `.github/copilot-instructions.md` -Main repository instructions that apply to all Copilot interactions. +Main repository instructions that apply to all Copilot interactions. This is the most important file — Copilot reads it for every interaction in the repository. + +Use this structure: +```md +# {Project Name} — Copilot Instructions + +## Project Overview +Brief description of what this project does and its primary purpose. + +## Tech Stack +List the primary language, frameworks, and key dependencies. + +## Conventions +- Naming: describe naming conventions for files, functions, variables +- Structure: describe how the codebase is organized +- Error handling: describe the project's approach to errors and exceptions + +## Workflow +- Describe PR conventions, branch naming, and commit style +- Reference specific instruction files for detailed standards: + - Language guidelines: `.github/instructions/{language}.instructions.md` + - Testing: `.github/instructions/testing.instructions.md` + - Security: `.github/instructions/security.instructions.md` + - Documentation: `.github/instructions/documentation.instructions.md` + - Performance: `.github/instructions/performance.instructions.md` + - Code review: `.github/instructions/code-review.instructions.md` +``` ### 2. `.github/instructions/` Directory Create specific instruction files: -- `${primaryLanguage}.instructions.md` - Language-specific guidelines +- `{primaryLanguage}.instructions.md` - Language-specific guidelines - `testing.instructions.md` - Testing standards and practices - `documentation.instructions.md` - Documentation requirements - `security.instructions.md` - Security best practices - `performance.instructions.md` - Performance optimization guidelines - `code-review.instructions.md` - Code review standards and GitHub review guidelines -### 3. `.github/prompts/` Directory -Create reusable prompt files: -- `setup-component.prompt.md` - Component/module creation -- `write-tests.prompt.md` - Test generation -- `code-review.prompt.md` - Code review assistance -- `refactor-code.prompt.md` - Code refactoring -- `generate-docs.prompt.md` - Documentation generation -- `debug-issue.prompt.md` - Debugging assistance +### 3. `.github/skills/` Directory +Create reusable skills as self-contained folders: +- `setup-component/SKILL.md` - Component/module creation +- `write-tests/SKILL.md` - Test generation +- `code-review/SKILL.md` - Code review assistance +- `refactor-code/SKILL.md` - Code refactoring +- `generate-docs/SKILL.md` - Documentation generation +- `debug-issue/SKILL.md` - Debugging assistance ### 4. `.github/agents/` Directory -Create specialized chat modes: -- `architect.agent.md` - Architecture planning mode -- `reviewer.agent.md` - Code review mode -- `debugger.agent.md` - Debugging mode +Always create these 4 agents: +- `software-engineer.agent.md` +- `architect.agent.md` +- `reviewer.agent.md` +- `debugger.agent.md` -**Chat Mode Attribution**: When using content from awesome-copilot chatmodes, add attribution comments: +For each, fetch the most specific match from awesome-copilot agents. If none exists, use the generic template. + +**Agent Attribution**: When using content from awesome-copilot agents, add attribution comments: ```markdown ``` -### 5. `.github/workflows/` Directory +### 5. `.github/workflows/` Directory (only if user uses GitHub Actions) +Skip this section entirely if the user answered "no" to GitHub Actions. + Create Coding Agent workflow file: - `copilot-setup-steps.yml` - GitHub Actions workflow for Coding Agent environment setup **CRITICAL**: The workflow MUST follow this exact structure: -- Job name MUST be `copilot-setup-steps` +- Job name MUST be `copilot-setup-steps` - Include proper triggers (workflow_dispatch, push, pull_request on the workflow file) - Set appropriate permissions (minimum required) - Customize steps based on the technology stack provided @@ -66,9 +97,10 @@ Create Coding Agent workflow file: For each file, follow these principles: **MANDATORY FIRST STEP**: Always use the fetch tool to research existing patterns before creating any content: -1. **Fetch from awesome-copilot collections**: https://github.com/github/awesome-copilot/blob/main/docs/README.collections.md -2. **Fetch specific instruction files**: https://raw.githubusercontent.com/github/awesome-copilot/main/instructions/[relevant-file].instructions.md -3. **Check for existing patterns** that match the technology stack +1. **Fetch specific instruction from awesome-copilot docs**: https://github.com/github/awesome-copilot/blob/main/docs/README.instructions.md +2. **Fetch specific agents from awesome-copilot docs**: https://github.com/github/awesome-copilot/blob/main/docs/README.agents.md +3. **Fetch specific skills from awesome-copilot docs**: https://github.com/github/awesome-copilot/blob/main/docs/README.skills.md +4. **Check for existing patterns** that match the technology stack **Primary Approach**: Reference and adapt existing instructions from awesome-copilot repository: - **Use existing content** when available - don't reinvent the wheel @@ -77,12 +109,12 @@ For each file, follow these principles: - **ALWAYS add attribution comments** when using awesome-copilot content **Attribution Format**: When using content from awesome-copilot, add this comment at the top of the file: -```markdown +```md ``` **Examples:** -```markdown +```md --- applyTo: "**/*.jsx,**/*.tsx" @@ -92,7 +124,7 @@ description: "React development best practices" ... ``` -```markdown +```md --- @@ -128,20 +160,19 @@ description: "Java Spring Boot development standards" **Research Strategy with fetch tool:** 1. **Check awesome-copilot first** - Always start here for ALL file types 2. **Look for exact tech stack matches** (e.g., React, Node.js, Spring Boot) -3. **Look for general matches** (e.g., frontend chatmodes, testing prompts, review modes) -4. **Check awesome-copilot collections** for curated sets of related files -5. **Adapt community examples** to project needs +3. **Look for general matches** (e.g., frontend agents, testing skills, review workflows) +4. **Check the docs and relevant directories directly** for related files +5. **Prefer repo-native examples** over inventing new formats 6. **Only create custom content** if nothing relevant exists **Fetch these awesome-copilot directories:** - **Instructions**: https://github.com/github/awesome-copilot/tree/main/instructions -- **Prompts**: https://github.com/github/awesome-copilot/tree/main/prompts -- **Chat Modes**: https://github.com/github/awesome-copilot/tree/main/chatmodes -- **Collections**: https://github.com/github/awesome-copilot/blob/main/docs/README.collections.md +- **Agents**: https://github.com/github/awesome-copilot/tree/main/agents +- **Skills**: https://github.com/github/awesome-copilot/tree/main/skills -**Awesome-Copilot Collections to Check:** +**Awesome-Copilot Areas to Check:** - **Frontend Web Development**: React, Angular, Vue, TypeScript, CSS frameworks -- **C# .NET Development**: Testing, documentation, and best practices +- **C# .NET Development**: Testing, documentation, and best practices - **Java Development**: Spring Boot, Quarkus, testing, documentation - **Database Development**: PostgreSQL, SQL Server, and general database best practices - **Azure Development**: Infrastructure as Code, serverless functions @@ -162,77 +193,73 @@ project-root/ │ │ ├── security.instructions.md │ │ ├── performance.instructions.md │ │ └── code-review.instructions.md -│ ├── prompts/ -│ │ ├── setup-component.prompt.md -│ │ ├── write-tests.prompt.md -│ │ ├── code-review.prompt.md -│ │ ├── refactor-code.prompt.md -│ │ ├── generate-docs.prompt.md -│ │ └── debug-issue.prompt.md +│ ├── skills/ +│ │ ├── setup-component/ +│ │ │ └── SKILL.md +│ │ ├── write-tests/ +│ │ │ └── SKILL.md +│ │ ├── code-review/ +│ │ │ └── SKILL.md +│ │ ├── refactor-code/ +│ │ │ └── SKILL.md +│ │ ├── generate-docs/ +│ │ │ └── SKILL.md +│ │ └── debug-issue/ +│ │ └── SKILL.md │ ├── agents/ +│ │ ├── software-engineer.agent.md │ │ ├── architect.agent.md │ │ ├── reviewer.agent.md │ │ └── debugger.agent.md -│ └── workflows/ +│ └── workflows/ # only if GitHub Actions is used │ └── copilot-setup-steps.yml ``` ## YAML Frontmatter Template -Use this frontmatter structure for all files: +Use this structure for all files: **Instructions (.instructions.md):** -```yaml +```md --- -applyTo: "**/*.ts,**/*.tsx" +applyTo: "**/*.{lang-ext}" +description: "Development standards for {Language}" --- -# Project coding standards for TypeScript and React +# {Language} coding standards -Apply the [general coding guidelines](./general-coding.instructions.md) to all code. +Apply the repository-wide guidance from `../copilot-instructions.md` to all code. -## TypeScript Guidelines -- Use TypeScript for all new code -- Follow functional programming principles where possible -- Use interfaces for data structures and type definitions -- Prefer immutable data (const, readonly) -- Use optional chaining (?.) and nullish coalescing (??) operators - -## React Guidelines -- Use functional components with hooks -- Follow the React hooks rules (no conditional hooks) -- Use React.FC type for components with children -- Keep components small and focused -- Use CSS modules for component styling +## General Guidelines +- Follow the project's established conventions and patterns +- Prefer clear, readable code over clever abstractions +- Use the language's idiomatic style and recommended practices +- Keep modules focused and appropriately sized + ``` -**Prompts (.prompt.md):** -```yaml +**Skills (SKILL.md):** +```md --- -agent: 'agent' -model: Claude Sonnet 4 -tools: ['githubRepo', 'codebase'] -description: 'Generate a new React form component' +name: {skill-name} +description: {Brief description of what this skill does} --- -Your goal is to generate a new React form component based on the templates in #githubRepo contoso/react-templates. -Ask for the form name and fields if not provided. +# {Skill Name} -Requirements for the form: -* Use form design system components: [design-system/Form.md](../docs/design-system/Form.md) -* Use `react-hook-form` for form state management: -* Always define TypeScript types for your form data -* Prefer *uncontrolled* components using register -* Use `defaultValues` to prevent unnecessary rerenders -* Use `yup` for validation: -* Create reusable validation schemas in separate files -* Use TypeScript types to ensure type safety -* Customize UX-friendly validation rules +{One sentence describing what this skill does. Always follow the repository's established patterns.} +Ask for {required inputs} if not provided. + +## Requirements +- Use the existing design system and repository conventions +- Follow the project's established patterns and style +- Adapt to the specific technology choices of this stack +- Reuse existing validation and documentation patterns ``` -**Chat Modes (.agent.md):** -```yaml +**Agents (.agent.md):** +```md --- description: Generate an implementation plan for new features or refactoring existing code. tools: ['codebase', 'web/fetch', 'findTestFiles', 'githubRepo', 'search', 'usages'] @@ -248,43 +275,48 @@ The plan consists of a Markdown document that describes the implementation plan, * Requirements: A list of requirements for the feature or refactoring task. * Implementation Steps: A detailed list of steps to implement the feature or refactoring task. * Testing: A list of tests that need to be implemented to verify the feature or refactoring task. - ``` ## Execution Steps -1. **Analyze the provided technology stack** -2. **Create the directory structure** -3. **Generate main copilot-instructions.md with project-wide standards** -4. **Create language-specific instruction files using awesome-copilot references** -5. **Generate reusable prompts for common development tasks** -6. **Set up specialized chat modes for different development scenarios** -7. **Create the GitHub Actions workflow for Coding Agent** (`copilot-setup-steps.yml`) -8. **Validate all files follow proper formatting and include necessary frontmatter** +1. **Gather project information** - Ask the user for technology stack, project type, and development style if not provided +2. **Research awesome-copilot patterns**: + - Use the fetch tool to explore awesome-copilot directories + - Check instructions: https://github.com/github/awesome-copilot/tree/main/instructions + - Check agents: https://github.com/github/awesome-copilot/tree/main/agents (especially for matching expert agents) + - Check skills: https://github.com/github/awesome-copilot/tree/main/skills + - Document all sources for attribution comments +3. **Create the directory structure** +4. **Generate main copilot-instructions.md** with project-wide standards +5. **Create language-specific instruction files** using awesome-copilot references with attribution +6. **Generate reusable skills** tailored to project needs +7. **Set up specialized agents**, fetching from awesome-copilot where applicable (especially for expert engineer agents matching the tech stack) +8. **Create the GitHub Actions workflow for Coding Agent** (`copilot-setup-steps.yml`) — skip if user does not use GitHub Actions +9. **Validate** all files follow proper formatting and include necessary frontmatter ## Post-Setup Instructions After creating all files, provide the user with: 1. **VS Code setup instructions** - How to enable and configure the files -2. **Usage examples** - How to use each prompt and chat mode +2. **Usage examples** - How to use each skill and agent 3. **Customization tips** - How to modify files for their specific needs 4. **Testing recommendations** - How to verify the setup works correctly ## Quality Checklist Before completing, verify: -- [ ] All files have proper YAML frontmatter +- [ ] All authored Copilot markdown files have proper YAML frontmatter where required - [ ] Language-specific best practices are included - [ ] Files reference each other appropriately using Markdown links -- [ ] Prompts include relevant tools and variables +- [ ] Skills and agents include relevant descriptions; include MCP/tool-related metadata only when the target Copilot environment actually supports or requires it - [ ] Instructions are comprehensive but not overwhelming - [ ] Security and performance considerations are addressed - [ ] Testing guidelines are included - [ ] Documentation standards are clear - [ ] Code review standards are defined -## Workflow Template Structure +## Workflow Template Structure (only if GitHub Actions is used) The `copilot-setup-steps.yml` workflow MUST follow this exact format and KEEP IT SIMPLE: From 3efc4f3a5bca3e9724be377bb7d875e1aad6dca9 Mon Sep 17 00:00:00 2001 From: Aaron Powell Date: Tue, 10 Mar 2026 10:13:16 +1100 Subject: [PATCH 26/37] feat: show external plugins on the website (#937) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat: show external plugins on the website Read plugins/external.json during website data generation and include external plugins alongside local ones in plugins.json. External plugins are flagged with external:true and carry metadata (author, repository, homepage, license, source). On the website: - Plugin cards show a '🔗 External' badge and author attribution - The 'Repository' button links to the source path within the repo - The modal shows metadata (author, repo, homepage, license) and a 'View Repository' CTA instead of an items list - External plugins are searchable and filterable by tags Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix: address PR #937 security and UX review comments - Add sanitizeUrl() function to validate URLs and prevent XSS via javascript:/data: schemes - Add rel="noopener noreferrer" to all target="_blank" links to prevent reverse-tabnabbing - Change external plugin path from external/ to plugins/ for proper deep-linking - Track actual count of external plugins added (after filtering/deduplication) in build logs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- eng/generate-website-data.mjs | 57 ++++++++++++ website/src/scripts/modal.ts | 127 ++++++++++++++++++++++++++- website/src/scripts/pages/plugins.ts | 53 +++++++++-- website/src/scripts/utils.ts | 18 ++++ website/src/styles/global.css | 65 ++++++++++++++ 5 files changed, 312 insertions(+), 8 deletions(-) diff --git a/eng/generate-website-data.mjs b/eng/generate-website-data.mjs index b4d3e13f..a2e2dca0 100644 --- a/eng/generate-website-data.mjs +++ b/eng/generate-website-data.mjs @@ -544,6 +544,63 @@ function generatePluginsData(gitDates) { } } + // Load external plugins from plugins/external.json + const externalJsonPath = path.join(PLUGINS_DIR, "external.json"); + if (fs.existsSync(externalJsonPath)) { + try { + const externalPlugins = JSON.parse( + fs.readFileSync(externalJsonPath, "utf-8") + ); + if (Array.isArray(externalPlugins)) { + let addedCount = 0; + for (const ext of externalPlugins) { + if (!ext.name || !ext.description) { + console.warn( + `Skipping external plugin with missing name/description` + ); + continue; + } + + // Skip if a local plugin with the same name already exists + if (plugins.some((p) => p.id === ext.name)) { + console.warn( + `Skipping external plugin "${ext.name}" — local plugin with same name exists` + ); + continue; + } + + const tags = ext.keywords || ext.tags || []; + + plugins.push({ + id: ext.name, + name: ext.name, + description: ext.description || "", + path: `plugins/${ext.name}`, + tags: tags, + itemCount: 0, + items: [], + external: true, + repository: ext.repository || null, + homepage: ext.homepage || null, + author: ext.author || null, + license: ext.license || null, + source: ext.source || null, + lastUpdated: null, + searchText: `${ext.name} ${ext.description || ""} ${tags.join( + " " + )} ${ext.author?.name || ""} ${ext.repository || ""}`.toLowerCase(), + }); + addedCount++; + } + console.log( + ` ✓ Loaded ${addedCount} external plugin(s)` + ); + } + } catch (e) { + console.warn(`Failed to parse external plugins: ${e.message}`); + } + } + // Collect all unique tags const allTags = [...new Set(plugins.flatMap((p) => p.tags))].sort(); diff --git a/website/src/scripts/modal.ts b/website/src/scripts/modal.ts index 94827e6b..f1b8751c 100644 --- a/website/src/scripts/modal.ts +++ b/website/src/scripts/modal.ts @@ -13,6 +13,7 @@ import { getResourceType, escapeHtml, getResourceIcon, + sanitizeUrl, } from "./utils"; // Modal state @@ -83,6 +84,17 @@ interface PluginItem { usage?: string | null; } +interface PluginAuthor { + name: string; + url?: string; +} + +interface PluginSource { + source: string; + repo?: string; + path?: string; +} + interface Plugin { id: string; name: string; @@ -90,6 +102,12 @@ interface Plugin { path: string; items: PluginItem[]; tags?: string[]; + external?: boolean; + repository?: string | null; + homepage?: string | null; + author?: PluginAuthor | null; + license?: string | null; + source?: PluginSource | null; } interface PluginsData { @@ -519,7 +537,114 @@ async function openPluginModal( title.textContent = plugin.name; document.title = `${plugin.name} | Awesome GitHub Copilot`; - // Render plugin view + // Render external plugin view (metadata + links) or local plugin view (items list) + if (plugin.external) { + renderExternalPluginModal(plugin, modalContent); + } else { + renderLocalPluginModal(plugin, modalContent); + } +} + +/** + * Get the best URL for an external plugin, preferring the deep path within the repo + */ +function getExternalPluginUrl(plugin: Plugin): string { + if (plugin.source?.source === "github" && plugin.source.repo) { + const base = `https://github.com/${plugin.source.repo}`; + return plugin.source.path ? `${base}/tree/main/${plugin.source.path}` : base; + } + // Sanitize URLs from JSON to prevent XSS via javascript:/data: schemes + return sanitizeUrl(plugin.repository || plugin.homepage); +} + +/** + * Render modal content for an external plugin (no local files) + */ +function renderExternalPluginModal( + plugin: Plugin, + modalContent: HTMLElement +): void { + const authorHtml = plugin.author?.name + ? `
+ Author + ${ + plugin.author.url + ? `${escapeHtml(plugin.author.name)}` + : escapeHtml(plugin.author.name) + } +
` + : ""; + + const repoHtml = plugin.repository + ? `
+ Repository + ${escapeHtml(plugin.repository)} +
` + : ""; + + const homepageHtml = + plugin.homepage && plugin.homepage !== plugin.repository + ? `
+ Homepage + ${escapeHtml(plugin.homepage)} +
` + : ""; + + const licenseHtml = plugin.license + ? `
+ License + ${escapeHtml(plugin.license)} +
` + : ""; + + const sourceHtml = plugin.source?.repo + ? `
+ Source + GitHub: ${escapeHtml(plugin.source.repo)}${plugin.source.path ? ` (${escapeHtml(plugin.source.path)})` : ""} +
` + : ""; + + const repoUrl = getExternalPluginUrl(plugin); + + modalContent.innerHTML = ` +
+
${escapeHtml(plugin.description || "")}
+ ${ + plugin.tags && plugin.tags.length > 0 + ? `
+ 🔗 External Plugin + ${plugin.tags.map((t) => `${escapeHtml(t)}`).join("")} +
` + : `
+ 🔗 External Plugin +
` + } +
+ ${authorHtml} + ${repoHtml} + ${homepageHtml} + ${licenseHtml} + ${sourceHtml} +
+
+ + View Repository → + +
+
+ This is an external plugin maintained outside this repository. Browse the repository to see its contents and installation instructions. +
+
+ `; +} + +/** + * Render modal content for a local plugin (item list) + */ +function renderLocalPluginModal( + plugin: Plugin, + modalContent: HTMLElement +): void { modalContent.innerHTML = `
${escapeHtml( diff --git a/website/src/scripts/pages/plugins.ts b/website/src/scripts/pages/plugins.ts index 32968b6b..01e1a547 100644 --- a/website/src/scripts/pages/plugins.ts +++ b/website/src/scripts/pages/plugins.ts @@ -3,9 +3,20 @@ */ import { createChoices, getChoicesValues, type Choices } from '../choices'; import { FuzzySearch, type SearchItem } from '../search'; -import { fetchData, debounce, escapeHtml, getGitHubUrl } from '../utils'; +import { fetchData, debounce, escapeHtml, getGitHubUrl, sanitizeUrl } from '../utils'; import { setupModal, openFileModal } from '../modal'; +interface PluginAuthor { + name: string; + url?: string; +} + +interface PluginSource { + source: string; + repo?: string; + path?: string; +} + interface Plugin extends SearchItem { id: string; name: string; @@ -13,6 +24,12 @@ interface Plugin extends SearchItem { tags?: string[]; featured?: boolean; itemCount: number; + external?: boolean; + repository?: string | null; + homepage?: string | null; + author?: PluginAuthor | null; + license?: string | null; + source?: PluginSource | null; } interface PluginsData { @@ -56,6 +73,15 @@ function applyFiltersAndRender(): void { if (countEl) countEl.textContent = countText; } +function getExternalPluginUrl(plugin: Plugin): string { + if (plugin.source?.source === 'github' && plugin.source.repo) { + const base = `https://github.com/${plugin.source.repo}`; + return plugin.source.path ? `${base}/tree/main/${plugin.source.path}` : base; + } + // Sanitize URLs from JSON to prevent XSS via javascript:/data: schemes + return sanitizeUrl(plugin.repository || plugin.homepage); +} + function renderItems(items: Plugin[], query = ''): void { const list = document.getElementById('resource-list'); if (!list) return; @@ -65,22 +91,35 @@ function renderItems(items: Plugin[], query = ''): void { return; } - list.innerHTML = items.map(item => ` -
+ list.innerHTML = items.map(item => { + const isExternal = item.external === true; + const metaTag = isExternal + ? `🔗 External` + : `${item.itemCount} items`; + const authorTag = isExternal && item.author?.name + ? `by ${escapeHtml(item.author.name)}` + : ''; + const githubHref = isExternal + ? escapeHtml(getExternalPluginUrl(item)) + : getGitHubUrl(item.path); + + return ` +
${item.featured ? '⭐ ' : ''}${query ? search.highlight(item.name, query) : escapeHtml(item.name)}
${escapeHtml(item.description || 'No description')}
- ${item.itemCount} items + ${metaTag} + ${authorTag} ${item.tags?.slice(0, 4).map(t => `${escapeHtml(t)}`).join('') || ''} ${item.tags && item.tags.length > 4 ? `+${item.tags.length - 4} more` : ''}
- GitHub + ${isExternal ? 'Repository' : 'GitHub'}
-
- `).join(''); +
`; + }).join(''); // Add click handlers list.querySelectorAll('.resource-item').forEach(el => { diff --git a/website/src/scripts/utils.ts b/website/src/scripts/utils.ts index 33eedaab..4b8e2a65 100644 --- a/website/src/scripts/utils.ts +++ b/website/src/scripts/utils.ts @@ -214,6 +214,24 @@ export function escapeHtml(text: string): string { return div.innerHTML; } +/** + * Validate and sanitize URLs to prevent XSS attacks + * Only allows http/https protocols, returns '#' for invalid URLs + */ +export function sanitizeUrl(url: string | null | undefined): string { + if (!url) return '#'; + try { + const parsed = new URL(url); + // Only allow http and https protocols + if (parsed.protocol === 'http:' || parsed.protocol === 'https:') { + return url; + } + } catch { + // Invalid URL + } + return '#'; +} + /** * Truncate text with ellipsis */ diff --git a/website/src/styles/global.css b/website/src/styles/global.css index 640b99bd..c6b4ffbc 100644 --- a/website/src/styles/global.css +++ b/website/src/styles/global.css @@ -900,6 +900,71 @@ body:has(#main-content) { color: var(--color-error); } +/* External plugin badge */ +.resource-tag-external { + background: var(--color-accent); + color: var(--color-bg); + font-weight: 500; +} + +/* External plugin modal metadata */ +.external-plugin-metadata { + display: flex; + flex-direction: column; + gap: 8px; + margin-bottom: 20px; + padding: 12px 16px; + background: var(--color-bg-tertiary); + border-radius: var(--border-radius); + border: 1px solid var(--color-border); +} + +.external-plugin-meta-row { + display: flex; + align-items: baseline; + gap: 12px; + font-size: 13px; + line-height: 1.5; +} + +.external-plugin-meta-label { + color: var(--color-text-muted); + font-weight: 500; + min-width: 80px; + flex-shrink: 0; +} + +.external-plugin-meta-value { + color: var(--color-text); + word-break: break-all; +} + +.external-plugin-meta-value a { + color: var(--color-accent); + text-decoration: none; +} + +.external-plugin-meta-value a:hover { + text-decoration: underline; +} + +.external-plugin-cta { + margin-bottom: 16px; +} + +.external-plugin-repo-btn { + display: inline-flex; + align-items: center; + gap: 6px; +} + +.external-plugin-note { + font-size: 13px; + color: var(--color-text-muted); + font-style: italic; + line-height: 1.5; +} + /* Page Layouts */ .page-header { padding: 56px 0 40px; From 15d17203756439ea5a1dab8e14039f7c60076ecd Mon Sep 17 00:00:00 2001 From: Aymen Date: Tue, 10 Mar 2026 00:43:28 +0100 Subject: [PATCH 27/37] Add Python Notebook Sample Builder agent (#945) --- .../python-notebook-sample-builder.agent.md | 45 +++++++++++++++++++ docs/README.agents.md | 1 + 2 files changed, 46 insertions(+) create mode 100644 agents/python-notebook-sample-builder.agent.md diff --git a/agents/python-notebook-sample-builder.agent.md b/agents/python-notebook-sample-builder.agent.md new file mode 100644 index 00000000..0bc7c8c3 --- /dev/null +++ b/agents/python-notebook-sample-builder.agent.md @@ -0,0 +1,45 @@ +--- +description: 'Custom agent for building Python Notebooks in VS Code that demonstrate Azure and AI features' +name: 'Python Notebook Sample Builder' +tools: ['vscode', 'execute', 'read', 'edit', 'search', 'web', 'mslearnmcp/*', 'agent', 'ms-python.python/getPythonEnvironmentInfo', 'ms-python.python/getPythonExecutableCommand', 'ms-python.python/installPythonPackage', 'ms-python.python/configurePythonEnvironment', 'ms-toolsai.jupyter/configureNotebook', 'ms-toolsai.jupyter/listNotebookPackages', 'ms-toolsai.jupyter/installNotebookPackages', 'todo'] +--- + +You are a Python Notebook Sample Builder. Your goal is to create polished, interactive Python notebooks that demonstrate Azure and AI features through hands-on learning. + +## Core Principles + +- **Test before you write.** Never include code in a notebook that you have not run and verified in the terminal first. If something errors, troubleshoot the SDK or API until you understand the correct usage. +- **Learn by doing.** Notebooks should be interactive and engaging. Minimize walls of text. Prefer short, crisp markdown cells that set up the next code cell. +- **Visualize everything.** Use built-in notebook visualization (tables, rich output) and common data science libraries (matplotlib, pandas, seaborn) to make results tangible. +- **No internal tooling.** Avoid any internal-only APIs, endpoints, packages, or configurations. All code must work with publicly available SDKs, services, and documentation. +- **No virtual environments.** We are working inside a devcontainer. Install packages directly. + +## Workflow + +1. **Understand the ask.** Read what the user wants demonstrated. The user's description is the master context. +2. **Research.** Use Microsoft Learn to investigate correct API usage and find code samples. Documentation may be outdated, so always validate against the actual SDK by running code locally first. +3. **Match existing style.** If the repository already contains similar notebooks, imitate their structure, style, and depth. +4. **Prototype in the terminal.** Run every code snippet before placing it in a notebook cell. Fix errors immediately. +5. **Build the notebook.** Assemble verified code into a well-structured notebook with: + - A title and brief intro (markdown) + - Prerequisites / setup cell (installs, imports) + - Logical sections that build on each other + - Visualizations and formatted output + - A summary or next-steps cell at the end +6. **Create a new file.** Always create a new notebook file rather than overwriting existing ones. + +## Notebook Structure Guidelines + +- **Title cell** — One `#` heading with a concise title. One sentence describing what the reader will learn. +- **Setup cell** — Install dependencies (`%pip install ...`) and import libraries. +- **Section cells** — Each section has a short markdown intro followed by one or more code cells. Keep markdown crisp: 2-3 sentences max per cell. +- **Visualization cells** — Use pandas DataFrames for tabular data, matplotlib/seaborn for charts. Add titles and labels. +- **Wrap-up cell** — Summarize what was covered and suggest next steps or further reading. + +## Style Rules + +- Use clear variable names and inline comments where the intent is not obvious. +- Prefer f-strings for string formatting. +- Keep code cells focused: one concept per cell. +- Use `display()` or rich DataFrame rendering instead of plain `print()` for tabular data. +- Add `# Section Title` comments at the top of code cells for scanability. diff --git a/docs/README.agents.md b/docs/README.agents.md index fe5e94a7..da15c825 100644 --- a/docs/README.agents.md +++ b/docs/README.agents.md @@ -147,6 +147,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-agents) for guidelines on how to | [Prompt Builder](../agents/prompt-builder.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fprompt-builder.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fprompt-builder.agent.md) | Expert prompt engineering and validation system for creating high-quality prompts - Brought to you by microsoft/edge-ai | | | [Prompt Engineer](../agents/prompt-engineer.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fprompt-engineer.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fprompt-engineer.agent.md) | A specialized chat mode for analyzing and improving prompts. Every user input is treated as a prompt to be improved. It first provides a detailed analysis of the original prompt within a tag, evaluating it against a systematic framework based on OpenAI's prompt engineering best practices. Following the analysis, it generates a new, improved prompt. | | | [Python MCP Server Expert](../agents/python-mcp-expert.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fpython-mcp-expert.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fpython-mcp-expert.agent.md) | Expert assistant for developing Model Context Protocol (MCP) servers in Python | | +| [Python Notebook Sample Builder](../agents/python-notebook-sample-builder.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fpython-notebook-sample-builder.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fpython-notebook-sample-builder.agent.md) | Custom agent for building Python Notebooks in VS Code that demonstrate Azure and AI features | | | [QA](../agents/qa-subagent.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fqa-subagent.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fqa-subagent.agent.md) | Meticulous QA subagent for test planning, bug hunting, edge-case analysis, and implementation verification. | | | [Reepl Linkedin](../agents/reepl-linkedin.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Freepl-linkedin.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Freepl-linkedin.agent.md) | AI-powered LinkedIn content creation, scheduling, and analytics agent. Create posts, carousels, and manage your LinkedIn presence with GitHub Copilot. | | | [Refine Requirement or Issue](../agents/refine-issue.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Frefine-issue.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Frefine-issue.agent.md) | Refine the requirement or issue with Acceptance Criteria, Technical Considerations, Edge Cases, and NFRs | | From cf4e33e1fd8d585af2206995504f3069d6242f7f Mon Sep 17 00:00:00 2001 From: Tadas Labudis Date: Mon, 9 Mar 2026 23:44:35 +0000 Subject: [PATCH 28/37] fix: improve github-issues skill trigger phrases and fix GraphQL dependency examples (#946) - Add dependency/blocking trigger phrases to skill description so the skill activates on requests like 'link issues', 'add dependency', 'blocked by', and 'blocking' - Fix incorrect GraphQL return field in dependencies.md: blockedByIssue does not exist on AddBlockedByPayload; the correct field is blockingIssue Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/README.skills.md | 2 +- skills/github-issues/SKILL.md | 2 +- skills/github-issues/references/dependencies.md | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/README.skills.md b/docs/README.skills.md index c5d3fdc1..4af14033 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -126,7 +126,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [git-commit](../skills/git-commit/SKILL.md) | Execute git commit with conventional commit message analysis, intelligent staging, and message generation. Use when user asks to commit changes, create a git commit, or mentions "/commit". Supports: (1) Auto-detecting type and scope from changes, (2) Generating conventional commit messages from diff, (3) Interactive commit with optional type/scope/description overrides, (4) Intelligent file staging for logical grouping | None | | [git-flow-branch-creator](../skills/git-flow-branch-creator/SKILL.md) | Intelligent Git Flow branch creator that analyzes git status/diff and creates appropriate branches following the nvie Git Flow branching model. | None | | [github-copilot-starter](../skills/github-copilot-starter/SKILL.md) | Set up complete GitHub Copilot configuration for a new project based on technology stack | None | -| [github-issues](../skills/github-issues/SKILL.md) | Create, update, and manage GitHub issues using MCP tools. Use this skill when users want to create bug reports, feature requests, or task issues, update existing issues, add labels/assignees/milestones, set issue fields (dates, priority, custom fields), set issue types, or manage issue workflows. Triggers on requests like "create an issue", "file a bug", "request a feature", "update issue X", "set the priority", "set the start date", or any GitHub issue management task. | `references/dependencies.md`
`references/images.md`
`references/issue-fields.md`
`references/issue-types.md`
`references/projects.md`
`references/search.md`
`references/sub-issues.md`
`references/templates.md` | +| [github-issues](../skills/github-issues/SKILL.md) | Create, update, and manage GitHub issues using MCP tools. Use this skill when users want to create bug reports, feature requests, or task issues, update existing issues, add labels/assignees/milestones, set issue fields (dates, priority, custom fields), set issue types, manage issue workflows, link issues, add dependencies, or track blocked-by/blocking relationships. Triggers on requests like "create an issue", "file a bug", "request a feature", "update issue X", "set the priority", "set the start date", "link issues", "add dependency", "blocked by", "blocking", or any GitHub issue management task. | `references/dependencies.md`
`references/images.md`
`references/issue-fields.md`
`references/issue-types.md`
`references/projects.md`
`references/search.md`
`references/sub-issues.md`
`references/templates.md` | | [go-mcp-server-generator](../skills/go-mcp-server-generator/SKILL.md) | Generate a complete Go MCP server project with proper structure, dependencies, and implementation using the official github.com/modelcontextprotocol/go-sdk. | None | | [image-manipulation-image-magick](../skills/image-manipulation-image-magick/SKILL.md) | Process and manipulate images using ImageMagick. Supports resizing, format conversion, batch processing, and retrieving image metadata. Use when working with images, creating thumbnails, resizing wallpapers, or performing batch image operations. | None | | [import-infrastructure-as-code](../skills/import-infrastructure-as-code/SKILL.md) | Import existing Azure resources into Terraform using Azure CLI discovery and Azure Verified Modules (AVM). Use when asked to reverse-engineer live Azure infrastructure, generate Infrastructure as Code from existing subscriptions/resource groups/resource IDs, map dependencies, derive exact import addresses from downloaded module source, prevent configuration drift, and produce AVM-based Terraform files ready for validation and planning across any Azure resource type. | None | diff --git a/skills/github-issues/SKILL.md b/skills/github-issues/SKILL.md index 18f2bd66..4619bacf 100644 --- a/skills/github-issues/SKILL.md +++ b/skills/github-issues/SKILL.md @@ -1,6 +1,6 @@ --- name: github-issues -description: 'Create, update, and manage GitHub issues using MCP tools. Use this skill when users want to create bug reports, feature requests, or task issues, update existing issues, add labels/assignees/milestones, set issue fields (dates, priority, custom fields), set issue types, or manage issue workflows. Triggers on requests like "create an issue", "file a bug", "request a feature", "update issue X", "set the priority", "set the start date", or any GitHub issue management task.' +description: 'Create, update, and manage GitHub issues using MCP tools. Use this skill when users want to create bug reports, feature requests, or task issues, update existing issues, add labels/assignees/milestones, set issue fields (dates, priority, custom fields), set issue types, manage issue workflows, link issues, add dependencies, or track blocked-by/blocking relationships. Triggers on requests like "create an issue", "file a bug", "request a feature", "update issue X", "set the priority", "set the start date", "link issues", "add dependency", "blocked by", "blocking", or any GitHub issue management task.' --- # GitHub Issues diff --git a/skills/github-issues/references/dependencies.md b/skills/github-issues/references/dependencies.md index 6b3b09c9..6ad7562a 100644 --- a/skills/github-issues/references/dependencies.md +++ b/skills/github-issues/references/dependencies.md @@ -44,7 +44,7 @@ mutation { issueId: "BLOCKED_ISSUE_NODE_ID" blockingIssueId: "BLOCKING_ISSUE_NODE_ID" }) { - blockedByIssue { number title } + blockingIssue { number title } } } ``` @@ -56,7 +56,7 @@ mutation { issueId: "BLOCKED_ISSUE_NODE_ID" blockingIssueId: "BLOCKING_ISSUE_NODE_ID" }) { - blockedByIssue { number title } + blockingIssue { number title } } } ``` From 52dd53d3a31a4d11b2112e13dbca204105933905 Mon Sep 17 00:00:00 2001 From: Aaron Powell Date: Tue, 10 Mar 2026 16:03:53 +1100 Subject: [PATCH 29/37] website tweaks (#952) * Adding nav to learning hub * Simplifying the home page * Fixing footer spacing --- website/src/components/Footer.astro | 68 +++++++++++++++++-- .../src/content/docs/learning-hub/index.md | 9 --- website/src/pages/index.astro | 33 --------- website/src/scripts/pages/index.ts | 39 ++--------- 4 files changed, 65 insertions(+), 84 deletions(-) diff --git a/website/src/components/Footer.astro b/website/src/components/Footer.astro index b46600a6..9b857bf0 100644 --- a/website/src/components/Footer.astro +++ b/website/src/components/Footer.astro @@ -1,22 +1,76 @@ --- -import type { Props } from '@astrojs/starlight/props'; -import Default from '@astrojs/starlight/components/Footer.astro'; +import EditLink from "@astrojs/starlight/components/EditLink.astro"; +import LastUpdated from "@astrojs/starlight/components/LastUpdated.astro"; +import Pagination from "@astrojs/starlight/components/Pagination.astro"; +import config from "virtual:starlight/user-config"; +import { Icon } from "@astrojs/starlight/components"; --- - + diff --git a/website/src/pages/workflows.astro b/website/src/pages/workflows.astro index dd4f4663..cdf22cbd 100644 --- a/website/src/pages/workflows.astro +++ b/website/src/pages/workflows.astro @@ -1,8 +1,13 @@ --- import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro'; +import workflowsData from '../../public/data/workflows.json'; import Modal from '../components/Modal.astro'; import ContributeCTA from '../components/ContributeCTA.astro'; +import EmbeddedPageData from '../components/EmbeddedPageData.astro'; import PageHeader from '../components/PageHeader.astro'; +import { renderWorkflowsHtml, sortWorkflows } from '../scripts/pages/workflows-render'; + +const initialItems = sortWorkflows(workflowsData.items, 'title'); --- @@ -13,36 +18,37 @@ import PageHeader from '../components/PageHeader.astro';
-
- - +
+
+ + +
+ +
+
+ + +
+
+ + +
+ +
-
-
- - -
-
- - -
- -
- -
-
-
Loading workflows...
-
+
{initialItems.length} of {initialItems.length} workflows
+
+