azure-workload-docs

name	azure-workload-docs
description	Generates comprehensive Azure workload documentation from deployed infrastructure. Creates 7 document types: design document, operations runbook, resource inventory, backup/DR plan, compliance matrix, cost estimate, and documentation index. Synthesizes from WAF assessments, Bicep templates, and deployment artifacts. **Triggers**: "generate documentation", "create workload docs", "document the deployment"
compatibility	Works with Claude Code, GitHub Copilot, VS Code, and any Agent Skills compatible tool. No external dependencies required.
license	MIT
metadata	{"author":"jonathan-vella","version":"1.0","category":"workflow-automation"}

Azure Workload Documentation Skill

Generate comprehensive, production-ready documentation for deployed Azure infrastructure. This skill creates a complete documentation package from existing artifacts.

When to Use This Skill

Trigger Phrase	Use Case
"Generate workload documentation"	Create full doc package
"Document the deployment"	Post-deployment documentation
"Create operations runbook"	Specific runbook generation
"Generate resource inventory"	List all deployed resources

Output Files

All documentation is saved to agent-output/{project}/:

File	Purpose	Template
07-documentation-index.md	Master index linking all docs	Required
07-design-document.md	10-section technical design	Required
07-operations-runbook.md	Day-2 operational procedures	Required
07-resource-inventory.md	Complete resource listing	Required
07-ab-cost-estimate.md	As-built cost analysis	Required
07-compliance-matrix.md	Security control mapping	Optional
07-backup-dr-plan.md	Disaster recovery procedures	Optional

Source Artifacts

This skill synthesizes from existing project artifacts:

Source	Information Extracted
01-requirements.md	Business context, NFRs, compliance needs
02-architecture-assessment.md	WAF scores, SKU recommendations
04-implementation-plan.md	Resource inventory, dependencies
06-deployment-summary.md	Deployed resources, outputs
infra/bicep/{project}/	Actual configuration values

Example Prompts

Full Documentation Package

Generate comprehensive workload documentation for the ecommerce project.
Include all 7 document types with resource inventory from the deployed infrastructure.

Specific Documents

Create an operations runbook for the ecommerce deployment.
Focus on daily operations, incident response, and maintenance procedures.

Generate a resource inventory from the deployed Bicep templates.
Include resource names, SKUs, and monthly cost estimates.

Post-Deployment

Use the azure-workload-docs skill to document the infrastructure
we just deployed. Synthesize from the deployment summary and Bicep templates.

Document Templates

Document structures are defined in the templates folder. Follow these when generating output:

Document	Template
Design Document	See 07-design-document.template.md (10 sections)
Operations Runbook	See 07-operations-runbook.template.md (6 sections)
Resource Inventory	See 07-resource-inventory.template.md (2 sections + table)
Backup/DR Plan	See 07-backup-dr-plan.template.md (9 sections)
Compliance Matrix	See 07-compliance-matrix.template.md (6 sections)
Documentation Index	See 07-documentation-index.template.md (5 sections)

Integration with Workflow

This skill is typically invoked:

1. After Step 6 (Deploy) - Document what was deployed
2. Via handoff button - From deploy or bicep-code agents
3. Explicitly - User requests documentation at any time

Workflow Step 6 (Deploy) → azure-workload-docs skill → Step 7 outputs

Best Practices

1. Run after deployment - Ensures documentation reflects actual state
2. Include cost estimates - Use Azure Pricing MCP for accuracy
3. Map to compliance frameworks - Reference specific controls
4. Keep runbooks actionable - Include actual commands, not just concepts
5. Version documentation - Include generation date and source artifacts
6. Follow visual styling - Use callouts, emoji, collapsible sections per styling guide

Visual Styling Standards

MANDATORY: All generated documentation MUST follow:

📚 documentation-styling.md

Key requirements:

Element	Usage	Example
Callouts	Emphasis & warnings	> [!NOTE], > [!TIP], > [!WARNING]
Status Emoji	Progress indicators	✅ ⚠️ ❌ 💡
Category Icons	Resource sections	💻 💾 🌐 🔐 📊
Collapsible	Long content (>10 rows)	<details>...</details>
References	Evidence links	Microsoft Learn URLs in ## References section

References Section (Required)

Every document MUST include a ## References section at the bottom with relevant Microsoft Learn links:

---

## References

> [!NOTE]
> 📚 The following Microsoft Learn resources provide additional guidance.

| Topic                      | Link                                                                             |
| -------------------------- | -------------------------------------------------------------------------------- |
| Well-Architected Framework | [Overview](https://learn.microsoft.com/azure/well-architected/)                  |
| Azure Backup               | [Best Practices](https://learn.microsoft.com/azure/backup/backup-best-practices) |

What This Skill Does NOT Do

• ❌ Generate Bicep or Terraform code (use bicep-code agent)
• ❌ Create architecture diagrams (use azure-diagrams skill)
• ❌ Deploy resources (use deploy agent)
• ❌ Create ADRs (use azure-adr skill)
• ❌ Perform WAF assessments (use architect agent)

Required Context

For best results, ensure these artifacts exist before invoking:

agent-output/{project}/
├── 01-requirements.md          # Optional but helpful
├── 02-architecture-assessment.md  # WAF scores, recommendations
├── 04-implementation-plan.md   # Resource inventory
└── 06-deployment-summary.md    # Deployed resources

infra/bicep/{project}/
├── main.bicep                  # Entry point
└── modules/                    # Module configurations

Output Quality Checklist

• All resources from deployment summary are documented
• SKUs and configurations match Bicep templates
• Cost estimates reflect actual deployed SKUs
• Runbook procedures are specific, not generic
• Compliance controls map to actual implementations
• DR procedures include RTO/RPO from requirements
• H2 headings validated with npm run lint:artifact-templates
• Content under each H2 semantically matches the heading text

Template References

When generating documentation, follow these template structures:

• 07-documentation-index.template.md
• 07-design-document.template.md
• 07-operations-runbook.template.md
• 07-resource-inventory.template.md
• 07-ab-cost-estimate.template.md
• 07-backup-dr-plan.template.md
• 07-compliance-matrix.template.md

Generation Workflow

Follow these steps when generating documentation:

1. Gather Context - Read project artifacts (01-06), Bicep templates, deployment outputs
2. Load Templates - Read each template from .github/templates/07-*.template.md
3. Extract Resources - Parse deployed resources from 06-deployment-summary.md
4. Query Pricing - Use Azure Pricing MCP for cost estimates (if available)
5. Generate Documents - Create each document following template H2 structure
6. Cross-Reference - Ensure consistency across all documents
7. Create Index - Generate 07-documentation-index.md linking all documents
8. Validate H2 Compliance - Run the heading validator to verify all H2 headings match templates. Fix any drift before committing. Command: node scripts/fix-artifact-h2.mjs agent-output/{project}/07-*.md

Template Compliance Rules

CRITICAL: Templates define the H2 structure for each document.

Rule	Requirement
Exact text	Use template's H2 text verbatim
Exact order	Required H2s appear in template-defined order
Anchor rule	Extra sections allowed only AFTER last H2
No omissions	All template H2s must appear in output
Attribution	Include generation date and source in header

Example header format:

# Step 7: Design Document - {project-name}

> Generated by azure-workload-docs skill | {YYYY-MM-DD}
> Source artifacts: 02-architecture-assessment.md, 06-deployment-summary.md

Guardrails

DO

• ✅ Read templates BEFORE generating any output
• ✅ Run npm run lint:artifact-templates AFTER generating all outputs
• ✅ Verify content under each H2 semantically matches the heading text
• ✅ Parse actual Bicep for resource configurations
• ✅ Include specific Azure CLI/PowerShell commands in runbooks
• ✅ Map compliance controls to actual resource configurations
• ✅ Use actual SKU names, not generic placeholders
• ✅ Calculate costs from deployed SKUs, not estimates

DO NOT

• ❌ Generate documents without reading templates first
• ❌ Use placeholder text like "TBD" or "Insert here"
• ❌ Create generic runbooks without project-specific commands
• ❌ Skip sections defined in templates
• ❌ Reorder H2 headings from template structure
• ❌ Generate cost estimates without checking actual SKUs