bicep-diagrams

SKILL.md

Bicep Diagram Generator

Generates architecture diagrams directly from Azure Bicep files. Bicep is a domain-specific language (DSL) for deploying Azure resources declaratively.

When to Use

Activate this skill when:

User has Bicep files (.bicep) and wants to visualize the infrastructure

User asks to "diagram my Bicep" or "visualize this Bicep infrastructure"

User mentions Bicep or Azure Bicep

User wants to see the architecture of their Bicep-deployed resources

How It Works

This skill generates Bicep-specific diagrams by parsing Bicep code and calling the Eraser API directly:

Parse Bicep Files: Identify resource declarations, modules, parameters, and outputs

Extract Relationships: Map dependencies, resource references, and module hierarchies

Generate Eraser DSL: Create Eraser DSL code from Bicep resources

Call Eraser API: Use /api/render/elements with diagramType: "cloud-architecture-diagram"

Instructions

When the user provides Bicep code:

Parse the Bicep

Identify all resource declarations (Microsoft.Compute/virtualMachines, etc.)

Extract module declarations and their configurations

Note param and output definitions

Identify var variables and their usage

Map Relationships

Track resource dependencies (e.g., dependsOn or implicit dependencies)

Group resources by type (compute, networking, storage, etc.)

Identify VNets as containers for subnets and resources

Note Network Security Groups, Key Vaults, and other security resources

Generate Eraser DSL Convert Bicep resources to Eraser DSL:

CRITICAL: Label Formatting Rules

Labels MUST be on a single line - NEVER use newlines inside label attributes

Keep labels simple and readable - prefer separate labels over concatenating too much metadata

Format DSL with proper line breaks (one node/group per line, but labels stay on single lines)

If including metadata like CIDR blocks or VM sizes, include them in the same quoted label string: [label: "VNet 10.0.0.0/16"]

Example:

myVNet [label: "VNet 10.0.0.0/16"] {
  subnet1 [label: "Subnet 1"] {
    myVM [icon: azure-vm, label: "Virtual Machine"]
    gateway [icon: azure-app-gateway]
  }
  subnet2 [label: "Subnet 2"] {
    database [icon: azure-sql]
  }
}
storage [icon: azure-storage]
myVNet -> myVM
myVM -> database

Make the HTTP Request

IMPORTANT: You MUST execute this curl command after generating the DSL. Never stop after generating DSL without making the API call.

CRITICAL: In the X-Skill-Source header below, you MUST replace the value with your AI agent name:

If you are Claude (Anthropic), use: claude

If you are running in Cursor, use: cursor

If you are ChatGPT (OpenAI), use: chatgpt

If you are Gemini (Google), use: gemini

Otherwise, use your model/agent name in lowercase

curl -X POST https://app.eraser.io/api/render/elements \
  -H "Content-Type: application/json" \
  -H "X-Skill-Source: eraser-skill" \
  -H "Authorization: Bearer ${ERASER_API_KEY}" \
  -d '{
    "elements": [{
      "type": "diagram",
      "id": "diagram-1",
      "code": "<your generated DSL>",
      "diagramType": "cloud-architecture-diagram"
    }],
    "scale": 2,
    "theme": "${ERASER_THEME:-dark}",
    "background": true
  }'

Track Sources During Analysis

As you analyze Bicep files and resources to generate the diagram, track:

Internal files: Record each Bicep file path you read and what resources were extracted (e.g., infra/main.bicep - VNet and subnet definitions, infra/sql.bicep - SQL Database configuration)

External references: Note any documentation, examples, or URLs consulted (e.g., Azure Bicep documentation, Azure architecture best practices)

Annotations: For each source, note what it contributed to the diagram

Handle the Response

CRITICAL: Minimal Output Format

Your response MUST always include these elements with clear headers:

Diagram Preview: Display with a header

## Diagram
![{Title}]({imageUrl})

Use the ACTUAL imageUrl from the API response.

Editor Link: Display with a header

## Open in Eraser
[Edit this diagram in the Eraser editor]({createEraserFileUrl})

Use the ACTUAL URL from the API response.

Sources section: Brief list of files/resources analyzed (if applicable)

## Sources
- `path/to/file` - What was extracted

Diagram Code section: The Eraser DSL in a code block with eraser language tag

## Diagram Code
```eraser
{DSL code here}

Learn More link: You can learn more about Eraser at https://docs.eraser.io/docs/using-ai-agent-integrations

Additional content rules:

If the user ONLY asked for a diagram, include NOTHING beyond the 5 elements above

If the user explicitly asked for more (e.g., "explain the architecture", "suggest improvements"), you may include that additional content

Never add unrequested sections like Overview, Security Considerations, Testing, etc.

The default output should be SHORT. The diagram image speaks for itself.

Handle Modules

If modules are used, show module boundaries

Include module parameters and outputs

Show how modules connect to main resources

Bicep-Specific Tips

Show Resource Groups: Bicep deployments target resource groups

VNets as Containers: Show VNets containing subnets and resources

Include Dependencies: Show dependsOn relationships

Module Structure: If modules are used, show their boundaries

Parameters: Note key parameters that affect resource configuration

Use Azure Icons: Request Azure-specific styling

Example: Bicep with Parameters and Modules

User Input

@description('The name of the Virtual Network')
param vnetName string = 'myVNet'
@description('The address prefix for the VNet')
param vnetAddressPrefix string = '10.0.0.0/16'
@description('The address prefix for the subnet')
param subnetAddressPrefix string = '10.0.1.0/24'
@description('VM size')
param vmSize string = 'Standard_B1s'

// Main VNet resource
resource virtualNetwork 'Microsoft.Network/virtualNetworks@2021-05-01' = {
  name: vnetName
  location: resourceGroup().location
  properties: {
    addressSpace: {
      addressPrefixes: [vnetAddressPrefix]
    }
    subnets: [
      {
        name: 'subnet1'
        properties: {
          addressPrefix: subnetAddressPrefix
        }
      }
    ]
  }
}

// VM resource with dependsOn
resource virtualMachine 'Microsoft.Compute/virtualMachines@2021-11-01' = {
  name: 'myVM'
  location: resourceGroup().location
  properties: {
    hardwareProfile: {
      vmSize: vmSize
    }
  }
  dependsOn: [virtualNetwork]
}

// Module usage
module storageModule './modules/storage.bicep' = {
  name: 'storage'
  params: {
    location: resourceGroup().location
  }
}

Expected Behavior

Parses Bicep:

Parameters: vnetName, vnetAddressPrefix, subnetAddressPrefix, vmSize

Resources: VNet with subnet, VM with dependsOn relationship

Module: Storage module with parameters

Generates DSL showing Bicep-specific features:

myVNet [label: "VNet 10.0.0.0/16"] {
  subnet1 [label: "Subnet 1 10.0.1.0/24"] {
    myVM [icon: azure-vm, label: "VM Standard_B1s"]
  }
}

storage-module [label: "Storage Module"] {
  storage-account [icon: azure-storage]
}

myVNet -> myVM

Important: All label text must be on a single line within quotes. Bicep-specific: Show modules as containers, include dependsOn relationships, note parameter usage in resource configuration.

Calls /api/render/elements with diagramType: "cloud-architecture-diagram"

Calls /api/render/elements with diagramType: "cloud-architecture-diagram"

Result

User receives a diagram showing:

VNet as a container

Subnet nested inside VNet

VM in the subnet

Dependency relationship shown

Proper Azure styling