npm - @elizaos/skills - Versions diffs - 2.0.0-alpha.3 - Mend

@elizaos/skills 2.0.0-alpha.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (371) hide show

package/skills/canvas/SKILL.md ADDED Viewed

@@ -0,0 +1,203 @@
+---
+name: canvas
+description: "Display HTML content on connected Otto nodes (Mac app, iOS, Android). Use for games, visualizations, dashboards, and interactive demos."
+---
+# Canvas Skill
+Display HTML content on connected Otto nodes (Mac app, iOS, Android).
+## Overview
+The canvas tool lets you present web content on any connected node's canvas view. Great for:
+- Displaying games, visualizations, dashboards
+- Showing generated HTML content
+- Interactive demos
+## How It Works
+### Architecture
+```
+┌─────────────────┐     ┌──────────────────┐     ┌─────────────┐
+│  Canvas Host    │────▶│   Node Bridge    │────▶│  Node App   │
+│  (HTTP Server)  │     │  (TCP Server)    │     │ (Mac/iOS/   │
+│  Port 18793     │     │  Port 18790      │     │  Android)   │
+└─────────────────┘     └──────────────────┘     └─────────────┘
+```
+1. **Canvas Host Server**: Serves static HTML/CSS/JS files from `canvasHost.root` directory
+2. **Node Bridge**: Communicates canvas URLs to connected nodes
+3. **Node Apps**: Render the content in a WebView
+### Tailscale Integration
+The canvas host server binds based on `gateway.bind` setting:
+| Bind Mode  | Server Binds To     | Canvas URL Uses            |
+| ---------- | ------------------- | -------------------------- |
+| `loopback` | 127.0.0.1           | localhost (local only)     |
+| `lan`      | LAN interface       | LAN IP address             |
+| `tailnet`  | Tailscale interface | Tailscale hostname         |
+| `auto`     | Best available      | Tailscale > LAN > loopback |
+**Key insight:** The `canvasHostHostForBridge` is derived from `bridgeHost`. When bound to Tailscale, nodes receive URLs like:
+```
+http://<tailscale-hostname>:18793/__otto__/canvas/<file>.html
+```
+This is why localhost URLs don't work - the node receives the Tailscale hostname from the bridge!
+## Actions
+| Action     | Description                          |
+| ---------- | ------------------------------------ |
+| `present`  | Show canvas with optional target URL |
+| `hide`     | Hide the canvas                      |
+| `navigate` | Navigate to a new URL                |
+| `eval`     | Execute JavaScript in the canvas     |
+| `snapshot` | Capture screenshot of canvas         |
+## Configuration
+In `~/.otto/otto.json`:
+```json
+{
+  "canvasHost": {
+    "enabled": true,
+    "port": 18793,
+    "root": "/Users/you/clawd/canvas",
+    "liveReload": true
+  },
+  "gateway": {
+    "bind": "auto"
+  }
+}
+```
+### Live Reload
+When `liveReload: true` (default), the canvas host:
+- Watches the root directory for changes (via chokidar)
+- Injects a WebSocket client into HTML files
+- Automatically reloads connected canvases when files change
+Great for development!
+## Workflow
+### 1. Create HTML content
+Place files in the canvas root directory (default `~/clawd/canvas/`):
+```bash
+cat > ~/clawd/canvas/my-game.html << 'HTML'
+<!DOCTYPE html>
+<html>
+<head><title>My Game</title></head>
+<body>
+  <h1>Hello Canvas!</h1>
+</body>
+</html>
+HTML
+```
+### 2. Find your canvas host URL
+Check how your gateway is bound:
+```bash
+cat ~/.otto/otto.json | jq '.gateway.bind'
+```
+Then construct the URL:
+- **loopback**: `http://127.0.0.1:18793/__otto__/canvas/<file>.html`
+- **lan/tailnet/auto**: `http://<hostname>:18793/__otto__/canvas/<file>.html`
+Find your Tailscale hostname:
+```bash
+tailscale status --json | jq -r '.Self.DNSName' | sed 's/\.$//'
+```
+### 3. Find connected nodes
+```bash
+otto nodes list
+```
+Look for Mac/iOS/Android nodes with canvas capability.
+### 4. Present content
+```
+canvas action:present node:<node-id> target:<full-url>
+```
+**Example:**
+```
+canvas action:present node:mac-63599bc4-b54d-4392-9048-b97abd58343a target:http://peters-mac-studio-1.sheep-coho.ts.net:18793/__otto__/canvas/snake.html
+```
+### 5. Navigate, snapshot, or hide
+```
+canvas action:navigate node:<node-id> url:<new-url>
+canvas action:snapshot node:<node-id>
+canvas action:hide node:<node-id>
+```
+## Debugging
+### White screen / content not loading
+**Cause:** URL mismatch between server bind and node expectation.
+**Debug steps:**
+1. Check server bind: `cat ~/.otto/otto.json | jq '.gateway.bind'`
+2. Check what port canvas is on: `lsof -i :18793`
+3. Test URL directly: `curl http://<hostname>:18793/__otto__/canvas/<file>.html`
+**Solution:** Use the full hostname matching your bind mode, not localhost.
+### "node required" error
+Always specify `node:<node-id>` parameter.
+### "node not connected" error
+Node is offline. Use `otto nodes list` to find online nodes.
+### Content not updating
+If live reload isn't working:
+1. Check `liveReload: true` in config
+2. Ensure file is in the canvas root directory
+3. Check for watcher errors in logs
+## URL Path Structure
+The canvas host serves from `/__otto__/canvas/` prefix:
+```
+http://<host>:18793/__otto__/canvas/index.html  → ~/clawd/canvas/index.html
+http://<host>:18793/__otto__/canvas/games/snake.html → ~/clawd/canvas/games/snake.html
+```
+The `/__otto__/canvas/` prefix is defined by `CANVAS_HOST_PATH` constant.
+## Tips
+- Keep HTML self-contained (inline CSS/JS) for best results
+- Use the default index.html as a test page (has bridge diagnostics)
+- The canvas persists until you `hide` it or navigate away
+- Live reload makes development fast - just save and it updates!
+- A2UI JSON push is WIP - use HTML files for now

package/skills/clawhub/SKILL.md ADDED Viewed

@@ -0,0 +1,77 @@
+---
+name: clawhub
+description: Use the ClawHub CLI to search, install, update, and publish agent skills from clawhub.com. Use when you need to fetch new skills on the fly, sync installed skills to latest or a specific version, or publish new/updated skill folders with the npm-installed clawhub CLI.
+metadata:
+  {
+    "otto":
+      {
+        "requires": { "bins": ["clawhub"] },
+        "install":
+          [
+            {
+              "id": "node",
+              "kind": "node",
+              "package": "clawhub",
+              "bins": ["clawhub"],
+              "label": "Install ClawHub CLI (npm)",
+            },
+          ],
+      },
+  }
+---
+# ClawHub CLI
+Install
+```bash
+npm i -g clawhub
+```
+Auth (publish)
+```bash
+clawhub login
+clawhub whoami
+```
+Search
+```bash
+clawhub search "postgres backups"
+```
+Install
+```bash
+clawhub install my-skill
+clawhub install my-skill --version 1.2.3
+```
+Update (hash-based match + upgrade)
+```bash
+clawhub update my-skill
+clawhub update my-skill --version 1.2.3
+clawhub update --all
+clawhub update my-skill --force
+clawhub update --all --no-input --force
+```
+List
+```bash
+clawhub list
+```
+Publish
+```bash
+clawhub publish ./my-skill --slug my-skill --name "My Skill" --version 1.2.0 --changelog "Fixes + docs"
+```
+Notes
+- Default registry: https://clawhub.com (override with CLAWHUB_REGISTRY or --registry)
+- Default workdir: cwd (falls back to Otto workspace); install dir: ./skills (override with --workdir / --dir / CLAWHUB_WORKDIR)
+- Update command hashes local files, resolves matching version, and upgrades to latest unless --version is set

package/skills/coding-agent/SKILL.md ADDED Viewed

@@ -0,0 +1,284 @@
+---
+name: coding-agent
+description: Run Codex CLI, Claude Code, OpenCode, or Pi Coding Agent via background process for programmatic control.
+metadata:
+  {
+    "otto": { "emoji": "🧩", "requires": { "anyBins": ["claude", "codex", "opencode", "pi"] } },
+  }
+---
+# Coding Agent (bash-first)
+Use **bash** (with optional background mode) for all coding agent work. Simple and effective.
+## ⚠️ PTY Mode Required!
+Coding agents (Codex, Claude Code, Pi) are **interactive terminal applications** that need a pseudo-terminal (PTY) to work correctly. Without PTY, you'll get broken output, missing colors, or the agent may hang.
+**Always use `pty:true`** when running coding agents:
+```bash
+# ✅ Correct - with PTY
+bash pty:true command:"codex exec 'Your prompt'"
+# ❌ Wrong - no PTY, agent may break
+bash command:"codex exec 'Your prompt'"
+```
+### Bash Tool Parameters
+| Parameter    | Type    | Description                                                                 |
+| ------------ | ------- | --------------------------------------------------------------------------- |
+| `command`    | string  | The shell command to run                                                    |
+| `pty`        | boolean | **Use for coding agents!** Allocates a pseudo-terminal for interactive CLIs |
+| `workdir`    | string  | Working directory (agent sees only this folder's context)                   |
+| `background` | boolean | Run in background, returns sessionId for monitoring                         |
+| `timeout`    | number  | Timeout in seconds (kills process on expiry)                                |
+| `elevated`   | boolean | Run on host instead of sandbox (if allowed)                                 |
+### Process Tool Actions (for background sessions)
+| Action      | Description                                          |
+| ----------- | ---------------------------------------------------- |
+| `list`      | List all running/recent sessions                     |
+| `poll`      | Check if session is still running                    |
+| `log`       | Get session output (with optional offset/limit)      |
+| `write`     | Send raw data to stdin                               |
+| `submit`    | Send data + newline (like typing and pressing Enter) |
+| `send-keys` | Send key tokens or hex bytes                         |
+| `paste`     | Paste text (with optional bracketed mode)            |
+| `kill`      | Terminate the session                                |
+---
+## Quick Start: One-Shot Tasks
+For quick prompts/chats, create a temp git repo and run:
+```bash
+# Quick chat (Codex needs a git repo!)
+SCRATCH=$(mktemp -d) && cd $SCRATCH && git init && codex exec "Your prompt here"
+# Or in a real project - with PTY!
+bash pty:true workdir:~/Projects/myproject command:"codex exec 'Add error handling to the API calls'"
+```
+**Why git init?** Codex refuses to run outside a trusted git directory. Creating a temp repo solves this for scratch work.
+---
+## The Pattern: workdir + background + pty
+For longer tasks, use background mode with PTY:
+```bash
+# Start agent in target directory (with PTY!)
+bash pty:true workdir:~/project background:true command:"codex exec --full-auto 'Build a snake game'"
+# Returns sessionId for tracking
+# Monitor progress
+process action:log sessionId:XXX
+# Check if done
+process action:poll sessionId:XXX
+# Send input (if agent asks a question)
+process action:write sessionId:XXX data:"y"
+# Submit with Enter (like typing "yes" and pressing Enter)
+process action:submit sessionId:XXX data:"yes"
+# Kill if needed
+process action:kill sessionId:XXX
+```
+**Why workdir matters:** Agent wakes up in a focused directory, doesn't wander off reading unrelated files (like your soul.md 😅).
+---
+## Codex CLI
+**Model:** `gpt-5.2-codex` is the default (set in ~/.codex/config.toml)
+### Flags
+| Flag            | Effect                                             |
+| --------------- | -------------------------------------------------- |
+| `exec "prompt"` | One-shot execution, exits when done                |
+| `--full-auto`   | Sandboxed but auto-approves in workspace           |
+| `--yolo`        | NO sandbox, NO approvals (fastest, most dangerous) |
+### Building/Creating
+```bash
+# Quick one-shot (auto-approves) - remember PTY!
+bash pty:true workdir:~/project command:"codex exec --full-auto 'Build a dark mode toggle'"
+# Background for longer work
+bash pty:true workdir:~/project background:true command:"codex --yolo 'Refactor the auth module'"
+```
+### Reviewing PRs
+**⚠️ CRITICAL: Never review PRs in Otto's own project folder!**
+Clone to temp folder or use git worktree.
+```bash
+# Clone to temp for safe review
+REVIEW_DIR=$(mktemp -d)
+git clone https://github.com/user/repo.git $REVIEW_DIR
+cd $REVIEW_DIR && gh pr checkout 130
+bash pty:true workdir:$REVIEW_DIR command:"codex review --base origin/main"
+# Clean up after: trash $REVIEW_DIR
+# Or use git worktree (keeps main intact)
+git worktree add /tmp/pr-130-review pr-130-branch
+bash pty:true workdir:/tmp/pr-130-review command:"codex review --base main"
+```
+### Batch PR Reviews (parallel army!)
+```bash
+# Fetch all PR refs first
+git fetch origin '+refs/pull/*/head:refs/remotes/origin/pr/*'
+# Deploy the army - one Codex per PR (all with PTY!)
+bash pty:true workdir:~/project background:true command:"codex exec 'Review PR #86. git diff origin/main...origin/pr/86'"
+bash pty:true workdir:~/project background:true command:"codex exec 'Review PR #87. git diff origin/main...origin/pr/87'"
+# Monitor all
+process action:list
+# Post results to GitHub
+gh pr comment <PR#> --body "<review content>"
+```
+---
+## Claude Code
+```bash
+# With PTY for proper terminal output
+bash pty:true workdir:~/project command:"claude 'Your task'"
+# Background
+bash pty:true workdir:~/project background:true command:"claude 'Your task'"
+```
+---
+## OpenCode
+```bash
+bash pty:true workdir:~/project command:"opencode run 'Your task'"
+```
+---
+## Pi Coding Agent
+```bash
+# Install: npm install -g @mariozechner/pi-coding-agent
+bash pty:true workdir:~/project command:"pi 'Your task'"
+# Non-interactive mode (PTY still recommended)
+bash pty:true command:"pi -p 'Summarize src/'"
+# Different provider/model
+bash pty:true command:"pi --provider openai --model gpt-5-mini -p 'Your task'"
+```
+**Note:** Pi now has Anthropic prompt caching enabled (PR #584, merged Jan 2026)!
+---
+## Parallel Issue Fixing with git worktrees
+For fixing multiple issues in parallel, use git worktrees:
+```bash
+# 1. Create worktrees for each issue
+git worktree add -b fix/issue-78 /tmp/issue-78 main
+git worktree add -b fix/issue-99 /tmp/issue-99 main
+# 2. Launch Codex in each (background + PTY!)
+bash pty:true workdir:/tmp/issue-78 background:true command:"pnpm install && codex --yolo 'Fix issue #78: <description>. Commit and push.'"
+bash pty:true workdir:/tmp/issue-99 background:true command:"pnpm install && codex --yolo 'Fix issue #99: <description>. Commit and push.'"
+# 3. Monitor progress
+process action:list
+process action:log sessionId:XXX
+# 4. Create PRs after fixes
+cd /tmp/issue-78 && git push -u origin fix/issue-78
+gh pr create --repo user/repo --head fix/issue-78 --title "fix: ..." --body "..."
+# 5. Cleanup
+git worktree remove /tmp/issue-78
+git worktree remove /tmp/issue-99
+```
+---
+## ⚠️ Rules
+1. **Always use pty:true** - coding agents need a terminal!
+2. **Respect tool choice** - if user asks for Codex, use Codex.
+   - Orchestrator mode: do NOT hand-code patches yourself.
+   - If an agent fails/hangs, respawn it or ask the user for direction, but don't silently take over.
+3. **Be patient** - don't kill sessions because they're "slow"
+4. **Monitor with process:log** - check progress without interfering
+5. **--full-auto for building** - auto-approves changes
+6. **vanilla for reviewing** - no special flags needed
+7. **Parallel is OK** - run many Codex processes at once for batch work
+8. **NEVER start Codex in ~/clawd/** - it'll read your soul docs and get weird ideas about the org chart!
+9. **NEVER checkout branches in ~/Projects/otto/** - that's the LIVE Otto instance!
+---
+## Progress Updates (Critical)
+When you spawn coding agents in the background, keep the user in the loop.
+- Send 1 short message when you start (what's running + where).
+- Then only update again when something changes:
+  - a milestone completes (build finished, tests passed)
+  - the agent asks a question / needs input
+  - you hit an error or need user action
+  - the agent finishes (include what changed + where)
+- If you kill a session, immediately say you killed it and why.
+This prevents the user from seeing only "Agent failed before reply" and having no idea what happened.
+---
+## Auto-Notify on Completion
+For long-running background tasks, append a wake trigger to your prompt so Otto gets notified immediately when the agent finishes (instead of waiting for the next heartbeat):
+```
+... your task here.
+When completely finished, run this command to notify me:
+otto gateway wake --text "Done: [brief summary of what was built]" --mode now
+```
+**Example:**
+```bash
+bash pty:true workdir:~/project background:true command:"codex --yolo exec 'Build a REST API for todos.
+When completely finished, run: otto gateway wake --text \"Done: Built todos REST API with CRUD endpoints\" --mode now'"
+```
+This triggers an immediate wake event — Skippy gets pinged in seconds, not 10 minutes.
+---
+## Learnings (Jan 2026)
+- **PTY is essential:** Coding agents are interactive terminal apps. Without `pty:true`, output breaks or agent hangs.
+- **Git repo required:** Codex won't run outside a git directory. Use `mktemp -d && git init` for scratch work.
+- **exec is your friend:** `codex exec "prompt"` runs and exits cleanly - perfect for one-shots.
+- **submit vs write:** Use `submit` to send input + Enter, `write` for raw data without newline.
+- **Sass works:** Codex responds well to playful prompts. Try asking it for a haiku about your project.