Quickstart with your agent

Your coding agent can draw your project's architecture for you. Give it the archgram skill, ask, and it reads the code, writes the spec, draws the diagram and shows you the file behind every part. You need Node 22 or later.

1. Add the skill#

The skill is written to the open Agent Skills format, so any agent that reads skills can use it. Add it with the skills command, in your project's folder.

npx skills add byabas/archgram

It asks which of your agents to add it for and puts it where each one looks. Add -g to add it for every project on your machine rather than this one.

These agents read it, among others. The folder is where the skill lands in your project. Name agents with --agent to skip the question.

The skills command keeps the full list of agents and where each one looks.

In Claude Code, as a plugin#

archgram is also a plugin in Anthropic's directory. Find archgram there and add it to your claude.ai account. Claude Code loads it the next time it starts signed in with that account.

Without the skills command#

Each release also carries the skill as an archive. Download archgram-skill-X.Y.Z.tar.gz from the latest release, then unpack it into your agent's skills folder, ~/.agents/skills, or ~/.claude/skills for Claude Code.

mkdir -p ~/.agents/skills && tar -xzf archgram-skill-*.tar.gz -C ~/.agents/skills

2. Ask your agent#

Open your agent in the project and ask in your own words.

Draw this project's architecture with archgram.

In Claude Code you can also type /archgram. Say more when you know what you want. Name a flow, a part of the system or a direction, and the agent draws that.

Draw how a checkout goes from the browser to the payment provider.

3. What the agent does#

1. Decides who the diagram is for and the few questions it must answer for them.
2. Reads the code and the docs. It draws a part only where a file backs it, and a line only where a line of code makes it.
3. Asks you when the code is unclear, for example when the README describes a part the code does not have. Everything else it decides itself.
4. Writes the spec in docs/diagrams/ and checks it with archgram until it passes.
5. Draws it and opens the drawing for you.
6. Reports each part with the file behind it, each line with the code that makes it, and what the diagram still does not show.

The agent runs archgram through npx, at the version the skill names, so nothing else needs installing. If your project already lists archgram in its package.json, the agent uses that one.

4. What you get#

• The spec, such as docs/diagrams/architecture.archgram.yaml. Read it like code. Each part names the file behind it.
• The drawing beside it, docs/diagrams/architecture.svg, light and dark in one file.
• A report in the chat, with the line to paste into your README and alt text that tells the flow in words.

The agent edits your README or commits only when you ask.

Draw from a document#

The skill can also draw what a document describes, a design doc, a docs page or an article. Name the document.

Draw the design in docs/design.md with archgram.

The agent then takes its facts from the text instead of the code. It draws a part only where a sentence states it, labels it in the document's own words, and tells you what the document leaves out.

Keep it true#

Ask the agent again when the code changes.

Update the architecture diagram.

It starts from what archgram check says has lost its code, changes only that and what is new, and keeps the diagram's direction so it does not turn on its side. You can run the check yourself, or in CI, at any time.

npm exec -- archgram check docs/diagrams/architecture.archgram.yaml

pnpm exec archgram check docs/diagrams/architecture.archgram.yaml

yarn archgram check docs/diagrams/architecture.archgram.yaml

In your colours#

archgram draws in black and white by default. Ask for your project's colours, "in our colours", and the agent reads them from your design tokens or your styles and draws with them.