openryoko 0.9.4-ryoko.2

package/template/migrations/0.7.3/files/CLAUDE.md

@@ -0,0 +1,127 @@
+# {{portalName}} — Operating Instructions
+
+You are {{portalName}}, the COO of the user's AI organization.
+<!-- NOTE: The COO name above is personalized during onboarding via POST /api/onboarding -->
+
+## Core Principles
+- Be proactive — suggest next steps, flag issues, take initiative
+- Be concise — lead with the answer, not the reasoning
+- Be capable — use the filesystem, run commands, call APIs, manage the system
+- Be honest — say clearly when you don't know something
+- Evolve — learn the user's preferences and update your knowledge files
+
+## Home Directory (~/.jinn/)
+- `config.yaml` — gateway configuration (hot-reloads)
+- `org/` — employee personas (YAML files)
+- `skills/` — reusable skill prompts (subdirectories with SKILL.md)
+- `docs/` — documentation and architecture
+- `knowledge/` — persistent knowledge about the user, their projects, preferences
+- `cron/` — scheduled job definitions
+- `sessions/` — session database
+- `CLAUDE.md` — these instructions (update when the user gives persistent feedback)
+
+## Self-Evolution
+When you learn something new about the user, write it to the appropriate knowledge file:
+- `knowledge/user-profile.md` — who the user is, their business, goals
+- `knowledge/preferences.md` — communication style, emoji usage, verbosity, tech preferences
+- `knowledge/projects.md` — active projects, tech stacks, status
+
+When the user corrects you or gives persistent feedback (e.g. "always do X", "never do Y"), update this file.
+You should become more useful with every interaction.
+
+## Skills
+Skills are markdown playbooks in `~/.jinn/skills/<skill-name>/SKILL.md`. Read and follow them step by step.
+
+Every SKILL.md requires YAML frontmatter with `name` and `description` fields — this is how engine CLIs discover skills. The gateway auto-syncs symlinks in `.claude/skills/` and `.agents/skills/` so engines find them as project-local skills.
+
+## Proactive Skill Discovery
+
+When you encounter a task that requires specialized domain knowledge or tooling you don't currently have:
+
+1. **Detect the gap** — You're asked to do something specific (iOS testing, browser automation, Terraform, etc.) and no installed skill covers it
+2. **Search silently** — Run `npx skills find <relevant keywords>` WITHOUT asking the user first. This is read-only, zero risk.
+3. **Evaluate results** — Filter by install count and relevance:
+   - 🟢 1000+ installs or known sources (vercel-labs, anthropics, microsoft) → suggest confidently
+   - 🟡 50-999 installs → suggest with install count context
+   - 🔴 <50 installs → mention but note low adoption
+4. **Suggest concisely** — Present top 1-3 results:
+   "🔍 Found a skill that could help: **skill-name** (N installs) — description. Install it?"
+5. **Install on approval** — Follow the find-and-install skill's instructions
+6. **Apply immediately** — Read the new SKILL.md and use it for the current task
+
+Do NOT ask permission to search. Searching is free and silent. Only ask before installing.
+
+## The Org System
+You manage AI employees defined in `~/.jinn/org/`. Each has a persona, rank, department, and engine.
+- Delegate tasks that fit an employee's role
+- Use boards (`board.json`) to track work: `todo` → `in_progress` → `done`
+- As executive, you have full visibility over all boards
+- Apply oversight levels when reviewing employee work: TRUST (relay directly), VERIFY (spot-check), THOROUGH (full review + multi-turn follow-ups)
+- When a department grows (3+ employees), promote a reliable senior to manager — managers handle their own delegation
+
+### Automatic employee coordination
+When you receive a task, **always assess whether it requires multiple employees** before starting. Don't wait for the user to tell you who to contact — check the org roster and match employees to the task proactively.
+
+- **Analyze first**: Break the task into sub-tasks and identify which employee(s) are needed
+- **Parallel when independent**: Spawn multiple child sessions simultaneously when sub-tasks don't depend on each other
+- **Serialize when dependent**: If employee A's output feeds into employee B's task, wait for A before spawning B
+- **Cross-reference**: Compare results from multiple employees before responding — look for contradictions, gaps, and insights that connect
+- **Follow up**: If results are incomplete or need revision, send corrections to the same child session
+- **Synthesize**: Give the user a unified answer, not a dump of each employee's raw output
+
+### Agent teams for multi-phase tasks
+When delegating a task with multiple independent phases or sub-tasks to an employee, instruct them in the prompt to use **agent teams** — parallel sub-agents that handle different parts of the work concurrently. Instead of "do A, then B, then C" sequentially, tell the employee to spawn agents for A, B, and C in parallel where there are no dependencies between them. This leverages the engine's native capabilities (Claude Code's Agent tool, Codex parallel execution) and dramatically speeds up multi-step work. Only use sequential ordering when one step genuinely depends on another's output.
+
+### Child Session Protocol (Async Notifications)
+
+When you delegate to an employee via a child session:
+
+1. **Spawn** the child session (`POST /api/sessions` with `parentSessionId`)
+2. **Tell the user** what you delegated and to whom
+3. **End your turn.** Do NOT poll, wait, sleep, or block.
+4. The gateway automatically notifies you when the employee replies.
+   You will receive a notification message like:
+   > 📩 Employee "name" replied in session {id}.
+   > Read the latest messages: GET /api/sessions/{id}?last=N
+5. When notified, **read only the latest messages** via the API (use `?last=N`
+   to avoid context pollution). Then decide:
+   - Send a follow-up (`POST /api/sessions/{id}/message`) → go to step 3
+   - Or do nothing — the conversation is complete
+6. **Never read the full conversation history** on every notification. Only read
+   the latest messages relevant to the current round.
+
+This protocol applies to ALL employee child sessions, not just specific ones.
+The gateway handles the notification plumbing — you just reply and stop.
+
+## Cron Jobs
+Defined in `~/.jinn/cron/jobs.json`. The gateway watches and auto-reloads on changes.
+
+### Delegation rule for cron jobs
+**NEVER** set an employee directly as the cron job target when the output needs COO review/filtering before reaching the user. The correct pattern:
+- Cron triggers **{{portalSlug}}** (COO)
+- {{portalName}} spawns a child session with the employee
+- {{portalName}} reviews the output, filters noise, and produces the final deliverable
+- Only the filtered result reaches the user
+
+Direct employee → user delivery is only acceptable for simple, no-review-needed tasks (e.g. a health check ping). Any analytical, reporting, or decision-informing output MUST flow through {{portalSlug}} first.
+
+## Self-Modification
+You can edit any file in `~/.jinn/`. The gateway watches for changes:
+- `config.yaml` changes → gateway reloads
+- `cron/jobs.json` changes → scheduler reloads
+- `org/` changes → employee registry rebuilds
+- `skills/` changes → symlinks in `.claude/skills/` and `.agents/skills/` re-synced
+
+## Slash Commands
+
+Users can type slash commands in chat. Each command has a skill playbook in `~/.jinn/skills/<command>/SKILL.md` that teaches you how to handle it.
+
+| Command | Usage | What happens |
+|---------|-------|-------------|
+| `/sync` | `/sync @employee-name` | You fetch the employee's recent conversation via the gateway API (`GET /api/sessions`), read through it, and respond with full awareness. See the sync skill for details. |
+| `/new` | `/new` | Starts a fresh chat session. |
+| `/status` | `/status` | Shows current session info. |
+
+## Conventions
+- YAML for personas/config, JSON for boards/cron, Markdown for skills/docs
+- kebab-case for all file and directory names

package/template/migrations/0.7.5/MIGRATION.md

@@ -0,0 +1,78 @@
+# Migration: 0.7.5 (File Attachments, Mobile Sidebar, Connector Improvements)
+
+## Summary
+
+Releases v0.3.1 through v0.7.5 include significant gateway and dashboard improvements but **no template file changes** beyond what was covered in migrations 0.3.0 and 0.7.3. This migration exists to bump the version stamp and document the feature additions.
+
+## Template files changed
+
+None. All changes in this range are gateway code, web dashboard, and runtime improvements.
+
+## Version bump
+
+Update `jinn.version` in `config.yaml` from the previous migration version to `"0.7.5"`.
+
+## Notable features added (no migration action needed)
+
+### v0.3.1 — macOS Sleep Prevention
+- Gateway runs `caffeinate` to prevent macOS from sleeping while active
+
+### v0.4.0 — Gateway-to-Gateway File Transfer
+- `POST /api/files/transfer` endpoint for remote file sharing between Jinn instances
+- Claude crash recovery with retry and session resume on restart
+
+### v0.5.0–v0.5.2 — Stability & Notifications
+- Kanban board wired to gateway API
+- System prompt token usage reduced ~70%
+- Browser push notifications and notification history
+- Agent interrupt on new message (v0.5.2)
+- 12+ bug fixes
+
+### v0.6.0 — New Connectors & Queue Management
+- Discord connector with channel routing
+- WhatsApp connector via Baileys with QR pairing
+- Persistent queue management with pause/resume
+- Portal UI redesign (chat sidebar, settings, session management)
+
+### v0.7.0 — Project Phoenix Dashboard
+- Complete dashboard overhaul with new layout and navigation
+
+### v0.7.2 — Session Delete Fix
+- Fixed crash when deleting sessions from the web UI
+
+### v0.7.3 — Stale Session Recovery
+- Fixed infinite retry loop from stale engine session IDs
+- Added `?last=N` message filtering to sessions API
+- (Template changes covered in 0.7.3 migration)
+
+### v0.7.4 — Onboarding Persistence
+- Onboarding wizard state persisted server-side (survives new browsers)
+
+### v0.7.5 — File Attachments & Polish
+- Drag & drop file attachments in chat
+- Collapsible sidebar toggle
+- Markdown-to-mrkdwn conversion for Slack and WhatsApp connectors
+- Mobile sidebar improvements
+
+## Optional config additions
+
+These config keys are supported but **not required** — the gateway uses sensible defaults:
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `connectors.discord.token` | string | _(unset)_ | Discord bot token (enable Discord connector) |
+| `connectors.discord.channels` | object | _(unset)_ | Channel ID → name mapping for Discord routing |
+| `connectors.whatsapp.enabled` | boolean | `false` | Enable WhatsApp connector |
+| `portal.onboarded` | boolean | `false` | Whether onboarding wizard has been completed |
+
+These are opt-in features. Only add them if you want to use Discord or WhatsApp connectors.
+
+## Merge instructions
+
+1. **Config**: Update `jinn.version` to `"0.7.5"`. No other config changes required.
+2. **No template file changes** — nothing to copy or merge.
+3. **Database**: Schema changes are handled automatically on gateway start.
+
+## Files
+
+No files directory — this migration is version-stamp only.

package/template/migrations/0.8.0/MIGRATION.md

@@ -0,0 +1,73 @@
+# Migration: 0.8.0 (Gemini CLI, Telegram, Keyboard Shortcuts, Session Rename)
+
+## Summary
+
+Major release adding a third AI engine (Gemini CLI), Telegram connector, keyboard shortcuts, inline session rename, employee picker, and numerous web dashboard improvements.
+
+## Template files changed
+
+None. All changes are gateway code, web dashboard, and runtime improvements.
+
+## Version bump
+
+Update `jinn.version` in `config.yaml` from `"0.7.8"` to `"0.8.0"`.
+
+## New features
+
+### Gemini CLI Engine
+- Third engine alongside Claude Code and Codex
+- Full streaming support, session resume, process management
+- Configure via `engines.gemini.enabled: true` in `config.yaml`
+- Requires `gemini` CLI installed (`npm install -g @anthropic-ai/gemini-cli` or equivalent)
+
+### Telegram Connector
+- Polling-based bot using `node-telegram-bot-api`
+- User allowlist (`allowFrom` config)
+- Markdown-to-Telegram format conversion
+- Configure via `connectors.telegram` in `config.yaml`
+
+### Keyboard Shortcuts (web)
+- Linear-style shortcut overlay (press `?` to see all)
+- `J`/`K` to navigate sessions, `/` to focus search, `N` for new chat
+- Shortcut hints displayed inline in the UI
+
+### Employee Picker (web)
+- Grouped, searchable employee picker when starting new chats
+- Vertical layout organized by department
+
+### Session Rename (web)
+- Inline rename via right-click context menu or hover menu
+- Cross-tab sync via WebSocket `session:updated` event
+- Backend validation (type check, trim, non-empty, 200-char max)
+
+### alwaysNotify Per-Employee
+- `alwaysNotify` field in employee YAML
+- `PATCH /api/org/employees/:name` endpoint to toggle from dashboard
+- Suppresses notification for quiet employees
+
+### Other improvements
+- Auto-focus chat input on new chat
+- Chat auto-scroll fix — no longer interrupts history reading
+- `jinn --version` reads from package.json (no more stale version)
+- `jinn migrate` fix for `--cwd` flag on Node.js
+- Mobile zoom prevention on input focus
+- Sidebar delete navigation and tab switching fixes
+
+## Optional config additions
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `engines.gemini.enabled` | boolean | `false` | Enable Gemini CLI engine |
+| `engines.gemini.model` | string | `"gemini-2.5-pro"` | Default Gemini model |
+| `connectors.telegram.botToken` | string | _(unset)_ | Telegram bot token |
+| `connectors.telegram.allowFrom` | string[] | _(unset)_ | Allowed Telegram usernames |
+
+## Merge instructions
+
+1. **Config**: Update `jinn.version` to `"0.8.0"`. Optionally add Gemini/Telegram config.
+2. **No template file changes** — nothing to copy or merge.
+3. **Database**: Schema changes are handled automatically on gateway start.
+
+## Files
+
+No files directory — this migration is version-stamp only.

package/template/migrations/0.9.0/MIGRATION.md

@@ -0,0 +1,82 @@
+# Migration: 0.9.0 (Hierarchical Org, Service Routing, Multi-Instance Connectors)
+
+## Summary
+
+Major release adding infinite-depth hierarchical org tree via `reportsTo` field, cross-department service routing with LCA-based path resolution, chain-of-command context injection, multi-instance connector support, and Homebrew formula.
+
+## Template files changed
+
+- `CLAUDE.md` — added hierarchy documentation (reportsTo, chain of command), cross-department service routing API docs
+- `AGENTS.md` — same hierarchy and service routing updates as CLAUDE.md
+- `skills/management/SKILL.md` — updated hiring (auto-detect reportsTo), firing (reassign direct reports), promotion (report reassignment)
+
+## Version bump
+
+Update `jinn.version` in `config.yaml` to `"0.9.0"`.
+
+## New features
+
+### Hierarchical Org Tree
+- Employees can declare `reportsTo: <employee-name>` in their YAML
+- Gateway resolves full tree automatically with smart defaults (infers hierarchy from rank when `reportsTo` is absent)
+- Supports infinite depth, cross-department reporting, cycle detection
+- Advisory delegation — hierarchy informs context prompts but never blocks direct access
+- Same-rank rule: employees of equal rank never implicitly report to each other
+
+### Cross-Department Service Routing
+- Employees can declare `provides` services in their YAML:
+  ```yaml
+  provides:
+    - name: code-review
+      description: "Review PRs and provide feedback"
+  ```
+- `GET /api/org/services` — list all available services across the org
+- `POST /api/org/cross-request` — route a service request to the provider, creating a session with a formatted brief
+- LCA (Lowest Common Ancestor) algorithm for routing path resolution
+- Manager chain tracking for audit/tracing
+- Collision handling: higher-ranked employee wins, alphabetical tiebreak
+
+### Chain-of-Command Context
+- Employee prompts now include rich chain-of-command section: department, manager (with rank), direct reports (with ranks), escalation path
+- Available services from other departments listed with API usage instructions
+- Replaces the old simple `reportsTo` / `directReports` lines
+
+### Multi-Instance Connectors (PR #23)
+- Connectors (Slack, Discord, etc.) can now run multiple instances with different configurations
+- Each instance gets its own channel mapping and credentials
+
+### Homebrew Formula (PR #33)
+- `brew install hristo2612/tap/jinn` now works
+- Includes Node.js dependency management
+
+## Employee YAML changes
+
+New optional fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `reportsTo` | `string \| string[]` | Who this employee reports to (primary parent used for hierarchy) |
+| `provides` | `ServiceDeclaration[]` | Services this employee provides to the org |
+
+Example:
+```yaml
+name: jimmy-dev
+displayName: Jimmy Dev
+rank: senior
+department: platform
+reportsTo: jimbo
+provides:
+  - name: code-review
+    description: "Review PRs and provide feedback"
+```
+
+## Merge instructions
+
+1. **Config**: Update `jinn.version` to `"0.9.0"`.
+2. **Template files**: Merge the updated `CLAUDE.md`, `AGENTS.md`, and `skills/management/SKILL.md` from the template. These contain new documentation sections — merge carefully with any user customizations.
+3. **Employee YAMLs**: Optionally add `reportsTo` and `provides` fields to employee definitions. The system works without them (smart defaults infer hierarchy from rank).
+4. **Database**: No schema changes — handled automatically on gateway start.
+
+## Files
+
+No files directory — template file updates should be merged manually or via AI.

package/template/skills/cron-manager/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: cron-manager
+description: Create, edit, delete, enable, disable, and list scheduled cron jobs
+---
+
+# Cron Manager Skill
+
+## Trigger
+
+This skill activates when the user wants to create, edit, delete, enable, disable, or list scheduled cron jobs.
+
+## Data File
+
+All cron jobs are stored in `~/.jinn/cron/jobs.json` as a JSON array of job objects. If the file does not exist, create it with an empty array `[]`.
+
+## CronJob Schema
+
+```json
+{
+  "id": "uuid-v4",
+  "name": "daily-standup-summary",
+  "enabled": true,
+  "schedule": "0 9 * * 1-5",
+  "timezone": "America/New_York",
+  "engine": "claude",
+  "model": "sonnet",
+  "employee": "project-manager",
+  "prompt": "Review all department boards and summarize progress since yesterday. Highlight blockers and upcoming deadlines.",
+  "delivery": {
+    "connector": "slack",
+    "channel": "#engineering-standup"
+  }
+}
+```
+
+Field details:
+- `id` — UUID v4, generated when creating the job
+- `name` — kebab-case human-readable identifier, must be unique across all jobs
+- `enabled` — boolean, whether the job is active
+- `schedule` — standard cron expression (minute hour day month weekday)
+- `timezone` — IANA timezone string (e.g., `America/New_York`, `Europe/London`, `UTC`)
+- `engine` — AI engine to run the job: `claude` or `codex`
+- `model` — model identifier (e.g., `sonnet`, `opus`, `o3`)
+- `employee` — optional, the employee persona to use (must match an employee name in the org)
+- `prompt` — the instruction to execute when the job fires
+- `delivery` — optional object specifying where to send output
+  - `connector` — the connector to use (e.g., `slack`, `discord`)
+  - `channel` — the target channel or destination
+
+## Operations
+
+### Creating a Job
+
+1. Read the current `~/.jinn/cron/jobs.json` (or initialize as `[]` if missing).
+2. Ask the user for the required fields: name, schedule, engine, model, and prompt.
+3. Ask about the timezone. Default to `UTC` if not specified.
+4. Ask about the employee persona to use. This is optional.
+5. **Always ask the user about the delivery channel** if they did not specify one. Explain that without delivery, the output will only be logged.
+6. **Delegation check**: If the job has delivery configured AND targets a non-{{portalSlug}} employee, warn the user. The correct pattern for reporting/analytical jobs is: target `{{portalSlug}}`, and include delegation instructions in the prompt (e.g. "Delegate to @employee-name: ..."). {{portalName}} reviews and filters the output before it reaches the delivery channel. Only simple, no-review tasks (e.g. health checks) should target employees directly with delivery.
+7. Generate a UUID for the `id` field.
+8. Set `enabled` to `true` by default.
+9. Append the new job object to the array.
+10. Write the updated array back to `~/.jinn/cron/jobs.json`.
+11. Confirm the creation and summarize the schedule in plain English.
+
+### Editing a Job
+
+1. Read `~/.jinn/cron/jobs.json`.
+2. Find the job by name or id.
+3. Show the current values to the user.
+4. Apply the requested changes.
+5. Write the updated array back.
+6. Confirm the changes.
+
+### Deleting a Job
+
+1. Read `~/.jinn/cron/jobs.json`.
+2. Find the job by name or id.
+3. Confirm deletion with the user (show job details).
+4. Remove the job from the array.
+5. Write the updated array back.
+6. Confirm deletion.
+
+### Enabling / Disabling a Job
+
+1. Read `~/.jinn/cron/jobs.json`.
+2. Find the job by name or id.
+3. Set `enabled` to `true` (enable) or `false` (disable).
+4. Write the updated array back.
+5. Confirm the status change.
+
+### Listing Jobs
+
+1. Read `~/.jinn/cron/jobs.json`.
+2. Display jobs in a readable format, grouped by enabled/disabled.
+3. Include name, schedule (with plain-English interpretation), timezone, engine, and delivery info.
+
+## Cron Schedule Reference
+
+The schedule field uses standard 5-field cron syntax:
+
+```
+┌───────────── minute (0-59)
+│ ┌───────────── hour (0-23)
+│ │ ┌───────────── day of month (1-31)
+│ │ │ ┌───────────── month (1-12)
+│ │ │ │ ┌───────────── day of week (0-7, 0 and 7 = Sunday)
+│ │ │ │ │
+* * * * *
+```
+
+Common examples:
+- `0 9 * * 1-5` — Every weekday at 9:00 AM
+- `0 0 * * *` — Every day at midnight
+- `*/15 * * * *` — Every 15 minutes
+- `0 9 * * 1` — Every Monday at 9:00 AM
+- `0 8,17 * * *` — Every day at 8:00 AM and 5:00 PM
+- `0 0 1 * *` — First day of every month at midnight
+- `30 14 * * 5` — Every Friday at 2:30 PM
+
+## Error Handling
+
+- If `jobs.json` is malformed, attempt to fix it. If unrecoverable, back it up as `jobs.json.bak` and start fresh with `[]`.
+- If a job name already exists when creating, warn the user and ask for a different name.
+- Validate the cron expression format before saving. Warn if the expression looks incorrect.
+- Validate that the timezone is a valid IANA timezone string.
+- If an employee is specified, verify it exists in the org directory.

package/template/skills/find-and-install/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: find-and-install
+description: Find and install skills from skills.sh when a capability gap is detected
+---
+
+# Find & Install Skills
+
+## Trigger
+
+This skill activates when you detect a capability gap that a community skill might fill, the user explicitly asks to find or install a skill and a task would benefit from a specialized skill you don't currently have
+
+## Searching for Skills
+
+Run a search using the skills CLI:
+
+```bash
+npx skills find [query]
+```
+
+Review the results and assess trust level before suggesting:
+
+- 🟢 **VERIFIED** (1000+ installs or known orgs like `vercel-labs`, `anthropics`, `microsoft`): Suggest confidently
+- 🟡 **COMMUNITY** (50–999 installs): Suggest with a note about the install count
+- 🔴 **UNKNOWN** (<50 installs): Show but warn the user — offer to preview the SKILL.md before installing
+
+## Installing a Skill
+
+Once the user approves (or for 🟢 VERIFIED skills when you're confident it fits):
+
+### Step 1: Install globally
+
+```bash
+npx skills add <owner/repo@skill> -g -y
+```
+
+This places files into `~/.claude/skills/<name>/` or `~/.agents/skills/<name>/`.
+
+### Step 2: Copy into {{portalSlug}} skills directory
+
+```bash
+cp -r ~/.claude/skills/<name>/ ~/.{{portalSlug}}/skills/<name>/
+```
+
+The {{portalName}} file watcher will detect the new directory and create the appropriate symlinks automatically.
+
+### Step 3: Update the skills manifest
+
+Read `~/.{{portalSlug}}/skills.json`, add the new skill entry, and write it back.
+
+The manifest format:
+
+```json
+{
+  "installed": {
+    "<name>": {
+      "source": "<owner/repo@skill>",
+      "installedAt": "<ISO 8601 timestamp>"
+    }
+  }
+}
+```
+
+### Step 4: Apply the skill immediately
+
+Read the newly installed `~/.{{portalSlug}}/skills/<name>/SKILL.md` and follow its instructions to complete the current task.
+
+## When No Skills Are Found
+
+If `npx skills find` returns no results:
+
+1. Offer to help the user directly with the task using your built-in capabilities
+2. Suggest creating a custom skill if this is a recurring need (use the `skill-creator` skill)
+
+## Examples
+
+**User asks to deploy to Vercel:**
+
+```bash
+npx skills find "vercel deploy"
+# → vercel-labs/ai-skills@vercel-deploy (🟢 VERIFIED, 5200 installs)
+npx skills add vercel-labs/ai-skills@vercel-deploy -g -y
+cp -r ~/.claude/skills/vercel-deploy/ ~/.{{portalSlug}}/skills/vercel-deploy/
+# → update skills.json → read SKILL.md → follow deploy instructions
+```
+
+**User asks for an obscure skill:**
+
+```bash
+npx skills find "arduino serial monitor"
+# → random-user/arduino-tools@serial-monitor (🔴 UNKNOWN, 12 installs)
+# → Warn user, offer to preview SKILL.md before installing
+```