A new and improved AI-agent skill for creating, auditing, and maintaining production-grade design projects and design systems in Penpot via the official Penpot MCP Server:
Compatible with MCP-capable clients such as Claude Code, Cursor, VS Code/Copilot, Codex/OpenCode, Amp, Cline, Windsurf, Claude Desktop via mcp-remote, and similar clients.
Feedback and PRs welcome — especially for new workflow recipes, additional platform templates, or corrections as the Penpot MCP API evolves.
Congrats on putting this together @ar27111994 
This looks like a genuinely useful set of Penpot MCP skills, especially for teams trying to move past one-off prompts and build more repeatable design-system workflows.
I had a few questions after reading through it.
Have you tested these skills on real Penpot projects yet, or mostly on controlled/demo files? I’d be interested to know where they held up best: early UI exploration, mature design systems, production handoff files, prototypes, audits, or something else.
Which use cases would you recommend people start with? For example, would you point someone first toward creating a design system from scratch, auditing an existing file, generating prototype flows, keeping tokens and components consistent, or extracting design-to-code information?
Have you tracked token usage or context-window impact when using the packaged skill? I’m wondering how much overhead it adds in practice, especially when the agent needs to inspect a large Penpot file while also loading the extra reference docs.
I’m also curious whether you’ve seen a clear benefit from packaging the workflows together as a skill instead of keeping the instructions separate and letting the agent choose which recipe or reference to use. Does the bundled structure make the results more reliable, or can it sometimes add too much context and noise?
One last thing I’d love to understand: have you seen measurable improvements compared with using the Penpot MCP server directly with ad-hoc prompts? For example, better output quality, fewer failed MCP calls, safer batch operations, or more consistent design-system maintenance.
Great work overall 
This seems like a valuable step toward making AI-assisted Penpot workflows more predictable and useful in real production work.
Hi @juan.delacruz Thank you for the detailed response.
Yes, I’m currently using this in a real Android-first PWA Mobile and Web-based cross-platform project alongside OpenCode, OpenDesign and the official Penpot MCP Server. In my experience, this skill is particularly useful when doing some slightly complex stuff like setting up a shared components library, applying complex typography tokens across the project, etc.
I personally always start with setting up a base design system, including the shared design tokens, theme presets, typography setup, WCAG Compliance checks, etc. So, I’d personally recommend keeping the design system and spec, including the tokens and components being used, consistent across the project. Haven’t yet had a chance to try out the design-to-code workflow.
No, I haven’t tracked token usage or context-window impact when using the packaged skill.
Yes, I’ve seen a clear benefit from packaging the workflows together as a skill, especially with complex batch writes, fewer write timeouts and race conditions, better context handling and page switching, etc.
Lastly, yes, there are significant improvements in general Penpot use via the AI Agents paired with this skill compared with using the Penpot MCP server directly with ad-hoc prompts.
Update — significant API coverage expansion + real-world corrections
Since the initial announcement, the skill has gone through several substantial updates based on real production use and careful cross-referencing with the official plugin API docs at doc.plugins.penpot.app. Here’s what’s new:
New API coverage
The penpot-api-patterns.md reference now covers the complete plugin API surface, including things that weren’t documented anywhere else in a skills context:
Full Token API — TokenCatalog, TokenSet, TokenTheme, addToken with all TokenType values, cross-set references using {token.path} syntax, idempotent set/theme creation
Library creation API — createColor(), createTypography(), createComponent() with the correct property names (fontFamilies not fontFamily; color.color not color.fillColor)
Page management API — createPage(), openPage(), getPages(), getPageByName(), getPageById(), page.findShapes({ type, name, nameLike }) (criteria-based, not predicate)
Prototype flows via API — page.createFlow(name, entryBoard) and page.flows — flows can actually be created programmatically, not just from the Prototype panel
Visual effects — gradient fills (linear/radial with stop arrays), image fills via uploadMediaUrl(), shape.blurs array, full shadow color format
storage global — persists JS objects across execute_code calls within a session; essential for multi-call workflows
Idempotency helpers — ensureColor, ensureTypography, ensureSet, ensurePage, ensureBoard — prevents duplicate creation on retried or resumed sessions
Real-world gotchas added (from production experience)
Several silent failure modes that weren’t documented anywhere:
Font weight rejection — Penpot rejects weights not explicitly installed for a font family. Always query penpot.library.local.typographies to discover installed variants before applying weights.
Library fontSize must be string — typography.fontSize = '16' not 16. Text layers accept numbers, library styles require strings.
Stale fontId — Updating fontFamily/fontWeight on a library typography does not update the internal fontId. Known API limitation; rendered layers use the correct ID. Workaround: delete and recreate.
LibraryColor.color not fillColor — When creating/reading library colors, the property is .color, not .fillColor as you’d expect from shape fills.
Shadow color format — { color: '#hex', opacity: 0.08 } — not an {r,g,b,a} object.
shape.blurs is an array — shape.blurs = [{ type: 'layer-blur', value: 20 }], not a single object.
Page.findShapes() takes a criteria object — page.findShapes({ type: 'board' }), not a predicate function.
createComponent takes an array — createComponent([shape]), not createComponent(shape).
shape.x/shape.y for root-level shapes — Direct assignment does work for top-level boards. Only parented shapes require penpotUtils.setParentXY().
Write batch timeouts — Large batches time out silently, leaving partial updates. Keep execute_code calls to ~10 operations max.
Page switch async — openPage() followed by a write in the same call writes to the previously active page. Always use two calls.
Install / update
npx skills add ar27111994/penpot-mcp
Or manually: copy the penpot-mcp/ folder from github.com/ar27111994/penpot-mcp into your agent’s skills directory.
Compatible with Claude Code, Cursor, VS Code/Copilot, Codex/OpenCode, Amp, Cline, Windsurf, and any other MCP-compatible client.
Feedback and corrections welcome — especially if you hit API behaviour that differs from what’s documented here. The goal is for this to be accurate enough that you can rely on it without trial-and-error.
Quick follow-up update on the Penpot MCP skill:
I added a small guardrail pass around community plugins and MCP usage.
The short version: Penpot MCP is still the right default path for read/plan/write/verify workflows in a design file, but the skill now explicitly avoids assuming that MCP can enumerate, install, launch, or drive arbitrary installed community plugins. If a community plugin is relevant, agents should treat user-provided plugin inventories as context, ask for confirmation, and usually ask the user to run plugin-specific UI manually before re-inspecting the file via MCP.
I also added a specific caution for marketplace/browser-style plugins such as “Plugins list”: agents should not use those to browse/search/install plugins unless the user explicitly asks for plugin discovery or installation, so routine design tasks do not accidentally turn into plugin-search loops.
While doing that pass I also cleaned up a few older documentation review items in the examples: safer page lookup guards, token idempotency by name+type, prototype naming consistency, safer overlay wiring examples, and package dry-run hygiene.
PRs welcome — especially for new workflow recipes, additional platform templates, or corrections as the Penpot MCP API evolves. See CONTRIBUTING.md.
Please report security issues according to SECURITY.md.
Update: penpot-mcp skill v1.5.2 is now in a much more stable/public-ready state.
This is a community AI-agent skill for using Penpot through the official Penpot MCP Server. The goal is to help agents work with Penpot files more safely and consistently: inspect first, plan changes, write in small batches, and verify structurally instead of relying only on exports.
Recent improvements:
npx @penpot/mcp@stable usage./mcp vs /sse guidance for local MCP transport conflicts.Error: Already connected to a transport.execute_code, high_level_overview, penpot_api_info, export_shape, and import_image.penpot.createText(...)growType after resizeresize() instead of assigning read-only dimensionsInstall:
npx skills add ar27111994/penpot-mcp
Or manually copy the penpot-mcp/ folder into your agent’s skills directory.
Compatible with MCP-capable clients such as Claude Code, Cursor, VS Code/Copilot, Codex/OpenCode, Amp, Cline, Windsurf, Claude Desktop via mcp-remote, and similar clients.
I’d really appreciate feedback from people using this with real Penpot files:
Did the setup instructions work for your MCP client?
Did any Penpot API behavior differ from what the skill says?
Are there workflow recipes you’d like added? Design systems, prototyping, design-to-code, audits, tokens, components, etc.
Did the safety rules prevent bad agent behavior, or are there missing guardrails?
Issues and PRs are welcome:
https://github.com/ar27111994/penpot-mcp/issues
