@skilly-hand/skilly-hand 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -16,6 +16,22 @@ All notable changes to this project are documented in this file.
 ### Removed
 - _None._
 
+## [0.3.0] - 2026-04-03
+[View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.3.0)
+
+### Added
+- Added portable skill `figma-mcp-0to1` with setup, tool-selection, first-canvas, and troubleshooting documentation.
+
+### Changed
+- Synced generated documentation outputs in `AGENTS.md` and `catalog/README.md` to include the current 5-skill registry.
+- Refreshed root documentation to reflect current catalog composition and release/doc sync workflow.
+
+### Fixed
+- Updated catalog manifest test expectations for the 5-skill portable catalog.
+
+### Removed
+- _None._
+
 ## [0.1.1] - 2026-04-03
 [View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.1.1)
 

package/README.md

@@ -25,6 +25,7 @@
 - **Installs portable AI agent skills** into your project from a curated catalog
 - **Auto-detects your stack** and recommends relevant skills automatically
 - **Supports every major coding assistant** — Claude Code, OpenCode, Cursor, Copilot, Gemini, and Codex — from a single command
+- **Ships a curated core skill set** including orchestration, SDD workflow, and Figma MCP onboarding
 - **Preserves original agentic structures** in `source/legacy/` as a migration reference
 
 ---
@@ -50,11 +51,25 @@ npx skilly-hand
 
 ---
 
+## Current Portable Catalog
+
+The catalog currently includes:
+
+- `agents-root-orchestrator`
+- `figma-mcp-0to1`
+- `skill-creator`
+- `spec-driven-development`
+- `token-optimizer`
+
+See [catalog/README.md](./catalog/README.md) for generated skill metadata.
+
+---
+
 ## Release Workflow (npm)
 
 1. Confirm session: `npm whoami` (or `npm login`).
 2. Keep `CHANGELOG.md` up to date under `## [Unreleased]` as work lands.
-3. Regenerate derived catalog files when needed: `npm run build && npm run catalog:sync`.
+3. Regenerate derived files when needed: `npm run build && npm run catalog:sync && npm run agentic:self:sync`.
 4. Run publish gate: `npm run verify:publish`.
 5. Inspect package payload: `npm pack --dry-run --json`.
 6. Bump version intentionally: `npm version patch|minor|major` (this auto-rotates `CHANGELOG.md`, creates a dated release section, and inserts a version-specific npm link).

package/catalog/README.md

@@ -1,30 +1,13 @@
-<div align="center">
+# Portable Catalog
 
-# Portable Skill Catalog
+Published portable skills consumed by the `skilly-hand` CLI.
 
-*Published portable skills consumed by the `skilly-hand` CLI.*
+| Skill | Description | Tags | Installs For |
+| ----- | ----------- | ---- | ------------ |
+| `agents-root-orchestrator` | Author root AGENTS.md as a Where/What/When orchestrator that routes tasks and skill invocation clearly. | core, workflow, orchestration | all |
+| `figma-mcp-0to1` | Guide users from Figma MCP installation and authentication through first canvas creation, with function-level tool coverage and operational recovery patterns. | figma, mcp, workflow, design | all |
+| `skill-creator` | Create and standardize AI skills with reusable structure, metadata rules, and templates. | core, workflow, authoring | all |
+| `spec-driven-development` | Plan, execute, and verify multi-step work through versioned specs with small, testable tasks. | core, workflow, planning | all |
+| `token-optimizer` | Classify task complexity and right-size reasoning depth, context gathering, and response detail to reduce wasted tokens. | core, workflow, efficiency | all |
 
-</div>
-
----
-
-## Skills
-
-| Skill | Description | Tags |
-| ----- | ----------- | ---- |
-| `agents-root-orchestrator` | Author root `AGENTS.md` as a Where/What/When orchestrator that routes tasks and skill invocation clearly. | `core` `workflow` `orchestration` |
-| `skill-creator` | Create and standardize AI skills with reusable structure, metadata rules, and templates. | `core` `workflow` `authoring` |
-| `spec-driven-development` | Plan, execute, and verify multi-step work through versioned specs with small, testable tasks. | `core` `workflow` `planning` |
-| `token-optimizer` | Classify task complexity and right-size reasoning depth, context gathering, and response detail to reduce wasted tokens. | `core` `workflow` `efficiency` |
-
----
-
-## Install a skill
-
-```bash
-npx skilly-hand install <skill-name>
-npx skilly-hand install agents-root-orchestrator
-```
-
-> [!NOTE]
-> Legacy source under `source/legacy/agentic-structure` is preserved as reference material and is **excluded from installation**.
+Legacy source remains under `source/legacy/agentic-structure` and is excluded from installation.

package/catalog/catalog-index.json

@@ -1,5 +1,6 @@
 [
   "agents-root-orchestrator",
+  "figma-mcp-0to1",
   "skill-creator",
   "spec-driven-development",
   "token-optimizer"

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

@@ -0,0 +1,69 @@
+# Figma MCP 0-to-1 Guide
+
+## When to Use
+
+Use this skill when:
+
+- You need to set up Figma MCP from scratch.
+- 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.
+
+Do not use this skill for:
+
+- Generic frontend implementation that does not require Figma MCP.
+- One-off code-only tasks with no design context.
+- Legacy repository-specific Figma pipelines that already define their own strict workflow.
+
+---
+
+## Routing Map
+
+Choose subskills by intent:
+
+| Intent | Subskill |
+| --- | --- |
+| Install and authenticate MCP connection | [agents/install-auth.md](agents/install-auth.md) |
+| Select exact function/tool and expected inputs | [agents/tool-function-catalog.md](agents/tool-function-catalog.md) |
+| Create first canvas output safely | [agents/canvas-creation-playbook.md](agents/canvas-creation-playbook.md) |
+| Recover from errors, limits, or drift | [agents/troubleshooting-ops.md](agents/troubleshooting-ops.md) |
+
+---
+
+## Standard Execution Sequence
+
+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.
+
+---
+
+## Core Rules
+
+- Prefer remote server for broadest feature coverage and write workflows.
+- 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.
+- For repeated team workflows, reuse prompts and config snippets from `assets/`.
+
+---
+
+## Key References
+
+- Full function matrix: [references/official-tools-matrix.md](references/official-tools-matrix.md)
+- Client setup snippets: [assets/client-config-snippets.md](assets/client-config-snippets.md)
+- Prompt starters: [assets/prompt-recipes.md](assets/prompt-recipes.md)
+
+---
+
+## Commands
+
+```bash
+# Codex CLI (manual remote setup)
+codex mcp add figma --url https://mcp.figma.com/mcp
+
+# Verify catalog integrity in this repository
+npm run catalog:check
+```

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

@@ -0,0 +1,54 @@
+# Canvas Creation Playbook
+
+## Goal
+
+Deliver a first successful Figma canvas result with low risk and clear verification.
+
+## Safe 0-to-1 Workflow
+
+1. **Create or choose file context**
+- New file path: call `create_new_file`.
+- Existing file path: confirm URL/node target and permissions.
+
+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**
+- Call `search_design_system` to reuse components/variables.
+- Optionally call `get_metadata` for structure baseline.
+
+4. **Perform first write step**
+- Use `use_figma` for a small, atomic action:
+- Create one frame.
+- Add one text node.
+- Apply one style/token decision.
+
+5. **Validate state**
+- Inspect with `get_metadata` or `get_screenshot`.
+- Confirm node IDs and visual result.
+
+6. **Iterate in small increments**
+- Add layout, spacing, variants, or additional sections in separate write steps.
+- Re-validate after each step.
+
+## Alternative First-Creation Flows
+
+### Diagram-first flow (FigJam)
+
+1. `create_new_file` (FigJam)
+2. `generate_diagram` from plain-language workflow description
+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
+
+## 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.

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

@@ -0,0 +1,54 @@
+# Install and Auth
+
+## Goal
+
+Get Figma MCP connected and authenticated, with a verified first tool call.
+
+## Server Modes
+
+| 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. |
+
+## Codex Setup
+
+### Preferred path (Figma app/plugin workflow)
+
+- Use the Figma app path if available in your Codex client.
+- Complete auth prompt flow and grant access.
+
+### Manual Codex CLI path
+
+```bash
+codex mcp add figma --url https://mcp.figma.com/mcp
+```
+
+When prompted, authenticate the server.
+
+## Other Common Clients (manual patterns)
+
+- 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).
+
+## Verification Checklist
+
+1. Confirm server appears in client MCP list.
+2. Run a low-risk probe:
+- 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.
+
+## 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."
+
+## 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.

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

@@ -0,0 +1,38 @@
+# Tool and Function Catalog
+
+## Goal
+
+Pick the smallest correct Figma MCP function for the task, with predictable inputs and output shape.
+
+## 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.
+3. Prefer read-first calls before write calls on unknown files.
+
+## Selection Rules
+
+- Need full style/layout context for implementation: `get_design_context`.
+- 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 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 code-connect lookup/update: `get_code_connect_map`, `add_code_connect_map`, suggestion/confirm functions.
+
+## Prompting Pattern
+
+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 Figma MCP `search_design_system` before creating any new component."
+- "Use Figma MCP `create_new_file`, then `use_figma` to add a first frame and typography style."
+
+## 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.
+- Desktop mode is valid for local selection-based extraction, but with narrower workflow coverage.

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

@@ -0,0 +1,54 @@
+# Troubleshooting and Recovery
+
+## Goal
+
+Recover quickly from Figma MCP setup and execution failures without compounding errors.
+
+## Decision Flow
+
+```text
+Failure observed?
+  -> Tools missing/not loading
+     -> Recheck MCP server config, restart client session, re-auth
+  -> Permission/resource error
+     -> 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
+  -> Write failure
+     -> Stop retries, inspect state with read tools, fix cause, retry scoped step
+```
+
+## Common Issues
+
+### Tools are not visible
+
+- Confirm server endpoint is correct.
+- Confirm MCP server is started in client.
+- Re-authenticate and restart client session.
+
+### Permission denied or inaccessible resources
+
+1. Validate Figma URL format and node id.
+2. Run `whoami` to verify authenticated account.
+3. Confirm authenticated user belongs to correct plan and has file access.
+
+### Rate limiting
+
+- Read-heavy calls are rate-limited by plan/seat.
+- Use smaller selections and fewer repeated reads.
+- Prefer `get_metadata` preflight before broad `get_design_context`.
+- Batch intent into fewer, targeted calls.
+
+### 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.
+
+## Scoped Retry Pattern
+
+1. Isolate the failed step.
+2. Run one diagnostic read call (`get_metadata` or `whoami`).
+3. Correct only the failing input.
+4. Retry that one step.
+5. Re-validate and continue.

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

@@ -0,0 +1,76 @@
+# Client Config Snippets
+
+## Remote Endpoint
+
+`https://mcp.figma.com/mcp`
+
+## Desktop Endpoint
+
+`http://127.0.0.1:3845/mcp`
+
+## Codex CLI (manual)
+
+```bash
+codex mcp add figma --url https://mcp.figma.com/mcp
+```
+
+## VS Code `mcp.json` (remote)
+
+```json
+{
+  "inputs": [],
+  "servers": {
+    "figma": {
+      "url": "https://mcp.figma.com/mcp",
+      "type": "http"
+    }
+  }
+}
+```
+
+## VS Code `mcp.json` (desktop)
+
+```json
+{
+  "servers": {
+    "figma-desktop": {
+      "type": "http",
+      "url": "http://127.0.0.1:3845/mcp"
+    }
+  }
+}
+```
+
+## Cursor MCP config (remote)
+
+```json
+{
+  "mcpServers": {
+    "figma": {
+      "url": "https://mcp.figma.com/mcp"
+    }
+  }
+}
+```
+
+## Claude Code (manual remote)
+
+```bash
+claude mcp add --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
+```
+
+## Gemini CLI
+
+```bash
+gemini extensions install https://github.com/figma/mcp-server-guide
+# then inside gemini CLI:
+# /mcp auth figma
+```

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

@@ -0,0 +1,34 @@
+# Prompt Recipes
+
+## Setup and Verification
+
+- "Set up Figma MCP remote server and verify with `whoami`."
+- "Use Figma MCP `whoami` and tell me which account and plans are active."
+
+## 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."
+
+## Design-System and Code Connect
+
+- "Use `search_design_system` to find an existing card and button component before creating anything new."
+- "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."
+
+## First Canvas Creation
+
+- "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."
+
+## 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."
+
+## 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."

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

@@ -0,0 +1,42 @@
+{
+  "id": "figma-mcp-0to1",
+  "title": "Figma MCP 0-to-1 Guide",
+  "description": "Guide users from Figma MCP installation and authentication through first canvas creation, with function-level tool coverage and operational recovery patterns.",
+  "portable": true,
+  "tags": ["figma", "mcp", "workflow", "design"],
+  "detectors": ["always"],
+  "detectionTriggers": ["manual"],
+  "installsFor": ["all"],
+  "agentSupport": ["codex", "claude", "cursor", "gemini", "copilot"],
+  "skillMetadata": {
+    "author": "skilly-hand",
+    "last-edit": "2026-04-03",
+    "license": "Apache-2.0",
+    "version": "1.0.0",
+    "changelog": "Added a complete Figma MCP setup-to-canvas guide with orchestrator subskills and full official tool matrix coverage; reduces onboarding ambiguity and improves first-run success rates; affects Figma MCP setup, tool selection, and troubleshooting workflows",
+    "auto-invoke": "Installing, configuring, or using Figma MCP from setup through first canvas creation",
+    "allowed-tools": [
+      "Read",
+      "Edit",
+      "Write",
+      "Glob",
+      "Grep",
+      "Bash",
+      "WebFetch",
+      "WebSearch",
+      "Task",
+      "SubAgent"
+    ]
+  },
+  "files": [
+    { "path": "SKILL.md", "kind": "instruction" },
+    { "path": "agents/install-auth.md", "kind": "instruction" },
+    { "path": "agents/tool-function-catalog.md", "kind": "instruction" },
+    { "path": "agents/canvas-creation-playbook.md", "kind": "instruction" },
+    { "path": "agents/troubleshooting-ops.md", "kind": "instruction" },
+    { "path": "assets/client-config-snippets.md", "kind": "asset" },
+    { "path": "assets/prompt-recipes.md", "kind": "asset" },
+    { "path": "references/official-tools-matrix.md", "kind": "reference" }
+  ],
+  "dependencies": []
+}

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

@@ -0,0 +1,49 @@
+# Official Figma MCP Tools Matrix (As of 2026-04-03)
+
+This matrix tracks the official Figma MCP tool/function set in current Figma documentation.
+
+## 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. |
+| `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. |
+| `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. |
+| `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. |
+
+## Rate-Limit Notes (Official)
+
+- Read tools are subject to seat/plan limits.
+- Officially documented exempt tools include:
+- `add_code_connect_map`
+- `generate_figma_design`
+- `whoami`
+
+## Practical Selection Heuristics
+
+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.
+
+## Sources
+
+- https://developers.figma.com/docs/figma-mcp-server/
+- 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/plans-access-and-permissions/
+- https://help.figma.com/hc/en-us/articles/32132100833559-Guide-to-the-Figma-MCP-server

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/skilly-hand",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "license": "CC-BY-NC-4.0",
   "type": "module",
   "publishConfig": {