azure-artifacts

name: azure-artifacts description: 'UTILITY SKILL — Artifact template structures, H2 compliance rules, and documentation styling for agent outputs (Steps 1-7). WHEN: "generate artifact", "check H2 structure", "artifact template", "step 7 as-built". USE FOR: generating any agent artifact, checking H2 structure compliance. DO NOT USE FOR: Azure resource configuration (use azure-defaults), Bicep/Terraform patterns (use azure-bicep-patterns or terraform-patterns).' 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 artifact template structures and styling. Per-step H2 definitions live in references/ — load only the step you are generating.

Rules

Mandatory Compliance

DO / DON'T

• DO: Read the step-specific template before generating
• DO: Copy H2 text character-for-character (including emoji)
• DO: Save all output to agent-output/{project}/
• DON'T: Reorder H2 headings from the listed sequence
• DON'T: Use placeholder text like "TBD" or "Insert here"
• 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.

After saving step artifact(s), update the README:

1. Mark your step as complete in ## ✅ Workflow Progress
2. Add artifact files to ## 📄 Generated Artifacts
3. Update Last Updated date and progress bar percentage

Steps

Artifact generation flow (per Step N):

1. Read template — load the matching references/0N-*-template.md for the step you are generating
2. Copy H2 skeleton — replicate every required H2 in the listed order, character-for-character
3. Fill content — replace {placeholder} tokens; never use "TBD" or "Insert here"
4. Add attribution — > Generated by {agent} agent | {YYYY-MM-DD}
5. Save to agent-output/{project}/ with the prescribed filename
6. Update README — mark step complete, list artifacts, refresh Last Updated date
7. Delegate validation — do not invoke npm run lint:artifact-templates, npm run lint:h2-sync, or markdownlint-cli2 directly against agent-output/**. The lefthook artifact-validation pre-commit hook (which wraps these scripts) and the 10-Challenger review own the artifact contract. See agent-authoring.instructions.md.

For revisions (challenger findings, user-decision Apply/Skip/Defer, approval-gate fixes), see references/revision-workflow.md — bundle all fixes into a single multi_replace_string_in_file call.

Post-write validation

Run a one-line shape check immediately after writing any non-markdown artifact, before moving to the next step. Catches malformed output at source instead of at deploy time. Markdown artifacts are owned by the lefthook artifact-validation hook — do not duplicate that check here.

Fail closed: if the validator exits non-zero, fix the artifact and re-validate before continuing. Do not record the artifact in the project README or hand off to the next step until it passes.

Placeholder Syntax

All templates use single-brace {placeholder-name} syntax:

• Lowercase, hyphen-separated: {project-name}, {monthly-cost}
• No Mustache/Handlebars {{double-braces}}

Automated Validation

These npm scripts are invoked by the lefthook artifact-validation pre-commit hook and by CI — not by agents directly (see agent-authoring.instructions.md).

npm run lint:artifact-templates   # H2 order and required headings (pre-commit + CI only)
npm run lint:h2-sync              # Template ↔ artifact sync (pre-commit + CI only)
npm run validate:all              # All validators together (humans / CI only)

Fast H2-order sanity check (agent-safe)

When an agent needs a quick "did I get the H2 structure right?" check before invoking the challenger, use the dedicated helper instead of improvising node -e '…' one-liners (which trip shell quoting and waste context on retries):

npm run check:h2-order -- <project>                       # defaults to 01-requirements.md
npm run check:h2-order -- <project> 04-implementation-plan.md
node tools/scripts/check-h2-order.mjs agent-output/<project>/02-architecture-assessment.md

Exit 0 = match (prints OK: …). Exit 1 = mismatch (prints structured JSON with expected/got/missingAt). Exit 2 = bad arguments or unknown artifact filename. The helper reads the canonical heading registry from tools/scripts/_lib/artifact-headings.mjs so it never drifts from the template source of truth.

Quality Checklist

Critical (always check):

• H2 headings match template exactly (text + order)
• Attribution header present with agent name and date
• No placeholder text (e.g. "TBD", "Insert here", task markers)
• File saved to agent-output/{project}/ with correct name

For the full structural / styling checklist (TOC, cross-nav table, traffic lights, Mermaid, collapsible blocks) read references/styling-standards.md.

Reference Index

When generating a Step N artifact, read the corresponding template: