| 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.
