diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index f967441..633e0ce 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -9,8 +9,8 @@ "plugins": [ { "name": "mcs-assistant", - "description": "Microsoft Copilot Studio new orchestration YAML authoring toolkit. Create, edit, validate, and test Copilot Studio agents using YAML files.", - "version": "1.0.2", + "description": "Microsoft Copilot Studio agent authoring and lifecycle toolkit. Create, migrate, describe, edit, and validate agents in YAML, manage their ALM (clone, pull, push, publish), and use skills to add knowledge sources and connections, delete agents, and scaffold new skills.", + "version": "1.1.0", "source": "./" } ] diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 64b9792..f75a31a 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "mcs-assistant", - "version": "1.0.2", - "description": "Microsoft Copilot Studio new orchestration YAML authoring toolkit. Create, edit, validate, and test Copilot Studio agents using YAML files.", + "version": "1.1.0", + "description": "Microsoft Copilot Studio agent authoring and lifecycle toolkit. Create, migrate, describe, edit, and validate agents in YAML, manage their ALM (clone, pull, push, publish), and use skills to add knowledge sources and connections, delete agents, and scaffold new skills.", "author": { "name": "Microsoft Copilot Studio CAT Team" } diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..9c2f230 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,39 @@ +# Changelog + +All notable changes to the `mcs-assistant` plugin are documented here. This project adheres to +[Semantic Versioning](https://semver.org/). + +## [1.1.0] + +### Added + +- **Skills subsystem** (`skills/`) exposing the agent project lifecycle as user-invocable skills: + - Thin wrappers that delegate to the plugin's existing agents/command (no logic duplication): + - `clone`, `pull`, `push`, `publish` -> `copilot-studio-manage` + - `create` -> `copilot-studio-init` + - `read-info` -> `copilot-studio-describer` + - `migrate` -> the `migrate` command workflow + - Gap-filling skills: + - `delete` - self-contained destructive delete via `pac copilot delete`, with a mandatory + explicit-confirmation guardrail. Kept out of `copilot-studio-manage`, whose ALM scope excludes delete. + - `add-knowledge` - authors a modern `KnowledgeSourceConfiguration` (SharePoint / public website) under + `capabilities/knowledge/` (delegates to `copilot-studio-architect`). + - `add-connection` - full connection setup: find/create connection, create a dedicated connection + reference, and wire the tool YAML. + - `add-skill` - scaffolds a new plugin skill (`skills//SKILL.md`). +- `PRODUCT-SUPPORTED.md` readiness/compliance checklist. +- Real `SUPPORT.md` issue-reporting guidance (replaced the unedited template). +- README "Skills" and "Support status" sections. + +### Changed + +- Plugin promoted from **experimental** to **product supported**: removed the experimental-research-project + disclaimer from the README. +- Expanded plugin/marketplace descriptions to reflect the lifecycle + skills surface. +- Version bumped `1.0.2` -> `1.1.0` in `.claude-plugin/plugin.json` and `.claude-plugin/marketplace.json`. + +### Notes + +- Skills are validated structurally (frontmatter well-formed, JSON parses). PAC-backed behavior requires + PAC CLI **>= 2.9.3** and an authenticated Dataverse environment to live-test; see + [`PRODUCT-SUPPORTED.md`](PRODUCT-SUPPORTED.md) for the outstanding live-validation items. diff --git a/PRODUCT-SUPPORTED.md b/PRODUCT-SUPPORTED.md new file mode 100644 index 0000000..b59d10a --- /dev/null +++ b/PRODUCT-SUPPORTED.md @@ -0,0 +1,74 @@ +# Product-Supported Readiness + +This document tracks the readiness of the `mcs-assistant` plugin against its product-supported +definition-of-done. It is a checklist, not a guarantee - items in section 5 require a live environment to +close. + +## 1. Skill surface (complete) + +The plugin exposes the requested capabilities as user-invocable skills. 7 are thin wrappers over existing +agents/command; 4 fill real gaps. + +| Capability | Skill | Type | Status | +| --- | --- | --- | --- | +| Migrate | `migrate` | wrapper -> migrate command | authored | +| Create | `create` | wrapper -> `copilot-studio-init` | authored | +| Read Info | `read-info` | wrapper -> `copilot-studio-describer` | authored | +| Clone | `clone` | wrapper -> `copilot-studio-manage` | authored | +| Pull | `pull` | wrapper -> `copilot-studio-manage` | authored | +| Push | `push` | wrapper -> `copilot-studio-manage` | authored | +| Publish | `publish` | wrapper -> `copilot-studio-manage` | authored | +| Delete | `delete` | gap, self-contained | authored | +| Add Knowledge source | `add-knowledge` | gap -> `copilot-studio-architect` | authored | +| Add Connection / Connection setup ops | `add-connection` | gap, self-contained (merged) | authored | +| AddSkill (net-new) | `add-skill` | gap, self-contained | authored | + +## 2. Authoring quality bar (complete) + +- Every `SKILL.md` is agent-facing only (no human onboarding/marketing prose in the skill body), following the + cat-agent-skills authoring discipline used as the reference/quality bar. +- `allowed-tools` are least-privilege and scoped to the specific `pac` command patterns each skill uses. +- Agent workspaces are auto-discovered (`Glob: **/agent.mcs.yml`); no hardcoded agent names or paths. +- Destructive operations (`delete`) are gated behind an explicit, unambiguous user confirmation before + `--confirm` is ever passed. + +## 3. Packaging (complete) + +- `plugin.json` and `marketplace.json` bumped to `1.1.0` with expanded descriptions. +- `CHANGELOG.md` documents the 1.1.0 additions. +- README has a Skills section and a Support-status section. +- `SUPPORT.md` provides real issue-reporting guidance. +- Experimental-research-project disclaimer removed (plugin presented as product supported). + +## 4. Structural validation (complete) + +- All `.claude-plugin/*.json` parse as valid JSON. +- All new `SKILL.md` files have well-formed YAML frontmatter delimited by `---`. + +## 5. Live validation (blocked - needs PAC >= 2.9.3 + a Dataverse environment) + +These cannot be closed in the current environment (local PAC is below 2.9.3 and there is no authenticated +environment). Each must be exercised against a disposable dev environment before declaring full support: + +- [ ] `create` / `clone` / `pull` / `push` / `publish` against a real agent, verifying the Manage/Init agents + run end-to-end. +- [ ] `delete` against a throwaway agent, including verifying the confirmation guardrail blocks a non-confirm + response and that `pac copilot list` shows the agent gone afterwards. +- [ ] `add-knowledge`: **confirm the public-website knowledge `kind`/fields** for the installed PAC schema + version. The SharePoint shape (`SharePointKnowledgeSource` / `siteUrl` / `targetKind: Folder`) is + confirmed from the architect agent; the public-website shape (`PublicSiteSearchSource` / `site`) follows + the authoring schema but must be verified by a successful `pac copilot push`. +- [ ] `add-connection`: exercise the connection-reference `Collect` flow and confirm push succeeds with the + new reference. +- [ ] `migrate`: run the full workflow end-to-end. +- [ ] Confirm there is no runtime collision between the `migrate` **skill** and the existing `migrate` + **command** (both would surface as `migrate`). If the host disallows the overlap, either rename the + wrapper or have the command delegate to the skill. + +## 6. Open decisions / tech debt + +- The `migrate` skill delegates to `commands/migrate.md` (single source of truth). Consider consolidating the + command and skill once the naming-overlap behavior is confirmed (see 5). +- cat-agent-skills is used here only as a **reference/quality bar**; these skills are not (yet) published to + that community gallery. If co-publishing is later desired, each skill would need a `metadata.json` sidecar + and would move to that repo's `submissions/` format. diff --git a/README.md b/README.md index 6f609dc..504ed46 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,12 @@ # Copilot Studio Plugin -This repository is the successor to [skills-for-copilot-studio](https://github.com/microsoft/skills-for-copilot-studio). It contains an experimental plugin for creating, editing, validating, and migrating classic agents to the new experience. +This repository is the successor to [skills-for-copilot-studio](https://github.com/microsoft/skills-for-copilot-studio). It contains a plugin for creating, editing, validating, and migrating classic agents to the new experience. This plugin relies on the new version of the Power Platform CLI (`pac`), specifically version 2.9.3. A version greater that that is required to use the plugin. Install the latest version from [here](https://learn.microsoft.com/en-us/power-platform/developer/cli/introduction?tabs=windows) or just grab it from the [nuget feed](https://www.nuget.org/packages/Microsoft.PowerApps.CLI). -## Disclaimer +## Support status -This plugin is an experimental research project, not an officially supported Microsoft product. The Copilot Studio YAML schema may change without notice. Always review and validate generated YAML before pushing to your environment - AI-generated output may contain errors or unsupported patterns. This plugin is not meant for production use. +This plugin is **product supported**. The Copilot Studio YAML schema continues to evolve, so always review generated YAML and validate it against your environment (by pushing) before relying on it. See [`SUPPORT.md`](SUPPORT.md) for how to get help and [`PRODUCT-SUPPORTED.md`](PRODUCT-SUPPORTED.md) for the readiness checklist. ## Installation @@ -15,6 +15,27 @@ This plugin is an experimental research project, not an officially supported Mic /plugin install mcs-assistant@copilot-studio-plugin ``` +## Skills + +The plugin ships user-invocable skills that cover the agent project lifecycle. Thin wrappers delegate to the plugin's agents/commands; the rest are self-contained. + +| Skill | What it does | +| --- | --- | +| `migrate` | Migrate a classic agent to the new agentic-loop architecture (runs the migrate workflow). | +| `create` | Initialize a new empty agent project (`pac copilot init`). | +| `read-info` | Read-only: describe what an existing agent does. | +| `clone` | Clone an agent from an environment into a local workspace. | +| `pull` | Sync cloud changes down into the local workspace. | +| `push` | Pull-then-push local YAML edits up to the environment. | +| `publish` | Push and publish an agent so changes go live for shared users. | +| `delete` | Delete an agent from an environment (destructive; requires explicit confirmation). | +| `add-knowledge` | Author a SharePoint or public-website knowledge source under `capabilities/knowledge/`. | +| `add-connection` | Set up and wire a connector connection + connection reference onto a tool. | +| `add-skill` | Scaffold a new plugin skill (`skills//SKILL.md`). | + +Skills are auto-discovered from the `skills/` folder when the plugin is loaded. See [`CHANGELOG.md`](CHANGELOG.md) for version history. + + ## Contributing This project welcomes contributions and suggestions. Most contributions require you to agree to a diff --git a/SUPPORT.md b/SUPPORT.md index eaf439a..b66abfd 100644 --- a/SUPPORT.md +++ b/SUPPORT.md @@ -1,25 +1,29 @@ -# TODO: The maintainer of this repo has not yet edited this file +# Support -**REPO OWNER**: Do you want Customer Service & Support (CSS) support for this product/project? +## How to file issues and get help -- **No CSS support:** Fill out this template with information about how to file issues and get help. -- **Yes CSS support:** Fill out an intake form at [aka.ms/onboardsupport](https://aka.ms/onboardsupport). CSS will work with/help you to determine next steps. -- **Not sure?** Fill out an intake as though the answer were "Yes". CSS will help you decide. +This project uses **GitHub Issues** to track bugs and feature requests. Please search the +[existing issues](https://github.com/microsoft/copilot-studio-plugin/issues) before filing a new one to avoid +duplicates. For a new problem, [open an issue](https://github.com/microsoft/copilot-studio-plugin/issues/new) +and include: -*Then remove this first heading from this SUPPORT.MD file before publishing your repo.* +- what you were doing (the skill or command you invoked and its arguments), +- the installed `pac` version (`pac help`) and OS, +- the full error output, and +- the relevant agent YAML (redact any secrets, connection ids, or tenant/environment identifiers). -# Support +For questions and discussion about using the plugin, use the repository's +[GitHub Issues](https://github.com/microsoft/copilot-studio-plugin/issues) with the `question` label. -## How to file issues and get help +## Underlying platform support -This project uses GitHub Issues to track bugs and feature requests. Please search the existing -issues before filing new issues to avoid duplicates. For new issues, file your bug or -feature request as a new Issue. +This plugin authors and manages Microsoft Copilot Studio agents through the Power Platform CLI (`pac`). The +underlying Microsoft products (Copilot Studio, Power Platform, Dataverse) are fully supported through their own +official channels: -For help and questions about using this project, please **REPO MAINTAINER: INSERT INSTRUCTIONS HERE -FOR HOW TO ENGAGE REPO OWNERS OR COMMUNITY FOR HELP. COULD BE A STACK OVERFLOW TAG OR OTHER -CHANNEL. WHERE WILL YOU HELP PEOPLE?**. +- [Power Platform CLI documentation](https://learn.microsoft.com/en-us/power-platform/developer/cli/introduction) +- [Copilot Studio documentation](https://learn.microsoft.com/en-us/microsoft-copilot-studio/) -## Microsoft Support Policy +## Microsoft Support Policy -Support for this **PROJECT or PRODUCT** is limited to the resources listed above. +Support for this plugin is provided through the GitHub Issues channel listed above. diff --git a/skills/add-connection/SKILL.md b/skills/add-connection/SKILL.md new file mode 100644 index 0000000..0c8865d --- /dev/null +++ b/skills/add-connection/SKILL.md @@ -0,0 +1,135 @@ +--- +user-invocable: true +description: Set up and wire a connector connection for a modern Copilot Studio agent tool - guides connection creation in the portal (or via PAC for service principals), resolves the raw connection id, creates a dedicated Dataverse connection reference, and updates the tool YAML. Use when a connector-backed tool needs an authenticated connection, or for connection setup / connection reference wiring in general. +argument-hint: [connector name or tool file path] +allowed-tools: Bash(pac auth *), Bash(pac connection list *), Bash(pac connection create *), Bash(pac power-fx run *), Read, Write, Edit, Glob, Grep +context: fork +--- + +# Add Connection + +Set up and wire an authenticated connector connection into a **modern (agentic-loop)** Copilot Studio agent +tool. This single skill covers the full **connection setup ops** flow: finding or creating the underlying +connection, creating a dedicated connection reference, and wiring the tool YAML. + +Connector tools reference a Dataverse **connection reference** (a logical name) which in turn points at a raw +**connection** record. This skill: finds/creates the connection, creates a dedicated connection reference for +this agent, and updates the tool YAML to use it. + +> Interactive (delegated) connections - SharePoint, Teams, Outlook, etc. - are created by the user signing in +> through the portal; they cannot be fully created non-interactively. Service-principal connections can be +> created with `pac connection create`. This skill guides both paths. + +## Phase 0: Locate the agent and the tool + +Auto-discover the agent (never hardcode): + +``` +Glob: **/agent.mcs.yml +``` + +- Read the agent `schemaName` from `settings.mcs.yml` / `agent.mcs.yml`. +- Read the target environment from `.mcs/conn.json` (`EnvironmentId`) if present; otherwise ask the user for + the environment id or Dataverse URL. + +Identify the connector tool that needs a connection under `capabilities/tools/`. A connector-backed tool has +`kind: ConnectorTool` and/or a `connectorId` and/or a `connectionReference`. Record its file path, +`connectorId` (e.g. `/providers/Microsoft.PowerApps/apis/shared_sharepointonline`), `operationId`, and current +`connectionReference`. + +## Phase 1: Authenticate + +Run only if there is no active PAC profile or a command reports an auth error: + +```bash +pac auth create +``` + +## Phase 2: Find or create the connection + +List existing connections in the environment: + +```bash +pac connection list --environment "" +``` + +Look for a usable, connected connection for the required `connectorId`. + +**If a usable connection exists**, capture its **raw connection id** (e.g. `48e11359c0f344f9a495f649e515612a`). +Use the raw id exactly as PAC prints it - do not invent or reformat it into older forms like +`shared-sharepointonline-...`. + +**If no usable connection exists**, choose a path: + +- **Interactive / delegated (default for SharePoint, Teams, Outlook, etc.):** ask the user to create it in the + portal at `https://make.preview.powerautomate.com/environments//connections`, sign in for the + connector, then tell you when done. Then re-run `pac connection list` and read the new raw connection id. +- **Service principal (app registration):** create it non-interactively: + ```bash + pac connection create --environment "" --name "" --tenant-id "" --application-id "" --client-secret "" + ``` + Then re-run `pac connection list` to read the new raw connection id. + +Do not proceed until you have a raw connection id for the required connector. + +## Phase 3: Create a dedicated connection reference + +Create a **new** connection reference dedicated to this agent - do not reuse or mutate an existing shared one, +which may belong to another agent. + +Choose a unique logical name using the pattern `.cr..`. + +Write a temporary Power Fx file **outside** the agent project directory (never inside it) and create the +record with `Collect` (do not use `Defaults('Connection References')`): + +```powerfx +Collect('Connection References'; + { + connectionreferencedisplayname: ""; + connectionreferencelogicalname: ""; + connectorid: ""; + connectionid: "" + } +) +``` + +Run it: + +```bash +pac power-fx run --environment "" --file "" --echo +``` + +Then write a `ShowColumns()` verification query and confirm the record exists with the expected `connectionid` +and `connectorid`. Delete the temporary Power Fx file when done. + +## Phase 4: Wire the tool YAML + +Update the connector tool under `capabilities/tools/` so its `connectionReference` uses the new dedicated +logical name: + +```yaml +connectionReference: +``` + +## Phase 5: Validate and hand off + +- The connection reference record **must exist before push**. If it does not, push fails with + `A record with the specified key values does not exist in connectionreference entity`. +- Tell the user to sync (pull then push, via the push skill or `pac copilot push --project-dir ""`). +- Report: the connector wired, the raw connection id used, the new connection-reference logical name, and the + tool file updated. + +## Error Handling + +| Error | Likely cause | Resolution | +|---|---|---| +| Auth / active profile error | No/invalid PAC profile | Run `pac auth create`, then retry. | +| No connection for connector | Connection not created or not connected | Create it (portal or `pac connection create`), then re-list. | +| `Defaults('Connection References')` not supported | PAC Power Fx runner limitation | Use `Collect`, as shown above. | +| Push fails: record does not exist in connectionreference entity | Connection reference not created before push | Create/verify the connection reference (Phase 3), then push. | +| Connector id mismatch | Wrong `connectorId` on the tool | Confirm the tool's `connectorId` matches the connection's connector. | + +## Final answer + +Keep it short and factual: connector wired, raw connection id, new connection-reference logical name, tool file +updated, and the reminder that the connection reference must exist before pushing. diff --git a/skills/add-knowledge/SKILL.md b/skills/add-knowledge/SKILL.md new file mode 100644 index 0000000..1801e9e --- /dev/null +++ b/skills/add-knowledge/SKILL.md @@ -0,0 +1,127 @@ +--- +user-invocable: true +description: Add a knowledge source (SharePoint folder or public website) to a modern Copilot Studio agent by authoring a KnowledgeSourceConfiguration component under capabilities/knowledge. Use when the user asks to add a knowledge source, documentation URL, website, or SharePoint site for the agent to search. +argument-hint: [name] +allowed-tools: Read, Write, Glob, Grep +context: fork +agent: copilot-studio-architect +--- + +# Add Knowledge Source + +Add a knowledge source to a **modern (agentic-loop)** Copilot Studio agent. This authors a +`KnowledgeSourceConfiguration` component under the agent's `capabilities/knowledge/` folder. It does not push; +after authoring, the user syncs with the push (or publish) skill (`pac copilot push`). + +Supported here: **SharePoint** and **Public Website**. Other source types (Dataverse, uploaded files, AI +Search, SQL, Graph connectors) must be configured in the Copilot Studio portal - see Limitations. + +## Phase 0: Locate the agent (never hardcode) + +Auto-discover the modern agent workspace: + +``` +Glob: **/agent.mcs.yml +``` + +Confirm it is a modern CLI-authored agent: the project should contain `settings.mcs.yml` and a +`capabilities/` folder. If `capabilities/knowledge/` does not exist yet, create it. If multiple workspaces are +found, present a numbered pick-list rather than silently choosing one. + +Also note the **customization/publisher prefix** used by the project's existing component files. PAC derives +each Dataverse `botcomponent.schemaname` from the file stem, so every component file stem must start with a +valid prefix for the target environment (e.g. `cr123_`) and be <= 100 characters. Reuse the prefix already +present on sibling files under `capabilities/`. If none exists, ask the user for the approved publisher prefix. + +## Phase 1: Parse inputs + +From the arguments and request, extract: +- The **URL** (required). +- An optional **name** and **description**. If not given, derive a short, descriptive name from the URL. + +## Phase 2: Determine the source type + +- URL contains `sharepoint.com` -> **SharePoint** (`SharePointKnowledgeSource`). Normalize the URL first (below). +- Otherwise -> **Public Website** (`PublicSiteSearchSource`). + +### SharePoint URL normalization + +Copilot Studio needs a direct folder path, e.g. `https://contoso.sharepoint.com/sites/MySite/Shared%20Documents/MyFolder`. + +| URL pattern | Action | +|---|---| +| **Direct path** (`/sites/.../Shared%20Documents/...`) | Use as-is. | +| **AllItems.aspx with `?id=`** | Extract and URL-decode the `id` query parameter to get the path, prepend the origin (`https://.sharepoint.com`), and drop all query params. | +| **Sharing link** (`/:f:/s/...`, `/:x:/s/...`) | Cannot convert - opaque token. Ask the user: *"That's a SharePoint sharing link - I can't extract the folder path. Please open the folder in SharePoint, copy the URL from the browser address bar, and paste it here."* | + +**Encoding:** spaces in the final static URL must be `%20` (e.g. `Shared%20Documents`). + +## Phase 3: Author the component YAML + +Write to `capabilities/knowledge/__.mcs.yml`, where `` is the project's +customization prefix, `` is a slugified name, and `` is a short unique suffix. + +Every component starts with the `mcs.metadata` block. + +**SharePoint** (this is the confirmed modern format used by this plugin): + +```yaml +mcs.metadata: + componentName: + description: +kind: KnowledgeSourceConfiguration +source: + kind: SharePointKnowledgeSource + siteUrl: https://contoso.sharepoint.com/sites/MySite/Shared%20Documents/MyFolder + additionalSearchTerms: + targetKind: Folder +``` + +**Public Website:** + +> `PublicSiteSearchSource` uses Bing search to find relevant snippets within the scoped URL. It does **not** +> crawl or summarize full pages, and supports a **maximum depth of 2 levels** beyond the domain +> (e.g. `https://example.com/docs/api` works; `https://example.com/docs/api/v2` is too deep). + +```yaml +mcs.metadata: + componentName: + description: +kind: KnowledgeSourceConfiguration +source: + kind: PublicSiteSearchSource + site: https://www.example.com/docs +``` + +> **Schema note (verify on push).** This plugin's SharePoint knowledge uses the modern +> `SharePointKnowledgeSource` shape (`siteUrl`, `targetKind`). The public-website shape above follows the +> Copilot Studio authoring schema (`PublicSiteSearchSource` / `site`). Field/kind names for public websites +> can differ by PAC schema version, so after authoring, **validate by syncing** (Phase 5). If push reports an +> unknown `kind` or property, reconcile against the schema for the installed PAC version before retrying. + +## Phase 4: Dynamic URLs (optional) + +Knowledge URLs support `{VariableName}` placeholders via Power Fx interpolation for per-user routing, e.g.: + +```yaml +source: + kind: SharePointKnowledgeSource + siteUrl: =$"{Global.UserKBURL}" + targetKind: Folder +``` + +The variable must hold a clean direct URL (not an `AllItems.aspx` link) and be set **before** any +knowledge-search step runs. + +## Phase 5: Validate and hand off + +- Confirm the file is under `capabilities/knowledge/`, the stem starts with the customization prefix, and the + `mcs.metadata` block plus `kind` are present. +- Tell the user to sync the change so the platform validates it: pull, then push (use the push skill or run + `pac copilot push --project-dir ""`). Report any schema error from push verbatim. + +## Limitations + +This skill creates **SharePoint** and **Public Website** sources. For the following, tell the user they must be +created in the Copilot Studio portal (they require Power Platform configuration), then cloned/pulled to edit +locally: Dataverse tables, uploaded files, AI Search, SQL Server, and Microsoft Graph connectors. diff --git a/skills/add-skill/SKILL.md b/skills/add-skill/SKILL.md new file mode 100644 index 0000000..7ad4180 --- /dev/null +++ b/skills/add-skill/SKILL.md @@ -0,0 +1,92 @@ +--- +user-invocable: true +description: Scaffold a brand-new plugin skill (a skills//SKILL.md, plus an optional README.md) following this plugin's skill conventions. Use when the user wants to add, author, or scaffold a new skill for the mcs-assistant plugin. +argument-hint: [one-line purpose] +allowed-tools: Read, Write, Glob, Grep +context: fork +--- + +# Add Skill + +Scaffold a new **plugin skill** for this repository: a `skills//SKILL.md` file (plus an optional +`README.md` sidecar) that follows the conventions used by the existing skills in this plugin. This is a +net-new authoring capability - there is no `pac` operation involved; it only writes local files. + +## Phase 0: Resolve the skill identity + +1. Determine the **slug**: lowercase, hyphenated (e.g. `add-topic`, `run-eval`). Derive it from the requested + name; confirm with the user if ambiguous. +2. Check for collisions - the slug must not already exist: + ``` + Glob: skills/*/SKILL.md + ``` + Also check `commands/*.md` and `agents/*.md` for a same-named command or agent, to avoid a confusing + duplicate surface. If a collision exists, stop and ask the user for a different name or confirm they intend + to overwrite. + +## Phase 1: Decide the skill shape + +Ask (or infer from the request) two things: + +1. **Self-contained vs delegating.** If the skill's work is already owned by an existing agent + (`copilot-studio-manage`, `copilot-studio-init`, `copilot-studio-describer`, `copilot-studio-architect`), + prefer a thin skill that delegates via the `agent:` frontmatter field rather than duplicating that agent's + logic. Otherwise author a self-contained skill. +2. **Tools needed.** List the minimal `allowed-tools` the skill actually needs (e.g. specific `Bash(pac ...)` + command patterns, `Read`, `Write`, `Glob`, `Grep`). Keep it least-privilege - do not grant broad `Bash(*)`. + +## Phase 2: Author `skills//SKILL.md` + +Write the file with this frontmatter (omit `agent:` for a self-contained skill): + +```markdown +--- +user-invocable: true +description: +argument-hint: +allowed-tools: +context: fork +agent: # only when delegating; otherwise remove this line +--- + +# + +<One or two lines: what this skill does.> + +## Instructions +1. <Concrete, numbered, imperative steps addressed to the agent.> +2. ... + +## Guardrails +- <What the skill must not do; confirmation gates for any destructive action.> +``` + +Authoring rules (the quality bar for this plugin's skills): + +- **`SKILL.md` is agent-facing only.** Write imperative instructions to the agent. Do not put human onboarding, + "why use this", setup prose, or marketing in `SKILL.md` - that belongs in the optional `README.md`. +- The frontmatter **`description`** is the trigger the model reads to decide *when* to invoke - make it a + precise "Use this skill when..." sentence. Do not restate *when to use* inside the body. +- Auto-discover agent workspaces with `Glob: **/agent.mcs.yml`; **never hardcode** an agent name or path. +- Any **destructive or irreversible** action must have an explicit user-confirmation gate before it runs. +- Prefer delegating to an existing agent over duplicating its logic. + +## Phase 3: Optional `README.md` + +If the skill has genuine human-facing content (setup steps, prerequisites, examples, adoption notes), add a +`skills/<slug>/README.md` sidecar for it - keep that content out of `SKILL.md`. If there is no human-facing +content, do not create an empty README. + +## Phase 4: Validate and report + +- Confirm the folder name, the frontmatter `name`-equivalent title, and the slug all agree. +- Confirm the YAML frontmatter is well-formed (delimited by `---`, valid keys) and `allowed-tools` is + least-privilege. +- Tell the user the new skill path, whether it delegates or is self-contained, and that it will be discovered + from the `skills/` folder the next time the plugin is loaded (reload the session to pick it up). + +## Guardrails + +- Do not modify unrelated skills, agents, or commands. +- Do not grant broader tool permissions than the new skill needs. +- Do not author a skill that performs a destructive action without a confirmation gate. diff --git a/skills/clone/SKILL.md b/skills/clone/SKILL.md new file mode 100644 index 0000000..5b39d8f --- /dev/null +++ b/skills/clone/SKILL.md @@ -0,0 +1,24 @@ +--- +user-invocable: true +description: Clone an existing Copilot Studio agent from a Dataverse environment into a local workspace (downloads its YAML files). Use when the user wants to pull down or clone an agent they do not have locally yet. +argument-hint: [agent name, Copilot Studio url, or environment hint] +allowed-tools: Bash(pac auth *), Bash(pac copilot list *), Bash(pac copilot clone *), Read, Glob, Grep +context: fork +agent: copilot-studio-manage +--- + +# Clone Agent + +Thin wrapper over the **Copilot Studio Manage** agent for the **clone** operation only. + +The user wants to clone an agent from the cloud into a local workspace. Perform a clone using the Manage +agent's ALM rules: + +1. Resolve the target **environment** (from a discovered `.mcs/conn.json`, a pasted Copilot Studio URL, or by + asking the user for the environment id / Dataverse URL). Never hardcode it. +2. Authenticate first if there is no active PAC profile or a command reports an auth error (`pac auth create`). +3. Run the clone, then confirm the result with `Glob: **/agent.mcs.yml` and check that `.mcs/conn.json` was + written. +4. Report which agent was cloned and where its files live. + +Do **only** the clone. Do not push, pull, publish, edit, or delete the agent. diff --git a/skills/create/SKILL.md b/skills/create/SKILL.md new file mode 100644 index 0000000..9fea4f7 --- /dev/null +++ b/skills/create/SKILL.md @@ -0,0 +1,26 @@ +--- +user-invocable: true +description: Create (initialize) a new empty CLI-authoring Copilot Studio agent project in a target environment via `pac copilot init`. Use when the user wants to create a brand-new agent or scaffold a migration target project. +argument-hint: [display name] [target project directory] [environment id] +allowed-tools: Bash(pac auth *), Bash(pac copilot init *), Read, Write, Glob, Grep +context: fork +agent: copilot-studio-init +--- + +# Create Agent + +Thin wrapper over the **Copilot Studio Init** agent for the **create/init** operation only. + +The user wants to create a new empty agent project. Delegate to the Init agent, which runs the single +`pac copilot init` command. Collect the required inputs first, deriving nothing that was not provided: + +1. **Display name** for the new agent. +2. **Target project directory.** +3. **Target environment id.** +4. Optional **publisher prefix** for the solution/components (falls back to the Init agent's default if not + given). + +Authenticate first if there is no active PAC profile (`pac auth create`). Then run init and report the created +project location. + +Do **only** the initialization. Do not describe, design, edit, migrate, validate, test, or publish the agent. diff --git a/skills/delete/SKILL.md b/skills/delete/SKILL.md new file mode 100644 index 0000000..27bdd2a --- /dev/null +++ b/skills/delete/SKILL.md @@ -0,0 +1,131 @@ +--- +user-invocable: true +description: Delete a Copilot Studio agent from a Dataverse environment (cloud) using PAC. This is a destructive operation and always requires explicit user confirmation before anything is deleted. Use when the user asks to delete, remove, or destroy an agent in an environment. +argument-hint: [agent name, bot id, or schema name] [environment id or url] +allowed-tools: Bash(pac auth *), Bash(pac copilot list *), Bash(pac copilot delete *), Read, Glob, Grep +context: fork +--- + +# Delete Agent (Cloud) + +Delete a Copilot Studio agent from a Dataverse environment using the Power Platform CLI (`pac`). + +> **This is a destructive, irreversible cloud operation.** It deletes the agent record from the target +> environment. You MUST get explicit user confirmation (see Phase 3) before passing `--confirm`. Never +> delete without showing the user exactly what will be removed first. + +This is a standalone skill on purpose: the plugin's Manage agent explicitly excludes `delete` from its ALM +scope, so deletion lives here with its own guardrail rather than inside the sync/publish flow. + +## Scope + +- This skill deletes the agent **in the cloud environment** (the Dataverse `bot` record). +- It does **not** delete local workspace files. If the user also wants the local folder removed, tell them + which folder it is and let them delete it themselves - do not delete local files as part of this skill. +- It does not publish, pull, push, or otherwise modify other agents. + +## Prerequisite: PAC version + +This skill relies on `pac copilot delete`, which requires PAC CLI **>= 2.9.3**. If `pac` is missing or older, +stop and tell the user to install the required version from +https://learn.microsoft.com/en-us/power-platform/developer/cli/introduction#install-microsoft-power-platform-cli. +Do not install PAC yourself unless the user explicitly asks. + +## Phase 0: Resolve the target agent and environment + +You need two things: a **bot identifier** (`--bot`, either the Copilot ID GUID or the schema name) and an +**environment** (`--environment`, a GUID or Dataverse URL). + +Resolve them in this order: + +1. **From a local workspace.** Auto-discover the agent - never hardcode a name: + ``` + Glob: **/agent.mcs.yml + ``` + - Read the schema name / bot id from `settings.mcs.yml` or `agent.mcs.yml` (look for `schemaName` and, if + present, the bot/agent id). + - Read the environment from the sibling `.mcs/conn.json` (`EnvironmentId`) if it exists. + - If multiple workspaces are found, present a numbered pick-list; never silently pick the first. +2. **From a Copilot Studio URL.** If the user pastes a URL containing + `/environments/<environmentId>/bots/<botId>/`, extract both IDs and use them. +3. **Ask the user.** If neither the bot identifier nor the environment can be resolved, ask for the missing + value. Prefer a schema name or bot id already present in project files or user-provided context. + +## Phase 1: Authenticate + +Commands that talk to Dataverse require an authenticated PAC profile. Run this only when no active profile +exists or a command reports an auth/profile error: + +```bash +pac auth create +``` + +Let the user complete sign-in, then continue. + +## Phase 2: Confirm the agent exists + +List agents in the target environment and confirm the target is present before attempting deletion: + +```bash +pac copilot list --environment "<environment-id-or-dataverse-url>" +``` + +- Match the target by display name, schema name, or bot id and capture its identity. +- If the agent is **not** in the list, stop and tell the user it was not found in that environment (it may + already be deleted or you may have the wrong environment). Do not run delete. + +## Phase 3: Explicit confirmation (MANDATORY) + +Before deleting, show the user exactly what will be removed and require an explicit, unambiguous yes: + +> **You are about to permanently delete this agent from the cloud:** +> - Agent: `<display name>` +> - Bot id / schema name: `<id-or-schema>` +> - Environment: `<environment-id-or-url>` +> +> This cannot be undone. Type **delete** to confirm, or anything else to cancel. + +Rules: +- Only proceed if the user clearly confirms (e.g. "delete", "yes, delete it"). +- If the response is ambiguous, negative, or empty, **cancel** and report that nothing was deleted. +- Never pass `--confirm` unless the user has explicitly confirmed in this phase. + +## Phase 4: Delete + +Only after explicit confirmation, run: + +```bash +pac copilot delete --bot "<bot-id-or-schema-name>" --environment "<environment-id-or-dataverse-url>" --confirm +``` + +- `--confirm` (`-y`) is required for the delete to actually execute. +- Read the command output directly and surface any error in full. + +## Phase 5: Verify and report + +Confirm the deletion took effect: + +```bash +pac copilot list --environment "<environment-id-or-dataverse-url>" +``` + +- Confirm the agent no longer appears. +- Report: which agent (name + id) was deleted, from which environment, and whether the verification listing + confirms it is gone. +- If the user has a local workspace for this agent, remind them the **local files were not deleted** and tell + them the folder path so they can remove it if they wish. + +## Error Handling + +| Error | Likely cause | Resolution | +|---|---|---| +| Authentication or active profile error | No/invalid PAC auth profile | Run `pac auth create`, then retry. | +| Agent not found in list | Wrong environment, or already deleted | Verify the environment and bot identifier; do not run delete. | +| Delete reports insufficient permissions | User lacks maker/admin rights on the agent | Ask the user to confirm they have delete permission in that environment. | +| Delete succeeds but agent still listed | Deletion still propagating | Re-run `pac copilot list` after a moment; if it persists, report the raw output. | +| `pac copilot delete` unknown/invalid command | PAC older than 2.9.3 | Ask the user to upgrade PAC to >= 2.9.3. | + +## Final answer + +Keep it short and factual: the agent deleted (name + id), the environment, confirmation that it no longer +appears in the listing, and the reminder about local files if a local workspace exists. diff --git a/skills/migrate/SKILL.md b/skills/migrate/SKILL.md new file mode 100644 index 0000000..538f5ad --- /dev/null +++ b/skills/migrate/SKILL.md @@ -0,0 +1,34 @@ +--- +user-invocable: true +description: Migrate a classic Copilot Studio agent to the new agentic-loop architecture (cloning it first if it is not already local). Use when the user asks to migrate, upgrade, or convert an existing agent to the new experience. +argument-hint: Agent name or path to migrate (and source environment if it must be cloned) +allowed-tools: Bash(pac *), Bash(node *convert-actions-to-tools.js*), Read, Write, Glob, Grep, WebFetch(domain:raw.githubusercontent.com), Task +context: fork +--- + +# Migrate Agent + +Thin wrapper that runs the plugin's migration workflow. The full, authoritative migration orchestration lives +in the plugin's migrate command; this skill executes that same workflow so migration is reachable as a skill. + +## Instructions + +1. **Read the migration workflow** and follow it exactly: + ``` + Read: ${CLAUDE_SKILL_DIR}/../../commands/migrate.md + ``` + Treat the user's arguments as that workflow's `$ARGUMENTS`. +2. Execute the workflow's steps in their natural order (PAC prerequisite check -> ensure the agent is local + (clone if needed) -> describe -> plan + approval -> tool migration -> architect -> push), delegating to the + sub-agents it names. Do not re-implement or reorder those steps here. + +## Prerequisite + +The migration workflow requires PAC CLI **>= 2.9.3**. Verify it before starting, exactly as the workflow's +first step specifies, and stop if the installed version is older. + +## Guardrails + +- Do not invent behavior the source agent files do not support. +- Do not skip the plan-approval step defined in the workflow. +- This skill is a thin entry point; the migrate command file is the single source of truth for the steps. diff --git a/skills/pull/SKILL.md b/skills/pull/SKILL.md new file mode 100644 index 0000000..0bbd1fa --- /dev/null +++ b/skills/pull/SKILL.md @@ -0,0 +1,22 @@ +--- +user-invocable: true +description: Pull the latest server-side changes for a locally cloned Copilot Studio agent (sync cloud -> local). Use before editing, or when the user asks to refresh / sync down the local agent files. +argument-hint: [agent project path] +allowed-tools: Bash(pac auth *), Bash(pac copilot pull *), Read, Glob, Grep +context: fork +agent: copilot-studio-manage +--- + +# Pull Agent + +Thin wrapper over the **Copilot Studio Manage** agent for the **pull** operation only. + +The user wants to sync the cloud agent's latest state into the local workspace. Perform a pull using the Manage +agent's ALM rules: + +1. Identify the agent workspace (`Glob: **/agent.mcs.yml`; read the environment from the sibling + `.mcs/conn.json`). If multiple workspaces exist, present a numbered pick-list; never silently pick one. +2. Authenticate first if needed (`pac auth create`). +3. Run the pull and report what changed locally. + +Do **only** the pull. This is the correct first step before any local edit. diff --git a/skills/push/SKILL.md b/skills/push/SKILL.md new file mode 100644 index 0000000..0929ea9 --- /dev/null +++ b/skills/push/SKILL.md @@ -0,0 +1,23 @@ +--- +user-invocable: true +description: Push local Copilot Studio agent YAML changes up to the Dataverse environment (sync local -> cloud). Use when the user asks to save, sync up, or upload local agent edits. +argument-hint: [agent project path] +allowed-tools: Bash(pac auth *), Bash(pac copilot pull *), Bash(pac copilot push *), Read, Glob, Grep +context: fork +agent: copilot-studio-manage +--- + +# Push Agent + +Thin wrapper over the **Copilot Studio Manage** agent for the **push** operation only. + +The user wants to upload local agent edits to the cloud. Perform a push using the Manage agent's ALM rules: + +1. Identify the agent workspace (`Glob: **/agent.mcs.yml`; environment from the sibling `.mcs/conn.json`). +2. Authenticate first if needed (`pac auth create`). +3. **Always pull before push** so local is based on the latest server state, then push. +4. If push reports there is nothing to send, tell the user the agent is already up to date. +5. Surface any schema/validation error from push verbatim. + +Do **only** the pull-then-push. Do not publish as part of this skill unless the user asks (use the publish +skill for that). diff --git a/skills/read-info/SKILL.md b/skills/read-info/SKILL.md new file mode 100644 index 0000000..a8d0ca4 --- /dev/null +++ b/skills/read-info/SKILL.md @@ -0,0 +1,21 @@ +--- +user-invocable: true +description: Read-only. Understand an existing Copilot Studio agent and produce a detailed report of what it does (topics, actions, knowledge, instructions). Use when the user asks what an agent does, to explain, summarize, or get info about an agent. +argument-hint: [agent name or project path] +allowed-tools: Read, Glob, Grep +context: fork +agent: copilot-studio-describer +--- + +# Read Agent Info + +Thin wrapper over the **Copilot Studio Describer** agent (read-only) for the **read info / describe** operation. + +The user wants to understand an existing agent. Delegate to the Describer agent: + +1. Auto-discover the agent workspace (`Glob: **/agent.mcs.yml`). Never hardcode a name. If multiple are found, + ask which one to describe. +2. Produce the Describer agent's structured, read-only report. + +This skill is strictly **read-only**: never create, edit, delete, push, pull, publish, or test anything. If the +user actually wants changes, hand off to the appropriate authoring or manage skill instead.