azure-artifacts

name	azure-artifacts
description	Defines canonical artifact templates, H2 structures, and documentation styling rules for agent outputs (Steps 1-7); use for artifact generation, formatting, and template compliance.
compatibility	Works with Claude Code, GitHub Copilot, VS Code, and any Agent Skills compatible tool.
license	MIT
metadata	{"author":"jonathan-vella","version":"2.0","category":"workflow-automation"}

Azure Artifacts Skill

Single source of truth for all artifact template structures and documentation styling. Load this SKILL.md first — then load references/ files on demand for the current task.

Reference Files (Load on Demand)

File	When to Load
references/h2-templates.md	Generating a specific artifact — get exact H2 heading sequence
references/standard-components.md	Building artifact structure (badges, TOC, navigation, placeholders)
references/styling-standards.md	Formatting content (callouts, emoji, icons, reference links)

Templates directory: templates/ contains .template.md skeleton files.

---

Artifact Generation Rules

[!NOTE] This skill is the SINGLE SOURCE OF TRUTH for artifact H2 headings and templates. The similar section in azure-defaults/SKILL.md defers to this skill for template compliance.

Mandatory Compliance

Rule	Requirement
Template skeleton	Read .template.md file and replicate its structure
Exact text	Use H2 text from references/h2-templates.md verbatim
Exact order	Required H2s appear in the order listed
Anchor rule	Extra sections allowed ONLY after last required H2
No omissions	Every H2 listed must appear in output
Attribution	Include header: > Generated by {agent} agent | {YYYY-MM-DD}

DO / DON'T

• DO: Read references/h2-templates.md BEFORE generating any artifact
• DO: Copy H2 text character-for-character (including emoji prefixes)
• DO: Include ## References section at bottom when listed
• DO: Use callout styles from references/styling-standards.md
• DO: Save all output to agent-output/{project}/
• DON'T: Generate artifacts without checking H2 structure first
• DON'T: Reorder H2 headings from the listed sequence
• DON'T: Use placeholder text like "TBD" or "Insert here"
• DON'T: Skip sections — empty sections are better than missing ones
• DON'T: Add custom H2 sections BEFORE the last required H2

---

Mandatory: Project README

Every project in agent-output/{project}/ MUST have a README.md. This is a cross-agent requirement — not owned by a single step.

Responsibility	Agent
Create initial README from PROJECT-README.template.md	Requirements (Step 1)
Update workflow progress after saving step artifacts	Every step agent (Steps 2-7)

README Update Rules (All Agents)

After saving your step artifact(s), update agent-output/{project}/README.md:

1. Mark your step as complete in the ## ✅ Workflow Progress table
2. Add your artifact files to the ## 📄 Generated Artifacts section
3. Update the Last Updated date in ## 📋 Project Summary
4. Update the progress bar percentage (each of the 7 steps = ~14%)
5. If README doesn't exist, create from PROJECT-README.template.md and backfill

Template: .github/skills/azure-artifacts/templates/PROJECT-README.template.md

---

Step 7: Workload Documentation Generation

When to Generate

Trigger	Action
After Step 6 (Deploy)	Generate full documentation package
"Generate workload documentation"	Create all 7 document types
"Document the deployment"	Synthesize from deployment artifacts
"Create operations runbook"	Generate specific document
Conductor handoff	Auto-generate post-deployment docs

Output Files (Step 7)

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

Source Artifacts for Step 7

Source	Information Extracted
01-requirements.md	Business context, NFRs, compliance
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 Bicep configuration values

Generation Workflow

1. Gather Context — Read project artifacts (01-06) and Bicep templates
2. Check H2 Structures — Read references/h2-templates.md for the target artifact
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 H2 structure exactly
6. Cross-Reference — Ensure consistency across all documents
7. Create Index — Generate 07-documentation-index.md linking all documents

Step 7 DO / DON'T

• DO: Read ALL source artifacts before generating
• DO: Use actual SKU names and config from Bicep, not placeholders
• DO: Include specific Azure CLI/PowerShell commands in runbooks
• DO: Map compliance controls to actual resource configurations
• DON'T: Generate docs without reading source artifacts
• DON'T: Create generic runbooks without project-specific commands
• DON'T: Skip required documents (index, design, runbook, inventory, cost)

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)

---

Automated Validation

Script	Scope	npm Command
validate-artifact-templates.mjs	All 16 artifact types — H2 order, required H2s	npm run lint:artifact-templates

Run npm run validate:all to execute all validators together.

---

Quality Checklist

Before finalizing any artifact:

• H2 headings match references/h2-templates.md exactly (text + order)
• Attribution header present with agent name and date
• No placeholder text ("TBD", "Insert here", "TODO")
• Callout styles used for emphasis (not bold text alone)
• Status emoji consistent with references/styling-standards.md
• References section included (when template specifies it)
• Collapsible sections used for tables >10 rows
• File saved to agent-output/{project}/ with correct filename