Terminal
Terminal/Skill
Entry point that reads a Penpot request and routes it to the right Penpot skill or workflow without changing the canvas.
By Penpot
Works with
npx skills add penpot/penpot-ai-kit --skill penpot-routerpenpot-router is a thin entry point. It does not draw, tokenize, or restructure anything — it
reads the user's intent and hands off to exactly one downstream skill or workflow (build a screen, build a
slide deck, build a design system, audit, migrate, extract DESIGN.md, …). Every mutation goes
through execute_code; validate visually with export_shape; read structure with
penpotUtils.shapeStructure (full tool surface: shared/penpot-mcp-tool-reference.md). This skill only
ever uses high_level_overview plus read-only execute_code discovery calls (penpotUtils.shapeStructure,
penpotUtils.tokenOverview()). Every mutation belongs to the skill it routes to; this router
validates nothing visually because it changes nothing. If the host client already auto-selects skills
by their description, this router degrades gracefully to documentation — the intent taxonomy in
references/01-intent-taxonomy.md becomes a reference map rather than an active dispatcher.
Route to exactly one target, and run preflight before doing so. Never start mutating from inside the router, and never fan a single request out to multiple mutating skills in parallel. One request → one preflight (overview + a quick structure/token read) → one target skill or workflow → handoff. If intent is ambiguous between two targets, ask one disambiguating question; do not guess and act.
Full surface: shared/penpot-mcp-tool-reference.md. The router leans on only two calls:
| Call | Why the router uses it |
|---|---|
high_level_overview | Mandatory session preamble. Must have been called before any routing decision is acted on. |
execute_code (read-only) | penpotUtils.shapeStructure(penpot.currentPage.root, 2) and penpotUtils.tokenOverview() to sense the current state of the file so routing is grounded in reality, not assumptions. |
The router never calls execute_code to create/modify/delete, and never calls export_shape
(nothing to validate). Downstream skills own all mutation and validation.
The router touches only read paths: penpot.currentPage, penpot.selection,
penpot.library.local.tokens, penpotUtils.shapeStructure, penpotUtils.tokenOverview,
penpotUtils.getPages. Gotchas (shared/plugin-api-gotchas.md):
penpot_api_info (e.g. penpot_api_info("PenpotUtils", "shapeStructure")) rather than guessing.Before routing, restate the request as a compact contract so the chosen skill inherits a clean brief. Assign the role: "act as a senior design-systems triage lead who never starts work in the wrong flow." Capture:
tokenOverview() + shapeStructure).antiSlop: on|off —
the build skill then stores it and skips its opt-in question. The router never asks it itself.The router emits this contract as the handoff payload. It does not invent token values or names — if the request implies new tokens, that is the downstream skill's job (and a human approval gate).
Goal: ensure the session is initialized and the file's state is known.
high_level_overview has been called this session; if not, call it now.execute_code call for a shallow state sense:
return {
pages: penpotUtils.getPages().map(p => p.name),
currentPage: penpot.currentPage && penpot.currentPage.name,
selectionCount: penpot.selection.length,
selection: penpot.selection.map(s => ({ id: s.id, name: s.name, type: s.type })),
topLevel: penpotUtils.shapeStructure(penpot.currentPage.root, 1)
};
return penpotUtils.tokenOverview();
Exit criterion: you know (a) whether tokens/sets exist, (b) what is selected, (c) the page layout at depth 1. ✋ Checkpoint: none needed — read-only — proceed straight to Phase 1.
Goal: map the user's words to one row of the routing table (§8 / references/01-intent-taxonomy.md).
Read the literal request, combine it with the Phase 0 state (e.g. "no tokens exist yet" biases a vague
"set up my design system" toward penpot-foundations / the design-system-bootstrap workflow). If the
request maps cleanly to one target, continue. If it maps to two or more with comparable confidence,
✋ Checkpoint: ask one disambiguating question (offer the two candidate targets in plain language).
Goal: transfer control with a clean brief.
high_level_overview ran before acting on a route. No routing decision is
executed in a session where the overview was skipped.execute_code and never calls export_shape.The router's product is a decision, not a canvas artifact. The decision space is the table below.
Full phrasing map and fallbacks: references/01-intent-taxonomy.md.
| Intent | Target skill | Example user phrasings |
|---|---|---|
| Establish tokens / foundations (color, spacing, type, radius scales; themes) | penpot-foundations | "set up our design tokens", "create a color + spacing scale", "add a dark theme", "bootstrap foundations" |
| Build / extend reusable components & variants | penpot-component-factory | "make a Button component with variants", "build an Input with states", "turn this into a component", "add a Size axis" |
| Assemble a screen/view from brief + existing system | penpot-build-screen | "design a settings screen", "lay out a dashboard", "build the pricing page from this brief" |
| Build a screen/view from code/markup | penpot-build-from-code | "create this React page in Penpot", "push this component's JSX to a board", "build the screen to match this code" |
| Design a presentation / slide deck from a brief | penpot-build-deck | "create a presentation", "build a slide deck", "pitch deck", "make slides for this talk", "turn this outline into slides" |
| Document/annotate a design for handoff | penpot-document-handoff | "document this design", "annotate this screen", "prepare this for handoff", "add observation notes", "create a critique card", "explain this flow for devs" |
| Accessibility audit (WCAG) | penpot-audit-accessibility | "check accessibility", "WCAG AA audit", "contrast check", "are touch targets big enough", "a11y review" |
| Token governance audit | penpot-audit-tokens | "find hardcoded colors", "audit token usage", "what's off the 4px grid", "find orphan/unused tokens" |
| Compare design vs. code (drift) | penpot-design-to-code-review | "does this design match the code", "design-to-code review", "find drift between Penpot and the component" |
| Extract a portable DESIGN.md spec from the file | penpot-design-md | "generate a DESIGN.md", "export our design guidelines as markdown", "style guide file for our coding agent" |
| Import / migrate from Figma | penpot-migrate | "migrate this Figma file", "import from Figma", "bring our Figma library into Penpot" |
| Check / steer a design away from the generic-AI look | penpot-anti-slop | "does this look AI-generated", "anti-slop check", "make it feel less generic", "¿parece hecho por IA?", "evita la estética IA" |
| Rename layers semantically | penpot-rename-layers | "rename these layers", "clean up layer names", "semantic HTML layer names", "fix Rectangle 12 names" |
| Intent | Target workflow | Example user phrasings |
|---|---|---|
| Decide where to start (meta) | routing | "I don't know which tool I need", "where do I begin", "help me with this Penpot file" |
| End-to-end design system from scratch/code | design-system-bootstrap | "set up a full design system", "tokens + components + docs from our codebase", "bootstrap the whole library" |
| Brief → finished screen (foundations check → build → a11y) | brief-to-screen | "take this brief and ship a screen", "design and validate this page end to end" |
| Brief → finished, playable deck (build-deck → a11y on slides + deck-quality loop) | brief-to-deck | "turn this outline into a polished deck", "design and validate this presentation end to end" |
| Keep Penpot in sync with code | code-to-penpot-sync | "sync our components to code", "reconcile Penpot with the repo", "keep design and code aligned" |
| Full Figma → Penpot migration program | figma-migration | "migrate our entire Figma project", "full Figma import with tokens, components, screens" |
| Gate a design on accessibility before handoff | accessibility-gate | "block handoff until a11y passes", "run the accessibility gate", "validate before we ship" |
Mode-default: suggest (see shared/modes-and-policies.md). The router is read-only by nature, so
it has no safe-set auto-fix items — it never mutates the canvas under any mode. What it may do
without asking: call high_level_overview, run read-only shapeStructure/tokenOverview discovery,
and propose a route. What always requires the user (or the downstream skill's own gate): executing the
route when intent is ambiguous, and anything the target skill does (those inherit that skill's mode).
The router writes minimal state (shared/state-management.md). It does not own a RUN_ID workflow —
that belongs to the skill it routes to — but it records its decision so a resumed session can see how
it got there:
storage.router = { lastIntent, chosenTarget, queuedIntents, overviewCalled: true } (session cache).penpot-ai, key router.lastRoute, via
setSharedPluginData (verify signature with penpot_api_info before relying on it).On resume: re-read storage.router and the breadcrumb, re-run Phase 0 discovery (file state may have
changed), and reclassify rather than blindly continuing — routing must reflect current reality.
| After phase | Artifacts shown | What we ask |
|---|---|---|
| Phase 0 (discovery) | Page list, selection summary, token-set presence | (Informational — no approval; proceed.) |
| Phase 1 (classification) — only if ambiguous | Two candidate targets in plain language | "Which best matches what you want — A or B?" |
| Phase 2 (handoff) — only if ambiguous or the target is an expensive mutating flow on existing content | Chosen target + the Token-Aware Brief Contract + queued intents | "Routing to X — confirm or redirect?" (clean matches: state the route and proceed) |
The router enforces no names itself, but it must speak the kit's vocabulary when restating the
brief so the downstream skill inherits correct expectations (shared/naming-conventions.md): tokens in
dot-notation (color.action.primary.bg), components in PascalCase (Button), variants as
Property=Value pairs (State=Hover), layers as semantic kebab-case HTML names (nav, card-container).
If a request implies a RUN_ID (any multi-step workflow), use the convention slug, e.g.
dsb-2026-06-05-a, and let the target skill own it.
| Excuse the LLM makes | Why it's wrong | Deterministic countermeasure that halts the flow |
|---|---|---|
| "This is obviously a build request — I'll just start creating boards now." | The router is read-only; starting mutation here bypasses the target skill's discovery, brief contract, and checkpoints. | Stop. Route to penpot-build-screen/penpot-build-from-code, emit the §5 brief, and let that skill own Phase 0 and all mutation. |
| "The request mentions both tokens and a screen — I'll route to both at once." | Fanning out to two mutating skills in parallel produces conflicting edits and an unauditable run. | Split intents. Route the primary objective; queue the rest in storage.router.queuedIntents. One target per request. |
| "Intent is a bit ambiguous, but I'll pick the more likely skill and proceed." | A wrong-flow start is expensive to undo (geometry/variant changes are not safe-set). | Halt at the Phase 1 checkpoint; ask one disambiguating question offering the two candidate targets. |
"high_level_overview was probably called earlier; I'll skip it." | Acting without the MCP's own guidance loaded is the #1 cause of API misuse downstream. | Confirm it ran this session; if uncertain, call it. No route is executed otherwise. |
| "The host client auto-selected a skill, but I'll re-dispatch to be safe." | Double-dispatch causes the same work to run twice or two skills to fight. | Detect host auto-selection; degrade to documentation (serve the taxonomy as a map) and step aside. |
| "I'll route based on the user's words alone — no need to read the file." | Identical phrasing routes differently in an empty file vs. a mature system ("set up my design system" → bootstrap vs. extend). | Run Phase 0 reads (tokenOverview, shapeStructure) and use file state to break ties before classifying. |
Read-only discovery only — the router never mutates.
// Phase 0a — state sense (paste into one execute_code call)
return {
pages: penpotUtils.getPages().map(p => p.name),
currentPage: penpot.currentPage && penpot.currentPage.name,
selectionCount: penpot.selection.length,
selection: penpot.selection.map(s => ({ id: s.id, name: s.name, type: s.type })),
topLevel: penpotUtils.shapeStructure(penpot.currentPage.root, 1)
};
// Phase 0b — token state (does a design system already exist?)
const ov = penpotUtils.tokenOverview();
return {
hasTokens: !!(ov && ov.totalTokens),
overview: ov
};
// Optional — drop a routing breadcrumb into the file (verify signature first via
// penpot_api_info("PenpotFile", "setSharedPluginData"))
penpot.currentFile.setSharedPluginData(
"penpot-ai",
"router.lastRoute",
JSON.stringify({ chosenTarget: "REPLACE-ME", at: "RUN_ID_HERE" })
);
return { recorded: true };
penpot_api_info("PenpotUtils", "shapeStructure"), penpot_api_info("PenpotUtils", "tokenOverview")
— confirm discovery helper signatures.penpot_api_info("PenpotFile", "setSharedPluginData") — confirm the breadcrumb signature.shared/penpot-mcp-tool-reference.md — the tool surface.shared/modes-and-policies.md — why the router is suggest-only.SKILL.md descriptions — the authoritative trigger lists the router maps onto.| File | Loaded when | Contents |
|---|---|---|
references/01-intent-taxonomy.md | Phase 1 (classification) | Full map of user phrasings → target skill/workflow, with fallbacks, tie-breakers, and multi-intent splitting rules. |
references/02-preflight-overview.md | Phase 0 (discovery) | How to call high_level_overview and run the quick shapeStructure / tokenOverview reads that ground a routing decision. |
execute_code templates)None. The router performs no mutations and needs no reusable mutation templates — its only execute_code
usage is the inline read-only discovery snippets in §14.
In a native Claude Code install this skill's bundle also carries workflows/ — the seven multi-skill
pipelines (§8's workflow targets: routing, design-system-bootstrap, brief-to-screen, brief-to-deck,
code-to-penpot-sync, figma-migration, accessibility-gate), each a README.md (prose) +
pipeline.json (deterministic step list). When routing to a workflow, open its files from here; in
seed-pointer installs they live at the kit root under workflows/.
Doctrine paths. shared/… and policies/… resolve inside this bundle in native installs (vendored by the installer); in a Claude Code plugin install they live at the plugin root — ${CLAUDE_PLUGIN_ROOT}/shared/…, two directories up from this file.