claude-code: Skill for Claude Code

Azure Bicep Skill

Microsoft's proven-practice guidance for production Bicep deployments, distilled. Use this skill whenever Bicep code is being authored, reviewed, or refactored, or when picking between custom modules and Azure Verified Modules.

When to use

Trigger this skill when you see any of the following:

• A .bicep or .bicepparam file being created, edited, or reviewed
• A request involving "landing zone," "AVM," "Azure Verified Module," "what-if," or "bicepconfig"
• A question about Bicep scopes (targetScope), parameter typing, or output design
• A GitHub Actions workflow that deploys Bicep
• A choice between Bicep and Terraform (Bicep is the default for Tim's stack; only deviate with explicit justification)
• A custom module being proposed when an AVM module exists for the same resource

Do not trigger for: pure ARM JSON work (recommend converting to Bicep first), Terraform-only workflows, Azure portal click-ops walkthroughs.

Core principles

1. AVM first, custom second

Azure Verified Modules are Microsoft-published, WAF-aligned, versioned Bicep modules in the public Bicep Registry. They have built-in support for diagnostics, managed identities, private endpoints, RBAC assignments, and tagging. Prefer them over hand-rolled modules.

Why: AVM modules are maintained by the product groups, tested across regions, and updated for breaking API changes. Reinventing them is technical debt you will pay forever.

// Preferred: AVM resource module, version-pinned
module storage 'br/public:avm/res/storage/storage-account:0.14.3' = {
  name: 'storage-deployment'
  params: {
    name: storageAccountName
    location: location
    skuName: 'Standard_GRS'
    tags: tags
  }
}

See references/AVM-GUIDE.md for the module catalog, the resource (res) vs pattern (ptn) distinction, and version-pinning strategy.

2. Strong types and decorators on every param

Bicep parameters should be self-documenting and self-validating.