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.
| - Browse the [issues list](https://github.com/microsoft/mcp/issues) | ||
| - Issues labeled **[help wanted](https://github.com/microsoft/mcp/labels/help%20wanted)** are good PR candidates | ||
| - Issues labeled **[good first issue](https://github.com/microsoft/mcp/labels/good%20first%20issue)** are ideal for first-time contributors | ||
| - Check the [GitHub project board](https://github.com/orgs/Azure/projects/812/views/13) for priorities |
There was a problem hiding this comment.
Is this Azure org project board publicly visible? If it's a private board, external contributors will get a 404 when the agent sends them here.
There was a problem hiding this comment.
seems like this is an old link from the old azure-mcp project
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.
| - **Unit Tests**: `./eng/scripts/Test-Code.ps1` | ||
| - **Format Code**: `dotnet format` | ||
| - **Spelling Check**: `.\eng\common\spelling\Invoke-Cspell.ps1` | ||
| - **Specific Tests**: `dotnet test --filter "FullyQualifiedName~StorageAccountGetCommandTests"` |
There was a problem hiding this comment.
-UsePaths isn't a valid parameter on Build-Local.ps1. The script has -NoUsePaths (to disable path-scoped builds) but -UsePaths doesn't exist as a switch. The Quick Start in the other file correctly uses just ./eng/scripts/Build-Local.ps1 -VerifyNpx.
| user-invocable: true | ||
| --- | ||
|
|
||
| You are a **friendly onboarding assistant** for the Azure MCP project. Your job is to guide new contributors through environment setup, codebase understanding, and their first contributions. Be conversational, patient, and proactive about common pitfalls. |
There was a problem hiding this comment.
This file covers the same onboarding ground as .github/copilot/agents/onboarding.md (296 lines) in the same PR. If this condensed format is the new standard for GitHub Agents, consider removing the longer file or at minimum cross-referencing so maintainers know which to update.
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.