From 4abd8b6b278ce6679cdccbbaebfb620d006dd5a2 Mon Sep 17 00:00:00 2001 From: Sergio Sisternes Date: Tue, 2 Jun 2026 16:04:41 +0100 Subject: [PATCH 1/7] Add APM package manifest with marketplace support - Add apm.yml with package identity, MCP dependency, and marketplace block - Add apm_modules/ and apm.lock.yaml to .gitignore - Add APM row to README Supported Clients table with awareness note - Update AGENTS.md with APM manifest documentation and sync rules Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .gitignore | 4 ++++ AGENTS.md | 5 +++-- README.md | 3 +++ apm.yml | 33 +++++++++++++++++++++++++++++++++ 4 files changed, 43 insertions(+), 2 deletions(-) create mode 100644 apm.yml diff --git a/.gitignore b/.gitignore index 166aa77..b31daf7 100644 --- a/.gitignore +++ b/.gitignore @@ -428,3 +428,7 @@ FodyWeavers.xsd *.msix *.msm *.msp + +# APM (Agent Package Manager) downloaded dependencies +apm_modules/ +apm.lock.yaml diff --git a/AGENTS.md b/AGENTS.md index 32131f5..d770419 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,13 +14,14 @@ The repo publishes plugin metadata for GitHub Copilot and Claude Code. Keep shar **Versioned plugin manifests**: - **GitHub Copilot** — `.github\plugin\plugin.json` is the Copilot marketplace manifest and points at the repo root. - **Claude Code** — `.claude-plugin\plugin.json` defines the Claude Code plugin package; `.claude-plugin\marketplace.json` defines Claude Code marketplace publishing metadata. +- **APM** — `apm.yml` is the Agent Package Manager manifest at the repo root. It declares the package identity, version, targets, MCP dependencies, and marketplace metadata. The `marketplace:` block in `apm.yml` is the source of truth for the APM marketplace index; `apm pack` generates `.claude-plugin/marketplace.json` from it. APM follows the existing `plugin.json` pointers to locate skills and MCP config — no separate `.apm/` directory is needed. ## Sync rules - Event support is duplicated by design between the CLI and skill docs. When adding, removing, or renaming events, update `cli\src\config.ts`, the supported/default event guidance in `skills\microsoft-build\SKILL.md`, and affected tests/docs together. - Treat `skills\microsoft-build\SKILL.md` as the product contract for event-session behavior. For Build, Ignite, or event-session work: default "Build" to `build-2026`, get session metadata from the live catalog through `msevents` or the endpoint, get SDK/API facts from Microsoft Learn MCP, and never invent session IDs, speakers, schedules, or links. -- Versioning gate: any meaningful `skills\microsoft-build\SKILL.md` change (agent behavior, commands/examples agents may follow, supported/default events, CLI/MCP/catalog usage, or user-facing workflow guidance) must bump both versioned plugin manifests to the same value; patch bumps are fine for guidance-only changes. -- PR review gate: GitHub Copilot/code reviewers should flag meaningful `SKILL.md` changes without synced plugin version bumps, and any plugin version drift. Typo/format-only skill edits may skip the bump only when the PR explicitly says so. +- Versioning gate: any meaningful `skills\microsoft-build\SKILL.md` change (agent behavior, commands/examples agents may follow, supported/default events, CLI/MCP/catalog usage, or user-facing workflow guidance) must bump all versioned plugin manifests (`.github\plugin\plugin.json`, `.claude-plugin\plugin.json`, and `apm.yml` including its `marketplace.plugins[].version`) to the same value; patch bumps are fine for guidance-only changes. +- PR review gate: GitHub Copilot/code reviewers should flag meaningful `SKILL.md` changes without synced plugin version bumps, and any plugin version drift across the three manifests. Typo/format-only skill edits may skip the bump only when the PR explicitly says so. - Keep README install/client guidance aligned with plugin manifest, skill, MCP, or CLI behavior changes. ## CLI diff --git a/README.md b/README.md index a46abb7..23c4505 100644 --- a/README.md +++ b/README.md @@ -69,6 +69,9 @@ Session results are a starting point. For broad topics, ask the agent to refine | VS Code | Open Extensions (Ctrl+Shift+X), search `@agentPlugins microsoft-events`, and install | | Visual Studio 2026 | Copy `skills/microsoft-build/` to a [supported skill location](https://learn.microsoft.com/visualstudio/ide/copilot-agent-skills) | | Claude Code | `/plugin marketplace add microsoft/Build-CLI` then `/plugin install microsoft-events@microsoft-events-marketplace` | +| APM | `apm install microsoft/Build-CLI` | + +> **What is APM?** [APM (Agent Package Manager)](https://github.com/nicepkg/apm) is to AI agent skills what npm is to JavaScript packages — it lets you install, version, and share reusable agent instructions, skills, and MCP configurations across projects with a single command. ## Scope and Limitations diff --git a/apm.yml b/apm.yml new file mode 100644 index 0000000..fdf31bf --- /dev/null +++ b/apm.yml @@ -0,0 +1,33 @@ +name: microsoft-events +version: 1.0.5 +description: >- + Connect your project to Microsoft Build and Ignite sessions — discover + relevant talks, explore what's new for your stack, and plan next steps + from your development environment. +author: Microsoft +license: Apache-2.0 +targets: [copilot, claude] + +dependencies: + mcp: + - name: microsoft-learn + registry: false + transport: http + url: "https://learn.microsoft.com/api/mcp" + +marketplace: + owner: + name: Microsoft + url: https://github.com/microsoft + metadata: + homepage: https://github.com/microsoft/Build-CLI + build: + tagPattern: "v{version}" + plugins: + - name: microsoft-events + description: >- + Connect your project to Microsoft Build and Ignite sessions — discover + relevant talks, explore what's new for your stack, and plan next steps + from your development environment. + source: ./ + version: "1.0.5" From c33552cf32d1c0127dfc5c7deb01df5a01997717 Mon Sep 17 00:00:00 2001 From: Sergio Sisternes Date: Tue, 2 Jun 2026 16:31:25 +0100 Subject: [PATCH 2/7] Expand README APM section with global install instructions Add dedicated 'Install with APM' section with prerequisites, global install commands with explicit --target flags, and verify/update/uninstall commands. Link the APM repo to microsoft/apm. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 42 ++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 40 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 23c4505..fd48772 100644 --- a/README.md +++ b/README.md @@ -69,9 +69,47 @@ Session results are a starting point. For broad topics, ask the agent to refine | VS Code | Open Extensions (Ctrl+Shift+X), search `@agentPlugins microsoft-events`, and install | | Visual Studio 2026 | Copy `skills/microsoft-build/` to a [supported skill location](https://learn.microsoft.com/visualstudio/ide/copilot-agent-skills) | | Claude Code | `/plugin marketplace add microsoft/Build-CLI` then `/plugin install microsoft-events@microsoft-events-marketplace` | -| APM | `apm install microsoft/Build-CLI` | +| APM | See [Install with APM](#install-with-apm) below | -> **What is APM?** [APM (Agent Package Manager)](https://github.com/nicepkg/apm) is to AI agent skills what npm is to JavaScript packages — it lets you install, version, and share reusable agent instructions, skills, and MCP configurations across projects with a single command. +## Install with APM + +[APM (Agent Package Manager)](https://github.com/microsoft/apm) is to AI agent skills what npm is to JavaScript packages — it lets you install, version, and share reusable agent instructions, skills, and MCP configurations across projects with a single command. + +### Prerequisites + +Install APM (one-time): + +```bash +# macOS / Linux +curl -sSL https://aka.ms/apm-unix | sh + +# Windows (PowerShell) +irm https://aka.ms/apm-windows | iex + +# Or via Homebrew +brew install microsoft/apm/apm +``` + +### Global install (all projects) + +```bash +# Both Claude Code and GitHub Copilot +apm install -g microsoft/Build-CLI#v1.0.5 --target claude,copilot + +# Claude Code only +apm install -g microsoft/Build-CLI#v1.0.5 --target claude + +# GitHub Copilot only +apm install -g microsoft/Build-CLI#v1.0.5 --target copilot +``` + +### Verify, update, and uninstall + +```bash +apm deps list -g # List globally installed packages +apm outdated -g # Check for updates +apm uninstall -g microsoft/Build-CLI # Remove +``` ## Scope and Limitations From 5449c4268cc780b7b14b4da3dfd5a4c67ccb31c0 Mon Sep 17 00:00:00 2001 From: Sergio Sisternes Date: Tue, 2 Jun 2026 18:05:22 +0100 Subject: [PATCH 3/7] Remove APM prerequisites section from README Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 15 --------------- 1 file changed, 15 deletions(-) diff --git a/README.md b/README.md index fd48772..937d194 100644 --- a/README.md +++ b/README.md @@ -75,21 +75,6 @@ Session results are a starting point. For broad topics, ask the agent to refine [APM (Agent Package Manager)](https://github.com/microsoft/apm) is to AI agent skills what npm is to JavaScript packages — it lets you install, version, and share reusable agent instructions, skills, and MCP configurations across projects with a single command. -### Prerequisites - -Install APM (one-time): - -```bash -# macOS / Linux -curl -sSL https://aka.ms/apm-unix | sh - -# Windows (PowerShell) -irm https://aka.ms/apm-windows | iex - -# Or via Homebrew -brew install microsoft/apm/apm -``` - ### Global install (all projects) ```bash From 5d046929df40a35f9c8836d6c99baeb83187e012 Mon Sep 17 00:00:00 2001 From: Sergio Sisternes Date: Tue, 2 Jun 2026 18:05:49 +0100 Subject: [PATCH 4/7] Add APM install command to Quick Start section Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index 937d194..3f44860 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,10 @@ A [GitHub Copilot CLI](https://github.com/features/copilot/cli/) skill that conn ``` /plugin install microsoft/Build-CLI ``` + Or install globally with [APM](https://github.com/microsoft/apm): + ``` + apm install -g microsoft/Build-CLI --target claude,copilot + ``` 2. Restart your Copilot CLI session: ``` /restart From 4aadcf0b1ba2ddc18939f4726472145658938a05 Mon Sep 17 00:00:00 2001 From: Sergio Sisternes Date: Tue, 2 Jun 2026 18:40:45 +0100 Subject: [PATCH 5/7] Fix apm.yml: use 'packages' instead of 'plugins' in marketplace block The APM schema expects 'packages' not 'plugins' for the marketplace listing key. Also fix the reference in AGENTS.md versioning gate. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- AGENTS.md | 2 +- apm.yml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index d770419..43b1106 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -20,7 +20,7 @@ The repo publishes plugin metadata for GitHub Copilot and Claude Code. Keep shar - Event support is duplicated by design between the CLI and skill docs. When adding, removing, or renaming events, update `cli\src\config.ts`, the supported/default event guidance in `skills\microsoft-build\SKILL.md`, and affected tests/docs together. - Treat `skills\microsoft-build\SKILL.md` as the product contract for event-session behavior. For Build, Ignite, or event-session work: default "Build" to `build-2026`, get session metadata from the live catalog through `msevents` or the endpoint, get SDK/API facts from Microsoft Learn MCP, and never invent session IDs, speakers, schedules, or links. -- Versioning gate: any meaningful `skills\microsoft-build\SKILL.md` change (agent behavior, commands/examples agents may follow, supported/default events, CLI/MCP/catalog usage, or user-facing workflow guidance) must bump all versioned plugin manifests (`.github\plugin\plugin.json`, `.claude-plugin\plugin.json`, and `apm.yml` including its `marketplace.plugins[].version`) to the same value; patch bumps are fine for guidance-only changes. +- Versioning gate: any meaningful `skills\microsoft-build\SKILL.md` change (agent behavior, commands/examples agents may follow, supported/default events, CLI/MCP/catalog usage, or user-facing workflow guidance) must bump all versioned plugin manifests (`.github\plugin\plugin.json`, `.claude-plugin\plugin.json`, and `apm.yml` including its `marketplace.packages[].version`) to the same value; patch bumps are fine for guidance-only changes. - PR review gate: GitHub Copilot/code reviewers should flag meaningful `SKILL.md` changes without synced plugin version bumps, and any plugin version drift across the three manifests. Typo/format-only skill edits may skip the bump only when the PR explicitly says so. - Keep README install/client guidance aligned with plugin manifest, skill, MCP, or CLI behavior changes. diff --git a/apm.yml b/apm.yml index fdf31bf..1ab08be 100644 --- a/apm.yml +++ b/apm.yml @@ -23,7 +23,7 @@ marketplace: homepage: https://github.com/microsoft/Build-CLI build: tagPattern: "v{version}" - plugins: + packages: - name: microsoft-events description: >- Connect your project to Microsoft Build and Ignite sessions — discover From 48f912f32a7d770bb5484edf0e0374c45a8d5d61 Mon Sep 17 00:00:00 2001 From: Sergio Sisternes Date: Tue, 2 Jun 2026 18:42:05 +0100 Subject: [PATCH 6/7] Fix AGENTS.md: clarify marketplace.json is generated, not hand-authored Update Claude Code bullet to state marketplace.json is generated by apm pack, resolving inconsistency with the APM bullet. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 43b1106..06278af 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,7 +13,7 @@ The repo publishes plugin metadata for GitHub Copilot and Claude Code. Keep shar **Versioned plugin manifests**: - **GitHub Copilot** — `.github\plugin\plugin.json` is the Copilot marketplace manifest and points at the repo root. -- **Claude Code** — `.claude-plugin\plugin.json` defines the Claude Code plugin package; `.claude-plugin\marketplace.json` defines Claude Code marketplace publishing metadata. +- **Claude Code** — `.claude-plugin\plugin.json` defines the Claude Code plugin package; `.claude-plugin\marketplace.json` is the Claude Code marketplace index, generated by `apm pack` from the `marketplace:` block in `apm.yml`. - **APM** — `apm.yml` is the Agent Package Manager manifest at the repo root. It declares the package identity, version, targets, MCP dependencies, and marketplace metadata. The `marketplace:` block in `apm.yml` is the source of truth for the APM marketplace index; `apm pack` generates `.claude-plugin/marketplace.json` from it. APM follows the existing `plugin.json` pointers to locate skills and MCP config — no separate `.apm/` directory is needed. ## Sync rules From bf812b63649c39f10620c8c50b4fba9f777609f1 Mon Sep 17 00:00:00 2001 From: Sergio Sisternes Date: Tue, 2 Jun 2026 18:49:50 +0100 Subject: [PATCH 7/7] Address review feedback: pin version in Quick Start, add sync comment - Pin APM install to #v1.0.5 in Quick Start for consistency with the Install with APM section - Add comment to apm.yml marketplace version noting it must stay in sync with the top-level version Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 2 +- apm.yml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 3f44860..0cc9b6a 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ A [GitHub Copilot CLI](https://github.com/features/copilot/cli/) skill that conn ``` Or install globally with [APM](https://github.com/microsoft/apm): ``` - apm install -g microsoft/Build-CLI --target claude,copilot + apm install -g microsoft/Build-CLI#v1.0.5 --target claude,copilot ``` 2. Restart your Copilot CLI session: ``` diff --git a/apm.yml b/apm.yml index 1ab08be..391c7f0 100644 --- a/apm.yml +++ b/apm.yml @@ -30,4 +30,4 @@ marketplace: relevant talks, explore what's new for your stack, and plan next steps from your development environment. source: ./ - version: "1.0.5" + version: "1.0.5" # keep in sync with top-level version