Skip to content
Kekonic DiagramsKekonic Diagrams

Design with agents

Generic “draw our architecture” prompts invent boxes to complete the graph. The design-kekonic-diagrams skill tells Cursor, Claude Code, Codex, and other Skills CLI hosts to inspect the repo you name, write .kdiagram source, and verify it with the CLI. Missing facts go in the notes, not in the diagram.

Install

Section titled “Install”
Terminal window
npx skills add kekonic/diagrams

What the agent does

Section titled “What the agent does”
  1. Names the reader and one question the diagram should answer.
  2. Separates what you said, what it found in code or configuration, and what it is assuming.
  3. Chooses a diagram kind before writing boxes (architecture, events, workflow, ERD, sequence, or state) and splits the work when one picture would have to explain everything.
  4. Writes .kdiagram source. Layout and presentation stay in that file.
  5. Runs kdiagrams check, format, render, and analyze.
  6. Returns the source, a portable SVG, assumptions, intentional omissions, and anything it could not resolve.

Missing facts go in those notes. They do not become extra boxes.

Request

Show a new engineer how checkout moves from the web app through payment authorization. Read the code. Do not invent services.

Found in the repo

Web app → API → Checkout → Billing → Stripe

Reported as an assumption

Mobile uses the same gateway — noted, not drawn as fact.

Checked

kdiagrams check · render · analyze

Diagram with 5 nodes and 4 edges Checkout authorizationWeb appAPICheckoutBillingStripeauthorize

Prompt

Section titled “Prompt”

Give a specific reader question and say which files the agent may inspect:

Use the Kekonic Diagrams skill to show a new engineer how checkout moves from the web app through payment authorization. Read the relevant code and configuration, distinguish observed facts from assumptions, and return the .kdiagram source plus a portable SVG.

Review the assumptions as carefully as the diagram.

After you have a file

Section titled “After you have a file”

Commit the .kdiagram source with the system it describes. Render SVG in CI the same way you render any other generated artifact. See the quickstart and the CLI reference.

Other install options

Section titled “Other install options”

From git (same skill files):

Terminal window
npx skills add https://github.com/kekonic/diagrams/tree/main/packages/diagrams-agents

The same files ship as @kekonic/diagrams-agents for environments that pin skills as a package dependency. The Skills CLI currently installs from git, not from the npm package name.