skill: elevate Learn MCP to required documentation source#44
Open
mikekinsman wants to merge 8 commits into
Open
skill: elevate Learn MCP to required documentation source#44mikekinsman wants to merge 8 commits into
mikekinsman wants to merge 8 commits into
Conversation
Adds a version-check step to 'Find sessions' and 'What s new' workflows. Agent fetches upstream plugin.json, compares version to local, and recommends /plugin update if newer. Bumps plugin version to 1.0.2 for testing. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Use aka.ms short links for all Book of News references Replace direct news.microsoft.com URLs with aka.ms redirects so we can update targets without changing the skill. Add Build 2025 Book of News link that was previously missing. - aka.ms/build2026-news - aka.ms/build2025-news - aka.ms/ignite2025-news Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * chore: bump plugin manifest versions to 1.0.2 Agent-Logs-Url: https://github.com/microsoft/Build-CLI/sessions/ac0d0496-c964-47b0-a76e-071164b1d6e7 Co-authored-by: mikekinsman <32281167+mikekinsman@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Harden catalog ingestion by adding safe JSON fetches, atomic cache writes, stricter limit validation, and untrusted-catalog guidance. Co-authored-by: Jose Luis Latorre Millas <9831011+joslat@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Replace terminology with 'News & Announcements' The AKA links remain unchanged. Agent behavior is preserved — it still fetches news content from the same endpoints, with news.microsoft.com as a fallback for unlisted events. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * chore: bump plugin manifest versions to 1.0.4 Agent-Logs-Url: https://github.com/microsoft/Build-CLI/sessions/7539cfe3-87aa-44ed-9bac-797a0a1087b0 Co-authored-by: mikekinsman <32281167+mikekinsman@users.noreply.github.com> * docs: align News & Announcements terminology in untrusted content section Agent-Logs-Url: https://github.com/microsoft/Build-CLI/sessions/ffa96bf5-2896-4865-9801-da10b2dc7902 Co-authored-by: mikekinsman <32281167+mikekinsman@users.noreply.github.com> * Fix review feedback: consistent terminology + version bump - Standardize on 'News & Announcements' (capitalized) everywhere - Bump plugin manifests from 1.0.4 to 1.0.5 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fix CRLF line endings in plugin.json files Normalize both plugin manifests back to LF to match repo conventions. Also restores original key ordering. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…CLI output (microsoft#41) * Surface deliveryTypes, viewingOptions, hasLiveStream, hasOnDemand in CLI output Add four fields from the upstream catalog that were silently dropped during normalization: deliveryTypes, viewingOptions, hasLiveStream, and hasOnDemand. This lets remote attendees see whether a session is in-person only, has a live stream, or will be recorded. Changes: - contracts.ts: Add fields to RawSession and Session interfaces - normalize.ts: Map the four fields in normalizeSession() - search/index.ts: Add fields to MiniSearch storeFields - format.ts: Show delivery type in short format, all four in full format - cache.test.ts: Update session() helper with new required fields - SKILL.md: Document new fields in catalog table and session workflow - Plugin manifests: Bump version 1.0.5 -> 1.0.6 Closes microsoft#40 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Bump @microsoft/events-cli version to 0.3.1 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Restructure SKILL.md so agents treat Learn MCP as mandatory rather than
optional. Two changes:
1. Move Learn MCP out of 'Session catalog access' into its own top-level
section ('Documentation source: Learn MCP Server (required)') positioned
before session catalog access. This sends a structural signal that Learn
MCP is the primary documentation layer, not one of several equal options.
2. Add prescriptive gate language: 'Every response that references SDK
features, API behavior, or documentation MUST include results from Learn
MCP tools.' Also bold Learn MCP as '(required)' in the data sources list.
Tested against the 'what''s new at Build for my project' scenario in
build-demo-project. Agent now explicitly discovers Learn MCP tools and
fires parallel microsoft_docs_search queries alongside session catalog
searches — the exact behavior that was missing before.
Fixes microsoft#42
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the Microsoft Build skill documentation to make Microsoft Learn MCP usage mandatory for doc-backed answers, and extends the Events CLI to improve catalog fetching/caching robustness while surfacing additional session metadata.
Changes:
- Restructures
skills/microsoft-build/SKILL.mdto elevate Learn MCP as a required documentation source and updates event “News & Announcements” guidance. - Enhances the CLI’s catalog pipeline (safe HTTP fetch with timeouts/size limits, atomic cache writes, stricter
--limitparsing, and additional session fields in normalization/search/output). - Bumps plugin manifest versions and updates user-facing docs/tests accordingly.
Reviewed changes
Copilot reviewed 18 out of 19 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| skills/microsoft-build/SKILL.md | Elevates Learn MCP to required source; updates workflow wording; adds version-check step and untrusted-text guidance. |
| README.md | Adds an overview video link to the main README. |
| cli/test/normalize.test.ts | Minor formatting-only change (trailing blank line). |
| cli/test/limit.test.ts | Adds unit coverage for new validateLimit behavior. |
| cli/test/http.test.ts | Adds tests for new safe JSON fetch helper (timeouts, size caps, 304 handling). |
| cli/test/cache.test.ts | Expands cache tests for atomic writes and failure fallbacks (timeouts/oversize/invalid catalogs). |
| cli/src/search/index.ts | Indexes new session fields to improve queryability. |
| cli/src/output/format.ts | Prints delivery/viewing/live/on-demand metadata in formatted output. |
| cli/src/index.ts | Uses validateLimit for sessions --limit parsing and validation. |
| cli/src/data/normalize.ts | Normalizes additional session fields from raw catalog objects. |
| cli/src/data/http.ts | Introduces safeFetchJson with timeout/content-type/size handling for catalog fetches. |
| cli/src/data/cache.ts | Switches to safe fetch, adds atomic cache writes, and tightens catalog validity checks. |
| cli/src/contracts.ts | Extends session contracts to include delivery/viewing/live/on-demand fields. |
| cli/src/commands/common.ts | Adds validateLimit with clamping and error signaling. |
| cli/README.md | Documents new environment variables for fetch timeout and response size limits. |
| cli/package.json | Bumps CLI package version to 0.3.1. |
| cli/package-lock.json | Updates lockfile metadata (but currently version-drifts vs package.json). |
| .github/plugin/plugin.json | Bumps Copilot plugin manifest version to 1.0.6. |
| .claude-plugin/plugin.json | Bumps Claude plugin manifest version to 1.0.6. |
Files not reviewed (1)
- cli/package-lock.json: Generated file
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+1
to
+5
| import { FetchError } from '../errors.js'; | ||
|
|
||
| export interface SafeFetchOptions { | ||
| timeoutMs?: number; | ||
| maxBytes?: number; |
| - Documentation updates: what changed in the SDKs and services they use, with links to current docs | ||
| - Relevant sessions: event sessions that cover their technologies, sorted by relevance | ||
| 7. For high-confidence matches, offer to explain the migration path or impact on the developer's project | ||
| 8. **Version check**: Fetch `https://raw.githubusercontent.com/mikekinsman/Build-CLI/refs/heads/main/.github/plugin/plugin.json` and read the `version` field. Compare it to the local `.github/plugin/plugin.json` version in this repo. If the remote version is higher, append to your response: "💡 A newer version of the Build CLI skill (v{remote}) is available. Run `/plugin update microsoft/Build-CLI` to get the latest sessions and features." |
| 6. For each recommended session, include: session code, title, one-line reason it's relevant, speaker(s), location, time slot, type (lab/breakout/demo), level | ||
| 7. If they have time for multiple sessions, suggest a learning path order: foundational first, then intermediate/advanced, ending with hands-on labs to apply what they learned | ||
| 8. After helping the user build a schedule (finding sessions, flagging conflicts), offer: "Would you like me to save this as a markdown file?" Do not create a file until the user confirms. Include day, time, session code, title, and location. | ||
| 9. **Version check**: Fetch `https://raw.githubusercontent.com/mikekinsman/Build-CLI/refs/heads/main/.github/plugin/plugin.json` and read the `version` field. Compare it to the local `.github/plugin/plugin.json` version in this repo. If the remote version is higher, append to your response: "💡 A newer version of the Build CLI skill (v{remote}) is available. Run `/plugin update microsoft/Build-CLI` to get the latest sessions and features." |
| { | ||
| "name": "@microsoft/events-cli", | ||
| "version": "0.1.0", | ||
| "version": "0.3.0", |
| "": { | ||
| "name": "@microsoft/events-cli", | ||
| "version": "0.1.0", | ||
| "version": "0.3.0", |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Restructure SKILL.md so agents treat Learn MCP as mandatory rather than optional. Addresses feedback from testing where agents skipped Learn MCP entirely during the 'what''s new at Build for my project' workflow.
Changes
Elevate Learn MCP to its own top-level section — Moved out of 'Session catalog access' into a new ## Documentation source: Learn MCP Server (required)\ section, positioned before session catalog access. This sends a clear structural signal: Learn MCP is the primary documentation layer, not one of several equal options.
Add prescriptive gate language — 'Every response that references SDK features, API behavior, or documentation MUST include results from Learn MCP tools.' Also bolds Learn MCP as (required) in the data sources list.
Testing
Tested against the 'what''s new at Build for my project' scenario in a demo project (Node/TS + Python agent with Cosmos DB, Azure OpenAI, AI Search).
Before: Agent skipped Learn MCP entirely — only searched sessions and news.
After: Agent explicitly discovered Learn MCP tools (\Search tools microsoft_docs|learn - Found 3 matching tool(s)) and fired three parallel \microsoft_docs_search\ queries alongside session catalog searches.
Fixes #42