Skip to content

jquatier/squinch

v0.17.1Apache-2.0

Turns your coding agent into an architecture diagrammer: describe a system in plain language and it writes, checks and renders a clean, professional diagram — AWS, Azure, Google Cloud and Kubernetes estates, landscapes you can zoom into at every altitude, numbered request flows — with real vendor icons, exported as SVG, PNG or interactive HTML. Requires the squinch CLI (npx squinch).

GitHubOpen Website

@squinch/skill

skills/squinch/ is the whole contract an agent needs to author Squinch diagrams. SKILL.md is the body — the check-render-fix loop, the hand-over, the quality bar, the grammar, the views and the layout hints — and references/ holds the lookup material it points at, one level deep: cookbook.md (symptom → fix, opened when a diagnostic is not self-explanatory) and icons.md (the ids per pack in full, opened when an icon is outside the AWS basics). The split is the Agent Skills guidance on size — a harness keeps only the first few thousand tokens of an invoked skill after context compaction. The body still carries compact id runs per pack, because the gauntlet measured that a cold agent writes from the lists it can see and never opens a sibling file (round 31 in the gauntlet README). The directory is the only thing the cold agents in the gauntlet are given, alongside the squinch binary — so if something an agent needs isn't in here, the gauntlet is where that shows up.

Installing it

The CLI carries the skill and installs it where agents look:

npx squinch skill            # this project: .agents/skills/ — Cursor, Codex,
                             # Gemini CLI, Copilot and every other agent that
                             # reads the Agent Skills standard (agentskills.io);
                             # adds .claude/skills/ when it detects Claude Code
npx squinch skill --global   # just for you: the same two, under your home
                             # directory — ~/.agents/skills, and ~/.claude/skills
                             # when ~/.claude is there (or with --claude)

Re-run after upgrading squinch — the installed directory is version-locked to the CLI that wrote it (the stamp is in SKILL.md; references/ is replaced whole on every install).

Or take the plugin instead, straight from this repo — updates then arrive with the plugin rather than living in your tree. Claude Code:

/plugin marketplace add jquatier/squinch
/plugin install squinch@squinch

Codex, and anything else that reads Agent Plugins — Cursor, Copilot, Kiro, VS Code:

codex plugin marketplace add jquatier/squinch
codex plugin add squinch@squinch

Then ask for a diagram in plain language — the frontmatter's description is what makes it fire, so "draw the architecture of this service" is enough. The skill drives squinch check and squinch render, so the CLI has to be reachable: npx squinch works with no install at all.

Using it with any other agent

There is nothing Claude-specific in the files below the frontmatter. Copy skills/squinch/ wherever your agent discovers skills, or squinch skill --print the whole directory as one stream — the body, then each reference file under a comment naming its path — to paste into a system prompt or hand to whatever your harness calls context. What matters is that the agent can run squinch check and read the diagnostics — the skill is written around that loop, not around one vendor's format.

Keeping it true

test/skill.test.ts compiles every DSL snippet in the directory through the real engine, asserts every icon id it names actually resolves in an installed pack, that every grammar keyword is documented somewhere in the set, that every engine diagnostic needing a technique has a cookbook row, and that every reference file is named from SKILL.md. Documentation that drifts from the language fails the build, which is the point: an agent reading a stale cookbook produces diagrams that don't check.

One file derives from the directory — edit only the canonical files: packages/cli/src/skill.generated.ts, the copy squinch skill installs, regenerated by scripts/gen-skill.mjs from every file under skills/squinch/ (pre-commit and CI diff it).

Two manifests here make this one directory two plugins off the same skills/ dir: .claude-plugin/plugin.json for Claude Code, and plugin.json — Agent Plugins 1.0 — for Codex and the rest. Each has a marketplace manifest at the repo root pointing back at this directory (.claude-plugin/marketplace.json and .agents/plugins/marketplace.json), and scripts/version.mjs moves both plugin manifests with everything else. test/skill.test.ts asserts the two agree on name, version and description, and core's guardrails assert both marketplaces still resolve here.