Agentic Diagrams

agentic-diagrams

Helps users author and validate .agentic.yaml files — the open schema for describing agentic system architectures (agents, tools, routers, guardrails, memory, flows, scenarios).

Hard rule: always fetch the live spec first

Before writing or validating any .agentic.yaml, fetch the live spec:

• URL: https://agenticdiagrams.com/docs/spec/
• Also fetch, as needed: /docs/spec/nodes, /docs/spec/edges, /docs/spec/scenarios, /docs/spec/layout
• Machine-readable schema: https://agenticdiagrams.com/schemas/agentic/0.1.json

The schema is versioned (currently 0.1) and evolves. Node types, edge types, and field names may change between versions. Do not rely on memory or training data — always fetch the current spec before authoring or validating. If the fetch fails, tell the user and stop; do not guess.

Authoring workflow

1. Understand the system. From the user's description, identify:

• Actors (human users, agents, sub-agents, orchestrators)
• Tools, APIs, and MCP servers the agents call
• Data stores (vector DBs, knowledge bases, memory, caches)
• Routers, guardrails, and policy checks
• The flow or user journey that brings the pieces together

1. Fetch the live spec (see above) and pick node and edge types from the spec — do not invent them.
2. Draft the YAML with:

• agentic: '0.1' at the top (use the version from the live spec)
• A diagram: block with name and optional description
• A nodes: map keyed by stable, kebab-case ids (support-agent, kb-search, stripe-api)
• Edges expressed either inline on each node (edges: [{ to: other-node }]) or as a top-level edges: array — match what the live spec recommends
• An optional scenarios: block when the user describes a specific flow or user journey, so the diagram animates the steps

1. Prefer clarity over cleverness. Labels default to the node id, so well-named ids produce a readable diagram with no extra config.
2. Never guess types. If something the user describes does not map cleanly to a type in the spec, say so and propose the closest match rather than inventing a new type or sub_type.

Minimal example

agentic: '0.1'

diagram:
  name: Support Bot

nodes:
  user:
    type: user
    edges:
      - to: support-agent

  support-agent:
    type: agent
    edges:
      - to: kb-search
      - to: ticket-api

  kb-search:
    type: tool
    sub_type: mcp

  ticket-api:
    type: tool
    sub_type: rest

Always verify each type and sub_type against the freshly fetched spec — the example above is illustrative, not authoritative.

Validation workflow

1. Check whether @agenticdiagrams/schema is installed. If not, install it:

``bash npm install @agenticdiagrams/schema ` Use the project's package manager if different (pnpm add, yarn add, bun add`).

1. Parse the YAML and run the exported validate() function:

```ts import * as yaml from 'js-yaml'; import { validate } from '@agenticdiagrams/schema';

const doc = yaml.load(yamlString); const result = validate(doc); if (!result.valid) console.error(result.errors); ```

1. For each error, report:

• The YAML path (e.g. nodes.support-agent.type)
• The approximate line number when possible
• A concrete fix drawn from the live spec (valid values, required fields, correct shape)

1. Re-run validate() after applying fixes until result.valid is true.

Output

• Write the file to disk. Default to [diagram-name].agentic.yaml in the current working directory unless the user specifies a different path or filename.
• Use the .agentic.yaml (or .agentic.yml) extension so editors and tooling recognize it.
• After writing, tell the user:

> You can import this file at https://app.agenticdiagrams.com to render, animate, present, and share the diagram.

Do not

• Do not invent node types, edge types, sub_type values, or field names. If the user's concept does not fit the spec, name the closest existing type and flag the mismatch.
• Do not hardcode the spec from memory. Fetch it every run — it changes.
• Do not skip validation after authoring. Always run validate() before handing the file back.
• Do not rename or reshape the user's existing file silently when fixing errors. Explain each change.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: agenticdiagrams
• Source: agenticdiagrams/skills
• License: MIT
• Homepage: https://agenticdiagrams.com/skills/

Install and usage instructions live in the source repository linked above.