# Technical Documentation: microsoft/plugins > ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/microsoft/plugins) ### Overview (`README.md`) # Microsoft 365 Copilot plugin samples and cookbooks This repository provides samples and guided cookbooks for building plugins and their components for Microsoft 365 Copilot. A plugin can combine connectors, skills, and agents into a complete Copilot experience. Use the samples to explore working implementations, then follow the WIQD cookbooks to build, test, improve, and deliver your own plugins. ## What's in this repository | Content | Status | Explore | |---------|--------|---------| | Plugin samples | Two available | [Browse plugin samples](samples/plugins/) | | Connector samples | Coming soon | Standalone connector samples will be added to `samples/connectors/` | | Skill samples | Coming soon | Standalone skill samples will be added to `samples/skills/` | | WIQD cookbooks | Available | [Browse WIQD cookbooks](tools/wiqd/cookbooks/README.md) | ## Plugin samples | Sample | Components | What it demonstrates | |--------|------------|----------------------| | [Microsoft Learn Helper](samples/plugins/microsoft-learn-plugin/README.md) | Microsoft Learn MCP connector | A plugin that searches and reads current official Microsoft documentation and code samples through the public Microsoft Learn MCP server | | [Retirement Radar](samples/plugins/retirement-radar-plugin/README.md) | Microsoft Learn MCP connector and Retirement Radar skill | A plugin that checks code, scripts, configuration, and architecture notes for deprecated or retired Microsoft technologies and recommends supported replacements | More plugin samples are planned. Standalone connector and skill samples are coming soon. ## WIQD cookbooks The [WIQD cookbooks](tools/wiqd/cookbooks/README.md) are short, end-to-end recipes for creating and improving plugins with the [wiqd CLI](https://microsoft.github.io/wiqd/). They cover declarative agents, MCP connectors, skills, grounding, evaluation, debugging, portability, and team delivery. You can follow the cookbooks with the GitHub Copilot app or GitHub Copilot CLI: - **GitHub Copilot app:** open the **Default agent** selector and choose **wiqd**. - **GitHub Copilot CLI:** install it with `npm install @github/copilot`, then run `copilot --agent wiqd:wiqd`. See the [cookbook getting started guide](tools/wiqd/cookbooks/README.md#getting-started) for Node.js, WIQD, Microsoft 365, authentication, and Azure requirements. ## Contributing Contributions are welcome. Before opening an issue or pull request, read the [contribution guidelines](CONTRIBUTING.md) for the CLA requirement, cookbook standards, validation expectations, and review process. Contributions must be submitted by pull request from a fork; do not push contribution branches directly to this repository. Participation in this project is governed by the [Microsoft Open Source Code of Conduct](CODE_OF_CONDUCT.md). For help with these samples, see [SUPPORT.md](SUPPORT.md). Report suspected security vulnerabilities privately according to [SECURITY.md](SECURITY.md). ## Disclaimers > **wiqd is in preview.** Work IQ Dev Tools (wiqd) are currently in preview. Commands, APIs, and behaviors may change before the 1.0 release. See the [wiqd documentation](https://microsoft.github.io/wiqd/) for the latest information. > **Sample purposes only.** The plugins, components, and recipes in this repository are provided as samples for learning and demonstration purposes. They are not intended for production use. AI-generated responses may be inaccurate, incomplete, or inappropriate. Always review and validate plugin behavior before sharing with end users. ## Trademarks This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow [Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/legal/intellectualproperty/trademarks/usage/general). Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos is subject to those third parties' policies. --- ### Overview (`samples/plugins/microsoft-learn-plugin/README.md`) # Microsoft Learn Helper Microsoft Learn Helper is a Microsoft 365 Copilot plugin that searches and reads current official Microsoft documentation and code samples. The plugin connects to the public [Microsoft Learn MCP server](https://learn.microsoft.com/api/mcp). The connector is read-only and does not require an API key or user sign-in. ## What this sample demonstrates - Adding a remote MCP server as an agent connector - Describing MCP tools for Microsoft 365 Copilot - Searching current Microsoft documentation - Fetching complete documentation pages for additional context - Finding official code samples by language - Packaging and provisioning a connector plugin ## Try the plugin ### Prerequisites You need: - Access to Microsoft 365 Copilot Cowork - Permission to upload a custom plugin in your tenant - Copilot Credits for testing in Cowork ### 1. Upload the package Use the prebuilt [`package.zip`](package.zip), or build a package from the source files in [`appPackage/`](appPackage/). In Microsoft 365 Copilot Cowork: 1. Open the plugin inventory. 2. Select the option to upload a custom plugin. 3. Upload `package.zip`. 4. Find **Microsoft Learn Helper** and enable it for the current Cowork session. The connector uses anonymous access, so Cowork should not ask you to sign in. ### 2. Test the connector Try prompts such as: ```text Find the current Microsoft documentation for building a declarative agent. Summarize the prerequisites and cite the source. ``` ```text Find an official TypeScript code sample for authenticating with Microsoft Graph. Explain the sample and link to its source. ``` ```text Search Microsoft Learn for the latest Azure Functions Node.js guidance, then read the most relevant page and summarize its recommendations. ``` ## Available tools | Tool | Purpose | |------|---------| | `microsoft_docs_search` | Searches official Microsoft documentation and returns relevant excerpts and source URLs | | `microsoft_docs_fetch` | Fetches the complete content of a Microsoft documentation page | | `microsoft_code_sample_search` | Finds current code samples in official Microsoft documentation, optionally filtered by language | ## Project structure | File or folder | Purpose | |----------------|---------| | [`appPackage/manifest.json`](appPackage/manifest.json) | Defines the Microsoft Learn remote MCP connector | | [`appPackage/microsoft-learn-mcp-tools.json`](appPackage/microsoft-learn-mcp-tools.json) | Describes the MCP tools exposed to Copilot | | [`wiqd.plugin.json`](wiqd.plugin.json) | Identifies the project as a WIQD plugin with an agent connector | | [`m365agents.yml`](m365agents.yml) | Defines provisioning, validation, packaging, and publishing actions | | [`m365agents.local.yml`](m365agents.local.yml) | Defines the local provisioning workflow | ## Develop the sample This project includes Microsoft 365 Agents Toolkit lifecycle files. Open the project in VS Code with Microsoft 365 Agents Toolkit, then use its lifecycle commands to provision, package, validate, and publish the plugin to your development environment. You can also inspect and modify the plugin with [WIQD](https://microsoft.github.io/wiqd/). See the [Microsoft Learn MCP connector cookbook](../../../tools/wiqd/cookbooks/plugins/microsoft-learn-mcp/README.md) for a guided, end-to-end build of this sample. ## Important This sample is for learning and demonstration purposes. Review the manifest, developer information, descriptions, icons, and tenant policies before sharing or publishing a derived plugin. --- ### Overview (`samples/plugins/retirement-radar-plugin/README.md`) # Retirement Radar for Copilot Cowork Retirement Radar helps you find retired and deprecated Microsoft technology before an old script fails in production. Give Copilot Cowork a script, configuration file, package list, or architecture note. Retirement Radar checks every Microsoft API, SDK, PowerShell module, endpoint, and service it finds against live Microsoft Learn documentation, then returns: - A clear supported, deprecated, or retired verdict - Official retirement dates and Microsoft Learn sources - Supported replacements - Updated code based on official samples - A prioritized migration checklist ## Try the plugin ### Prerequisites You need: - Access to **Microsoft 365 Copilot Cowork** - Copilot Credits for testing in Cowork The plugin uses the public, read-only [Microsoft Learn MCP server](https://learn.microsoft.com/api/mcp). It does not require an API key or a connector sign-in. ### 1. Get the plugin package Use the prebuilt package: ```text appPackage.dev.zip ``` The ZIP must contain `manifest.json`, `mcp-tools.json`, the icons, and `skills/` at its root. Do not zip the `appPackage` folder itself. ### 2. Upload and enable it in Cowork 1. Open **Microsoft 365 Copilot Cowork**. 2. Open the plugin inventory. 3. Select the option to upload a custom plugin. 4. Upload `appPackage.dev.zip`. 5. Find **Retirement Radar** and enable it for the current Cowork session. The plugin should show: - The **Retirement Radar** skill - The **Microsoft Learn** connector The connector uses anonymous access, so Cowork should not ask you to sign in. ### 3. Run the demo Open [`demo/legacy-admin-script copy.txt`](demo/legacy-admin-script%20copy.txt), copy the complete script, and paste it into Cowork with this prompt: > Is this still safe to run tonight? Check it for retired Microsoft APIs. Retirement Radar should: 1. Inventory the Microsoft technologies in the script. 2. Check each one against current Microsoft Learn content. 3. Classify each finding as **Broken now**, **Breaking soon**, **Deprecated**, or **OK**. 4. Cite an official source for every dated claim. 5. Recommend supported replacements. The demo includes intentionally old technology such as: - MSOnline and AzureAD PowerShell - Azure AD Graph (`graph.windows.net`) - AzureRM PowerShell - Office 365 connectors in Teams Because Retirement Radar checks Microsoft Learn at runtime, its wording and findings can change as Microsoft updates the documentation. ### 4. Ask for the migration Continue in the same Cowork session: > Rewrite the whole script with the supported replacements. The plugin uses Microsoft Learn code samples to produce an updated PowerShell script while preserving the intent and variable names where possible. ## More prompts to try Retirement Radar can inspect more than PowerShell. Try it with application code, dependency files, infrastructure definitions, or architecture notes: ```text Check this project for deprecated Microsoft SDKs and APIs. Cite an official source for every finding. ``` ```text Which dependencies in this package file need migration within the next 12 months? ``` ```text This integration started returning 403 errors. Check whether any Microsoft endpoint or authentication library in it has been retired. ``` ```text Create a prioritized migration plan, then rewrite only the broken parts. ``` Do not paste live secrets, access tokens, connection strings, or production webhook URLs into the chat. Replace them with redacted values first. ## What is in the plugin ```text appPackage/ ├── manifest.json ├── mcp-tools.json ├── color.png ├── outline.png └── skills/ └── retirement-radar/ ├── SKILL.md └── references/ └── report-template.md ``` Retirement Radar is a standard Microsoft 365 app package for Copilot Cowork: | Component | Purpose | |---|---| | `agentSkills[0]` | Registers the `retirement-radar` workflow from `skills/retirement-radar/SKILL.md` | | `agentConnectors[0]` | Connects Cowork to the remote Microsoft Learn MCP server | | `mcp-tools.json` | Describes the Microsoft Learn tools exposed to the skill | There is no declarative agent or hosted backend in this package. The skill contains the workflow, and the connector provides live Microsoft Learn search, page retrieval, and code-sample tools. ## Troubleshooting ### The plugin does not appear in Cowork - Confirm that `appPackage.dev.zip` uploaded successfully. - Reopen the plugin inventory after the upload completes. - Check that the plugin is installed and enabled for the current session. ### The package upload fails - Open the ZIP and confirm `manifest.json` is at the root. - Confirm `skills/retirement-radar/SKILL.md` exists with that exact capitalization. - Confirm the ZIP contains `mcp-tools.json`, `color.png`, and `outline.png`. - Do not place a parent `appPackage/` directory inside the ZIP. ### The skill does not activate Use an explicit prompt containing phrases such as **retired**, **deprecated**, **still supported**, or **check Microsoft dependencies**. Also confirm that Retirement Radar is enabled in the Cowork session. ### Microsoft Learn results are unavailable The skill depends on `https://learn.microsoft.com/api/mcp`. Confirm that your organization allows Cowork to reach that HTTPS endpoint. ## Learn more - [Copilot Camp: Build your first Copilot Cowork plugin](https://microsoft.github.io/copilot-camp/pages/copilot-cowork/02-cowork-plugins/) --- ### Overview (`tools/wiqd/cookbooks/README.md`) # wiqd plugin cookbooks wiqd cookbooks are short, end-to-end recipes for building and improving plugins for Microsoft 365 Copilot. A plugin can bring together skills, connectors (including MCP connectors), and agents. A declarative agent is one type of agent component. Some recipes focus on one component, while others show how to combine them into a more capable plugin. Each recipe is built around one clear outcome: **build it → make it do something → make it safe → make it good → make it grounded.** ## Getting started Before running any cookbook, make sure you have these installed and configured: ### 1. Install Node.js 24+ wiqd requires Node.js 24 or later. Install via your preferred method: ```bash # macOS / Linux (via nvm) nvm install 24 && nvm use 24 # Windows (via fnm) fnm install 24 && fnm use 24 ``` ### 2. Install wiqd CLI ```bash # macOS / Linux curl -fsSL https://aka.ms/wiqd/install.sh | bash # Windows (PowerShell) iex "& { $(irm 'https://aka.ms/wiqd/install.ps1') }" ``` Verify the installation: ```bash wiqd --version ``` ### 3. Choose how to use the WIQD Copilot agent You can run these recipes in the GitHub Copilot app or the standalone [GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli/set-up-copilot-cli/install-copilot-cli). In the GitHub Copilot app, open the agent selector labeled **Default agent** and choose **wiqd**. No CLI installation is required. If you prefer the CLI, install it: ```bash # Install on any platform with Node.js 22 or later npm install @github/copilot # Verify that the standalone CLI supports custom agents copilot --help ``` Confirm that the help output includes the `--agent` option before continuing. If it does not, check which executable your shell resolves for `copilot`, then reinstall the standalone CLI. Start the WIQD agent with: ```bash copilot --agent wiqd:wiqd ``` ### 4. Sign in to your Microsoft 365 account You need a Microsoft 365 account with access to Copilot and an Azure subscription for provisioning plugin components and required resources. Start an interactive sign-in: ```bash wiqd auth login --interactive ``` On macOS and Linux, this normally opens your system browser. Sign in with the work or school account for the tenant where you want to provision the agent, then complete any consent or multi-factor authentication prompts. `wiqd` delegates authentication to its installed providers, so you may see more than one provider reported in the terminal. Confirm that the intended account is signed in: ```bash wiqd auth status ``` If the status shows an account from the wrong tenant, sign out and repeat the interactive login, choosing the correct account in the browser: ```bash wiqd auth logout wiqd auth login --interactive ``` See the [wiqd authentication guide](https://microsoft.github.io/wiqd/getting-started/authentication/) for provider details and troubleshooting. ### 5. Confirm everything is ready ```bash wiqd doctor ``` This checks your environment for common issues (Node version, auth status, CLI version). --- ## Start with a guided plugin recipe New to wiqd? Begin with one of these self-contained recipes. Each takes you from setup to a working plugin and shows you how to test its core behavior. You can use the resulting plugin project as a starting point for the extension and lifecycle recipes in the next section. | Recipe | Primary component | What you'll build | |--------|-------------------|-------------------| | [Zero to agent, live in Copilot](./declarative-agents/zero-to-agent/README.md) | Declarative agent | Scaffold, provision, and open your first agent | | [Translator agent](./declarative-agents/translator-agent/README.md) | Declarative agent | Translate text into any language | | [Photobooth agent](./declarative-agents/photobooth-agent/README.md) | Declarative agent | Apply effects and create photobooth-style image composites | | [Mind Your Language agent](./declarative-agents/mind-your-language-agent/README.md) | Declarative agent | Coach tone and rewrite passive-aggressive text | | [Zava Insurance agent (MCP)](./declarative-agents/insurance-agent-mcp/README.md) | Declarative agent | Connect an agent to an MCP server for live insurance data | | [Demo Planning agent](./declarative-agents/demo-planning-agent/README.md) | Declarative agent | Plan demos, workshops, hackathons, and presentations | | [Microsoft Learn MCP connector](./plugins/microsoft-learn-mcp/README.md) | Connector (MCP) | Create and test a plugin with a public, no-auth MCP connector | ## Extend and improve your plugin Use these recipes to add components and capabilities or work on a later stage of the plugin lifecycle. Some build on a specific guided recipe, while others work with any existing plugin or declarative-agent component. Check **Start with** before you begin. | Recipe | Focus | Start with | What you'll learn | |--------|-------|------------|-------------------| | [Ground an existing agent in your SharePoint content](./declarative-agents/sharepoint-knowledge-agent/README.md) | Grounding | An existing declarative agent, such as [Zero to agent](./declarative-agents/zero-to-agent/README.md) | Scope organizational knowledge, require grounded answers, and verify citations | | [Build a public web research agent](./declarative-agents/public-web-research-agent/README.md) | Research | An existing declarative agent | Scope research to approved public sites and produce source-backed answers | | [Upgrade the Learn connector into a technology advisor](./plugins/learn-tech-advisor/README.md) | Composition | [Microsoft Learn MCP connector](./plugins/microsoft-learn-mcp/README.md) | Combine a reusable plugin skill with a declarative agent | | [Hill-climb agent quality with evals](./lifecycle/eval-hill-climb/README.md) | Evaluation | An existing working agent | Measure quality, diagnose failures, improve behavior, and compare results | | [Debug an agent in DevUI](./lifecycle/devui-debugging/README.md) | Debugging | An existing agent with a test scenario | Inspect tool selection, execution, grounding, citations, and failures | | [Deliver an agent to a team](./lifecycle/team-delivery/README.md) | Delivery | A validated agent | Validate a package, configure shared scope, and target distribution | | [Round-trip a plugin across formats](./plugins/plugin-portability/README.md) | Portability | An existing plugin | Export and re-import Agent Plugin, Claude, and Cursor formats | > All recipes support the GitHub Copilot app and GitHub Copilot CLI. In the > app, choose **wiqd** from the **Default agent** selector. In the CLI, start > the agent with `copilot --agent wiqd:wiqd`. Recipes also use `wiqd` CLI > commands. ## Authors and contributors
Rabia Williams
Rabia Williams
@rabwill		 Sébastien Levert
Sébastien Levert
@sebastienlevert
--- ### Overview (`tools/wiqd/cookbooks/declarative-agents/demo-planning-agent/README.md`) # Demo Planning agent: interactive lab Build and open a Microsoft 365 Copilot agent that plans demos, workshops, hackathons, presentations, and customer conversations. This README is organized like a notebook: run one cell at a time, confirm its checkpoint, and then continue. > [!NOTE] > Markdown cannot execute commands directly. Run terminal commands in a > terminal, enter prompts in the GitHub Copilot app or CLI, and keep the same > Copilot conversation open for all remaining steps. ## Before you start You need: - Node.js 24 or later - `wiqd` installed and signed in - Access to the GitHub Copilot app or GitHub Copilot CLI - Permission to provision an agent to a dev environment ### Step 1: Check the environment > [!NOTE] > See [Getting started](../../README.md#getting-started) in the cookbook README for wiqd prerequisites and installation instructions. ```bash node --version wiqd --version wiqd doctor ``` If you plan to use the CLI, also run `copilot --version`. **Checkpoint:** Node reports version 24 or later, and the commands for your chosen workflow complete successfully. ## Build the agent ### Step 2: Create the workspace ```bash mkdir -p demo-planning && cd demo-planning ``` ### Step 3: Start Copilot In the GitHub Copilot app, open the **Default agent** selector and choose **wiqd**. If you prefer the CLI, run: ```bash copilot --agent wiqd:wiqd ``` Start with a clean conversation: ```text /clear ``` ### Step 4: Scaffold the agent Enter this prompt in the same Copilot session: ```text Create a new declarative agent called Demo Planner that helps users plan professional demos, workshops, hackathons, presentations, and customer conversations. Ask about the audience, goals, time constraints, format, and technology, then generate a structured plan with an agenda, talking points, demo scripts, fallback options, and preparation checklists. ``` Review and approve the proposed file changes. **Checkpoint:** the current directory contains a new agent project with manifest and instruction files. ### Step 5: Review the instructions Confirm the generated instructions tell the agent to: - Ask about the audience, event type, duration, goals, and technology - Create an agenda with time allocations - Provide talking points and transitions - Include step-by-step demo actions and fallback plans - Produce a preparation checklist - Adapt depth and tone to technical, executive, or mixed audiences - Handle follow-up changes to the plan Ask Copilot to correct any missing behavior. Keep this Copilot session open for the remaining steps. ## Run the agent ### Step 6: Move into the agent project Copilot reports the path of the project it created. Move the current session into that project root: ```text /cwd ``` Replace the placeholder with the path Copilot reported. **Checkpoint:** the current directory contains the agent's `appPackage` directory and lifecycle configuration file. ### Step 7: Validate locally Enter this prompt in the same Copilot session: ```text Validate the agent with wiqd. If validation reports errors, explain them and help me fix them before continuing. ``` **Checkpoint:** validation completes without errors. ### Step 8: Provision to dev Enter this prompt in the same Copilot session: ```text Provision the agent to the dev environment with wiqd. ``` **Checkpoint:** provisioning succeeds and returns a Microsoft 365 Copilot share link. ### Step 9: Open in Copilot Enter this prompt in the same Copilot session: ```text Open the provisioned agent in Microsoft 365 Copilot with wiqd. ``` ## Try it | Prompt | Expected behavior | |---|---| | `Plan a 30-minute product demo for enterprise customers` | Asks for key details and returns a timed agenda | | `Plan a 2-hour hackathon kickoff for 50 developers` | Creates a timeline for setup, introduction, hacking, and judging | | `Add a 10-minute Q&A at the end` | Updates the plan and adjusts its time allocations | ## Reset the lab From the parent directory of `demo-planning`: ```bash rm -rf demo-planning ``` Deleting the local folder does not remove provisioned resources. --- Return to the [cookbook index](../../README.md). --- ### Overview (`tools/wiqd/cookbooks/declarative-agents/insurance-agent-mcp/README.md`) # Zava Insurance agent: interactive MCP lab Build and open a Microsoft 365 Copilot agent connected to the Zava Insurance MCP server. This README is organized like a notebook: run one cell at a time, confirm its checkpoint, and then continue. > [!NOTE] > Markdown cannot execute commands directly. Run terminal commands in a > terminal, enter prompts in the GitHub Copilot app or CLI, and keep the same > Copilot conversation open for all remaining steps. ## Before you start You need: - Node.js 24 or later - `wiqd` installed and signed in - Access to the GitHub Copilot app or GitHub Copilot CLI - Permission to provision an agent to a dev environment - Access to `https://zava-insurance-mcp.azurewebsites.net/mcp` ### Step 1: Check the environment > [!NOTE] > See [Getting started](../../README.md#getting-started) in the cookbook README for wiqd prerequisites and installation instructions. ```bash node --version wiqd --version wiqd doctor ``` If you plan to use the CLI, also run `copilot --version`. **Checkpoint:** Node reports version 24 or later, and the commands for your chosen workflow complete successfully. ## Build the agent ### Step 2: Create the workspace ```bash mkdir -p zava-insurance && cd zava-insurance ``` ### Step 3: Start Copilot In the GitHub Copilot app, open the **Default agent** selector and choose **wiqd**. If you prefer the CLI, run: ```bash copilot --agent wiqd:wiqd ``` Start with a clean conversation: ```text /clear ``` ### Step 4: Scaffold the agent Enter this prompt in the same Copilot session: ```text Create a new declarative agent called Zava Insurance that helps users inspect claims, find contractors and inspectors, and perform controlled claim operations. ``` Review and approve the proposed file changes. **Checkpoint:** the current directory contains a new agent project with manifest and instruction files. ### Step 5: Add the MCP action Enter this prompt in the same Copilot session: ```text Add a remote MCP action to the Zava Insurance agent using https://zava-insurance-mcp.azurewebsites.net/mcp with no authentication. Use the supported WIQD agent add action command and inspect the server's current tools before updating the agent instructions. ``` Review and approve the manifest changes. ### Step 6: Review the configuration Confirm the generated project includes: - The MCP endpoint `https://zava-insurance-mcp.azurewebsites.net/mcp` - An MCP action in the agent manifest with `None` authentication - Read workflows using `show-claims-dashboard`, `show-claim-detail`, `show-contractors`, `get-claim-summary`, and `list-inspectors` - Instructions that summarize the exact proposed change and wait for explicit confirmation in a separate user turn before calling `update-claim-status`, `update-inspection`, `update-purchase-order`, or `create-inspection` Ask Copilot to correct any missing configuration. Keep this Copilot session open for the remaining steps. ## Run the agent ### Step 7: Move into the agent project Copilot reports the path of the project it created. Move the current session into that project root: ```text /cwd ``` Replace the placeholder with the path Copilot reported. **Checkpoint:** the current directory contains the agent's `appPackage` directory and lifecycle configuration file. ### Step 8: Validate locally Enter this prompt in the same Copilot session: ```text Validate the agent with wiqd. If validation reports errors, explain them and help me fix them before continuing. ``` **Checkpoint:** validation completes without errors. ### Step 9: Provision to dev Enter this prompt in the same Copilot session: ```text Provision the agent to the dev environment with wiqd. ``` **Checkpoint:** provisioning succeeds and returns a Microsoft 365 Copilot share link. ### Step 10: Open in Copilot Enter this prompt in the same Copilot session: ```text Show me the Microsoft 365 Copilot launch URL for the provisioned dev agent. ``` ## Try it | Prompt | Expected behavior | |---|---| | `Summarize claim CN202504990.` | Calls `get-claim-summary` or `show-claim-detail` and reports the live demo result | | `Show preferred contractors for water damage.` | Calls `show-contractors` with the relevant filters | | `Change claim 1 to Closed and add a completion note.` | Describes the exact update and asks for confirmation without calling the write tool yet | ## Reset the lab From the parent directory of `zava-insurance`: ```bash rm -rf zava-insurance ``` Deleting the local folder does not remove provisioned resources. --- Return to the [cookbook index](../../README.md). --- ### Overview (`tools/wiqd/cookbooks/declarative-agents/mind-your-language-agent/README.md`) # Mind Your Language agent: interactive lab Build and open a Microsoft 365 Copilot tone coach that rewrites passive-aggressive, sarcastic, or harsh messages. This README is organized like a notebook: run one cell at a time, confirm its checkpoint, and then continue. > [!NOTE] > Markdown cannot execute commands directly. Run terminal commands in a > terminal, enter prompts in the GitHub Copilot app or CLI, and keep the same > Copilot conversation open for all remaining steps. ## Before you start You need: - Node.js 24 or later - `wiqd` installed and signed in - Access to the GitHub Copilot app or GitHub Copilot CLI - Permission to provision an agent to a dev environment ### Step 1: Check the environment > [!NOTE] > See [Getting started](../../README.md#getting-started) in the cookbook README for wiqd prerequisites and installation instructions. ```bash node --version wiqd --version wiqd doctor ``` If you plan to use the CLI, also run `copilot --version`. **Checkpoint:** Node reports version 24 or later, and the commands for your chosen workflow complete successfully. ## Build the agent ### Step 2: Create the workspace ```bash mkdir -p mind-your-language && cd mind-your-language ``` ### Step 3: Start Copilot In the GitHub Copilot app, open the **Default agent** selector and choose **wiqd**. If you prefer the CLI, run: ```bash copilot --agent wiqd:wiqd ``` Start with a clean conversation: ```text /clear ``` ### Step 4: Scaffold the agent Enter this prompt in the same Copilot session: ```text Create a new declarative agent called Mind Your Language that acts as a tone coach. When a user pastes text, detect passive-aggressive, sarcastic, or unkind phrasing and rewrite it in a kinder, more constructive tone. Explain what changed and why, and offer alternative phrasings ranked from most direct to most gentle. If the text is already kind, confirm that no changes are needed. ``` Review and approve the proposed file changes. **Checkpoint:** the current directory contains a new agent project with manifest and instruction files. ### Step 5: Review the instructions Confirm the generated instructions tell the agent to: - Detect passive-aggressive, sarcastic, or harsh phrasing - Identify phrases that could land poorly - Preserve the original intent in a kinder rewrite - Briefly explain why each change improves the tone - Offer two or three alternatives from direct to gentle - Leave already-kind text unchanged Ask Copilot to correct any missing behavior. Keep this Copilot session open for the remaining steps. ## Run the agent ### Step 6: Move into the agent project Copilot reports the path of the project it created. Move the current session into that project root: ```text /cwd ``` Replace the placeholder with the path Copilot reported. **Checkpoint:** the current directory contains the agent's `appPackage` directory and lifecycle configuration file. ### Step 7: Validate locally Enter this prompt in the same Copilot session: ```text Validate the agent with wiqd. If validation reports errors, explain them and help me fix them before continuing. ``` **Checkpoint:** validation completes without errors. ### Step 8: Provision to dev Enter this prompt in the same Copilot session: ```text Provision the agent to the dev environment with wiqd. ``` **Checkpoint:** provisioning succeeds and returns a Microsoft 365 Copilot share link. ### Step 9: Open in Copilot Enter this prompt in the same Copilot session: ```text Open the provisioned agent in Microsoft 365 Copilot with wiqd. ``` ## Try it | Prompt | Expected behavior | |---|---| | `Per my last email, I already explained this.` | Flags the passive-aggressive phrase and offers kinder rewrites | | `Great job finishing that a week late.` | Detects sarcasm and suggests a constructive alternative | | `Thanks for your help today!` | Confirms the positive tone and suggests no changes | ## Reset the lab From the parent directory of `mind-your-language`: ```bash rm -rf mind-your-language ``` Deleting the local folder does not remove provisioned resources. --- Return to the [cookbook index](../../README.md). --- ### Overview (`tools/wiqd/cookbooks/declarative-agents/photobooth-agent/README.md`) # Photobooth agent: interactive lab Build and open a Microsoft 365 Copilot agent that turns uploaded images into photobooth-style composites. This README is organized like a notebook: run one cell at a time, confirm its checkpoint, and then continue. > [!NOTE] > Markdown cannot execute commands directly. Run terminal commands in a > terminal, enter prompts in the GitHub Copilot app or CLI, and keep the same > Copilot conversation open for all remaining steps. ## Before you start You need: - Node.js 24 or later - `wiqd` installed and signed in - Access to the GitHub Copilot app or GitHub Copilot CLI - Permission to provision an agent to a dev environment ### Step 1: Check the environment > [!NOTE] > See [Getting started](../../README.md#getting-started) in the cookbook README for wiqd prerequisites and installation instructions. ```bash node --version wiqd --version wiqd doctor ``` If you plan to use the CLI, also run `copilot --version`. **Checkpoint:** Node reports version 24 or later, and the commands for your chosen workflow complete successfully. ## Build the agent ### Step 2: Create the workspace ```bash mkdir -p photobooth-agent && cd photobooth-agent ``` ### Step 3: Start Copilot In the GitHub Copilot app, open the **Default agent** selector and choose **wiqd**. If you prefer the CLI, run: ```bash copilot --agent wiqd:wiqd ``` Start with a clean conversation: ```text /clear ``` ### Step 4: Scaffold the agent Enter this prompt in the same Copilot session: ```text Create a new declarative agent called Photobooth that accepts user-uploaded images and creates photobooth-style image responses. Apply creative filters such as black-and-white, sepia, pop-art, and sketch. Combine multiple styled versions into a single photobooth strip and return the composite image. Let users request specific styles or regenerate the result with different effects. ``` Review and approve the proposed file changes. **Checkpoint:** the current directory contains a new agent project with manifest and instruction files. ### Step 5: Review the instructions Confirm the generated instructions tell the agent to: - Accept one or more user-uploaded images - Apply black-and-white, sepia, pop-art, and sketch styles - Arrange styled images in a 2-by-2 or 1-by-4 strip - Return the composite image directly in chat - Honor requests for specific styles or regeneration Ask Copilot to correct any missing behavior. Keep this Copilot session open for the remaining steps. ## Run the agent ### Step 6: Move into the agent project Copilot reports the path of the project it created. Move the current session into that project root: ```text /cwd ``` Replace the placeholder with the path Copilot reported. **Checkpoint:** the current directory contains the agent's `appPackage` directory and lifecycle configuration file. ### Step 7: Validate locally Enter this prompt in the same Copilot session: ```text Validate the agent with wiqd. If validation reports errors, explain them and help me fix them before continuing. ``` **Checkpoint:** validation completes without errors. ### Step 8: Provision to dev Enter this prompt in the same Copilot session: ```text Provision the agent to the dev environment with wiqd. ``` **Checkpoint:** provisioning succeeds and returns a Microsoft 365 Copilot share link. ### Step 9: Open in Copilot Enter this prompt in the same Copilot session: ```text Open the provisioned agent in Microsoft 365 Copilot with wiqd. ``` ## Try it | Prompt | Expected behavior | |---|---| | Upload a photo and ask `Create a photobooth strip` | Returns four styled versions in one composite | | `Make it all pop-art style` | Regenerates every frame in pop-art style | | Upload two photos and ask `Combine these into a photobooth` | Uses both images with different effects | ## Reset the lab From the parent directory of `photobooth-agent`: ```bash rm -rf photobooth-agent ``` Deleting the local folder does not remove provisioned resources. --- Return to the [cookbook index](../../README.md). --- ### Overview (`tools/wiqd/cookbooks/declarative-agents/public-web-research-agent/README.md`) # Build a public web research agent Create a research agent grounded in two public, authoritative sources: Microsoft Learn and Microsoft-owned GitHub repositories. This demonstrates site-scoped web grounding without private tenant content. ## Before you start - Complete [Getting started](../../README.md#getting-started). - Run from a parent directory where `microsoft-tech-radar` does not already exist. ## Build and validate Start one interactive Copilot session. In the GitHub Copilot app, open the **Default agent** selector and choose **wiqd**. If you prefer the CLI, run: ```bash copilot --agent wiqd:wiqd ``` Enter: ```text Create a declarative agent project named microsoft-tech-radar and make the generated project root the current working directory. Call the agent Microsoft Tech Radar. Add WebSearch grounded only in these sites: - https://learn.microsoft.com/ - https://github.com/microsoft/ Instruct it to prefer current official documentation, cite every factual recommendation, distinguish documented facts from its recommendation, and state when it cannot find current evidence. Add conversation starters for feature research, migration research, and repository discovery. Run static validation and stop before provisioning. ``` **Checkpoint:** validation passes and the WebSearch capability contains only the two public source scopes. ## Provision and test Enter: ```text Provision Microsoft Tech Radar to the dev environment and show me its Microsoft 365 Copilot launch URL. ``` Open the returned URL and try: | Prompt | Expected behavior | |---|---| | `What is the current guidance for connecting an MCP server to Microsoft 365 Copilot?` | Uses current Microsoft Learn pages and cites them | | `Find a Microsoft-owned GitHub repository related to declarative agents.` | Uses the scoped GitHub source and links the repository | | `Recommend an approach and separate the facts from your recommendation.` | Labels sourced facts and its recommendation distinctly | **Checkpoint:** answers contain links from the configured public sources rather than unsupported claims. --- Return to the [cookbook index](../../README.md). --- ### Overview (`tools/wiqd/cookbooks/declarative-agents/sharepoint-knowledge-agent/README.md`) # Ground an existing agent in your SharePoint content Upgrade an existing declarative agent so it answers only from a SharePoint site or folder you are authorized to use. This lab focuses on source scoping, citations, and grounded-only behavior instead of repeating project scaffolding. ## Before you start - Complete [Getting started](../../README.md#getting-started). - Start in an existing, statically validated declarative-agent project. The [Zero to agent](../zero-to-agent/README.md) project is sufficient. - Choose one SharePoint site, library, or folder that your signed-in account can read. - Pick one fact that exists in the selected content and one question that the content cannot answer. ## Add organizational grounding Start one interactive Copilot session from the existing agent project root. In the GitHub Copilot app, open the **Default agent** selector and choose **wiqd**. If you prefer the CLI, run: ```bash copilot --agent wiqd:wiqd ``` Enter: ```text I want to ground this existing agent in one SharePoint source. Inspect the current manifest and instructions, then ask me for the exact SharePoint site, library, or folder URL that I am authorized to use. Do not change the project until I provide it. ``` When Copilot asks for the source, enter: ```text Use this SharePoint URL and no other tenant content: Scope the OneDriveAndSharePoint capability to exactly that URL. Preserve the agent's existing purpose, upgrade the declarative-agent schema only if required, set discourage_model_knowledge to true, and update the instructions and conversation starters so answers cite the document used. If the source is unavailable or does not contain the answer, say so instead of guessing. Run static validation and stop before provisioning. ``` **Checkpoint:** validation passes, the existing agent retains its original purpose, and its new grounding scope contains only the URL you supplied. ## Deploy the update Enter: ```text Provision the updated agent to its existing development environment and show me the Microsoft 365 Copilot launch URL. ``` Open the returned URL and test: | Prompt | Expected behavior | |---|---| | Ask about the fact selected before starting | Answers from the configured content and cites the source | | Ask for the title or summary of a document in the scoped folder | Retrieves only from the supplied location | | Ask the deliberately unanswerable question | States that the configured source does not contain the answer | **Checkpoint:** the added organizational grounding is observable without turning the recipe into another first-agent walkthrough. --- Return to the [cookbook index](../../README.md). --- ### Overview (`tools/wiqd/cookbooks/declarative-agents/translator-agent/README.md`) # Translator agent: interactive lab Build and open a Microsoft 365 Copilot agent that translates text into any requested language. This README is organized like a notebook: run one cell at a time, confirm its checkpoint, and then continue. > [!NOTE] > Markdown cannot execute commands directly. Run terminal commands in a > terminal, enter prompts in the GitHub Copilot app or CLI, and keep the same > Copilot conversation open for all remaining steps. ## Before you start You need: - Node.js 24 or later - `wiqd` installed and signed in - Access to the GitHub Copilot app or GitHub Copilot CLI - Permission to provision an agent to a dev environment ### Step 1: Check the environment > [!NOTE] > See [Getting started](../../README.md#getting-started) in the cookbook README for wiqd prerequisites and installation instructions. ```bash node --version wiqd --version wiqd doctor ``` If you plan to use the CLI, also run `copilot --version`. **Checkpoint:** Node reports version 24 or later, and the commands for your chosen workflow complete successfully. ## Build the agent ### Step 2: Create the workspace ```bash mkdir -p translator-agent && cd translator-agent ``` **Checkpoint:** your terminal is now in the `translator-agent` directory. ### Step 3: Start Copilot In the GitHub Copilot app, open the **Default agent** selector and choose **wiqd**. If you prefer the CLI, run: ```bash copilot --agent wiqd:wiqd ``` The remaining prompts in this section belong inside that Copilot session. Start with a clean conversation: ```text /clear ``` ### Step 4: Scaffold the agent Enter this prompt in the same Copilot session: ```text Create a new declarative agent called Translator that translates text into any language the user requests. Ask for the target language when it is not specified, preserve the source formatting and tone, and return only the translated text without explanation. Support follow-up requests such as "now in French" by translating the previous source text again. ``` Review and approve the file changes Copilot proposes. **Checkpoint:** the current directory contains a new agent project with manifest and instruction files. ### Step 5: Review the instructions Confirm the generated instructions tell the agent to: - Detect the target language from the user's request - Ask for a target language when none is specified - Translate faithfully while preserving tone and formatting - Return only the translated text, with no preamble or explanation - Re-translate the previous source text for follow-up requests Ask Copilot to correct any missing behavior before continuing. Keep this Copilot session open for the remaining steps. ## Run the agent ### Step 6: Move into the agent project Copilot reports the path of the project it created. Move the current session into that project root: ```text /cwd ``` Replace the placeholder with the path Copilot reported. **Checkpoint:** the current directory contains the agent's `appPackage` directory and lifecycle configuration file. ### Step 7: Validate locally Enter this prompt in the same Copilot session: ```text Validate the agent with wiqd. If validation reports errors, explain them and help me fix them before continuing. ``` **Checkpoint:** validation completes without errors. ### Step 8: Provision to dev Enter this prompt in the same Copilot session: ```text Provision the agent to the dev environment with wiqd. ``` **Checkpoint:** provisioning succeeds and returns a Microsoft 365 Copilot share link. ### Step 9: Open in Copilot Enter this prompt in the same Copilot session: ```text Open the provisioned agent in Microsoft 365 Copilot with wiqd. ``` **Checkpoint:** the Translator agent opens in Microsoft 365 Copilot. ## Try it | Prompt | Expected behavior | |---|---| | `Translate "Good morning, how are you?" to Japanese` | Returns only the Japanese translation | | `Now in Spanish` | Translates the original text into Spanish | | `Translate "Hello world"` | Asks which target language you want | ## Reset the lab To remove only the local trial project, close Copilot and run this from the parent directory of `translator-agent`: ```bash rm -rf translator-agent ``` Provisioned resources are not removed by deleting the local folder. Use the appropriate `wiqd` cleanup command for your environment if you also want to remove the provisioned agent. --- Return to the [cookbook index](../../README.md). --- ### Overview (`tools/wiqd/cookbooks/declarative-agents/zero-to-agent/README.md`) # Zero to agent: interactive lab Build and open a Microsoft 365 Copilot agent from an empty folder. This README is organized like a notebook: run one cell at a time, confirm its checkpoint, and then continue. > [!NOTE] > Markdown cannot execute commands directly. Run terminal commands in a > terminal, enter prompts in the GitHub Copilot app or CLI, and keep the same > Copilot conversation open for all remaining steps. ## Before you start You need: - Node.js 24 or later - `wiqd` installed and signed in - Access to the GitHub Copilot app or GitHub Copilot CLI - Permission to provision an agent to a dev environment ### Step 1: Check the environment > [!NOTE] > See [Getting started](../../README.md#getting-started) in the cookbook README for wiqd prerequisites and installation instructions. Run in a terminal: ```bash node --version wiqd --version wiqd doctor ``` If you plan to use the CLI, also run `copilot --version`. **Checkpoint:** Node reports version 24 or later, and the commands for your chosen workflow complete successfully. ## Build the agent ### Step 2: Create the workspace ```bash mkdir -p hello-wiqd && cd hello-wiqd ``` **Checkpoint:** your terminal is now in the `hello-wiqd` directory. ```bash pwd ``` ### Step 3: Start Copilot In the GitHub Copilot app, open the **Default agent** selector and choose **wiqd**. If you prefer the CLI, start an interactive Copilot session from the project directory: ```bash copilot --agent wiqd:wiqd ``` The remaining prompts in this section belong inside that Copilot session. Start with a clean conversation: ```text /clear ``` **Checkpoint:** Copilot clears its conversation context and waits for the next prompt. ### Step 4: Scaffold the agent Enter this prompt in the same Copilot session: ```text Create a new declarative agent called Hello WIQD. The agent should greet every user with a warm hello and introduce itself as having been created by WIQD. Give it the personality of a curious, innocent, and wonder-filled character, like a child seeing the world for the first time. It should be enthusiastic, gentle, and genuinely delighted to meet the user. Keep responses short, sweet, and warm. ``` Review and approve the file changes Copilot proposes. **Checkpoint:** the current directory contains a new agent project with manifest and instruction files. Keep this Copilot session open for the remaining steps. ## Run the agent ### Step 5: Move into the agent project Copilot reports the path of the project it created. Move the current session into that project root: ```text /cwd ``` Replace the placeholder with the path Copilot reported. **Checkpoint:** the current directory contains the agent's `appPackage` directory and lifecycle configuration file. ### Step 6: Validate locally Enter this prompt in the same Copilot session: ```text Validate the agent with wiqd. If validation reports errors, explain them and help me fix them before continuing. ``` **Checkpoint:** validation completes without errors. Fix any reported errors before continuing. ### Step 7: Provision to dev Enter this prompt in the same Copilot session: ```text Provision the agent to the dev environment with wiqd. ``` **Checkpoint:** provisioning succeeds and returns a Microsoft 365 Copilot share link. ### Step 8: Open in Copilot Enter this prompt in the same Copilot session: ```text Open the provisioned agent in Microsoft 365 Copilot with wiqd. ``` **Checkpoint:** the Hello WIQD agent opens in Microsoft 365 Copilot. ## Try it Run these prompts one at a time in the opened agent: | Prompt | Expected behavior | |---|---| | `Hi` | Greets you warmly, mentions WIQD, and expresses delight at meeting you | | `What are you?` | Describes itself with curiosity and child-like wonder | | `Tell me something fun` | Shares something with brief, genuine enthusiasm | ## Reset the lab To remove only the local trial project, close Copilot and run this from the parent directory of `hello-wiqd`: ```bash rm -rf hello-wiqd ``` Provisioned resources are not removed by deleting the local folder. Use the appropriate `wiqd` cleanup command for your environment if you also want to remove the provisioned agent. --- Return to the [cookbook index](../../README.md). --- ### Overview (`tools/wiqd/cookbooks/lifecycle/devui-debugging/README.md`) # Debug an agent in DevUI Launch WIQD's local DevUI, send a real prompt, and inspect the full turn: matched and selected plugins, tool execution, grounding, citations, request identifiers, latency, raw JSON, and failures. ## Before you start - Complete [Getting started](../../README.md#getting-started). - Start in a provisioned declarative-agent project. - For the richest tool trace, use [Zava Insurance agent](../../declarative-agents/insurance-agent-mcp/README.md). - DevUI binds only to `127.0.0.1` and uses your existing Work IQ authentication. ## Enable and launch DevUI Start one interactive Copilot session from the agent project root. In the GitHub Copilot app, open the **Default agent** selector and choose **wiqd**. If you prefer the CLI, run: ```bash copilot --agent wiqd:wiqd ``` Enter: ```text Enable the WIQD devui preview flag with the supported config command. Read this project's provisioned title ID, then start DevUI for that agent. Use direct transport and open the browser. Do not modify or re-provision the agent. ``` **Checkpoint:** DevUI opens locally with the intended agent preselected. ## Watch a successful turn For Zava Claims Guide, enter: ```text Use WIQD DevUI ask to send "Summarize claim CN202504990" to this agent and open the live turn. Then tell me which plugin and tool DevUI selected, whether the tool execution succeeded, and which request, conversation, and task IDs identify the run. ``` For another agent, replace the quoted prompt with one of its conversation starters. **Checkpoint:** DevUI shows the matched and selected plugin, the executed tool when applicable, latency, raw event data, and the rendered answer. ## Inspect grounding and failure behavior Enter: ```text In the same DevUI, run one prompt that should retrieve grounded content and one safe prompt that should fail, such as an unknown demo claim number. Compare the retrieval and citation sections, tool arguments, execution result, and surfaced error. Do not retry with invented identifiers and do not call a write tool. ``` **Checkpoint:** the grounded turn shows its evidence, while the failing turn shows a real error or empty result instead of a success-shaped answer. ## Restore the preview flag When finished, enter: ```text Stop the running WIQD DevUI and reset the devui feature flag to its default. ``` --- Return to the [cookbook index](../../README.md). --- ### Overview (`tools/wiqd/cookbooks/lifecycle/eval-hill-climb/README.md`) # Hill-climb agent quality with evals Create a focused evaluation suite, run it, diagnose the weakest behavior, fix the agent rather than the test, and compare the next run. This recipe uses WIQD's GitHub Copilot judge path, so Azure OpenAI credentials are not required unless you deliberately select the Azure judge. ## Before you start - Complete [Getting started](../../README.md#getting-started). - Start in a declarative-agent project with non-empty instructions. - Provision the agent before running live evals. - Authenticate GitHub CLI if the GitHub Copilot judge cannot use an existing session: `gh auth login`. ## Initialize a focused suite Start one interactive Copilot session from the agent project root. In the GitHub Copilot app, open the **Default agent** selector and choose **wiqd**. If you prefer the CLI, run: ```bash copilot --agent wiqd:wiqd ``` Enter: ```text Initialize WIQD evals for this provisioned agent. Inspect the manifest, instructions, grounding sources, and actions. Propose a focused suite that covers every applicable Perceive, Reason, and Act behavior plus boundaries and failure handling. Show every proposed add or update as a diff and wait for my approval before writing an eval file. Do not lower thresholds, remove Groundedness or Citations, or delete a failing scenario to improve the score. ``` Review the proposed cases and approve only when they describe behavior the agent should actually satisfy. **Checkpoint:** `evals/prompts.json` contains approved, scenario-specific tests rather than only generic starter prompts. ## Run and diagnose Enter: ```text Run the eval suite with WIQD using the GitHub Copilot judge and write a timestamped HTML scorecard under .evals. Analyze failures by root cause: instruction, grounding, citation, tool selection, capability gap, or a genuinely incorrect eval. Report the weakest evaluator and the exact prompts that expose the problem. ``` **Checkpoint:** the result includes a pass rate, per-evaluator scores, and a root-cause diagnosis tied to specific prompts. ## Improve the agent, not the bar Enter: ```text Fix the highest-impact agent issue from the latest eval run. Preserve the eval suite, evaluator coverage, and thresholds. Make the smallest instruction or capability change that addresses the root cause, validate the project, re-provision it, rerun the same eval suite, and compare the two scorecards. Stop if the proposed fix would require weakening a test. ``` **Checkpoint:** the second report uses the same suite and shows whether the targeted score improved. A regression remains visible instead of being hidden by easier tests. ## Continue the hill climb Repeat one root-cause fix at a time. Add a new regression case when a real gap is discovered, but always review and approve the eval diff before it is written. --- Return to the [cookbook index](../../README.md). --- ### Overview (`tools/wiqd/cookbooks/lifecycle/team-delivery/README.md`) # Deliver an agent to a team Take a validated agent from local development to a targeted team preview: configure shared scope, provision the shared environment, package resolved artifacts, deep-validate the package, and share it with named users or a mail-enabled security group. ## Before you start - Complete [Getting started](../../README.md#getting-started). - Start in a validated declarative-agent project. - Obtain the exact email addresses of preview users or the mail address of a security group. WIQD does not resolve display names. - Confirm that your tenant permits app upload and sharing. ## Configure the shared environment Start one interactive Copilot session from the project root. In the GitHub Copilot app, open the **Default agent** selector and choose **wiqd**. If you prefer the CLI, run: ```bash copilot --agent wiqd:wiqd ``` Enter: ```text Prepare this agent for a team preview in the dev environment. Inspect the existing environment configuration first. Create the dev environment through WIQD if it does not exist, configure AGENT_SCOPE=shared without adding secrets, and ensure shared-version handling is correct. Show me the resulting non-secret environment settings and stop before provisioning. ``` **Checkpoint:** the dev environment is explicitly shared and contains no hardcoded tenant ID, title ID, OAuth reference ID, secret, or recipient address. ## Provision, package, and validate Enter: ```text Run the team delivery gates in this exact order for dev: 1. Static validation 2. Provision the shared agent 3. Package the provisioned agent so environment values are resolved 4. Deep validation of the generated package Stop on any validation error. Report skipped deep-validation providers separately from passing providers, and show the Copilot launch URL on success. ``` **Checkpoint:** provisioning precedes packaging, the package has resolved environment values, and no validation error is hidden. ## Share with a bounded audience Enter: ```text Share the dev agent with these authorized recipients: Use users scope, not tenant scope. Report the exact share result and do not broaden access beyond the addresses I supplied. ``` **Checkpoint:** the share command reports success for the supplied users or group. Each recipient can open the launch URL after tenant propagation completes. ## Update safely For a later content or manifest change, keep the same Copilot session and enter: ```text Validate this shared agent, apply the required shared-agent patch version bump, re-provision dev, rebuild the package, and deep-validate it. Preserve the existing audience unless I explicitly ask to change sharing. ``` --- Return to the [cookbook index](../../README.md). --- ### Overview (`tools/wiqd/cookbooks/plugins/learn-tech-advisor/README.md`) # Upgrade the Learn connector into a technology advisor Turn the existing Microsoft Learn connector plugin into a composite, independently shippable plugin by adding reusable decision logic and a declarative-agent experience. This lab starts after connector setup so it does not repeat endpoint discovery or tool-description authoring. ## Before you start - Complete [Getting started](../../README.md#getting-started). - Complete [Microsoft Learn MCP connector](../microsoft-learn-mcp/README.md), or start from a validated copy of that plugin. - Confirm that `appPackage/manifest.json` already contains the Microsoft Learn connector and its MCP tool-description file. ## Add the reusable skill and agent Start one interactive Copilot session from the connector plugin root. In the GitHub Copilot app, open the **Default agent** selector and choose **wiqd**. If you prefer the CLI, run: ```bash copilot --agent wiqd:wiqd ``` Enter: ```text Upgrade this existing Microsoft Learn connector plugin into a technology advisor. Do not recreate or alter the connector endpoint. Use the supported WIQD plugin add commands to add a skill named Technology Finder and a declarative agent component. Replace the generated skill template with a reusable decision workflow: - Ask for the user's goal, preferred language or platform, and hard constraints. - Search official documentation before comparing options. - Search official code samples when implementation detail is requested. - Fetch the most relevant pages before giving a final recommendation. - Compare two or three viable options in a concise table. - Separate sourced facts from the recommendation and link every source. - Say when official documentation does not support a claim. Configure the declarative agent to invoke the skill for technology-selection questions. Add conversation starters, show the plugin summary, run static validation, and stop before provisioning. ``` **Checkpoint:** the existing connector remains unchanged, the plugin summary now lists `agentConnectors`, `agentSkills`, and `declarativeAgent`, the skill is no longer a template, and validation passes. ## Deploy the composite update Enter: ```text Provision or re-provision this composite plugin locally. Then package it and deep-validate the generated package. Show me any skipped provider instead of treating a skip as a pass. ``` Enable the updated plugin in Copilot Cowork and try: | Prompt | Expected behavior | |---|---| | `Should I use Azure Functions or Container Apps for a small event-driven API?` | Asks for missing constraints, retrieves current docs, compares options, and recommends one | | `Show the current TypeScript approach for DefaultAzureCredential.` | Uses code-sample search and links the official source | | `What evidence supports that recommendation?` | Fetches the strongest pages and separates evidence from judgment | **Checkpoint:** the reusable skill turns connector results into a repeatable decision workflow rather than another raw documentation search. --- Return to the [cookbook index](../../README.md). --- ### Overview (`tools/wiqd/cookbooks/plugins/microsoft-learn-mcp/README.md`) # Microsoft Learn MCP connector: first Copilot Cowork plugin Build, install, and test a plugin that searches and reads current Microsoft Learn documentation through the public Microsoft Learn MCP server as an agent connector. The server at `https://learn.microsoft.com/api/mcp` is free, uses streamable HTTP, and does not require authentication. It currently exposes tools to search documentation, search code samples, and fetch complete documentation pages. > [!NOTE] > Markdown cannot execute commands directly. Start Copilot once, enter each prompt in the same session, and confirm its checkpoint before continuing. ## Before you start You need: - Node.js 24 or later - `wiqd` v0.13.1 or later installed and signed in - Access to Copilot Cowork - Permission to provision and share an app in your Microsoft 365 development tenant See [Getting started](../../README.md#getting-started) for installation and sign-in instructions. ### Step 1: Check the environment Start the WIQD Copilot agent. In the GitHub Copilot app, open the **Default agent** selector and choose **wiqd**. If you prefer the CLI, run: ```bash copilot --agent wiqd:wiqd ``` Enter this prompt: ```text Check that my environment is ready to build and provision a plugin with WIQD. Confirm that Node.js is version 24 or later, WIQD is version 0.13.1 or later, I am signed in, and WIQD doctor reports no blocking errors. Help me fix any failed check before continuing. ``` **Checkpoint:** Copilot confirms that the environment is ready. ## Build the plugin ### Step 2: Create the plugin Enter this prompt in the same Copilot session: ```text Create a standalone plugin called Microsoft Learn Helper. ``` **Checkpoint:** the current working directory is the generated plugin root and contains `wiqd.plugin.json`, `m365agents.yml`, and `appPackage/manifest.json`. ### Step 3: Add the no-auth connector Enter this prompt in the same Copilot session: ```text Add a connector named Microsoft Learn to this plugin using the public MCP endpoint https://learn.microsoft.com/api/mcp. Configure it with no authentication. Inspect the server's current tools and include an MCP tool-description file in the app package so the connector can be verified by Copilot Cowork. Its purpose is to search and read current official Microsoft documentation and code samples. ``` Review and approve the proposed file changes. **Checkpoint:** `appPackage/manifest.json` contains a Microsoft Learn entry in `agentConnectors`, references a tool-description file in the app package, and has no authorization block. ### Step 4: Inspect and validate locally Enter this prompt in the same Copilot session: ```text Show me a summary of this plugin, then validate it locally with WIQD. If validation reports errors, explain and fix them before continuing. ``` **Checkpoint:** the plugin summary lists the Microsoft Learn connector and static validation completes successfully. ## Install the plugin in Copilot Cowork ### Step 5: Provision the plugin Enter this prompt in the same Copilot session: ```text Provision this Copilot Cowork plugin. ``` **Checkpoint:** WIQD reports that **Microsoft Learn Helper** was provisioned successfully. ## Test it in Copilot Cowork 1. Open Copilot Cowork. 2. Open the plugin UI and find the provisioned **Microsoft Learn Helper** plugin. 3. Install the plugin. 4. Start a new Copilot Cowork session with **Microsoft Learn Helper** enabled. 5. Run each prompt below and confirm that Cowork invokes the expected connector tool and returns content from Microsoft Learn. | Prompt | Expected behavior | |---|---| | `Find the current Microsoft guidance for building a remote MCP server in TypeScript.` | Calls `microsoft_docs_search` and summarizes relevant official documentation with links. | | `Show me a C# code sample for authenticating with DefaultAzureCredential.` | Calls `microsoft_code_sample_search` with C# as the language. | | `Read this Learn page and summarize its prerequisites: ` | Calls `microsoft_docs_fetch` for the supplied URL. | ## References - [Build a plugin with WIQD](https://microsoft.github.io/wiqd/getting-started/build-a-plugin/) - [WIQD plugin authoring reference](https://microsoft.github.io/wiqd/getting-started/plugin-reference/) - [Microsoft Learn MCP Server overview](https://learn.microsoft.com/training/support/mcp) --- Return to the [cookbook index](../../README.md). --- ### Overview (`tools/wiqd/cookbooks/plugins/plugin-portability/README.md`) # Round-trip a plugin across formats Export a validated WIQD plugin to the Agent Plugin, Claude, and Cursor formats, then import the Agent Plugin export into a fresh WIQD project and validate that the connector, skill, and declarative agent survived. ## Before you start - Complete [Getting started](../../README.md#getting-started). - Start from a validated composite plugin such as [Learn Technology Advisor](../learn-tech-advisor/README.md). - Keep the entire export directory together. The declarative-agent payload is carried beside the exported manifest and is required for a lossless import. ## Export the plugin From the validated plugin root, start one interactive Copilot session. In the GitHub Copilot app, open the **Default agent** selector and choose **wiqd**. If you prefer the CLI, run: ```bash copilot --agent wiqd:wiqd ``` Enter: ```text Validate this WIQD plugin. If validation is clean, export it with the supported WIQD plugin export command to all three formats: open-plugin, claude-plugin, and cursor-plugin. Put each format in its default export directory. Do not provision or change the source plugin. ``` **Checkpoint:** the plugin contains `export/open-plugin`, `export/claude-plugin`, and `export/cursor-plugin`, and each export has its format-specific manifest plus the carried skill and agent content. ## Prove the round trip Enter: ```text Import export/open-plugin into a new sibling project named -roundtrip using the supported WIQD plugin import command. Because this export came from WIQD, reuse its round-trip privacy, terms, and agent metadata rather than inventing replacements. Show the imported plugin and run static validation. Compare its capability list with the source plugin. ``` **Checkpoint:** import reports that the agent was restored, validation passes, and both projects list the same `agentConnectors`, `agentSkills`, and `declarativeAgent` capabilities. ## Test the boundary Copy an entire export directory to a temporary location and import it again. Do not copy only the manifest: that intentionally omits the carried agent and is not a valid lossless round trip. **Checkpoint:** a complete exported directory imports successfully without asking for new privacy or terms URLs. --- Return to the [cookbook index](../../README.md). --- ### Conventions (`docs/conventions.md`) # Conventions ## Cookbook layout - Place wiqd cookbooks under `tools/wiqd/cookbooks/` in the category that best matches the recipe: `declarative-agents`, `plugins`, or `lifecycle`. - Use a lowercase, hyphen-separated directory name and keep the entry point in a `README.md` file. - Add new cookbooks to the appropriate table in `tools/wiqd/cookbooks/README.md`. ## Writing recipes - Start with a concrete outcome and keep the recipe focused on one end-to-end scenario. - State prerequisites and supported tool versions before the steps that use them. - Use fenced code blocks for commands and identify the shell where it matters. - Explain placeholders and environment-specific values. Never commit working credentials, secrets, tenant identifiers, personal data, or confidential information. - Include a way to verify the result. Include cleanup steps when a recipe creates cloud or Microsoft 365 resources. - Prefer stable public documentation links and relative links for files in this repository. - Use clear, inclusive language and write instructions directly to the reader. ## Before submitting Run every command you changed in a suitable test environment, verify all links, and review the rendered Markdown. Keep pull requests focused and describe any steps that could not be validated. --- --- METRICS --- - Files Extracted: 19 - Estimated Token Budget: ~18487 tokens - Canonical Reference: https://codewiki.google/github.com/microsoft/plugins