azure-artifacts - SKILL.md Agent Skill

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:

Mark your step as complete in the ## ✅ Workflow Progress table
Add your artifact files to the ## 📄 Generated Artifacts section
Update the Last Updated date in ## 📋 Project Summary
Update the progress bar percentage (each of the 7 steps = ~14%)
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

Gather Context — Read project artifacts (01-06) and Bicep templates
Check H2 Structures — Read references/h2-templates.md for the target artifact
Extract Resources — Parse deployed resources from 06-deployment-summary.md
Query Pricing — Use Azure Pricing MCP for cost estimates (if available)
Generate Documents — Create each document following H2 structure exactly
Cross-Reference — Ensure consistency across all documents
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