# 333 Effective Prompts B4c29278 > Effective Prompts for Diagrams-as-Code - Skill: `tools-only/333-effective-prompts-b4c29278` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add tools-only/333-effective-prompts-b4c29278` - Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/333-effective-prompts-b4c29278/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: tools-only (https://skillmd.com/u/tools-only) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/tools-only/333-effective-prompts-b4c29278 --- # Effective Prompts for Diagrams-as-Code ## Conversation Approach Philosophy The goal is **learning**, not just code generation. These prompts are designed to help you understand diagrams-as-code concepts so you can create and modify diagrams independently. ### Key Principles 1. **Ask WHY before HOW** - Understand the concept before implementing 2. **Admit what you don't know** - "I've never used this" gets better teaching 3. **Request explanations** - "Explain each part as we go" 4. **Iterate and refine** - Build complexity through conversation 5. **Ask about trade-offs** - Understanding limitations is knowledge --- ## Phase 1: Understanding the Concept ### Starting from Zero ``` I need to document our Azure architecture for a design review. I've heard about "diagrams as code" but never used it. Can you help me understand what it is and whether it's the right approach for my situation? ``` ### Comparing Approaches ``` What are the pros and cons of diagrams-as-code vs. traditional tools like Visio or Draw.io? I want to make an informed decision. ``` ### Specific Fit Questions ``` I have [describe your situation - deadline, team size, type of diagram]. Is diagrams-as-code a good fit, or should I use something else? ``` --- ## Phase 2: Architecture Discovery ### Describing Your Architecture ``` I need to diagram our [type of system]. We have: - [Component 1 and its role] - [Component 2 and its role] - [Component 3 and its role] How should I think about organizing this in a diagram? ``` ### Refining Connections ``` One clarification - [specific detail about how components interact]. Does that change how we should organize the diagram? ``` ### Asking About Tiers ``` What are the common ways to organize Azure/AWS/GCP architectures visually? Should I group by tier, by function, or something else? ``` ### Understanding Clusters ``` What's the best way to visually group related services in diagrams-as-code? For example, I have [list of related services]. ``` --- ## Phase 3: Code Generation with Understanding ### Learning-First Code Generation ``` Let's write the code! But please explain each part as we go - I want to understand what I'm writing, not just copy-paste. ``` ### Understanding Imports ``` What does each import do in the diagrams library? I see references to Diagram, Cluster, Edge - what's the purpose of each? ``` ### Understanding Icons ``` How do I find the right icon for [Azure Service Name]? What's the naming convention for icons in the diagrams library? ``` ### Understanding Connections ``` What do the >> and << operators mean? How do I add labels to connections? Can you show me examples of different connection styles? ``` --- ## Phase 4: Customization and Iteration ### Highlighting Important Paths ``` I'd like to highlight [specific component/path] as critical. How can I make it stand out visually? ``` ### Adding Labels ``` Can I add text labels to show things like "read-only" or "primary" on the connections? How? ``` ### Changing Layout ``` The diagram is flowing left-to-right but I want top-to-bottom. How do I change the layout direction? ``` ### Styling Clusters ``` Can I add background colors or borders to the clusters to make them more distinct? What options do I have? ``` ### Multiple Options Request ``` Give me a few different options for [styling goal]. I want to understand what's possible before choosing. ``` --- ## Phase 5: Best Practices ### Team Adoption ``` How should I manage diagrams-as-code across a team of [N] architects? What's the recommended folder structure and workflow? ``` ### Version Control ``` Should I commit the generated images or just the Python code? What's the best practice for Git? ``` ### CI/CD Integration ``` Can I automate diagram generation in CI/CD? What would that pipeline look like? ``` ### Shared Styling ``` How can I ensure consistent styling across multiple diagrams created by different team members? ``` --- ## Follow-Up and Refinement Prompts ### When You Don't Understand ``` I don't understand what [specific term/concept] means. Can you explain it with a simple example? ``` ### When Code Doesn't Work ``` I got this error: [error message]. What does it mean and how do I fix it? ``` ### When Output Looks Wrong ``` The diagram doesn't look right - [describe the issue]. What might be wrong with my code? ``` ### Exploring Alternatives ``` Is there another way to accomplish [goal]? I want to understand my options. ``` --- ## Advanced Questions ### After Learning the Basics ``` Now that I understand the basics, are there any advanced features I should know about? Things like [nested clusters, custom icons, subgraphs]? ``` ### Multi-Cloud Diagrams ``` Can I mix Azure, AWS, and on-premises components in the same diagram? How does that work? ``` ### Programmatic Generation ``` I have a list of resources in [JSON/YAML]. Can I generate diagrams programmatically from data? ``` ### Documentation Integration ``` How do I embed these diagrams in Markdown documentation so they stay up-to-date? ``` --- ## Common Mistakes to Avoid ### ❌ Wrong Approach: Script-First ``` Generate a Python script for an Azure architecture diagram ``` *This gets code but no understanding. Next time you'll ask again.* ### ✅ Right Approach: Learning-First ``` I want to create an Azure architecture diagram using Python. I've never used diagrams-as-code before. Can you help me understand the concept and walk me through creating one step by step? ``` *This builds transferable knowledge. Next time you'll be faster.* ### ❌ Wrong: One-Shot Requests ``` Create a diagram with Azure Front Door, AKS, SQL, and Redis ``` *This skips the learning.* ### ✅ Right: Iterative Conversation ``` I need to diagram these components: [list]. How should I think about organizing them before we write any code? ``` *This teaches architectural thinking.* --- ## Use Case Templates ### Design Review Scenario ``` I have a design review in [timeframe] and need to document [what]. I've [never/sometimes] used diagrams-as-code. Can you help me understand if it's right for this situation and walk me through creating a diagram? ``` ### Documentation Update Scenario ``` Our architecture has changed - we added [new component]. I have an existing diagram.py file. How do I update it, and can you explain what I'm changing? ``` ### Team Standardization Scenario ``` Our team of [N] architects all create diagrams differently. How can we standardize on diagrams-as-code? What shared conventions should we establish? ``` ### Client Deliverable Scenario ``` I need to create professional architecture diagrams for a customer presentation. What are the best practices for making diagrams-as-code output look polished? ``` --- ## Success Indicators You're using prompts effectively when: 1. ✅ You understand **why** code is structured a certain way 2. ✅ You can **modify** diagrams without asking for help 3. ✅ You can **teach** the approach to others 4. ✅ Your **next diagram** takes less time 5. ✅ You know the **limitations** as well as capabilities 6. ✅ You're having a **conversation**, not issuing commands --- ## Philosophy **"Learn first, generate later."** Understanding diagrams-as-code concepts makes you effective. Automation makes you efficient. Do both - in that order. --- *These prompts are designed for conversation-based learning with GitHub Copilot. The goal is transferable knowledge, not just immediate output.*