Using with AI

TDL was designed with AI generation in mind. Here's how to get the best results.

Why TDL Works Well with AI

1. Token Efficient - More diagram per context window

2. Predictable Syntax - Easy for AI to learn patterns

3. No Edge Cases - Simple strings, no escaping needed

4. Clear Structure - Sections prevent AI confusion

Prompting Tips

Be Specific About Components

Good prompt:

Create a TDL diagram showing a user authentication flow with:

• API Gateway

• Auth Service (connects to Redis for sessions)

• User Database (PostgreSQL)

• Show both sync calls and async events

Vague prompt:

Make a diagram of a login system

Specify Diagram Type

Good prompt:

Create a TDL sequence diagram (@seq) showing the OAuth2 authorization code flow

Vague prompt:

Show me how OAuth works

Request Specific Features

Good prompt:

Create a TDL architecture diagram with:

• AWS icons for cloud services

• Groups for VPC boundaries

• Dashed lines for async communication

Example Conversation

You: Create a TDL diagram for a data pipeline that:

• Ingests from Kafka

• Processes with Spark

• Stores in S3 and Redshift

• Use AWS icons

AI:

@arch
#!ext icons

[nodes]
  kafka:Kafka|icon:aws-amazon-managed-streaming-for-apache-kafka
  spark:Spark Cluster|icon:aws-amazon-emr
  s3:Data Lake|icon:aws-s3
  redshift:Warehouse|icon:aws-amazon-redshift

[edges]
  kafka->spark:stream
  spark->s3:raw data
  spark->redshift:aggregated

Rendered diagram

MCP Integration (Claude Code)

If you're using Claude Code with the TDL MCP server, Claude can render diagrams directly:

You: Create a microservices diagram and render it

Claude:

@arch
[nodes]
  gw:API Gateway
  users:User Service|cyl
  orders:Order Service|cyl
[edges]
  gw->users
  gw->orders
  users-->orders

Rendered diagram

Setting Up MCP

Add to your Claude Code settings:

{
  "mcpServers": {
    "tdl": {
      "command": "npx",
      "args": ["-y", "@tdl/mcp"]
    }
  }
}

The SKILL.md Reference

For AI systems that support it, TDL includes a comprehensive skill file at packages/tdl/SKILL.md. This 600+ line reference teaches AI:

• All syntax rules

• Every shape and edge type

• Icon namespaces

• Common patterns

• Anti-patterns to avoid

Common AI Mistakes

Mistake	Cause	How to Fix
Missing @arch	AI forgets diagram type	Always specify type in prompt
Quoted labels	Mermaid habits	Labels don't need quotes
Wrong edge syntax	PlantUML habits	Use -> and -->, not -->>
Missing sections	Incomplete output	Ask to "include [nodes] and [edges] sections"

Next Steps

• Architecture Diagrams - Master the most common type

• All Shapes - Visual reference

• Icon Library - 200+ available icons