microsoft · Anderson Silva (anderson-joyle) · Sep 4, 2026
diff --git 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
@@ -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
@@ -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/<name>/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
@@ -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
@@ -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/<name>/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
@@ -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
@@ -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 "<environment-id-or-dataverse-url>"
+```
+
+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/<environment-id>/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 "<environment-id-or-dataverse-url>" --name "<connection-name>" --tenant-id "<tenant-id>" --application-id "<app-id>" --client-secret "<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 `<agent-schema-name>.cr.<connector-name>.<short-suffix>`.
+
+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: "<display-name>";
+    connectionreferencelogicalname: "<new-connection-reference-logical-name>";
+    connectorid: "<connector-id>";
+    connectionid: "<raw-connection-id-from-pac-connection-list>"
+  }
+)
+```
+
+Run it:
+
+```bash
+pac power-fx run --environment "<environment-id-or-dataverse-url>" --file "<temp-connection-reference.powerfx>" --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: <new-connection-reference-logical-name>
+```
+
+## 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 "<agent-folder>"`).
+- 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.