Conversation
Add a new skill for installing and managing the Figma MCP server, which provides tools to interact with Figma designs directly from OpenHands using OAuth authentication. Co-authored-by: openhands <openhands@all-hands.dev>
The URL was incorrectly pointing to https://figma.com/mcp/sse but the official Figma documentation specifies https://mcp.figma.com/mcp Reference: https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/ Co-authored-by: openhands <openhands@all-hands.dev>
all-hands-bot
left a comment
all-hands-bot
left a comment
There was a problem hiding this comment.
🔴 Needs improvement: Critical inconsistency between installation commands and architectural issues with skill structure. See inline comments for details.
Co-authored-by: openhands <openhands@all-hands.dev>
all-hands-bot
left a comment
all-hands-bot
left a comment
There was a problem hiding this comment.
🔴 Needs improvement: Installation commands contradict each other and will break for users. The previous "fix" did not resolve this.
- Fix URL inconsistency: use official https://mcp.figma.com/mcp URL in both files - Update description to clarify read-only access - Apply progressive disclosure: slim SKILL.md to ~15 lines, move details to README.md - Remove content duplication between files - Add Usage and Troubleshooting sections to README.md Co-authored-by: openhands <openhands@all-hands.dev>
all-hands-bot
left a comment
all-hands-bot
left a comment
There was a problem hiding this comment.
🔴 Needs improvement: Same data consistency issue persists - installation commands don't match across the PR.
- Updated PR description to use correct installation command - Clarified in README.md that OAuth is handled automatically by the server at runtime, not via an installation flag - All installation commands now consistent across PR description, SKILL.md, and README.md Co-authored-by: openhands <openhands@all-hands.dev>
all-hands-bot
left a comment
all-hands-bot
left a comment
There was a problem hiding this comment.
🟡 Acceptable - Structure is clean and follows conventions. Core functionality looks solid, but documentation could be more precise about what actually happens when using this skill.
all-hands-bot
left a comment
all-hands-bot
left a comment
There was a problem hiding this comment.
🟡 Acceptable - Structure is clean and follows conventions. Core functionality looks solid, but documentation could be more precise about what actually happens when using this skill.
|
This should not be marked ready yet because it requires testing with oauth, which a human needs to do. |
all-hands-bot
left a comment
all-hands-bot
left a comment
There was a problem hiding this comment.
🟡 Acceptable - Clean structure, follows conventions. Two minor clarifications would improve user experience.
- Clarify why restart is required (MCP servers initialized at session startup) - Fix OAuth troubleshooting guidance (browser session, not re-running mcp add) Co-authored-by: openhands <openhands@all-hands.dev>
all-hands-bot
left a comment
all-hands-bot
left a comment
There was a problem hiding this comment.
🟡 Acceptable - Functional skill that follows repository conventions, but documentation has clarity gaps that will cause user confusion. The installation works, but users will struggle to understand the actual workflow.
all-hands-bot
left a comment
all-hands-bot
left a comment
There was a problem hiding this comment.
🟡 Acceptable - Clean structure that solves a real problem. Documentation over-emphasizes code generation when the tool has broader capabilities. See inline comments for specific improvements.
| The MCP server is link-based. To use it: | ||
|
|
||
| 1. In Figma, copy the link to a frame or layer (for example `https://www.figma.com/file/ABC123/MyDesign?node-id=1-2`) | ||
| 2. In OpenHands, prompt: `Generate a React component from this Figma frame: https://www.figma.com/file/ABC123/MyDesign?node-id=1-2` |
There was a problem hiding this comment.
🟡 Suggestion - Scope Mismatch: Your Usage section shows ONE use case (code generation: "Generate a React component"), but your capabilities list claims FOUR use cases (generate code, extract context, retrieve tokens, inspect properties).
Line 60 says "You can use the same pattern for other tasks" but this is hand-waving - show, don't tell. Users will assume this skill is ONLY for code generation unless you show them otherwise.
Suggestion: Add 2-3 concrete example prompts:
## Example Prompts
**Code generation:**
`Generate a React component from this Figma frame: https://www.figma.com/file/ABC123/MyDesign?node-id=1-2`
**Extract design tokens:**
`What colors and typography are defined in this Figma file: https://www.figma.com/file/ABC123/MyDesign`
**Inspect component structure:**
`Show me the component tree and layer hierarchy for this frame: https://www.figma.com/file/ABC123/MyDesign?node-id=1-2`If the skill actually can't do these things reliably, narrow your capabilities list to match what actually works.
|
|
||
| This adds the Figma MCP server to your OpenHands configuration. The first time OpenHands calls a Figma MCP tool, the server will open your browser and prompt you to authorize access with Figma OAuth. | ||
|
|
||
| **Note:** Restart your OpenHands session after installation to load the new MCP server. This is required because MCP servers are initialized at session startup - the server configuration is loaded once when OpenHands starts, so changes to `mcp.json` require a restart to take effect. |
There was a problem hiding this comment.
🟢 Nit - Verbosity: You say the same thing twice:
- "MCP servers are initialized at session startup"
- "the server configuration is loaded once when OpenHands starts"
These mean the same thing. The second clause adds no new information.
Simpler: "This is required because MCP servers are initialized at session startup."
(But honestly, explaining WHY helps users who wonder if they can skip the restart, so the verbosity is somewhat justified. Low priority.)
| openhands mcp add figma --transport http https://mcp.figma.com/mcp | ||
| ``` | ||
|
|
||
| You'll be prompted to authorize via Figma OAuth when first used. Restart your OpenHands session after installation. |
There was a problem hiding this comment.
🟡 Suggestion - Vague Timing: "when first used" - by whom? when exactly?
Your README is more precise: "The first time OpenHands calls a Figma MCP tool, the server will open your browser..."
Even in the brief SKILL.md, precision costs almost nothing:
| You'll be prompted to authorize via Figma OAuth when first used. Restart your OpenHands session after installation. | |
| You'll be prompted to authorize via Figma OAuth the first time OpenHands calls a Figma tool. Restart your OpenHands session after installation. |
| - **Generate implementation prompts from frames**: Ask OpenHands to read a Figma frame through MCP and generate React, HTML, or other code from the retrieved design data | ||
| - **Extract design context**: Pull in variables, components, and layout data | ||
| - **Retrieve design tokens**: Access colors, typography, and spacing values | ||
| - **Inspect layer properties**: Get detailed information about supported Figma nodes such as frames, components, instances, text, and shapes |
There was a problem hiding this comment.
🟢 Minor - Inconsistent Specificity: Your capability bullets mix concrete and vague language:
- Line 11: VERY specific - names frameworks (React, HTML)
- Line 12: Vague - what is "design context"? which "variables"?
- Line 13: Medium - mentions specific token types
- Line 14: Specific - lists node types
Pick a consistent level. Either:
- All high-level: "Generate code", "Extract design data", "Retrieve style tokens", "Inspect element properties"
- All concrete with examples
Mixing specificity is jarring. Not critical, but hurts polish.
4 participants
Summary
Adds a Figma MCP skill plus companion README documentation for installing the remote Figma MCP server and using it from OpenHands.
Fixes #81
Details
SKILL.mdshort and decision-oriented for progressive disclosureREADME.mdwith concrete installation, usage, and troubleshooting guidancemarketplaces/default.jsonTesting
Documentation/skill change - no automated tests were added.
Validation completed:
Claude Code CompatibilityGitHub Action: ✅ passedTestsGitHub Action: ✅ passedEvidence
Verification link: View conversation
Cannot be tested in current environment:
openhands mcp add figma --transport http https://mcp.figma.com/mcpGenerate a React component from this Figma frame: https://www.figma.com/file/ABC123/MyDesign?node-id=1-2Checklist