Add onboarding Copilot agent for new contributors#2523
Conversation
Create a custom GitHub Copilot agent at .github/copilot/agents/onboarding.md that guides new contributors through environment setup, codebase understanding, and their first contribution. Content sourced from CONTRIBUTING.md. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
KarishmaGhiya
requested review from
JasonYeMSFT,
alzimmermsft,
fanyang-mono,
srnagar,
tmeschter,
wbreza and
xiangyan99
There was a problem hiding this comment.
Pull request overview
Adds a GitHub Copilot custom agent (@onboarding) to help new contributors get oriented with Azure MCP, including setup, workflow, command authoring, testing, and PR checklist guidance.
Changes:
- Introduces a new onboarding agent markdown file under
.github/copilot/agents/. - Documents repo structure, prerequisites, quick-start commands, and contribution workflow.
- Provides step-by-step guidance for adding new commands, testing (unit/live/e2e), and PR quality checks.
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
jongio
left a comment
jongio
left a comment
There was a problem hiding this comment.
The agent concept is valuable. Having a guided onboarding path for new contributors makes sense, and the content is well-organized.
Main concern: roughly 160 lines here duplicate content from AGENTS.md and CONTRIBUTING.md (coding standards, repo structure, prerequisites, workflow). When those source files change, this file won't track, and the agent will give stale guidance to new contributors.
Consider keeping the agent's personality and high-level orientation inline, but referencing the canonical docs for details. Something like See AGENTS.md for current coding standards rather than reproducing them. The content stays fresh without manual sync.
Also noting: the three existing bot review comments appear to be false positives. All three suggest changes that already match what's in the PR (the paths and commands are correct as written).
|
|
||
| ## Coding Standards | ||
|
|
||
| ### Do |
There was a problem hiding this comment.
This Do/Don't list is a near-copy of the same section in AGENTS.md. If someone adds a convention to AGENTS.md, this file won't get the update. Consider referencing AGENTS.md as the source of truth here instead of duplicating, or add a sync-check note so future maintainers know to keep both in lockstep.
| 3. **Point to real examples** in the codebase (Storage toolset is the best reference) | ||
| 4. **Warn about common mistakes** proactively | ||
| 5. **If you're unsure**, point them to `docs/new-command.md` or suggest opening an issue | ||
| 6. **For Microsoft employees**, remind them to also review [Azure Internal Onboarding Documentation](https://aka.ms/azmcp/intake) |
There was a problem hiding this comment.
This aka.ms/azmcp/intake link is internal to Microsoft. External contributors following the agent's guidance will hit an auth wall. The For Microsoft employees qualifier is good, but since the agent generates this text dynamically, it might present the link without the conditional context. Consider removing this from the agent instructions or ensuring the agent always gates it clearly.
jongio
left a comment
jongio
left a comment
There was a problem hiding this comment.
New commit adds a second agent file at .github/agents/onboarding.agent.md (68 lines) alongside the existing .github/copilot/agents/onboarding.md (296 lines). This is the condensed GitHub Agents format version.
Two concerns with this addition:
-
You now have two agent definitions covering the same onboarding content at different paths. When one is updated, the other goes stale. Consider either making the short one the canonical source and having the longer one reference it, or removing the longer one if the new format replaces it.
-
The
Standard Commandssection in the new file uses-UsePathswhich isn't a valid parameter onBuild-Local.ps1(it only has-NoUsePaths). The original file's Quick Start correctly uses just-VerifyNpx.
…ew skill - Remove .github/copilot/agents/onboarding.md (not discoverable by GitHub) - Update .github/agents/onboarding.agent.md with consolidated content - Replace new-command.md references with /skills add-azure-mcp-tools - Reference AGENTS.md for coding standards instead of duplicating - Fix Build-Local.ps1 invalid -UsePaths flag - Fix consolidated-tools.json path - Update to two-generic pattern ([Option] attributes, SubscriptionCommandUnitTestsBase) - Remove internal-only links (aka.ms/azmcp/intake, private project board) - Add eng/scripts/Update-Solutions.ps1 -All guidance - Use New-TestResources.ps1 for live test deployment Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
|
I didn't realize this PR has been created before reviewing #2918. Could you please consolidate changes in the onboarding agent.md? |
- Update onboarding.agent.md with external MCP server integration, NuGet feed, server modes, and namespace creation guidance - Add docs/Onboarding.md as human-readable onboarding guide with correct patterns - Add onboarding callout tip to CONTRIBUTING.md - Fix typos in CONTRIBUTING.md (Substitue -> Substitute, whem -> when) - Add cspell words: configfile, remotemcp, slnx, uniqueprefix Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
|
|
||
| ## Adding a New Namespace (Toolset) | ||
|
|
||
| A **namespace** is a top-level command group (e.g., `storage`, `keyvault`, `sql`), implemented as a toolset project under `tools/Azure.Mcp.Tools.{Toolset}`. |
There was a problem hiding this comment.
I think this section has too much implementation detail that a first time contributor needs to know during onboarding. It can point people to an architecture doc or existing implementations instead. This also prevents the onboarding doc deviating as the design changes.
I feel it's OK for docs/Onboarding.md to have more details compared to this onboarding.agent.md since this file is more tailored for agent to consume. A concise agent file that can point contributors to the right places to get information would be good enough for the onboarding experience.
|
|
||
| ### Testing Your Local Build | ||
|
|
||
| Point your `mcp.json` at the freshly built binary: |
There was a problem hiding this comment.
How easy is it to setup debugging for the first time? Since the doc mentioned VS Code as a prerequisite, it's good to have VS Code debugging setup instructions.
JasonYeMSFT
left a comment
JasonYeMSFT
left a comment
There was a problem hiding this comment.
I noticed that onboarding.agent.md and Onboarding.md have similar content. Can we simplify the agent.md to function like an index that points contributors to the right places for information and dedupe the content?
Summary
Adds a custom GitHub Copilot agent at
.github/copilot/agents/onboarding.mdthat serves as an interactive onboarding assistant for new contributors.What it does
Contributors can invoke
@onboardingin Copilot Chat to get guided help with:help wantedandgood first issueContent source
All content is sourced from CONTRIBUTING.md and the project's AGENTS.md conventions.
Invoking Livetests
Copilot submitted PRs are not trustworthy by default. Users with
writeaccess to the repo need to validate the contents of this PR before leaving a comment with the text/azp run mcp - pullrequest - live. This will trigger the necessary livetest workflows to complete required validation.