| name | bicep-scaffolder |
| description | Scaffold parameterized Bicep modules. Use when the user requests a new Bicep module or asks to scaffold infrastructure code. |
Bicep Scaffolder Skill
Summary: Scaffold a small, parameterized Bicep module (idempotent main.bicep + parameters.json) and guidance for production use. Use when a user requests a new Bicep module, needs a repeatable module scaffold, or asks whether to use an Azure Verified Module (AVM) vs a custom module.
When to use (triggers):
- "scaffold bicep module", "create bicep module", "generate bicep scaffold"
- When the user provides a resource type, a name pattern, or a Git diff of infra changes
Inputs
resource_type (string): Azure resource type, e.g., Microsoft.Storage/storageAccounts.name_pattern (string, optional): pattern for resource names (short prefix, environment token)parameters (object, optional): minimal parameter hints (types and example defaults)
Outputs
module_dir/ with main.bicep, parameters.json, README.example.md and scripts/validate_bicep.sh (automation helpers)
Core workflow
- Validate requested resource type and suggest latest API version (consult Azure resource type list).
- Decide: Prefer Azure Verified Module (AVM) when available and matches requirements; otherwise scaffold an idempotent, modular Bicep module.
- Populate
main.bicep with clear parameter metadata, @description() and safe defaults for test deployments.
- Add small
README.example.md and a scripts/validate_bicep.sh to run bicep build and bicep linter.
- Return
pr_description and pr_checks describing CI validation steps to use in a PR.
NEVER — Anti-patterns (explicit examples + WHY)
- Bad: Use string concatenation for child resource names (e.g.,
name: '${vnetName}-subnet').
- Why: Loses implicit relationships; use nested resources or
parent instead.
- Bad: Overly restrictive
@allowed decorators for parameters.
- Why: Breaks reusability and may block valid SKUs across environments.
- Bad: Exposing secrets in outputs (returning connection strings unmasked).
- Why: Use
@secure() on outputs or avoid emitting secrets altogether.
- Bad: Skipping
bicep build or linter checks in CI.
- Why: Fails fast and prevents broken modules from merging.
- Bad: Putting large examples in SKILL.md body.
- Why: Increases token cost and reduces discoverability; put examples in
references/ and mark them MANDATORY - READ when needed.
Decision checklist — AVM vs Custom
- Prefer AVM when:
- An Azure Verified Module exists for the resource and matches required configuration
- You need a well-tested, supported pattern with versioning
- Prefer Custom when:
- AVM does not cover the required configuration (custom behavior or preview features)
- You need to control resource naming, parents, or unusual lifecycle semantics
Progressive disclosure & references
- Heavy examples, templates, and extended guidance live in
references/:
references/main.bicep (template)references/parameters.json (example params)references/README.example.md (deploy + linter + CI usage)
- Use explicit triggers inside workflows to MANDATORY - READ ENTIRE FILE for large references when needed.
- Keep SKILL.md < 500 lines and one-level references deep.
Validation & CI
- Provide
scripts/validate_bicep.sh to run bicep build and bicep linter and exit non‑zero on failure.
- Example GitHub Actions snippet (see
.github/workflows/validate-bicep.yml) to run validation on PRs.
Evaluation scenarios
- Create module for
Microsoft.Storage/storageAccounts with env=dev and verify bicep build passes.
- Scaffold module where AVM exists — verify decision suggests AVM and includes rationale.
- Generate module with sensitive output — assert
@secure() used and linter flags are resolved.
References
