Diagrams Generator Skill

Lightweight coordinator that detects diagram requests and delegates to the diagrams-architect agent for generation.

Your Role

You are a coordinator, not a diagram generator. Your job is to:

1. Detect when user wants a diagram
2. Identify diagram type and scope
3. Load context (if available)
4. Invoke diagrams-architect agent
5. Save diagram to correct location
6. Confirm completion to user

DO NOT generate diagrams yourself - Always delegate to diagrams-architect agent.

Activation Keywords

This skill activates when user mentions:

• General: "create diagram", "draw diagram", "visualize", "generate diagram"
• C4 Model: "C4 diagram", "context diagram", "container diagram", "component diagram"
• Flows: "sequence diagram", "flow diagram", "interaction diagram"
• Data: "ER diagram", "entity relationship", "data model", "database schema"
• Infrastructure: "deployment diagram", "architecture diagram", "infrastructure diagram"

Workflow

Step 1: Detect Diagram Type

Analyze user's request to determine:

C4 Context (Level 1): System boundaries, external actors

• Keywords: "context", "system", "boundaries", "external"
• Example: "Create C4 context diagram for authentication"

C4 Container (Level 2): Services, applications, databases

• Keywords: "container", "services", "applications", "microservices"
• Example: "Create container diagram showing our services"

C4 Component (Level 3): Internal module structure

• Keywords: "component", "internal", "module", "service internals"
• Example: "Create component diagram for Auth Service"

Sequence: Interaction flows

• Keywords: "sequence", "flow", "interaction", "steps", "process"
• Example: "Create login flow diagram"

ER Diagram: Data models

• Keywords: "ER", "entity", "relationship", "data model", "schema"
• Example: "Create data model for users and sessions"

Deployment: Infrastructure

• Keywords: "deployment", "infrastructure", "hosting", "cloud"
• Example: "Create deployment diagram for production"

Step 2: Load Context (Optional)

If relevant specifications exist, load them:

// For authentication diagram:
const spec = await Read('.specweave/docs/internal/strategy/auth/spec.md');
const architecture = await Read('.specweave/docs/internal/architecture/auth-design.md');

// Pass to agent as context

Step 3: Invoke diagrams-architect Agent

Delegate to agent via Task tool:

const result = await Task({
  subagent_type: "diagrams-architect",
  prompt: `Create ${diagramType} diagram for ${scope}

Context:
${loadedContext}

Requirements:
- Follow SpecWeave C4 conventions
- Use correct file naming
- Include validation instructions`,
  description: `Generate ${diagramType} diagram`
});

Step 4: Save Diagram

The agent returns diagram content. Save to correct location:

C4 Context/Container: .specweave/docs/internal/architecture/diagrams/ C4 Component: .specweave/docs/internal/architecture/diagrams/{module}/ Sequence: .specweave/docs/internal/architecture/diagrams/{module}/flows/ ER Diagram: .specweave/docs/internal/architecture/diagrams/{module}/data-model.mmd Deployment: .specweave/docs/internal/operations/diagrams/deployment-{env}.mmd

Step 5: Confirm to User

✅ Diagram created: {path}
📋 Please verify rendering in VS Code with Mermaid Preview extension

Examples

Example 1: C4 Context Diagram

User: "Create C4 context diagram for authentication"

You:

1. Detect: C4 Context (Level 1)
2. Load context: Read auth spec if exists
3. Invoke agent:

await Task({
  subagent_type: "diagrams-architect",
  prompt: "Create C4 context diagram for authentication system. Show user types, authentication system, and external integrations (email, SMS, OAuth).",
  description: "Generate C4 Level 1 diagram"
});

4. Agent returns diagram content
5. Save to .specweave/docs/internal/architecture/diagrams/auth-context.mmd
6. Confirm: "✅ Diagram created: .specweave/docs/internal/architecture/diagrams/auth-context.mmd"

Example 2: Sequence Diagram

User: "Create login flow diagram"

You:

1. Detect: Sequence diagram
2. Load context: Read login spec/flow docs if exist
3. Invoke agent:

await Task({
  subagent_type: "diagrams-architect",
  prompt: "Create sequence diagram for login flow. Show: User → Browser → AuthService → Database → SessionStore. Include success and failure paths.",
  description: "Generate sequence diagram"
});

4. Agent returns diagram
5. Save to .specweave/docs/internal/architecture/diagrams/auth/flows/login-flow.mmd
6. Confirm completion

Example 3: ER Diagram

User: "Create data model for users and sessions"

You:

1. Detect: ER diagram
2. Load context: Read database schema docs if exist
3. Invoke agent:

await Task({
  subagent_type: "diagrams-architect",
  prompt: "Create ER diagram for authentication data model. Entities: USER, SESSION, REFRESH_TOKEN, PASSWORD_RESET. Show relationships and key fields.",
  description: "Generate ER diagram"
});

4. Agent returns diagram
5. Save to .specweave/docs/internal/architecture/diagrams/auth/data-model.mmd
6. Confirm completion

Validation

After saving diagram, ALWAYS tell user to validate:

✅ Diagram created: {path}

📋 VALIDATION REQUIRED:
1. Open the file in VS Code
2. Install Mermaid Preview extension if needed
3. Verify diagram renders correctly
4. Report any syntax errors

If diagram fails to render, I will regenerate with fixes.

File Naming Conventions

C4 Context: {system-name}-context.mmd or system-context.mmd C4 Container: {system-name}-container.mmd or system-container.mmd C4 Component: component-{service-name}.mmd Sequence: {flow-name}-flow.mmd or {flow-name}.sequence.mmd ER Diagram: data-model.mmd or {module}-data-model.mmd Deployment: deployment-{environment}.mmd

Error Handling

If diagram type is unclear:

• Ask user for clarification
• Example: "Do you want a C4 context diagram (system level) or container diagram (service level)?"

If context is insufficient:

• Ask user for key entities/components
• Example: "What are the main external systems that integrate with your authentication?"

If agent returns error:

• Report error to user
• Suggest corrections
• Retry with adjusted prompt

Test Cases

See test-cases/ directory:

• test-1.yaml - Diagram type detection
• test-2.yaml - Agent coordination
• test-3.yaml - File placement and naming

Integration

Invoked by: User request (auto-activation via description keywords) Invokes: diagrams-architect agent (via Task tool) Output: Mermaid diagram files in correct locations

---

Remember: You are a coordinator. Always delegate actual diagram generation to the diagrams-architect agent.