Agent skill

Let an AI agent with dtctl generate, validate and register diagrams for you.

What it does

skill/SKILL.md teaches an AI agent that has dtctl how to create, validate and register diagrams in the same lookup table the app reads. Ask it for "a diagram of the checkout flow" and it:

1. discovers the real entities with Smartscape queries — it never invents ids — and writes them into each component's entities list (or an entityDql when the selection must stay dynamic);
2. builds a JSON document that matches skill/diagram.schema.json, with layers laid out from left to right;
3. reads the real dependencies from Smartscape (calls and runs_on edges) and checks when the environment has data, to pick the diagram's timeframe;
4. runs every query in that timeframe to check it returns what the app expects;
5. upserts the diagram into /lookups/custom-diagram-creator/diagrams without touching other rows;
6. gives you the JSON and the id, so the diagram opens at …/ui/apps/my.custom.diagram.creator/ui/diagram/<id>.

Prerequisites

• dtctl authenticated against the environment (dtctl auth whoami).
• Scopes: storage:files:read, storage:files:write, storage:smartscape:read, storage:entities:read, storage:events:read, storage:buckets:read; replacing an existing table with dtctl also needs storage:files:delete.

Discovering entities

dtctl query 'smartscapeNodes "SERVICE"
  | filter contains(name, "payment", caseSensitive: false)
  | fields id, name
  | limit 20'

Useful node types: SERVICE, PROCESS, HOST, FRONTEND (also returns id_classic), K8S_DEPLOYMENT, K8S_STATEFULSET, K8S_DAEMONSET and DB_INSTANCE_*.

Registering a diagram

The table is replaced as a whole, so the agent downloads the current rows, upserts its row and uploads everything again with the typed parse pattern:

dtctl create lookup -f rows.jsonl \
  --path /lookups/custom-diagram-creator/diagrams --lookup-field id \
  --display-name "Custom Diagram Creator diagrams" \
  --parse-pattern 'JSON{STRING:id, STRING:name, STRING:description, STRING:owner, STRING:createdAt, STRING:updatedAt, BOOLEAN:deleted, STRING:payload}:row'

Examples

The sample the app adds to every environment is the skill's example too:

• easytrade-showcase.json — Sample – EasyTrade trading platform, built with the skill's showcase recipe: digital experience, gateway, trading APIs, core services, data tier and host, with golden signals on every hop and real dependencies read from Smartscape. Its components select EasyTrade's entities by name, so it works in any environment running EasyTrade; it is saved with a fixed window in which the demo had traffic.

Rules the skill follows

• Never drop other diagrams when upserting.
• Never invent entity ids, SLO ids or icon names.
• Ask before deleting diagrams or the lookup file.
• If a query fails, report the error and don't register the diagram.