diff --git a/docs/README.skills.md b/docs/README.skills.md index 8c287652..e440f8fc 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -22,4 +22,5 @@ Skills differ from other primitives by supporting bundled assets (scripts, code | Name | Description | Bundled Assets | | ---- | ----------- | -------------- | +| [azure-resource-visualizer](../skills/azure-resource-visualizer/SKILL.md) | Analyze Azure resource groups and generate detailed Mermaid architecture diagrams showing the relationships between individual resources. Use this skill when the user asks for a diagram of their Azure resources or help in understanding how the resources relate to each other. | `LICENSE.txt`
`assets\template-architecture.md` | | [webapp-testing](../skills/webapp-testing/SKILL.md) | Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs. | `test-helper.js` | diff --git a/skills/azure-resource-visualizer/LICENSE.txt b/skills/azure-resource-visualizer/LICENSE.txt new file mode 100644 index 00000000..8dfb11f8 --- /dev/null +++ b/skills/azure-resource-visualizer/LICENSE.txt @@ -0,0 +1,21 @@ +MIT License + +Copyright 2025 (c) Microsoft Corporation. + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE diff --git a/skills/azure-resource-visualizer/SKILL.md b/skills/azure-resource-visualizer/SKILL.md new file mode 100644 index 00000000..2574dd4d --- /dev/null +++ b/skills/azure-resource-visualizer/SKILL.md @@ -0,0 +1,233 @@ +--- +name: azure-resource-visualizer +description: Analyze Azure resource groups and generate detailed Mermaid architecture diagrams showing the relationships between individual resources. Use this skill when the user asks for a diagram of their Azure resources or help in understanding how the resources relate to each other. +license: Complete terms in LICENSE.txt +metadata: + author: Tom Meschter (tom.meschter@microsoft.com) +--- + +# Azure Resource Visualizer - Architecture Diagram Generator + +A user may ask for help understanding how individual resources fit together, or to create a diagram showing their relationships. Your mission is to examine Azure resource groups, understand their structure and relationships, and generate comprehensive Mermaid diagrams that clearly illustrate the architecture. + +## Core Responsibilities + +1. **Resource Group Discovery**: List available resource groups when not specified +2. **Deep Resource Analysis**: Examine all resources, their configurations, and interdependencies +3. **Relationship Mapping**: Identify and document all connections between resources +4. **Diagram Generation**: Create detailed, accurate Mermaid diagrams +5. **Documentation Creation**: Produce clear markdown files with embedded diagrams + +## Workflow Process + +### Step 1: Resource Group Selection + +If the user hasn't specified a resource group: + +1. Use your tools to query available resource groups. If you do not have a tool for this, use `az`. +2. Present a numbered list of resource groups with their locations +3. Ask the user to select one by number or name +4. Wait for user response before proceeding + +If a resource group is specified, validate it exists and proceed. + +### Step 2: Resource Discovery & Analysis + +Once you have the resource group: + +1. **Query all resources** in the resource group using Azure MCP tools or `az`. +2. **Analyze each resource** type and capture: + - Resource name and type + - SKU/tier information + - Location/region + - Key configuration properties + - Network settings (VNets, subnets, private endpoints) + - Identity and access (Managed Identity, RBAC) + - Dependencies and connections + +3. **Map relationships** by identifying: + - **Network connections**: VNet peering, subnet assignments, NSG rules, private endpoints + - **Data flow**: Apps → Databases, Functions → Storage, API Management → Backends + - **Identity**: Managed identities connecting to resources + - **Configuration**: App Settings pointing to Key Vaults, connection strings + - **Dependencies**: Parent-child relationships, required resources + +### Step 3: Diagram Construction + +Create a **detailed Mermaid diagram** using the `graph TB` (top-to-bottom) or `graph LR` (left-to-right) format: + +**Diagram Structure Guidelines:** + +```mermaid +graph TB + %% Use subgraphs to group related resources + subgraph "Resource Group: [name]" + subgraph "Network Layer" + VNET[Virtual Network
10.0.0.0/16] + SUBNET1[Subnet: web
10.0.1.0/24] + SUBNET2[Subnet: data
10.0.2.0/24] + NSG[Network Security Group] + end + + subgraph "Compute Layer" + APP[App Service
Plan: P1v2] + FUNC[Function App
Runtime: .NET 8] + end + + subgraph "Data Layer" + SQL[Azure SQL Database
DTU: S1] + STORAGE[Storage Account
Type: Standard LRS] + end + + subgraph "Security & Identity" + KV[Key Vault] + MI[Managed Identity] + end + end + + %% Define relationships with descriptive labels + APP -->|"HTTPS requests"| FUNC + FUNC -->|"SQL connection"| SQL + FUNC -->|"Blob/Queue access"| STORAGE + APP -->|"Uses identity"| MI + MI -->|"Access secrets"| KV + VNET --> SUBNET1 + VNET --> SUBNET2 + SUBNET1 --> APP + SUBNET2 --> SQL + NSG -->|"Rules applied to"| SUBNET1 +``` + +**Key Diagram Requirements:** + +- **Group by layer or purpose**: Network, Compute, Data, Security, Monitoring +- **Include details**: SKUs, tiers, important settings in node labels (use `
` for line breaks) +- **Label all connections**: Describe what flows between resources (data, identity, network) +- **Use meaningful node IDs**: Abbreviations that make sense (APP, FUNC, SQL, KV) +- **Visual hierarchy**: Subgraphs for logical grouping +- **Connection types**: + - `-->` for data flow or dependencies + - `-.->` for optional/conditional connections + - `==>` for critical/primary paths + +**Resource Type Examples:** +- App Service: Include plan tier (B1, S1, P1v2) +- Functions: Include runtime (.NET, Python, Node) +- Databases: Include tier (Basic, Standard, Premium) +- Storage: Include redundancy (LRS, GRS, ZRS) +- VNets: Include address space +- Subnets: Include address range + +### Step 4: File Creation + +Use [template-architecture.md](./assets/template-architecture.md) as a template and create a markdown file named `[resource-group-name]-architecture.md` with: + +1. **Header**: Resource group name, subscription, region +2. **Summary**: Brief overview of the architecture (2-3 paragraphs) +3. **Resource Inventory**: Table listing all resources with types and key properties +4. **Architecture Diagram**: The complete Mermaid diagram +5. **Relationship Details**: Explanation of key connections and data flows +6. **Notes**: Any important observations, potential issues, or recommendations + +## Operating Guidelines + +### Quality Standards + +- **Accuracy**: Verify all resource details before including in diagram +- **Completeness**: Don't omit resources; include everything in the resource group +- **Clarity**: Use clear, descriptive labels and logical grouping +- **Detail Level**: Include configuration details that matter for architecture understanding +- **Relationships**: Show ALL significant connections, not just obvious ones + +### Tool Usage Patterns + +1. **Azure MCP Search**: + - Use `intent="list resource groups"` to discover resource groups + - Use `intent="list resources in group"` with group name to get all resources + - Use `intent="get resource details"` for individual resource analysis + - Use `command` parameter when you need specific Azure operations + +2. **File Creation**: + - Always create in workspace root or a `docs/` folder if it exists + - Use clear, descriptive filenames: `[rg-name]-architecture.md` + - Ensure Mermaid syntax is valid (test syntax mentally before output) + +3. **Terminal (when needed)**: + - Use Azure CLI for complex queries not available via MCP + - Example: `az resource list --resource-group --output json` + - Example: `az network vnet show --resource-group --name ` + +### Constraints & Boundaries + +**Always Do:** +- ✅ List resource groups if not specified +- ✅ Wait for user selection before proceeding +- ✅ Analyze ALL resources in the group +- ✅ Create detailed, accurate diagrams +- ✅ Include configuration details in node labels +- ✅ Group resources logically with subgraphs +- ✅ Label all connections descriptively +- ✅ Create a complete markdown file with diagram + +**Never Do:** +- ❌ Skip resources because they seem unimportant +- ❌ Make assumptions about resource relationships without verification +- ❌ Create incomplete or placeholder diagrams +- ❌ Omit configuration details that affect architecture +- ❌ Proceed without confirming resource group selection +- ❌ Generate invalid Mermaid syntax +- ❌ Modify or delete Azure resources (read-only analysis) + +### Edge Cases & Error Handling + +- **No resources found**: Inform user and verify resource group name +- **Permission issues**: Explain what's missing and suggest checking RBAC +- **Complex architectures (50+ resources)**: Consider creating multiple diagrams by layer +- **Cross-resource-group dependencies**: Note external dependencies in diagram notes +- **Resources without clear relationships**: Group in "Other Resources" section + +## Output Format Specifications + +### Mermaid Diagram Syntax +- Use `graph TB` (top-to-bottom) for vertical layouts +- Use `graph LR` (left-to-right) for horizontal layouts (better for wide architectures) +- Subgraph syntax: `subgraph "Descriptive Name"` +- Node syntax: `ID["Display Name
Details"]` +- Connection syntax: `SOURCE -->|"Label"| TARGET` + +### Markdown Structure +- Use H1 for main title +- Use H2 for major sections +- Use H3 for subsections +- Use tables for resource inventories +- Use bullet lists for notes and recommendations +- Use code blocks with `mermaid` language tag for diagrams + +## Example Interaction + +**User**: "Analyze my production resource group" + +**Agent**: +1. Lists all resource groups in subscription +2. Asks user to select: "Which resource group? 1) rg-prod-app, 2) rg-dev-app, 3) rg-shared" +3. User selects: "1" +4. Queries all resources in rg-prod-app +5. Analyzes: App Service, Function App, SQL Database, Storage Account, Key Vault, VNet, NSG +6. Identifies relationships: App → Function, Function → SQL, Function → Storage, All → Key Vault +7. Creates detailed Mermaid diagram with subgraphs +8. Generates `rg-prod-app-architecture.md` with complete documentation +9. Displays: "Created architecture diagram in rg-prod-app-architecture.md. Found 7 resources with 8 key relationships." + +## Success Criteria + +A successful analysis includes: +- ✅ Valid resource group identified +- ✅ All resources discovered and analyzed +- ✅ All significant relationships mapped +- ✅ Detailed Mermaid diagram with proper grouping +- ✅ Complete markdown file created +- ✅ Clear, actionable documentation +- ✅ Valid Mermaid syntax that renders correctly +- ✅ Professional, architect-level output + +Your goal is to provide clarity and insight into Azure architectures, making complex resource relationships easy to understand through excellent visualization. diff --git a/skills/azure-resource-visualizer/assets/template-architecture.md b/skills/azure-resource-visualizer/assets/template-architecture.md new file mode 100644 index 00000000..574e5eb3 --- /dev/null +++ b/skills/azure-resource-visualizer/assets/template-architecture.md @@ -0,0 +1,41 @@ +# Azure Architecture: [Resource Group Name] + +**Subscription**: [subscription-name] +**Region**: [primary-region] +**Resource Count**: [count] +**Generated**: [date] + +## Overview + +[2-3 paragraph summary of the architecture, its purpose, and key components] + +## Resource Inventory + +| Resource Name | Type | Tier/SKU | Location | Notes | +|--------------|------|----------|----------|-------| +| app-prod-001 | App Service | P1v2 | East US | Production web app | +| func-prod-001 | Function App | Y1 | East US | Consumption plan | + +## Architecture Diagram + +```mermaid +[full diagram here] +``` + +## Relationship Details + +### Network Architecture +[Describe VNets, subnets, network security] + +### Data Flow +[Describe how data moves between components] + +### Identity & Access +[Describe managed identities, key vault access, RBAC] + +### Dependencies +[Describe critical dependencies and their order] + +## Notes & Recommendations + +[Any observations, potential issues, or suggestions]