New Microsoft Learn Module Skill

A GitHub Copilot Skill that helps Microsoft Cloud Advocates and Microsoft Learn authors start drafting new Microsoft Learn training modules — from a topic idea to a review-ready draft with the correct folder structure, valid YAML, drafted Markdown, required metadata, and a knowledge-check quiz.

The skill targets the MicrosoftDocs/learn-pr publishing repository conventions and supports two module types:

• Standard modules — task/skill based, often with a hands-on exercise.
• "Introduction to" modules — conceptual, helping the audience decide whether/when to use a product or feature.

The skill produces a draft for human review. Authors remain responsible for technical accuracy, brand/style compliance, and opening the pull request.

What it does

Given a topic idea, GitHub Copilot will:

1. Gather inputs — module type, target learn-pr/<product>/ folder, author identity (GitHub + Microsoft aliases), audience role/level, and any source material.
2. Research the topic from author-provided sources and first-party docs.
3. Scaffold the full module folder: index.yml, numbered unit .yml files, includes/*.md content files, and a media/ folder.
4. Draft the content unit by unit, in Microsoft Learn style.
5. Add required metadata, setting the requesting user as the module author / ms.author.
6. Generate a knowledge check (3–5 understanding-focused questions, 3 options each, one correct, with explanations for every option).
7. Validate and summarize the draft with a TODO: checklist and an editorial preflight for canonical product naming, acronym expansion, semantic list types, accessible image text, publication-safe filenames, and spelling/grammar quality.

Installing the skill

A skill is a folder containing a SKILL.md file. Your GitHub Copilot client discovers skills under its skills directory — per user at ~/.copilot/skills/ (on Windows, $HOME\.copilot\skills\), or per workspace/repo if you include the folder in your repository.

Pick one of the two options below. After installing, restart/reload your editor so the skill is discovered. It then activates automatically when you ask Copilot to create or draft a Microsoft Learn module.

Option 1 — Copy the folder

Copy this skill folder directly into your Copilot skills directory:

$dest = "$HOME\.copilot\skills\new-mslearn-module"
New-Item -ItemType Directory -Force -Path (Split-Path $dest) | Out-Null
Copy-Item -Recurse -Force -Path "C:\GitHub\NewMSLearnModuleSkill" -Destination $dest

Simple and self-contained, but you must re-copy to pick up updates.

Option 2 — Clone once, then symlink (stays up to date with git pull)

Clone the repo to a generic location, then create a symbolic link from the Copilot skills directory to that clone. Updating later is just git pull — no re-copy needed.

# 1. Clone once to a generic location (skip if you already have it locally)
git clone https://github.com/<your-org-or-user>/NewMSLearnModuleSkill.git .\NewMSLearnModuleSkill

# 2. Ensure the Copilot skills directory exists
New-Item -ItemType Directory -Force -Path "$HOME\.copilot\skills" | Out-Null

# 3. Symlink the cloned folder into the skills directory
New-Item -ItemType SymbolicLink `
  -Path "$HOME\.copilot\skills\new-mslearn-module" `
  -Target "<location of your clone>\NewMSLearnModuleSkill"

Resulting module layout

The skill generates modules in the learn-pr layout. Note that the repo is MicrosoftDocs/learn-pr and it contains an inner folder also named learn-pr/; module paths below are relative to that inner folder (e.g. the live sample lives at learn-pr/azure/intro-to-azure-cloud-shell/):

learn-pr/<product>/<module-folder-name>/
├── index.yml                     # Module definition + metadata + unit list
├── 1-introduction.yml
├── 2-<slug>.yml                  # Content units
├── <n>-knowledge-check.yml       # YAML only — no Markdown file
├── <n+1>-summary.yml
├── includes/                     # One .md per unit EXCEPT the knowledge check
│   ├── 1-introduction.md
│   ├── 2-<slug>.md
│   └── <n+1>-summary.md
└── media/                        # Images, diagrams, video thumbnails

Using the skill

In GitHub Copilot Chat, describe the module you want, for example:

Create a new "Introduction to" Microsoft Learn module about Azure Cloud Shell. It goes under the azure folder. My GitHub alias is myalias and my Microsoft alias is myalias.

Copilot will ask any missing questions, then scaffold and draft the module. When working outside a real learn-pr clone, it generates the module under a local working folder (e.g. drafts/learn-pr/<product>/...) so you can copy it into your learn-pr fork and open a pull request.

Prerequisites & access

• Publishing to Microsoft Learn requires access to the private MicrosoftDocs/learn-pr repository under the MicrosoftDocs organization. The skill drafts content locally; you push to your fork and open a PR through your authorized account.
• Recommended: enable the Microsoft Learn Docs MCP server so Copilot can ground the draft in first-party Microsoft Learn content (microsoft_docs_search / microsoft_docs_fetch). The skill prefers it over generic web fetches. It's optional — the skill falls back to fetch_webpage.
• The skill does not push, commit, or open PRs on your behalf.

References

• Create a module (Microsoft Learn Help)
• Standard modules guidance
• Introduction modules guidance
• Required metadata for training modules
• Create the scaffold manually

Disclaimer

This skill accelerates drafting; it does not replace editorial review. Always verify product behavior, limits, pricing, and links against official first-party documentation before publishing. Generated content may contain TODO: markers indicating where author input is required.

Contributions

Contributions are welcome! Open an issue or PR here to improve the skill, add features, or report bugs. Please follow the Microsoft Learn contribution guidelines and Microsoft Open Source Code of Conduct.