Penpot Router

penpot-router — the dispatcher

1. Title + How it works

penpot-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. 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.

2. The One Rule That Matters Most

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.

3. Penpot MCP Tool Reference

Full surface: shared/penpot-mcp-tool-reference.md. The router leans on only two calls:

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.

4. Plugin API Essentials

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):

• #2 token application is async (~100 ms) — never read back a resolved value as authoritative; the router applies no tokens at all, so its only real trap is doing too much. If you are unsure whether a discovery helper exists with a given signature, verify with penpot_api_info (e.g. penpot_api_info("PenpotUtils", "shapeStructure")) rather than guessing.

5. Token-Aware Brief Contract

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:

• Context — product, audience, and whether a design system already exists in this file (derived from tokenOverview() + shapeStructure).
• Objective — a single verb-led intent ("build a settings screen", "audit contrast", "migrate the Figma button library"). If the user states two, split and route the primary; queue the rest.
• Inputs — selected shapes/boards, target page, referenced tokens/components, external refs (code paths, Figma URLs).
• Constraints — forbidden components, inviolable rules, mode (suggest/review/autofix), scope caps.
• Acceptance Criteria — what "done" means for the downstream skill (e.g. "WCAG AA contrast ≥ 4.5:1 on body text", "all spacing on the 4px grid", "variant matrix complete for State axis"). The router does not verify these; it forwards them so the target skill can.

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).

6. Mandatory Workflow

Phase 0 — Discovery (read-only)

Goal: ensure the session is initialized and the file's state is known.

1. Confirm high_level_overview has been called this session; if not, call it now.
2. One read-only 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)
   };
   

3. One read-only call for token state:

   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.

Phase 1 — Intent classification

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).

Phase 2 — Handoff

Goal: transfer control with a clean brief.

1. State the chosen target explicitly ("Routing to penpot-build-screen because…").
2. Emit the §5 Token-Aware Brief Contract as the payload.
3. Note any secondary intents queued for later.
4. Invoke / instruct the target skill. The router's job ends here; it performs no mutations. Exit criterion: exactly one target named, contract emitted, secondary intents queued. ✋ Checkpoint (conditional): ask "Routing to X — confirm or redirect?" only when (a) Phase 1 was ambiguous (two candidates with comparable confidence), or (b) the target is an expensive mutating flow on a file with existing content (a migration, a bootstrap over a mature system, anything that will restructure components). For a clean, unambiguous match, state the route and proceed — the target skill's own Phase-0 checkpoint is the user's natural review point; a second confirmation here is friction, not safety.

7. Critical Rules

1. Always confirm high_level_overview ran before acting on a route. No routing decision is executed in a session where the overview was skipped.
2. One target per request. Split multi-intent requests; route the primary, queue the rest.
3. Read-only only. The router never calls a mutating execute_code and never calls export_shape.
4. No guessing on ambiguity. Two plausible targets → one question, not a coin flip.
5. Ground the route in file state. Use Phase 0 reads to break ties (empty file vs. mature system).
6. Forward the brief verbatim. Do not silently drop constraints or acceptance criteria.
7. Degrade to documentation. If the host already routes by description, do not duplicate-dispatch; serve the taxonomy as a map and step aside.
8. Default mode = suggest. The router proposes a route; it owns no canvas changes.

8. Domain Architecture — the routing table

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.

Skills

Workflows (multi-skill orchestrations)

9. Modes & Policies

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).

10. State Management

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).
• Optional in-file breadcrumb under namespace 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.

11. User Checkpoints

12. Naming Conventions

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.

13. Anti-Rationalization Table

14. Helper Code Snippets

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 };

15. Reference Resources

• 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.
• Sibling skills' own SKILL.md descriptions — the authoritative trigger lists the router maps onto.

16. Supporting Files

references/ (progressive-disclosure deep dives)

scripts/ (paste-into-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.

workflows/ (vendored in native installs)

In a native Claude Code install this skill's bundle also carries workflows/ — the six multi-skill pipelines (§8's workflow targets: routing, design-system-bootstrap, brief-to-screen, 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/.