@skilly-hand/skilly-hand 0.25.1 → 0.25.3

package/CHANGELOG.md

@@ -16,6 +16,36 @@ All notable changes to this project are documented in this file.
 ### Removed
 - _None._
 
+## [0.25.3] - 2026-05-01
+[View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.25.3)
+
+### Added
+- _None._
+
+### Changed
+- Refreshed the `figma-mcp-0to1` skill with current Figma MCP tools, setup commands, agent coverage notes, Make resources, and trusted workflow guidance.
+
+### Fixed
+- _None._
+
+### Removed
+- _None._
+
+## [0.25.2] - 2026-04-29
+[View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.25.2)
+
+### Added
+- _None._
+
+### Changed
+- Added mandatory optimizer and planning challenge gates to generated convention files so `token-optimizer`, `output-optimizer`, and `roaster` are consistently enforced across agent instruction targets.
+
+### Fixed
+- _None._
+
+### Removed
+- _None._
+
 ## [0.25.1] - 2026-04-27
 [View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.25.1)
 

package/catalog/skills/figma-mcp-0to1/SKILL.md

@@ -3,10 +3,10 @@ name: "figma-mcp-0to1"
 description: "Guide users from Figma MCP installation and authentication through first canvas creation, with function-level tool coverage and operational recovery patterns."
 skillMetadata:
   author: "skilly-hand"
-  last-edit: "2026-04-03"
+  last-edit: "2026-05-01"
   license: "Apache-2.0"
-  version: "1.0.1"
-  changelog: "Added allowed-modes metadata to declare figma-mcp-0to1 sub-agent routing targets; improves discoverability of install-auth, tool-function-catalog, canvas-creation-playbook, and troubleshooting-ops delegation modes; affects figma-mcp-0to1 manifest metadata"
+  version: "1.0.2"
+  changelog: "Refreshed Figma MCP tools, commands, permissions, Make resources, and agent-support notes against current Figma coverage; improves setup accuracy and 0-to-1 workflow reliability; affects figma-mcp-0to1 docs, references, assets, and metadata"
   auto-invoke: "Installing, configuring, or using Figma MCP from setup through first canvas creation"
   allowed-tools:
     - "Read"
@@ -30,6 +30,7 @@ Use this skill when:
 - You need a reliable path from connection to first successful canvas output.
 - You need to choose the right Figma MCP function for a task.
 - You need operational recovery for permission, auth, tool-loading, or rate-limit failures.
+- You need to understand which skilly-hand agents overlap with Figma-supported MCP clients.
 
 Do not use this skill for:
 
@@ -57,14 +58,17 @@ Choose subskills by intent:
 1. Set up server transport and authentication.
 2. Verify connectivity with a low-risk call (`whoami` on remote, or a read tool).
 3. Select the smallest tool that solves the immediate task.
-4. Run creation in short, validated steps (avoid large one-shot requests).
-5. If anything fails, use troubleshooting flow before retrying.
+4. For writes, inspect existing file/design-system context before creating new content.
+5. Run creation in short, validated steps (avoid large one-shot requests).
+6. If anything fails, use troubleshooting flow before retrying.
 
 ---
 
 ## Core Rules
 
 - Prefer remote server for broadest feature coverage and write workflows.
+- Treat official Figma MCP docs as the source of truth for official tools, supported clients, permissions, and limits.
+- Keep client-specific helpers separate from official Figma MCP tools.
 - Treat write actions as staged operations, not a single large operation.
 - Use link-based node targeting for reliable design-context extraction.
 - Keep a clear distinction between read context tools and write/canvas tools.
@@ -72,6 +76,18 @@ Choose subskills by intent:
 
 ---
 
+## Agent Coverage
+
+Figma MCP support and skilly-hand installation support are related but not identical:
+
+| Coverage | Agents or Clients | Guidance |
+| --- | --- | --- |
+| Figma-supported and skilly-hand-supported | `codex`, `claude`, `cursor`, `copilot` | Include concrete setup paths in this skill. |
+| Figma-supported but not skilly-hand-native | VS Code, Warp, Augment, Factory, Firebender | Mention as Figma-supported clients, but do not add skilly-hand install assumptions. |
+| skilly-hand-supported but not source-backed in current Figma docs | `gemini`, `antigravity`, `windsurf`, `trae` | Keep broad `agentSupport`; document that Figma-specific setup may require client documentation or manual MCP config. |
+
+---
+
 ## Key References
 
 - Full function matrix: [references/official-tools-matrix.md](references/official-tools-matrix.md)
@@ -86,6 +102,21 @@ Choose subskills by intent:
 # Codex CLI (manual remote setup)
 codex mcp add figma --url https://mcp.figma.com/mcp
 
+# Claude Code plugin setup
+claude plugin install figma@claude-plugins-official
+
+# Claude Code manual remote setup
+claude mcp add --transport http figma https://mcp.figma.com/mcp
+
+# Claude Code manual remote setup, user scope
+claude mcp add --scope user --transport http figma https://mcp.figma.com/mcp
+
+# Claude Code manual desktop setup
+claude mcp add --transport http figma-desktop http://127.0.0.1:3845/mcp
+
+# Cursor plugin setup
+/add-plugin figma
+
 # Verify catalog integrity in this repository
 npm run catalog:check
 ```

package/catalog/skills/figma-mcp-0to1/agents/canvas-creation-playbook.md

@@ -7,14 +7,17 @@ Deliver a first successful Figma canvas result with low risk and clear verificat
 ## Safe 0-to-1 Workflow
 
 1. **Create or choose file context**
-- New file path: call `create_new_file`.
+- New file path: run `whoami` if needed to obtain a plan/team context, then call `create_new_file`.
 - Existing file path: confirm URL/node target and permissions.
+- Live web UI path: use `generate_figma_design` to capture to a new file, existing file, or clipboard.
+- Make path: use MCP resources from a Figma Make link to fetch project/file context before implementation.
 
 2. **Verify identity and access**
 - Run `whoami` (remote) to confirm account/plan.
 - If access mismatch appears, stop and fix permissions first.
 
 3. **Read before write**
+- Use `get_libraries` if the Codex Figma plugin exposes it and library scope matters.
 - Call `search_design_system` to reuse components/variables.
 - Optionally call `get_metadata` for structure baseline.
 
@@ -23,6 +26,7 @@ Deliver a first successful Figma canvas result with low risk and clear verificat
 - Create one frame.
 - Add one text node.
 - Apply one style/token decision.
+- For FigJam, create or update one small board object such as a sticky, section, connector, or shape.
 
 5. **Validate state**
 - Inspect with `get_metadata` or `get_screenshot`.
@@ -36,19 +40,27 @@ Deliver a first successful Figma canvas result with low risk and clear verificat
 
 ### Diagram-first flow (FigJam)
 
-1. `create_new_file` (FigJam)
-2. `generate_diagram` from plain-language workflow description
-3. Validate diagram structure and labels
+1. Call `generate_diagram` from plain-language workflow description or Mermaid syntax.
+2. Let `generate_diagram` create a new FigJam file, or provide an existing FigJam file key.
+3. Validate diagram structure and labels.
 
 ### Code-to-canvas flow
 
-1. Ask client to start local app capture workflow
-2. Capture screen/element states to Figma
-3. Open generated file and validate generated layers
-4. Follow up with `use_figma` for cleanup/polish
+1. Ask client to start local app capture workflow.
+2. Use `generate_figma_design` to capture screen/element states to a new file, existing file, or clipboard.
+3. Open generated file and validate generated layers.
+4. Follow up with `use_figma` for cleanup/polish.
+
+### Make-to-code context flow
+
+1. Provide a valid Figma Make link.
+2. Use MCP resources to list available project files.
+3. Fetch only the files needed for the task.
+4. Implement or refine the production code using that Make context.
 
 ## Guardrails
 
 - Do not run large multi-section writes as the first operation.
 - Always return to read/verify tools after each write step.
 - If a write fails, use troubleshooting flow before retrying.
+- Do not call `create_new_file` before `generate_diagram`; diagrams can create their own FigJam file.

package/catalog/skills/figma-mcp-0to1/agents/install-auth.md

@@ -8,8 +8,8 @@ Get Figma MCP connected and authenticated, with a verified first tool call.
 
 | Mode | Endpoint | Recommended | Notes |
 | --- | --- | --- | --- |
-| Remote | `https://mcp.figma.com/mcp` | Yes | Broadest features, including write-to-canvas workflows. |
-| Desktop | `http://127.0.0.1:3845/mcp` | Only for special org/enterprise needs | Requires Figma desktop app + Dev Mode desktop MCP toggle. |
+| Remote | `https://mcp.figma.com/mcp` | Yes | Broadest feature coverage, including write-to-canvas, code-to-canvas, diagrams, and file creation. |
+| Desktop | `http://127.0.0.1:3845/mcp` | Only for local selection-based or special org needs | Requires Figma desktop app + Dev Mode desktop MCP toggle; narrower workflow coverage. |
 
 ## Codex Setup
 
@@ -26,15 +26,29 @@ codex mcp add figma --url https://mcp.figma.com/mcp
 
 When prompted, authenticate the server.
 
-## Other Common Clients (manual patterns)
+## Other Supported Client Paths
 
+Use concrete setup paths for agents that are both Figma-supported and skilly-hand-supported:
+
+- Claude Code plugin: `claude plugin install figma@claude-plugins-official`
+- Claude Code manual remote: `claude mcp add --transport http figma https://mcp.figma.com/mcp`
+- Claude Code user-scope remote: `claude mcp add --scope user --transport http figma https://mcp.figma.com/mcp`
+- Claude Code manual desktop: `claude mcp add --transport http figma-desktop http://127.0.0.1:3845/mcp`
+- Cursor plugin: `/add-plugin figma`
+- Cursor manual: add the remote or desktop endpoint in MCP settings.
+- Copilot: use the VS Code MCP route and enable GitHub Copilot in the client.
 - VS Code: add HTTP MCP server in `mcp.json` using the remote endpoint.
-- Cursor: add MCP server in MCP settings or use its Figma plugin flow.
-- Claude Code: `claude mcp add --transport http figma https://mcp.figma.com/mcp`.
-- Gemini CLI: install Figma extension from `figma/mcp-server-guide`, then run auth command in CLI.
 
 See exact snippets in [../assets/client-config-snippets.md](../assets/client-config-snippets.md).
 
+## Agent Coverage Notes
+
+| Coverage | Agents or Clients | Guidance |
+| --- | --- | --- |
+| Figma-supported and skilly-hand-supported | `codex`, `claude`, `cursor`, `copilot` | Use the commands and setup paths above. |
+| Figma-supported but not skilly-hand-native | VS Code, Warp, Augment, Factory, Firebender | Follow Figma/client setup docs; do not assume skilly-hand skill install paths. |
+| skilly-hand-supported but not source-backed in current Figma docs | `gemini`, `antigravity`, `windsurf`, `trae` | Keep install support, but verify Figma MCP setup through that client's docs or manual MCP config. |
+
 ## Verification Checklist
 
 1. Confirm server appears in client MCP list.
@@ -42,13 +56,16 @@ See exact snippets in [../assets/client-config-snippets.md](../assets/client-con
 - Remote: `whoami` (recommended)
 - Desktop-only contexts: `get_metadata` or `get_design_context` on a known node
 3. Confirm the authenticated user has access to the target Figma file.
+4. For write workflows, confirm the authenticated seat can edit the target file.
 
 ## First Prompt After Setup
 
 - "Use Figma MCP `whoami` and show which account is authenticated."
 - "Use Figma MCP `get_design_context` for this node URL and summarize dimensions, layout, and variables."
+- "Using this Figma file URL, inspect the current libraries before creating anything new."
 
 ## Notes
 
 - If tools do not appear, restart MCP client session and retry authentication.
 - If permissions fail, verify file sharing and plan seat alignment before retry.
+- If a client does not expose an official tool, check the active tool list before changing the workflow.

package/catalog/skills/figma-mcp-0to1/agents/tool-function-catalog.md

@@ -7,20 +7,23 @@ Pick the smallest correct Figma MCP function for the task, with predictable inpu
 ## Start Here
 
 1. Read [../references/official-tools-matrix.md](../references/official-tools-matrix.md).
-2. Identify whether task is read, write, design-system search, code-connect, or diagram.
+2. Identify whether task is read, write, design-system search, code-connect, diagram, live UI capture, or Make resource context.
 3. Prefer read-first calls before write calls on unknown files.
 
 ## Selection Rules
 
 - Need full style/layout context for implementation: `get_design_context`.
+- Need Figma Make project/file context: use MCP resources if the client supports resources.
 - Output too large or structure-first pass: `get_metadata` first, then targeted `get_design_context`.
 - Need variables/tokens only: `get_variable_defs`.
 - Need visual reference: `get_screenshot`.
 - Need FigJam extraction: `get_figjam`.
+- Need library discovery in Codex before a scoped search: `get_libraries` if the Codex Figma plugin exposes it.
 - Need design-system discovery before creating: `search_design_system`.
-- Need to write/create/update content: `use_figma` (remote write workflows).
-- Need new blank file: `create_new_file`.
-- Need Mermaid-to-FigJam: `generate_diagram`.
+- Need to write/create/update Figma Design or FigJam content: `use_figma` (remote write workflow; use `figma-use` skill when available).
+- Need first-time live web UI capture: `generate_figma_design`.
+- Need new blank file: `create_new_file` (requires plan/team context such as `planKey` in some clients).
+- Need Mermaid-to-FigJam: `generate_diagram` (creates its own FigJam file unless an existing FigJam file key is provided).
 - Need code-connect lookup/update: `get_code_connect_map`, `add_code_connect_map`, suggestion/confirm functions.
 
 ## Prompting Pattern
@@ -28,11 +31,15 @@ Pick the smallest correct Figma MCP function for the task, with predictable inpu
 Use direct tool-trigger language when selection is ambiguous:
 
 - "Use Figma MCP `get_metadata` first, then `get_design_context` only for the selected child nodes."
+- "Use `get_libraries` if available, then use Figma MCP `search_design_system` for the selected library."
 - "Use Figma MCP `search_design_system` before creating any new component."
+- "Use Figma MCP `generate_figma_design` to capture this live web UI to a new Figma file."
 - "Use Figma MCP `create_new_file`, then `use_figma` to add a first frame and typography style."
+- "Use MCP resources from this Figma Make link and fetch only the files needed for implementation."
 
 ## Remote/Desktop Caveats
 
 - Remote-only flags are tracked in the matrix; confirm availability before relying on those functions.
-- Write-to-canvas flows are remote-first in current official guidance.
+- Write-to-canvas flows are remote-only in current official guidance.
 - Desktop mode is valid for local selection-based extraction, but with narrower workflow coverage.
+- Selection-based prompting works with the desktop server; remote workflows should use Figma file or node links.

package/catalog/skills/figma-mcp-0to1/agents/troubleshooting-ops.md

@@ -14,6 +14,8 @@ Failure observed?
      -> Verify link format, run whoami, confirm seat/plan and file access
   -> Rate-limit behavior
      -> Reduce read call volume, stage calls, wait/backoff, upgrade seat/plan if needed
+  -> Missing expected tool
+     -> Compare active client tools with official matrix, then choose a supported fallback
   -> Write failure
      -> Stop retries, inspect state with read tools, fix cause, retry scoped step
 ```
@@ -35,15 +37,27 @@ Failure observed?
 ### Rate limiting
 
 - Read-heavy calls are rate-limited by plan/seat.
+- Starter plan or View/Collab seats are limited to low monthly usage.
+- Dev/Full seats on Professional or Organization plans have higher daily usage.
+- Enterprise Dev/Full seats have the highest documented daily usage.
+- Officially documented exempt tools include `add_code_connect_map`, `generate_figma_design`, and `whoami`.
 - Use smaller selections and fewer repeated reads.
 - Prefer `get_metadata` preflight before broad `get_design_context`.
 - Batch intent into fewer, targeted calls.
 
+### Missing expected tools
+
+- Official Figma MCP tools may not be exposed by every client plugin surface.
+- Client-specific helpers, such as Codex `get_libraries`, are not official substitutes for every client.
+- Prefer a documented fallback rather than forcing an unavailable tool.
+
 ### Write step errors
 
 - Do not immediately retry the exact same large request.
 - Split into smaller write actions.
 - Verify partial outcomes using read tools before next step.
+- For `create_new_file`, ensure a plan/team context is available.
+- For `generate_diagram`, do not pre-create a blank FigJam file unless adding to an existing file is the explicit goal.
 
 ## Scoped Retry Pattern
 

package/catalog/skills/figma-mcp-0to1/assets/client-config-snippets.md

@@ -14,6 +14,37 @@
 codex mcp add figma --url https://mcp.figma.com/mcp
 ```
 
+## Codex App
+
+Use the Figma plugin/app install path in Codex when available, then complete the OAuth authentication flow.
+
+## Claude Code Plugin
+
+```bash
+claude plugin install figma@claude-plugins-official
+```
+
+## Claude Code (manual remote)
+
+```bash
+claude mcp add --transport http figma https://mcp.figma.com/mcp
+claude mcp list
+```
+
+## Claude Code (manual remote, user scope)
+
+```bash
+claude mcp add --scope user --transport http figma https://mcp.figma.com/mcp
+claude mcp list
+```
+
+## Claude Code (manual desktop)
+
+```bash
+claude mcp add --transport http figma-desktop http://127.0.0.1:3845/mcp
+claude mcp list
+```
+
 ## VS Code `mcp.json` (remote)
 
 ```json
@@ -53,24 +84,38 @@ codex mcp add figma --url https://mcp.figma.com/mcp
 }
 ```
 
-## Claude Code (manual remote)
+## Cursor Plugin
 
 ```bash
-claude mcp add --transport http figma https://mcp.figma.com/mcp
-claude mcp list
+/add-plugin figma
 ```
 
-## Claude Code (manual desktop)
+## Cursor MCP config (desktop)
 
-```bash
-claude mcp add --transport http figma-desktop http://127.0.0.1:3845/mcp
-claude mcp list
+```json
+{
+  "mcpServers": {
+    "figma-desktop": {
+      "url": "http://127.0.0.1:3845/mcp"
+    }
+  }
+}
 ```
 
-## Gemini CLI
+## Other Desktop MCP Config
 
-```bash
-gemini extensions install https://github.com/figma/mcp-server-guide
-# then inside gemini CLI:
-# /mcp auth figma
+```json
+{
+  "mcpServers": {
+    "figma-desktop": {
+      "url": "http://127.0.0.1:3845/mcp"
+    }
+  }
+}
 ```
+
+## Agent Coverage Notes
+
+- Figma-supported and skilly-hand-supported: `codex`, `claude`, `cursor`, `copilot`.
+- Figma-supported but not skilly-hand-native: VS Code, Warp, Augment, Factory, Firebender.
+- skilly-hand-supported but not source-backed in current Figma docs: `gemini`, `antigravity`, `windsurf`, `trae`.

package/catalog/skills/figma-mcp-0to1/assets/prompt-recipes.md

@@ -4,31 +4,55 @@
 
 - "Set up Figma MCP remote server and verify with `whoami`."
 - "Use Figma MCP `whoami` and tell me which account and plans are active."
+- "Check whether this client exposes the Figma MCP tools I need before starting."
 
 ## Read Context
 
 - "Use `get_design_context` for this node URL and return layout, spacing, typography, and variables."
 - "Use `get_metadata` first, then call `get_design_context` only for the button and header nodes."
 - "Use `get_variable_defs` for this node and list token names with resolved values."
+- "Use `get_screenshot` for this node and compare it against the generated implementation."
+- "Use Figma MCP resources from this Figma Make link and fetch only the files needed for this component."
 
 ## Design-System and Code Connect
 
+- "Use `get_libraries` if available, then search only the relevant design libraries."
 - "Use `search_design_system` to find an existing card and button component before creating anything new."
+- "Use `search_design_system` to find primary color, typography, and spacing variables."
 - "Use `get_code_connect_map` for this node and show mapped source locations."
 - "Use `add_code_connect_map` to map this Figma node to my component path."
+- "Use `get_code_connect_suggestions`, then confirm mappings with `send_code_connect_mappings` if the suggestions are correct."
 
 ## First Canvas Creation
 
+- "Use `whoami` to choose the right plan, then use `create_new_file` to create a new design file named 'MCP First Canvas'."
 - "Use `create_new_file` to create a new design file named 'MCP First Canvas'."
 - "Use `use_figma` to create one frame, add one title text layer, and apply auto layout spacing."
 - "After the write, use `get_screenshot` to verify the result."
+- "Before writing, inspect the file and use `search_design_system` for existing components or variables."
+
+## Live UI Capture
+
+- "Start my local app and use `generate_figma_design` to capture the current screen into a new Figma file."
+- "Use `generate_figma_design` to capture this URL into the existing Figma file."
+- "Use `generate_figma_design` to capture this page to my clipboard."
 
 ## FigJam Flows
 
 - "Use `create_new_file` to create a new FigJam board for architecture planning."
 - "Use `generate_diagram` to create a sequence diagram for login and checkout flow."
+- "Use `generate_diagram` to add an ERD to this existing FigJam file."
+- "Use `use_figma` to organize this FigJam board into sections with stickies and connectors."
+- "Use `use_figma` to update this architecture diagram with a new service."
+
+## Agent Coverage
+
+- "For this agent, tell me whether Figma officially supports its MCP setup path and which command/config I should use."
+- "Compare this client's active Figma tools against the official Figma MCP matrix before choosing a workflow."
 
 ## Troubleshooting
 
 - "I got a permission error. Use `whoami` and tell me what to check next."
 - "I am rate-limited. Switch to a staged workflow with fewer `get_design_context` calls."
+- "This client does not expose `get_screenshot`. Choose the closest supported verification path."
+- "My `create_new_file` call failed. Check whether a plan key or team context is missing."

package/catalog/skills/figma-mcp-0to1/manifest.json

@@ -10,10 +10,10 @@
   "agentSupport": ["codex", "claude", "cursor", "gemini", "copilot", "antigravity", "windsurf", "trae"],
   "skillMetadata": {
     "author": "skilly-hand",
-    "last-edit": "2026-04-03",
+    "last-edit": "2026-05-01",
     "license": "Apache-2.0",
-    "version": "1.0.1",
-    "changelog": "Added allowed-modes metadata to declare figma-mcp-0to1 sub-agent routing targets; improves discoverability of install-auth, tool-function-catalog, canvas-creation-playbook, and troubleshooting-ops delegation modes; affects figma-mcp-0to1 manifest metadata",
+    "version": "1.0.2",
+    "changelog": "Refreshed Figma MCP tools, commands, permissions, Make resources, and agent-support notes against current Figma coverage; improves setup accuracy and 0-to-1 workflow reliability; affects figma-mcp-0to1 docs, references, assets, and metadata",
     "auto-invoke": "Installing, configuring, or using Figma MCP from setup through first canvas creation",
     "allowed-modes": [
       "install-auth",

package/catalog/skills/figma-mcp-0to1/references/official-tools-matrix.md

@@ -1,31 +1,56 @@
-# Official Figma MCP Tools Matrix (As of 2026-04-03)
+# Official Figma MCP Tools Matrix (As of 2026-05-01)
 
-This matrix tracks the official Figma MCP tool/function set in current Figma documentation.
+This matrix tracks the official Figma MCP tool/function set in current Figma documentation. Treat it as the source of truth for official tool names, supported file types, and remote-only status. Client-specific helpers are listed separately.
 
 ## Coverage Matrix
 
 | Tool | Primary Purpose | Typical Input | Supported File Types | Availability Notes |
 | --- | --- | --- | --- | --- |
-| `generate_figma_design` | Generate design layers from live web UI (code to canvas path) | URL/local app capture context | No file context required | Remote-only in official docs. |
-| `get_design_context` | Fetch rich design context for implementation | Figma URL or `fileKey` + `nodeId` | Figma Design | Read tool; use link-based node targeting. |
+| `generate_figma_design` | Generate editable design layers from live web UI | URL/local app capture context | Figma Design output | Remote-only; select clients only; can output to new file, existing file, or clipboard; exempt from standard read limits. |
+| `get_design_context` | Fetch rich design context for implementation | Figma URL or `fileKey` + `nodeId` | Figma Design, Figma Make | Read tool; remote server requires link-based node targeting; desktop can use selection-based prompts. |
 | `get_variable_defs` | Retrieve variable/token definitions | `fileKey` + `nodeId` | Figma Design | Best for token-only extraction. |
 | `get_code_connect_map` | Read existing Code Connect mappings | `fileKey` + `nodeId` | Figma Design | Use to inspect mapping before updates. |
 | `add_code_connect_map` | Add mapping from node to code component | `fileKey`, `nodeId`, source details | Figma Design | Write-style utility; exempt from read rate limits in docs. |
-| `get_screenshot` | Render node screenshot for visual verification | `fileKey` + `nodeId` | Figma Design | Useful verification after write steps. |
+| `get_screenshot` | Render node screenshot for visual verification | `fileKey` + `nodeId` | Figma Design, FigJam | Useful verification after write steps and for preserving visual fidelity. |
 | `create_design_system_rules` | Generate design-system rules prompt/scaffold | Framework/language context | No file context required | Use to enforce repeatable design-system workflows. |
 | `get_metadata` | Sparse XML structure (ids, names, hierarchy, bounds) | Selection or `fileKey` + `nodeId` | Figma Design | Preferred preflight for large contexts. |
 | `get_figjam` | Fetch FigJam metadata (and node visuals) | `fileKey` + `nodeId` | FigJam | FigJam-specific extraction. |
-| `generate_diagram` | Create FigJam diagram from Mermaid or natural language intent | Diagram description or Mermaid syntax | No file context required | Supports flowchart, gantt, state, sequence. |
+| `generate_diagram` | Create FigJam diagram from Mermaid or natural language intent | Diagram description or Mermaid syntax | No file context required | Remote-only; supports flowchart, gantt, state, sequence, architecture, and ERD workflows. |
 | `whoami` | Show authenticated Figma identity, plans, and seat types | None | No file context required | Remote-only in official docs; exempt from read rate limits. |
 | `get_code_connect_suggestions` | Suggest candidate node-to-code mappings | File context + repo context | Figma Design | Usually part of Code Connect workflows. |
 | `send_code_connect_mappings` | Confirm/persist mapping suggestions | Suggestions payload | Figma Design | Follow-up action after suggestion generation. |
-| `use_figma` | General-purpose write/edit/delete/inspect in Figma via Plugin API workflow | Task instructions and file context | Figma Design, FigJam | Write-to-canvas workflow path; remote-first guidance. |
-| `search_design_system` | Search libraries for components, variables, styles | Query text and optional type narrowing | Figma Design | Use before creating new artifacts. |
-| `create_new_file` | Create new blank Design or FigJam file | Name/type intent | No file context required | Good first step for 0-to-1 creation workflows. |
+| `use_figma` | General-purpose write/edit/delete/inspect via Plugin API workflow | Task instructions and file context | Figma Design, FigJam | Remote-only; default direct write/update path; best used with the `figma-use` skill when available. |
+| `search_design_system` | Search libraries for components, variables, styles | Query text and optional type narrowing | Figma Design | Remote-only; use before creating new artifacts when design-system reuse is relevant. |
+| `create_new_file` | Create new blank Design or FigJam file | File name, file type, plan context | No file context required | Remote-only; creates files in drafts or a project; requires plan/team context in some clients. |
+
+## Figma Make Resources
+
+Figma Make project context is exposed through MCP resources on clients that support MCP resources. Use a valid Figma Make link, let the client list available project files, and fetch only the files needed for the implementation task.
+
+## Codex Plugin Helpers
+
+The Codex Figma plugin may expose helper tools beyond the current official tools page. Keep these documented as client-specific helpers:
+
+| Helper | Purpose | Notes |
+| --- | --- | --- |
+| `get_libraries` | List libraries associated with a Figma file | Use before scoped `search_design_system`; not listed on the official Figma tools page as of this matrix date. |
+
+Some official Figma MCP tools may not be exposed by every client plugin surface. Prefer the active client's tool list over assumptions when executing.
+
+## Client and Agent Coverage
+
+| Coverage | Agents or Clients | Guidance |
+| --- | --- | --- |
+| Figma-supported and skilly-hand-supported | `codex`, `claude`, `cursor`, `copilot` | Include concrete setup paths and prompts in this skill. |
+| Figma-supported but not skilly-hand-native | VS Code, Warp, Augment, Factory, Firebender | Mention as Figma-supported clients; do not add skilly-hand install assumptions. |
+| skilly-hand-supported but not source-backed in current Figma docs | `gemini`, `antigravity`, `windsurf`, `trae` | Keep broad install support; advise manual MCP/client docs for Figma-specific setup. |
 
 ## Rate-Limit Notes (Official)
 
-- Read tools are subject to seat/plan limits.
+- Read tools are subject to seat/plan limits and per-minute limits.
+- Starter plan or View/Collab seats: up to 6 tool calls per month.
+- Professional or Organization with Dev/Full seat: up to 200 tool calls per day.
+- Enterprise with Dev/Full seat: up to 600 tool calls per day.
 - Officially documented exempt tools include:
 - `add_code_connect_map`
 - `generate_figma_design`
@@ -35,9 +60,11 @@ This matrix tracks the official Figma MCP tool/function set in current Figma doc
 
 1. Start with `whoami` when authentication or permissions are uncertain.
 2. Use `get_metadata` before `get_design_context` for large files.
-3. Use `search_design_system` before creating new components.
-4. Keep `use_figma` calls small and validate after each step.
-5. Use `get_screenshot` as final visual verification after edits.
+3. Use `get_libraries` where available, then `search_design_system` for scoped design-system reuse.
+4. Use `generate_figma_design` for first-time live web UI capture.
+5. Use `use_figma` for direct Figma Design or FigJam writes and updates.
+6. Keep `use_figma` calls small and validate after each step.
+7. Use `get_screenshot` as final visual verification after edits when available.
 
 ## Sources
 
@@ -45,5 +72,8 @@ This matrix tracks the official Figma MCP tool/function set in current Figma doc
 - https://developers.figma.com/docs/figma-mcp-server/tools-and-prompts/
 - https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/
 - https://developers.figma.com/docs/figma-mcp-server/local-server-installation/
+- https://developers.figma.com/docs/figma-mcp-server/write-to-canvas/
+- https://developers.figma.com/docs/figma-mcp-server/code-to-canvas/
+- https://developers.figma.com/docs/figma-mcp-server/bringing-make-context-to-your-agent/
 - https://developers.figma.com/docs/figma-mcp-server/plans-access-and-permissions/
 - https://help.figma.com/hc/en-us/articles/32132100833559-Guide-to-the-Figma-MCP-server

package/catalog/templates/AGENTS.template.md

@@ -16,6 +16,26 @@ This file is generated by `skilly-hand`.
 | ----- | ------- | ---- |
 {{skillsTable}}
 
+### Mandatory Skill Gate (Must Use / Must Read)
+
+This gate has global precedence and applies to every user interaction across all supported agent conventions/files.
+
+1. Always run `token-optimizer` first to classify complexity and set the minimum viable reasoning depth.
+2. Always run `output-optimizer` immediately after `token-optimizer` for response-shape control.
+3. `output-optimizer` mode policy:
+   - Default: use `step-brief` when there is no explicit mode or strong phrasing signal.
+   - Override: if user explicitly requests a mode (for example `mode: step-brief`), that explicit mode wins.
+   - Persistence: keep the explicitly requested mode active until the user asks for a different mode.
+
+### Mandatory Planning Challenge Gate (Must Use / Must Read)
+
+This gate is mandatory whenever the user proposes, requests, or evaluates a plan of any kind.
+
+1. Always run `roaster` before agreeing with or executing a plan.
+2. Use `roaster` to critique assumptions, scope, sequencing, risks, and verification.
+3. Keep the critique constructive and actionable; target the plan, not the person.
+4. Skip only for emergencies, trivial one-step tasks, or sensitive contexts where roast tone would be inappropriate.
+
 ## When
 
 ### Auto-invoke Triggers

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/skilly-hand",
-  "version": "0.25.1",
+  "version": "0.25.3",
   "license": "CC-BY-NC-4.0",
   "type": "module",
   "repository": {

package/packages/catalog/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/catalog",
-  "version": "0.25.1",
+  "version": "0.25.3",
   "private": true,
   "type": "module"
 }

package/packages/catalog/src/index.js

@@ -543,9 +543,18 @@ export function renderAgentsMarkdown({ skills, detections, generatedAt, projectN
     "   - Override: if user explicitly requests a mode (for example `mode: step-brief`), that explicit mode wins.",
     "   - Persistence: keep the explicitly requested mode active until the user asks for a different mode.",
     "",
+    "### Mandatory Planning Challenge Gate (Must Use / Must Read)",
+    "",
+    "This gate is mandatory whenever the user proposes, requests, or evaluates a plan of any kind.",
+    "",
+    "1. Always run `roaster` before agreeing with or executing a plan.",
+    "2. Use `roaster` to critique assumptions, scope, sequencing, risks, and verification.",
+    "3. Keep the critique constructive and actionable; target the plan, not the person.",
+    "4. Skip only for emergencies, trivial one-step tasks, or sensitive contexts where roast tone would be inappropriate.",
+    "",
     "### Task Routing",
     "",
-    "**Mandatory-gate precedence:** apply the mandatory optimizer gate before task-routing chains below.",
+    "**Mandatory-gate precedence:** apply the mandatory optimizer gate first, then apply the mandatory planning challenge gate when the task includes planning.",
     "",
     "**SDD-first policy:** for feature delivery, bug fixes, or any multi-step implementation, start with `spec-driven-development` unless the task is clearly trivial and one-step.",
     "",

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/cli",
-  "version": "0.25.1",
+  "version": "0.25.3",
   "private": true,
   "type": "module",
   "bin": {

package/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/core",
-  "version": "0.25.1",
+  "version": "0.25.3",
   "private": true,
   "type": "module"
 }

package/packages/detectors/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/detectors",
-  "version": "0.25.1",
+  "version": "0.25.3",
   "private": true,
   "type": "module"
 }