lab-readme-authoring - SKILL.md Agent Skill

name: lab-readme-authoring description: Procedures for generating lab README.md content, section by section. Section order is defined in lab-shared-contract R-011. user-invokable: false

Lab README Authoring

Procedures for generating README content for Azure hands-on labs. Section order and count are defined in lab-shared-contract R-011 — this skill defines the content guidelines for each section.

When to Use

Writing README content for a new lab
Validating README content completeness
Generating specific sections of a lab README

README Template

Starting template: .github/skills/lab-azure-governance/templates/README.template.md (see lab-azure-governance R-160).

R-140: Per-Section Content Guidelines

Section order: see lab-shared-contract R-011.

Section 0: Title and Exam Coverage Metadata

The H1 title is followed immediately by exam coverage metadata. These lines are used by Update-CoverageTable.ps1 to populate the Exam Coverage table in each exam README.

# <Lab Title>

**Domain:** <Exam Domain from intake>
**Skill:** <Skill from intake>
**Task:** <Task from intake>

Rules:

Use the Exam Domain, Skill, and Task values from the intake metadata (R-041/R-043) — not the folder-path Domain.
Use exact wording — these values are copied verbatim from the exam's Skills.psd1 hierarchy.
If the intake specifies multiple tasks, use a header plus bullets:

**Task:**
- <task 1>
- <task 2>

Insert a blank line after the metadata block before the first ## section heading.

Section 1: Exam Question Scenario / Exam Task

Content depends on the Intake Mode field from the Phase 1 metadata.

Question Mode (Intake Mode: Question):

## Exam Question

> **Exam**: [EXAM] — [Domain]

### <Title from intake>

*<Question Type>*

<Scenario text, options, and answer table — copied verbatim from intake file>

The ## Exam Question heading and > **Exam** context line are the only new content.
Everything below them must be copied verbatim from the intake file (everything before ## Phase 1 — Metadata Output).
Preserve the Lab-Intake format exactly: H3 title, italic question type, paragraph breaks, lettered options with trailing spaces, answer tables, code blocks, and blank-token syntax.
Do not restructure, re-wrap, renumber, or paraphrase any part of the question.
Do NOT reveal the correct answer in this section.

Task Mode (Intake Mode: Task):

## Exam Task

> **Exam**: [EXAM] — [Domain]

### <Task name>

<Task overview and learning objectives — copied verbatim from intake file>

The ## Exam Task heading and > **Exam** context line are the only new content.
Everything below them must be copied verbatim from the intake file (everything before ## Phase 1 — Metadata Output).
Preserve the Lab-Intake format exactly: task overview paragraphs, numbered learning objectives.
Do not restructure or paraphrase.

Section 2: Solution Architecture

## Solution Architecture

[2-4 sentences from the architecture summary]

Section 3: Architecture Diagram

## Architecture Diagram

A Mermaid diagram is always required (lab-shared-contract R-013).
When 2+ interconnected resources: diagram the resource topology.
When fewer than 2 interconnected resources: diagram the overall process reflective of the exam question.

Section 4: Lab Objectives

## Lab Objectives

1. [Objective 1]
2. [Objective 2]
3. [Objective 3]

3–5 specific, measurable objectives aligned with the exam question.

Section 5: Lab Structure

## Lab Structure

Show the actual file tree of the lab.

Section 6: Prerequisites

## Prerequisites

- Azure subscription with required permissions
- Azure CLI installed and authenticated
- [Terraform >= 1.0 | Bicep CLI] installed
- PowerShell 7+ with Az module

Adapt to the deployment method.

Section 7: Deployment

Include the validation sequence from lab-shared-contract R-018 for IaaC labs.
Keep deployment instructions brief and actionable.

Section 8: Testing the Solution

Step-by-step validation with specific commands or portal navigation.
Include expected outcomes for each step.

Section 9: Cleanup

## Cleanup

> Destroy within 7 days per governance policy.

Include cleanup command for the deployment method.
Note purge requirements for soft-delete resources (lab-shared-contract R-016).

Section 10: Scenario Analysis / Task Deep Dive

Content depends on the Intake Mode field from the Phase 1 metadata.

Question Mode (Intake Mode: Question):

## Scenario Analysis

### Correct Answer: [Letter]

[Explanation]

### Why Other Options Are Incorrect

- **[Option]**: [Reasoning]

This is the only section where the correct answer is revealed.
Provide reasoning for every incorrect option.

Task Mode (Intake Mode: Task):

## Task Deep Dive

### Key Concepts

[Core concepts and terminology the user must understand]

### Best Practices

[Recommended configurations, patterns, and approaches]

### Common Pitfalls

[Frequent mistakes and misconceptions to avoid]

### Exam Relevance

[How this task typically appears on the exam — question patterns, tested scenarios, depth of knowledge expected]

Cover the task comprehensively to bring the user up to speed.
Reference findings from the question bank scan (if related practice questions were found).
Keep each sub-section concise (3–5 bullet points or short paragraphs).

Section 11: Key Learning Points

5–8 concise, actionable points focused on exam-relevant knowledge.

Section 12: Related Objectives

Link to specific exam objective references.

Section 13: Additional Resources

Links to official Microsoft documentation.
Relevant Learn modules or training paths.

Section 14: Related Labs

▶ Related Lab: [lab-folder-name](../../domain/lab-folder-name/README.md)

0–2 related labs using relative paths.

R-141: Template Reference

Starting template: .github/skills/lab-azure-governance/templates/README.template.md

R-142: Rules

No code header block in README (lab-shared-contract R-012 applies to code files only).
Correct answer revealed only in Section 10.
All 14 sections must appear, even if brief.
Use Mermaid diagrams only when meaningful (lab-shared-contract R-013).

R-143: When-to-Use Criteria

Use this skill when creating or validating README content for a hands-on lab.