@skilly-hand/skilly-hand 0.1.1 → 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,15 +51,30 @@ 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).
-7. Publish the root package: `npm publish` (or `npm publish --tag next` for prereleases).
+7. Publish with assisted 2FA flow: `npm run publish:otp` (or `npm run publish:next` for prereleases).
+   - The script runs the publish gate, asks for OTP with hidden input, and if left blank lets npm trigger your default security method.
 8. Smoke test after publish: `npx @skilly-hand/skilly-hand@<version> --help`.
 9. Verify npm metadata (README render, changelog, license, executable bin).
 

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.1.1",
+  "version": "0.3.0",
   "license": "CC-BY-NC-4.0",
   "type": "module",
   "publishConfig": {
@@ -30,6 +30,9 @@
     "test": "node --test tests/*.test.js",
     "verify:packlist": "node ./scripts/verify-packlist.mjs",
     "verify:publish": "npm run catalog:check && npm test && npm run verify:packlist",
+    "publish:prepare": "npm run verify:publish && npm pack --dry-run --json",
+    "publish:otp": "node ./scripts/publish-with-otp.mjs",
+    "publish:next": "node ./scripts/publish-with-otp.mjs --tag next",
     "prepublishOnly": "npm run verify:publish",
     "version": "node ./scripts/release-changelog.mjs",
     "changelog:release": "node ./scripts/release-changelog.mjs",

package/packages/cli/src/bin.js

@@ -2,8 +2,11 @@
 import path from "node:path";
 import { loadAllSkills } from "../../catalog/src/index.js";
 import { installProject, runDoctor, uninstallProject } from "../../core/src/index.js";
+import { createTerminalRenderer } from "../../core/src/terminal.js";
 import { detectProject } from "../../detectors/src/index.js";
 
+const renderer = createTerminalRenderer();
+
 function parseArgs(argv) {
   const args = [...argv];
   const positional = [];
@@ -11,11 +14,20 @@ function parseArgs(argv) {
     dryRun: false,
     yes: false,
     verbose: false,
+    json: false,
     agents: [],
     include: [],
     exclude: []
   };
 
+  function takeFlagValue(flagName) {
+    const value = args.shift();
+    if (!value || value.startsWith("-")) {
+      throw new Error(`Missing value for ${flagName}`);
+    }
+    return value;
+  }
+
   while (args.length > 0) {
     const token = args.shift();
     if (!token.startsWith("-")) {
@@ -26,10 +38,11 @@ function parseArgs(argv) {
     if (token === "--dry-run") flags.dryRun = true;
     else if (token === "--yes" || token === "-y") flags.yes = true;
     else if (token === "--verbose" || token === "-v") flags.verbose = true;
-    else if (token === "--agent" || token === "-a") flags.agents.push(args.shift());
-    else if (token === "--cwd") flags.cwd = args.shift();
-    else if (token === "--include") flags.include.push(args.shift());
-    else if (token === "--exclude") flags.exclude.push(args.shift());
+    else if (token === "--json") flags.json = true;
+    else if (token === "--agent" || token === "-a") flags.agents.push(takeFlagValue(token));
+    else if (token === "--cwd") flags.cwd = takeFlagValue(token);
+    else if (token === "--include") flags.include.push(takeFlagValue(token));
+    else if (token === "--exclude") flags.exclude.push(takeFlagValue(token));
     else if (token === "--help" || token === "-h") flags.help = true;
     else throw new Error(`Unknown flag: ${token}`);
   }
@@ -37,57 +50,251 @@ function parseArgs(argv) {
   return { command: positional[0], flags };
 }
 
-function printHelp() {
-  console.log(`skilly-hand
-
-Usage:
-  npx skilly-hand [install]
-  npx skilly-hand detect
-  npx skilly-hand list
-  npx skilly-hand doctor
-  npx skilly-hand uninstall
-
-Flags:
-  --dry-run
-  --yes
-  --verbose
-  --agent <codex|claude|cursor|gemini|copilot>
-  --cwd <path>
-  --include <tag>
-  --exclude <tag>
-`);
+function buildHelpText() {
+  const usage = renderer.section("Usage", renderer.list([
+    "npx skilly-hand [install]",
+    "npx skilly-hand detect",
+    "npx skilly-hand list",
+    "npx skilly-hand doctor",
+    "npx skilly-hand uninstall"
+  ], { bullet: "-" }));
+
+  const flags = renderer.section("Flags", renderer.list([
+    "--dry-run                     Show install plan without writing files",
+    "--json                        Emit stable JSON output for automation",
+    "--yes, -y                     Reserved for future non-interactive confirmations",
+    "--verbose, -v                 Reserved for future debug detail",
+    "--agent, -a <name>            codex|claude|cursor|gemini|copilot (repeatable)",
+    "--cwd <path>                  Project root (defaults to current directory)",
+    "--include <tag>               Include only skills matching all tags",
+    "--exclude <tag>               Exclude skills matching any tag",
+    "--help, -h                    Show help"
+  ], { bullet: "-" }));
+
+  const examples = renderer.section("Examples", renderer.list([
+    "npx skilly-hand install --dry-run",
+    "npx skilly-hand detect --json",
+    "npx skilly-hand install --agent codex --agent claude",
+    "npx skilly-hand list --include workflow"
+  ], { bullet: "-" }));
+
+  return renderer.joinBlocks([
+    renderer.status("info", "skilly-hand", "Portable AI skill orchestration for coding assistants."),
+    usage,
+    flags,
+    examples
+  ]);
+}
+
+function detectionRows(detections) {
+  return detections.map((item) => ({
+    technology: item.technology,
+    confidence: item.confidence.toFixed(2),
+    reasons: item.reasons.join("; "),
+    recommended: item.recommendedSkillIds.join(", ")
+  }));
 }
 
-function printDetections(detections) {
+function renderDetections(detections) {
   if (detections.length === 0) {
-    console.log("No technology signals were detected.");
-    return;
+    return renderer.status("warn", "No technology signals were detected.", "Only core skills will be selected.");
   }
 
-  for (const item of detections) {
-    console.log(`- ${item.technology} (${item.confidence})`);
-    console.log(`  reasons: ${item.reasons.join("; ")}`);
-    console.log(`  recommended skills: ${item.recommendedSkillIds.join(", ")}`);
+  return renderer.table(
+    [
+      { key: "technology", header: "Technology" },
+      { key: "confidence", header: "Confidence" },
+      { key: "reasons", header: "Reasons" },
+      { key: "recommended", header: "Recommended Skills" }
+    ],
+    detectionRows(detections)
+  );
+}
+
+function renderSkillTable(skills) {
+  if (skills.length === 0) {
+    return renderer.status("warn", "No skills selected.");
   }
+
+  return renderer.table(
+    [
+      { key: "id", header: "Skill ID" },
+      { key: "title", header: "Title" },
+      { key: "tags", header: "Tags" }
+    ],
+    skills.map((skill) => ({
+      id: skill.id,
+      title: skill.title,
+      tags: skill.tags.join(", ")
+    }))
+  );
+}
+
+function printInstallResult(result, flags) {
+  const mode = flags.dryRun ? "dry-run" : "apply";
+  const preflight = renderer.section(
+    "Install Preflight",
+    renderer.kv([
+      ["Project", result.plan.cwd],
+      ["Install root", result.plan.installRoot],
+      ["Agents", result.plan.agents.join(", ") || "none"],
+      ["Include tags", flags.include.join(", ") || "none"],
+      ["Exclude tags", flags.exclude.join(", ") || "none"],
+      ["Mode", mode]
+    ])
+  );
+
+  const detections = renderer.section("Detected Technologies", renderDetections(result.plan.detections));
+  const skills = renderer.section("Skill Plan", renderSkillTable(result.plan.skills));
+
+  const status = result.applied
+    ? renderer.status("success", "Installation completed.", "Managed files and symlinks are in place.")
+    : renderer.status("info", "Dry run complete.", "No files were written.");
+
+  const nextSteps = result.applied
+    ? renderer.nextSteps([
+      "Review generated AGENTS and assistant instruction files.",
+      "Run `npx skilly-hand doctor` to validate installation health.",
+      "Use `npx skilly-hand uninstall` to restore backed-up files if needed."
+    ])
+    : renderer.nextSteps([
+      "Run `npx skilly-hand install` to apply this plan.",
+      "Adjust `--include` and `--exclude` tags to tune skill selection."
+    ]);
+
+  renderer.write(renderer.joinBlocks([preflight, detections, skills, status, nextSteps]));
+}
+
+function printDetectResult(cwd, detections) {
+  const summary = renderer.section(
+    "Detection Summary",
+    renderer.kv([
+      ["Project", cwd],
+      ["Signals found", String(detections.length)]
+    ])
+  );
+
+  const details = renderer.section("Findings", renderDetections(detections));
+  renderer.write(renderer.joinBlocks([summary, details]));
+}
+
+function printListResult(skills) {
+  const summary = renderer.section(
+    "Catalog Summary",
+    renderer.kv([["Skills available", String(skills.length)]])
+  );
+
+  const table = renderer.section(
+    "Skills",
+    renderer.table(
+      [
+        { key: "id", header: "Skill ID" },
+        { key: "title", header: "Title" },
+        { key: "tags", header: "Tags" },
+        { key: "agents", header: "Agents" }
+      ],
+      skills.map((skill) => ({
+        id: skill.id,
+        title: skill.title,
+        tags: skill.tags.join(", "),
+        agents: skill.agentSupport.join(", ")
+      }))
+    )
+  );
+
+  renderer.write(renderer.joinBlocks([summary, table]));
+}
+
+function printDoctorResult(result) {
+  const health = result.installed
+    ? renderer.status("success", "Installation detected.")
+    : renderer.status("warn", "No installation detected.");
+
+  const summary = renderer.section(
+    "Doctor Summary",
+    renderer.kv([
+      ["Project", result.cwd],
+      ["Installed", result.installed ? "yes" : "no"],
+      ["Catalog issues", String(result.catalogIssues.length)]
+    ])
+  );
+
+  const lock = result.lock
+    ? renderer.section(
+        "Lock Metadata",
+        renderer.kv([
+          ["Generated at", result.lock.generatedAt],
+          ["Agents", result.lock.agents.join(", ")],
+          ["Skills", result.lock.skills.join(", ")]
+        ])
+      )
+    : "";
+
+  const issues = result.catalogIssues.length
+    ? renderer.section("Catalog Issues", renderer.list(result.catalogIssues))
+    : renderer.section("Catalog Issues", renderer.status("success", "No catalog issues found."));
+
+  const probes = renderer.section(
+    "Project Probes",
+    renderer.table(
+      [
+        { key: "path", header: "Path" },
+        { key: "exists", header: "Exists" },
+        { key: "type", header: "Type" }
+      ],
+      result.fileStatus.map((item) => ({
+        path: item.path,
+        exists: item.exists ? "yes" : "no",
+        type: item.type || "-"
+      }))
+    )
+  );
+
+  renderer.write(renderer.joinBlocks([health, summary, lock, issues, probes]));
 }
 
-function printPlan(plan) {
-  console.log(`Project: ${plan.cwd}`);
-  console.log(`Install root: ${plan.installRoot}`);
-  console.log(`Agents: ${plan.agents.join(", ")}`);
-  console.log("Detected technologies:");
-  printDetections(plan.detections);
-  console.log("Skills to install:");
-  for (const skill of plan.skills) {
-    console.log(`- ${skill.id}: ${skill.title} [${skill.tags.join(", ")}]`);
+function printUninstallResult(result) {
+  if (result.removed) {
+    renderer.write(
+      renderer.joinBlocks([
+        renderer.status("success", "skilly-hand installation removed."),
+        renderer.nextSteps([
+          "Run `npx skilly-hand install` if you want to reinstall managed files.",
+          "Run `npx skilly-hand doctor` to confirm the project state."
+        ])
+      ])
+    );
+    return;
   }
+
+  renderer.write(
+    renderer.joinBlocks([
+      renderer.status("warn", "Nothing to uninstall.", result.reason),
+      renderer.nextSteps(["Run `npx skilly-hand install` to create a managed installation first."])
+    ])
+  );
 }
 
 async function main() {
   const { command, flags } = parseArgs(process.argv.slice(2));
 
   if (flags.help) {
-    printHelp();
+    if (flags.json) {
+      renderer.writeJson({
+        command: command || "install",
+        help: true,
+        usage: [
+          "npx skilly-hand [install]",
+          "npx skilly-hand detect",
+          "npx skilly-hand list",
+          "npx skilly-hand doctor",
+          "npx skilly-hand uninstall"
+        ]
+      });
+      return;
+    }
+
+    renderer.write(buildHelpText());
     return;
   }
 
@@ -95,29 +302,57 @@ async function main() {
   const effectiveCommand = command || "install";
 
   if (effectiveCommand === "detect") {
-    printDetections(await detectProject(cwd));
+    const detections = await detectProject(cwd);
+    if (flags.json) {
+      renderer.writeJson({
+        command: "detect",
+        cwd,
+        count: detections.length,
+        detections
+      });
+      return;
+    }
+    printDetectResult(cwd, detections);
     return;
   }
 
   if (effectiveCommand === "list") {
     const skills = await loadAllSkills();
-    for (const skill of skills) {
-      console.log(`- ${skill.id}: ${skill.title}`);
-      console.log(`  tags: ${skill.tags.join(", ")}`);
-      console.log(`  agents: ${skill.agentSupport.join(", ")}`);
+    if (flags.json) {
+      renderer.writeJson({
+        command: "list",
+        count: skills.length,
+        skills
+      });
+      return;
     }
+    printListResult(skills);
     return;
   }
 
   if (effectiveCommand === "doctor") {
     const result = await runDoctor(cwd);
-    console.log(JSON.stringify(result, null, 2));
+    if (flags.json) {
+      renderer.writeJson({
+        command: "doctor",
+        ...result
+      });
+      return;
+    }
+    printDoctorResult(result);
     return;
   }
 
   if (effectiveCommand === "uninstall") {
     const result = await uninstallProject(cwd);
-    console.log(result.removed ? "skilly-hand installation removed." : result.reason);
+    if (flags.json) {
+      renderer.writeJson({
+        command: "uninstall",
+        ...result
+      });
+      return;
+    }
+    printUninstallResult(result);
     return;
   }
 
@@ -130,15 +365,53 @@ async function main() {
       excludeTags: flags.exclude
     });
 
-    printPlan(result.plan);
-    console.log(result.applied ? "Installation completed." : "Dry run only; nothing was written.");
+    if (flags.json) {
+      renderer.writeJson({
+        command: "install",
+        applied: result.applied,
+        plan: result.plan,
+        lockPath: result.lockPath || null
+      });
+      return;
+    }
+
+    printInstallResult(result, flags);
     return;
   }
 
   throw new Error(`Unknown command: ${effectiveCommand}`);
 }
 
+const jsonRequested = process.argv.includes("--json");
+
 main().catch((error) => {
-  console.error(error.message);
+  const hint =
+    error.message.startsWith("Unknown command:")
+      ? "Run `npx skilly-hand --help` to see available commands."
+      : error.message.startsWith("Unknown flag:") || error.message.startsWith("Missing value")
+      ? "Check command flags with `npx skilly-hand --help`."
+      : "Retry with `--verbose` for expanded context if needed.";
+
+  if (jsonRequested) {
+    renderer.writeErrorJson({
+      ok: false,
+      error: {
+        what: "skilly-hand command failed",
+        why: error.message,
+        hint
+      }
+    });
+    process.exitCode = 1;
+    return;
+  }
+
+  renderer.writeError(
+    renderer.error({
+      what: "skilly-hand command failed",
+      why: error.message,
+      hint,
+      exitCode: 1
+    })
+  );
   process.exitCode = 1;
 });

package/packages/core/src/terminal.js

@@ -0,0 +1,196 @@
+const ANSI_PATTERN = /\x1b\[[0-9;]*m/g;
+
+function asString(value) {
+  if (value === null || value === undefined) return "";
+  return String(value);
+}
+
+function stripAnsi(value) {
+  return asString(value).replace(ANSI_PATTERN, "");
+}
+
+function padEndAnsi(value, width) {
+  const clean = stripAnsi(value);
+  if (clean.length >= width) return value;
+  return value + " ".repeat(width - clean.length);
+}
+
+function normalizeBooleanEnv(value) {
+  if (value === undefined || value === null) return null;
+  const normalized = String(value).trim().toLowerCase();
+  if (normalized === "" || normalized === "0" || normalized === "false" || normalized === "no") return false;
+  return true;
+}
+
+export function detectColorSupport({ env = process.env, stream = process.stdout } = {}) {
+  const noColor = normalizeBooleanEnv(env.NO_COLOR);
+  if (noColor) return false;
+
+  const forceColor = normalizeBooleanEnv(env.FORCE_COLOR);
+  if (forceColor === true) return true;
+  if (forceColor === false) return false;
+
+  if (!stream?.isTTY) return false;
+  if (env.CI) return false;
+  return true;
+}
+
+export function detectUnicodeSupport({ env = process.env, stream = process.stdout, platform = process.platform } = {}) {
+  if (!stream?.isTTY) return false;
+  if (env.TERM === "dumb") return false;
+  if (env.NO_UNICODE) return false;
+  if (platform === "win32") {
+    return Boolean(env.WT_SESSION || env.TERM_PROGRAM || env.ConEmuTask || env.ANSICON);
+  }
+  return true;
+}
+
+function createStyler(enabled) {
+  if (!enabled) {
+    const passthrough = (value) => asString(value);
+    return {
+      reset: passthrough,
+      bold: passthrough,
+      dim: passthrough,
+      cyan: passthrough,
+      green: passthrough,
+      yellow: passthrough,
+      red: passthrough,
+      magenta: passthrough
+    };
+  }
+
+  const wrap = (code) => (value) => `\u001b[${code}m${asString(value)}\u001b[0m`;
+  return {
+    reset: wrap("0"),
+    bold: wrap("1"),
+    dim: wrap("2"),
+    cyan: wrap("36"),
+    green: wrap("32"),
+    yellow: wrap("33"),
+    red: wrap("31"),
+    magenta: wrap("35")
+  };
+}
+
+function renderKeyValue(entries, style) {
+  if (!entries || entries.length === 0) return "";
+  const normalized = entries.map(([key, value]) => [asString(key), asString(value)]);
+  const width = normalized.reduce((max, [key]) => Math.max(max, key.length), 0);
+  return normalized
+    .map(([key, value]) => `${style.dim(padEndAnsi(key, width))} : ${value}`)
+    .join("\n");
+}
+
+function renderList(items, { bullet }) {
+  if (!items || items.length === 0) return "";
+  return items.map((item) => `${bullet} ${asString(item)}`).join("\n");
+}
+
+function renderTable(columns, rows) {
+  if (!columns || columns.length === 0) return "";
+  const header = columns.map((column) => column.header);
+  const matrix = [header, ...rows.map((row) => columns.map((column) => asString(row[column.key] ?? "")))];
+  const widths = header.map((_, index) =>
+    matrix.reduce((max, line) => Math.max(max, stripAnsi(line[index]).length), 0)
+  );
+
+  const headerLine = header.map((value, index) => padEndAnsi(value, widths[index])).join("  ");
+  const separatorLine = widths.map((width) => "-".repeat(Math.max(3, width))).join("  ");
+  const body = rows.map((row) =>
+    columns.map((column, index) => padEndAnsi(asString(row[column.key] ?? ""), widths[index])).join("  ")
+  );
+
+  return [headerLine, separatorLine, ...body].join("\n");
+}
+
+function joinBlocks(blocks) {
+  const filtered = blocks.map((block) => asString(block).trimEnd()).filter(Boolean);
+  if (filtered.length === 0) return "";
+  return filtered.join("\n\n");
+}
+
+export function createTerminalRenderer({
+  stdout = process.stdout,
+  stderr = process.stderr,
+  env = process.env,
+  platform = process.platform
+} = {}) {
+  const colorEnabled = detectColorSupport({ env, stream: stdout });
+  const unicodeEnabled = detectUnicodeSupport({ env, stream: stdout, platform });
+  const style = createStyler(colorEnabled);
+  const symbols = unicodeEnabled
+    ? { info: "i", success: "✓", warn: "!", error: "x", bullet: "•", section: "■" }
+    : { info: "i", success: "+", warn: "!", error: "x", bullet: "-", section: "#" };
+
+  const statusStyles = {
+    info: style.cyan,
+    success: style.green,
+    warn: style.yellow,
+    error: style.red
+  };
+
+  const renderer = {
+    colorEnabled,
+    unicodeEnabled,
+    symbols,
+    style,
+    json(value) {
+      return JSON.stringify(value, null, 2);
+    },
+    section(title, body = "") {
+      const heading = `${style.cyan(symbols.section)} ${style.bold(asString(title))}`;
+      const bodyText = asString(body).trimEnd();
+      return bodyText ? `${heading}\n${bodyText}` : heading;
+    },
+    kv(entries) {
+      return renderKeyValue(entries, style);
+    },
+    list(items, options = {}) {
+      return renderList(items, { bullet: options.bullet || symbols.bullet });
+    },
+    table(columns, rows) {
+      return renderTable(columns, rows);
+    },
+    status(level, message, detail = "") {
+      const applied = statusStyles[level] || ((value) => value);
+      const icon = symbols[level] || symbols.info;
+      const main = `${applied(icon)} ${asString(message)}`;
+      if (!detail) return main;
+      return `${main}\n${style.dim("  " + asString(detail))}`;
+    },
+    summary(title, items = []) {
+      return renderer.section(title, renderer.list(items));
+    },
+    nextSteps(steps = []) {
+      if (!steps.length) return "";
+      return renderer.section("Next Steps", renderer.list(steps));
+    },
+    error({ what = "Command failed", why = "", hint = "", exitCode = 1 } = {}) {
+      const blocks = [
+        renderer.status("error", what),
+        why ? renderer.kv([["Why", why]]) : "",
+        hint ? renderer.kv([["How to recover", hint]]) : "",
+        renderer.kv([["Exit code", asString(exitCode)]])
+      ];
+      return joinBlocks(blocks);
+    },
+    joinBlocks
+  };
+
+  return {
+    ...renderer,
+    write(block = "") {
+      if (block) stdout.write(`${block}\n`);
+    },
+    writeError(block = "") {
+      if (block) stderr.write(`${block}\n`);
+    },
+    writeJson(value) {
+      stdout.write(`${renderer.json(value)}\n`);
+    },
+    writeErrorJson(value) {
+      stderr.write(`${renderer.json(value)}\n`);
+    }
+  };
+}