microsoft/agent-academy: What the Copilot Studio Course Repo Actually Contains

What microsoft/agent-academy is, and what it is not

The repository describes itself as hosting a three part course for people who want to build agents with Microsoft Copilot Studio. That sentence is the whole product statement. The README's first instruction is to visit the hosted course at the aka.ms link rather than to read the repository, which tells you where the intended audience is supposed to land.

So the repo is a content and publishing project. The package.json marks it as private and version 1.0.0, with VitePress, markdownlint-cli2, Playwright, gray-matter, jszip, mermaid and the Fluent UI SVG icons as dev dependencies. There is no agent runtime here, no SDK surface, no API to call. If you arrived looking for a library that builds Copilot Studio agents, this is the wrong repository and the README will not redirect you, because it never claims otherwise.

Who it is for: people who teach, write or maintain Copilot Studio onboarding material, and learners who want the course content in source form rather than through the hosted site. The topics list (agents, copilot) is accurate but thin; the real subject is curriculum authoring.

How the course content is assembled and published

The mechanism is visible in package.json. Course pages live under docs/ as markdown, and VitePress turns that directory into a site. Two scripts wrap the build: docs:dev and docs:build both run node scripts/copy-badges.mjs first, then hand off to vitepress dev docs or vitepress build docs. The badge copy step exists because icons are pulled from @fluentui/svg-icons and simple-icons at build time rather than committed by hand, which is why the script runs before VitePress in both commands.

A second script, lint:md, runs markdownlint-cli2 over docs/**/*.md while excluding docs/node_modules. That exclusion matters: without it the linter would walk into installed packages inside the docs tree. The lint configuration is .markdownlint.jsonc, with .markdownlintignore alongside it, and cspell.json handles spell checking. WRITING_STYLE.md sits at the top level as the prose counterpart to those machine checks.

The repository also carries four separate contributing guides rather than one: CONTRIBUTING-GENERAL.md plus CONTRIBUTING-COURSES.md, CONTRIBUTING-SPECIAL-OPS.md and CONTRIBUTING-COWORK-COLLECTIVE.md. That split is the clearest signal of the content model. Courses, Special Ops missions and Cowork Collective missions are treated as distinct contribution tracks with their own rules, and CUSTOM-COMPONENTS.md is the reference for the markdown components those pages are allowed to use. If you plan to send a pull request, the general guide is not sufficient on its own.

Installing the repository and running the docs site locally

There are no install instructions in the README. The scripts in package.json are the only documented entry points, so treat the commands below as what the repository layout supports rather than as a published quickstart. You need Node.js and npm available; the repository does not state a minimum version, and the dev dependencies include @types/node ^25.6.2 and VitePress ^2.0.0-alpha.12, so a recent Node release is the safe assumption.

Get the source and install the dev dependencies:

git clone https://github.com/microsoft/agent-academy.git
cd agent-academy
npm install

Start the local documentation server. The copy-badges step runs first, so you should see icon assets written before VitePress reports its local URL:

npm run docs:dev

To produce the static site instead, run the build script. The output is a VitePress build directory, and docs:preview then serves that output for inspection:

npm run docs:build
npm run docs:preview

Before committing any markdown change, run the linter. It targets docs/**/*.md and skips docs/node_modules:

npm run lint:md

If the linter reports nothing, your page conforms to .markdownlint.jsonc. If it reports violations, the rules to satisfy are in that file, not in the README.

What the README does not tell you

The README is short and points outward. It does not document the course structure beyond calling it three parts, even though CONTRIBUTING-COURSES.md names Recruit, Operative and Commander missions and CONTRIBUTING-SPECIAL-OPS.md covers standalone missions. It does not state prerequisites, a Copilot Studio licence requirement, or a sign-in flow for the hosted course. It does not describe the docs/ directory layout, the VitePress configuration, or how the hosted site at the aka.ms link is deployed from this repository. There is no rollback guidance, no release history, and no changelog: the repository has no releases, so there is no versioned upgrade path to follow.

The practical consequence is that the README answers "what is this" and stops. Everything operational lives in the contributing guides, CUSTOM-COMPONENTS.md and WRITING_STYLE.md. A contributor who reads only the README will miss the markdown component vocabulary and the section-specific review rules, and will likely have a pull request bounced for style rather than substance.

One more gap worth naming: the repository is public under MIT, but the course teaches Copilot Studio, a Microsoft product with its own licensing. Nothing in the README connects the two, so the open licence on the content should not be read as anything about the product it teaches.

The contribution gate: CLA, linting and four separate guides

Most contributions require agreeing to a Contributor License Agreement, per the README. A CLA bot checks each pull request and decorates it with a status check and comment; the README states you only need to complete this once across all Microsoft repositories using the same CLA. That is a one-time cost, but it is a gate before review, not after.

Behind the CLA sit the mechanical checks. markdownlint-cli2 enforces .markdownlint.jsonc, cspell.json enforces spelling, and WRITING_STYLE.md covers prose that neither tool can judge. Playwright appears in devDependencies, which suggests browser-level testing exists somewhere in the project, but the README does not describe a test command and package.json exposes no test script, so the test surface is not something you can invoke from the documented scripts.

The alternative to contributing here is simply not to. If you want to adapt the course for an internal audience, the MIT licence lets you fork and edit the markdown without going through the CLA, the four contributing guides or the lint rules. You lose upstream fixes, and you inherit the maintenance yourself. For a training team that wants its own branding and sequence, that trade is often the right one.

Licence, maintenance and what upgrading costs

The licence is MIT. That permits reuse, modification and redistribution of the repository contents, including the course markdown, provided the licence terms are met. It says nothing about Copilot Studio itself, and the README's trademark section adds a separate constraint: Microsoft trademarks and logos may be used only under Microsoft's Trademark & Brand Guidelines, and modified versions must not imply Microsoft sponsorship. For a fork that keeps the Fluent UI and simple-icons assets, the copy-badges script is the place those assets enter the build.

The last push was on 2026-09-13, two days before this writing, so the repository is not archived and is being changed. There are no releases, which means there is no version number to pin and no changelog to read before pulling. Upgrading means pulling main and re-running npm install, and the dev dependency list is where breakage would surface: VitePress is on a 2.0.0 alpha, @types/node is on a major version that moves quickly, and the package.json carries an override pinning lodash-es to ^4.18.1 plus an allowScripts block for esbuild and fsevents. Those three details are the ones most likely to need attention on a fresh install on a new machine.

There is no support contract implied. SUPPORT.md and SECURITY.md exist at the top level, but the README does not describe response times or a maintenance commitment for the course content.

Editorial conclusion

Clone this repository if you write or maintain Copilot Studio training content and want the course source, the markdown linting rules and the custom component reference in one place; the last push was on 2026-09-13, so it is current. Do not clone it expecting runnable agent code or an SDK, because the repository holds course material and site tooling rather than an agent runtime, and the README does not document how a learner signs in or which Copilot Studio licence a mission requires. Verify two things before you commit to it: that the three course tracks (Recruit, Operative, Commander) match the skill level you are teaching, and that the CONTRIBUTING-COURSES.md and WRITING_STYLE.md rules fit your own review process, since those files, not the README, govern what a merged lesson looks like.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. microsoft/agent-academy on GitHub
4. Project website
5. README