Skip to content

CONTRIBUTING-SPECIAL-OPS.md

Latest commit

 

History

History
214 lines (156 loc) · 8.37 KB

CONTRIBUTING-SPECIAL-OPS.md

File metadata and controls

214 lines (156 loc) · 8.37 KB
Raw

Contributing to Special Ops

Special Ops are standalone, one-off missions designed to sharpen skills in a specific area. Unlike course missions, they have no sequential navigation and are self-contained.

For general tooling setup (markdown linting, spell checking, local preview), see CONTRIBUTING-GENERAL.md. For writing style rules, see WRITING_STYLE.md. For custom component reference, see CUSTOM-COMPONENTS.md.

Folder structure

docs/special-ops/
├── index.md                          ← Landing page (uses <missions /> component)
├── assets/                           ← Shared badge images for all missions
│   ├── MCP_Joker_Badge.png
│   ├── YAML_Specialist_Badge.png
│   └── ...
├── mcs-mcp/
│   ├── index.md                      ← Mission content
│   ├── assets/                       ← Mission-specific screenshots
│   └── source/                       ← Optional: deployable code (Dockerfile, src/, etc.)
├── yaml-specialist/
│   ├── index.md
│   └── assets/
└── ...

Naming conventions

  • Mission folders: kebab-case/ (no numbering — missions are standalone)
  • Main content file: always index.md
  • Mission-specific assets: assets/ subfolder inside the mission folder
  • Badge images: stored in the shared docs/special-ops/assets/ folder, named Mission_Name_Badge.png
  • Screenshot filenames: description.png in lowercase with hyphens
  • All filenames lowercase with hyphens, no spaces

Required frontmatter

Every Special Ops mission requires the following YAML frontmatter:

---
tags:
  - yaml
difficulty: 3
time: 60
harness: standard
description: 'Build and extend Copilot Studio agents entirely from VS Code using the YAML agent definition language.'
badge: ../assets/YAML_Specialist_Badge.png
products:
  - copilot-studio
  - visual-studio-code
  - github-copilot
industries:
  - it
created-date: 2026-03-30
last-edited-date: 2026-04-02
---

Field reference

Field Type Required Description
tags string[] Yes Array of tag slugs from docs/.vitepress/data/tags.json.
difficulty number (1–5) Yes Difficulty level from 1 (beginner) to 5 (expert).
time number Yes Estimated completion time in minutes. Must be greater than 0.
harness string | string[] No The Microsoft Copilot Studio harness used by the agent: standard or github-copilot. Use an array only when the mission supports both harnesses.
description string Yes Mission description (minimum 10 characters). Used in mission cards and the <missions /> grid.
badge string Yes Relative path to the badge image in the shared assets folder (for example ../assets/Badge_Name.png).
products string[] Yes Array of product slugs from docs/.vitepress/data/products.json.
industries string[] Yes Array of industry slugs from docs/.vitepress/data/industries.json.
created-date date Yes ISO date when the mission was first published.
last-edited-date date Yes ISO date of the most recent edit. Update this on every change.
hide boolean No Set to true to exclude the page from all <missions /> grids. The page remains directly accessible.
preview boolean | string No Set to true to show a preview banner at the top of the page. Provide a string to replace the default banner text.

Important

Special Ops missions do not use prev, next, short-description, codename, or section in their frontmatter. They are standalone — there is no sequential navigation.

The <mission-meta /> component displays harness as a pill near the top of the page. Use standard harness and GitHub Copilot harness in learner-facing text. The field describes the Copilot Studio agent harness, not whether a mission uses GitHub Copilot in Visual Studio Code or the GitHub Copilot CLI.

For a mission that supports both Copilot Studio harnesses, use an array:

harness:
  - standard
  - github-copilot

Missions that use the GitHub Copilot harness must place this notice at the end of the prerequisites section:

> [!IMPORTANT] GitHub Copilot harness billing
> This mission uses the **GitHub Copilot harness in Microsoft Copilot Studio**, which uses usage-based billing. Building, testing in Preview, evaluating, and using the agent might consume **Copilot Credits**. Review the [Copilot Credits billing overview](https://learn.microsoft.com/microsoft-copilot-studio/agents-experience/billing-credit-overview) before you begin.

Frontmatter validation

Special Ops frontmatter is validated automatically by scripts/validate-frontmatter.mjs. The script checks:

  • difficulty is a number between 1 and 5
  • time is a number greater than 0
  • description is a string with at least 10 characters
  • created-date and last-edited-date are valid dates
  • preview, when present, is a boolean or a string
  • harness, when present, contains only supported harness slugs

Run the validation locally:

node scripts/validate-frontmatter.mjs

Mission content structure

Special Ops missions follow this layout:

# 🧬 Mission Title {#mission-slug}

<mission-meta />

![Badge image](../assets/Mission_Badge.png){ width="300" }

Welcome, agent. Your mission, should you choose to accept it...

[1-2 paragraphs introducing the mission context and what the agent will accomplish]

## Mission objectives

- Objective one
- Objective two
- Objective three

## ⚙️ Prerequisites

- [Tool/access requirement with link](https://example.com)
- Another requirement

## Concept Section Title

Conceptual content explaining the topic.

> [!INFO] What is X?
> Brief explanation of the core concept.

## Lab 1.1: First Lab Section

1. Step one
1. Step two

    ![Screenshot description](./assets/screenshot-name.png)

1. Step three

## ✅ Mission Accomplished

You completed this Special Ops mission! Here is what you accomplished:

✅ **Skill One**: Description
✅ **Skill Two**: Description

## 📚 Tactical Resources

- 📖 [Resource title](https://learn.microsoft.com/...)

## 🏅 Claim your completion badge

![Badge](../assets/Mission_Badge.png){ width="200" }

[Submit the completion form](https://forms.example.com)

<analytics-tag section="special-ops" mission="mission-slug" />

Key differences from course missions

Aspect Courses Special Ops
Navigation Sequential (prev/next in frontmatter) Standalone (no navigation links)
Codename Required (OPERATION NAME) Not used
Folder naming NN-kebab-case/ (numbered) kebab-case/ (no numbers)
Description field short-description description (validated, min 10 chars)
Badge location Course-level course-completion-badges-*/assets/ Shared docs/special-ops/assets/
Source code Not included Optional source/ folder for deployable code

Content patterns

  • Mission intro: Use a dramatic, agent-themed opener: "Welcome, agent. Your mission..."
  • Prerequisites: Always include a dedicated section listing tools, accounts, and access requirements with direct links.
  • Concept explanations: Special Ops missions are self-contained, so they must explain all prerequisite concepts within the mission itself. Use [!INFO] callouts for quick definitions and comparison tables for decision points.
  • Badge claim: Every mission ends with a badge claim section showing the badge image and a link to the completion form.

Adding a new Special Ops mission

  1. Create a folder: docs/special-ops/your-mission-name/

  2. Create index.md with the required frontmatter and content structure.

  3. Create an assets/ subfolder for screenshots.

  4. Add the badge image to the shared docs/special-ops/assets/ folder.

  5. Add any new tags, products, or industries to the corresponding JSON files in docs/.vitepress/data/.

  6. Run frontmatter validation:

    node scripts/validate-frontmatter.mjs

  7. Run npm run docs:dev and verify your mission appears on the Special Ops landing page and renders correctly.

  8. Run linting and spell check:

    markdownlint-cli2 "docs/special-ops/your-mission-name/**/*.md"
cspell "docs/special-ops/your-mission-name/**/*.md"