Create Mission Spec

Create Mission Spec

This skill produces a specification issue — not mission content. The output is a GitHub issue

on microsoft/agent-academy that another contributor (or a later run of

agent-academy-mission-builder) can implement from without further research.

The difference matters. A spec issue answers _what should be built and why_. The mission builder

answers _how it reads_. Never write the mission markdown in this skill.

🏁 Prerequisites

• Run gh --version to confirm the GitHub CLI is installed. If missing, install it

(brew install gh on macOS).

• Run gh auth status to confirm authentication. If not authenticated, run gh auth login and

guide the user through the flow.

Do not proceed until both checks pass.

Mission types

Four tracks exist, and each has its own folder, contributing guide, and style section. Identify

the track before anything else, because it determines the frontmatter contract.

| Track | Folder | Contributing guide |

| ----------------- | ------------------------------ | ----------------------------------- |

| Recruit | docs/recruit/NN-slug/ | CONTRIBUTING-COURSES.md |

| Operative | docs/operative/NN-slug/ | CONTRIBUTING-COURSES.md |

| Commander | docs/commander/NN-slug/ | CONTRIBUTING-COURSES.md |

| Special Ops | docs/special-ops/slug/ | CONTRIBUTING-SPECIAL-OPS.md |

| Cowork Collective | docs/cowork-collective/slug/ | CONTRIBUTING-COWORK-COLLECTIVE.md |

CONTRIBUTING-GENERAL.md covers markdown linting and spell checking for every track.

Phase 1: Mine the source documentation

Do this first, before the interview. You cannot offer the user good scoped options until you

know what the product actually does, and an interview built on guesses wastes a round trip.

If the user supplied URLs, fetch all of them in parallel. Extract and keep:

• Exact tool, API, or feature names and their required vs. optional parameters
• Endpoint URLs and placeholder segments (e.g. {environmentId})
• Licensing, role, and version prerequisites
• Governance, admin, and observability surfaces
• Anything gated behind admin rights, preview, or regional availability

These become the spec's Prerequisites, Lab outline, and Risks sections. A spec that

paraphrases the docs is useless; a spec that names the exact tools and endpoints saves the

implementer an hour.

If the user supplied no URLs, ask for them before going further. Never write a spec from memory

about a product surface that changes as fast as these do.

Phase 2: Gather intel

First, list the available milestones so you can offer real options rather than asking a second

time later:

GH_PAGER=cat gh api repos/microsoft/agent-academy/milestones \
  --jq '.[] | "\(.title)  due=\(.due_on)"'

Then ask everything in one batch using the ask-questions tool. Never interrogate one question

at a time. Offer concrete options with a recommended default so the user can answer by picking,

and derive those options from what you found in Phase 1.

Always ask:

• Mission type — Special Ops, Cowork Collective, or a course mission (Recruit / Operative /

Commander)?

• Scenario — what will the learner actually build? Offer 3-4 scoped options drawn from the

documentation rather than asking an open question.

• Surface — which product or client does the mission drive? (Copilot Studio, VS Code, both.)
• Difficulty and time — offer 2-3 sensible pairings, e.g. "Difficulty 3, ~45 min".
• Badge codename (Special Ops only) — offer 3-4 punchy options.
• Milestone — which fiscal quarter does this target? Offer the open milestones you just

listed, with the nearest one recommended. This is the due date.

• Deliverable — draft the body in chat, post the issue directly, or save to a file?

If the user already stated something in their prompt (for example "avoid the connectors one, start

with Graph APIs"), do not ask about it again. Treat it as a hard scope boundary and reflect it in

the Out of scope section.

Phase 3: Repo reconnaissance

Run these in parallel:

• Duplicate check in the docs — grep_search the repo for the feature name. Distinguish a

real duplicate (an existing mission on the topic) from a passing mention in another mission.

Report either way in the issue, and link passing mentions as cross-link targets.

• Duplicate check in the issues — someone may have already filed this spec. Run

GH_PAGER=cat gh issue list --repo microsoft/agent-academy --state all --search "<keyword>".

Grepping the docs alone misses proposals that have not been implemented yet.

• Read the contributing guide for the track — see the Mission types table above. Each guide

defines a different frontmatter contract; Special Ops omits prev, next, and codename,

which course missions require.

• Validate slugs — read docs/.vitepress/data/tags.json, products.json, and

industries.json. Every tags, products, and industries value in the proposed frontmatter

must already exist in those files. If one does not, either pick an existing slug or add an

explicit acceptance-criteria item to create it.

• Find the closest existing mission — use it as the structural reference and name it in the

issue so the implementer has a template to copy.

• Read WRITING_STYLE.md — specifically the section matching the mission type. Course

missions, Special Ops, and Cowork Collective have different required sections and intros. The

spec must reflect the right one; proposing a codename for a Special Ops mission or omitting

the ⚙️ Prerequisites section is a spec bug, not an authoring bug.

If either duplicate check finds a genuine match, stop and tell the user before drafting. Offer

to pivot the angle, extend the existing mission, or proceed anyway. Do not silently file a second

spec for work that already exists.

Phase 4: Title convention

Format: [New Mission] <Section>: <Action verb> <what they build>

Examples:

• [New Mission] Special Ops: Build your own MCP server with the MCP Management Server
• [New Mission] Operative Mission 12: Ground an agent in SharePoint knowledge
• [New Mission] Cowork Collective: Turn a badge-scan export into an emailed report

Rules:

• The prefix is [New Mission], not [New Lab]. Missions are the unit of content in this repo

across every track.

• Keep the whole title under 80 characters. GitHub truncates issue titles around 70 in list

views.

• One bracketed prefix only. Do not nest a pipe inside the brackets — [New Mission | Special Ops]

reads like a UI breadcrumb and costs characters without adding information.

• Course missions are sequential, so include the proposed number (Operative Mission 12). Confirm

the next free number from the track's index.md before claiming it. Special Ops and Cowork

Collective are standalone and take no number.

• Avoid repeating a product acronym. "Microsoft MCP Management Server" says MCP twice; "MCP

Management Server" is enough because the body spells it out.

• Prefer "Build your own" over "Build a custom" — shorter and states the value.
• Mirror the final title as the body's H1 so the issue reads consistently.

Phase 5: Draft the issue body

Write the body to a temp file outside the workspace (/tmp/), never into the repo. Use this

structure:

# <title>

## Summary

What the mission teaches, and the specific curriculum gap it closes. Name the existing missions
that cover adjacent ground so the gap is provable, not asserted. State the scope boundary here.

## Proposed mission

A table: Section, Folder, Title, Operation codename, Badge, Difficulty, Time.

### Proposed frontmatter

A fenced yaml block matching the contributing guide exactly for that mission type.
Follow it with a line confirming whether the tag/product/industry slugs already exist.

## Scenario

A fictional company, an industry, and a concrete problem. Include the analogy the mission
should use in its concept brief.

## Mission objectives

Bulleted, one concrete capability each, phrased as what the learner will do.

## Prerequisites (to state in the mission)

Licenses, roles, tool versions, tenant availability, and links. Bold any hard blocker.

## Proposed lab outline

A Recon section explaining the concept, then numbered labs. For each lab, one bold heading and
two or three sentences naming the exact tools, parameters, and UI paths involved. End with a
cleanup lab where the mission creates real resources.

## Acceptance criteria

A checkbox list covering: files created, assets and screenshots, required components
(`<mission-meta />`, `<analytics-tag />`), badge claim section, cross-links, conformance to
`WRITING_STYLE.md`, and every validation command from the contributing guide.

## Out of scope

Everything deliberately deferred, each on its own line. Name the follow-up mission where one
is implied.

## Risks

Access barriers, admin gates, and availability gaps that could block learners mid-lab.

## References

Every source URL used, with descriptive link text.

Only include a preview field or preview framing if the user confirms the mission should be

flagged as preview. Do not add it on the assumption that a preview product implies a preview

mission — those are separate decisions.

Phase 6: Writing-style check

Before posting, read WRITING_STYLE.md and run the draft against it. Two things get checked.

The spec's own prose

The issue is repo content and should read like it. Verify:

• Active voice, present tense, learner addressed as "you" in any objective or prerequisite text
• Sentences of 15-25 words; long paragraphs broken up
• Select, never "click". Field, never "textbox". This is an accessibility requirement,

not a preference — learners may use keyboard, touch, or a screen reader

• Action verbs opening every step-like line: Select, Enter, Navigate, Configure, Choose, Upload
• Exact UI text in bold; values to type in code format
• Objectives phrased as skills gained, not tasks performed, with parallel structure
• Mission-themed but professional tone; no marketing adjectives

The style constraints the spec must pass on

The implementer should not have to rediscover these. State the ones that apply in the lab outline

or acceptance criteria:

| Mission type | Style requirements the spec must name |

| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

| Course | Codename as OPERATION NAME, time-estimate blockquote, Mission Brief of 150-250 words, 3-5 objectives, theory before every lab, Mission Complete with next-mission link |

| Special Ops | No codename, agent-themed hook, dedicated ⚙️ Prerequisites section, all concepts explained in-mission, badge claim section at width="200" |

| Cowork Collective | 🔍 The Problem then 🎯 The Scenario, 📋 What You'll Produce checklist, full copy-pasteable prompts in fenced blocks, approval-flow steps documented |

Also carry forward the screenshot rules when the mission needs images: light theme, no browser

frame, no cursor, Microsoft red #e91c1c highlight boxes at 4px, cropped to the relevant region.

Fix anything the check surfaces before posting. Do not post and then clean up.

Phase 7: Post the issue

Unless the user has already asked you to post, show the draft and get confirmation first. Filing

an issue on a public Microsoft repo notifies watchers and cannot be undone quietly.

Gather the metadata

A spec issue needs four things set: title, label, milestone, and assignee. The milestone

carries the due date — GitHub issues have no native due-date field, so the repo tracks delivery

through fiscal-quarter milestones.

• Label — feature-request is the correct label for new content proposals. There is no

special-ops or new-mission label. Confirm with

GH_PAGER=cat gh label list --repo microsoft/agent-academy --limit 50.

• Milestone — use the quarter the user picked in Phase 2. Milestones are named by fiscal

quarter, for example FY27Q1 and FY27Q2. Do not ask again here.

• Assignee — default to the requesting user. Confirm the GitHub login with

GH_PAGER=cat gh api user --jq .login.

Create it

gh issue create --repo microsoft/agent-academy \
  --title "<title>" \
  --label feature-request \
  --milestone "FY27Q1" \
  --assignee "<login>" \
  --body-file /tmp/<name>.md

To set a milestone or assignee on an issue that already exists, use gh issue edit <n> --milestone

and gh issue edit <n> --add-assignee.

Phase 8: Verify and clean up

• Read the issue back:

   GH_PAGER=cat gh issue view <number> --repo microsoft/agent-academy \
     --json title,labels,milestone,assignees,url

Do not request projectCards — Projects (classic) is deprecated and the field errors the whole

query out.

• Confirm all four are set: title, label, milestone, assignee. A spec with no milestone has no due

date and drops off the plan.

• Confirm the body's H1 matches the title exactly. These drift easily and nothing else catches it.
• Delete the temp file.
• Report the issue URL to the user.

📜 Rules

• Always prefix gh commands with GH_PAGER=cat. Without it, gh opens an alternate screen

buffer and the tool returns no output.

• Always pass the body via --body-file. Inline --body mangles long markdown and breaks on

backticks and newlines.

• Always write temp files to /tmp/, never into the repo, and always delete them afterward.
• Never create mission markdown files in docs/ from this skill. The output is an issue only.
• Never invent tag, product, or industry slugs. Read the JSON data files and use what exists.
• Never state a duplicate check result you did not actually run, and always check both the docs and

the existing issues.

• Always confirm with the user before posting, unless they already asked you to post.
• Never post a spec issue without a milestone. The milestone is the due date, and an unmilestoned

spec is invisible to planning.

• Never request projectCards in a gh issue view --json query. Projects (classic) is deprecated

and the field fails the entire request.

• Always run the Phase 6 writing-style check before posting. WRITING_STYLE.md is the source of

truth, and its per-mission-type sections differ — read the one that applies.

• Never write "click" or "textbox" anywhere in the spec. Use "select" and "field".
• When editing an existing spec issue's title, update the body's H1 in the same pass so the two

never drift.

• To edit a posted body: fetch it with gh issue view <n> --json body -q .body > /tmp/b.md, edit

the file, then gh issue edit <n> --body-file /tmp/b.md.