@elizaos/skills 2.0.0-alpha.3

package/README.md

@@ -0,0 +1,126 @@
+# @elizaos/skills
+
+Bundled skills and skill loading utilities for elizaOS agents.
+
+## Overview
+
+Skills are markdown files that provide specialized instructions for AI agents to perform specific tasks. Each skill contains:
+
+- **Frontmatter**: YAML metadata including name, description, and configuration
+- **Body**: Detailed instructions, examples, and references
+
+## Installation
+
+```bash
+npm install @elizaos/skills
+# or
+pnpm add @elizaos/skills
+```
+
+## Usage
+
+### Get Bundled Skills Path
+
+```typescript
+import { getSkillsDir } from "@elizaos/skills";
+
+const skillsPath = getSkillsDir();
+// Returns absolute path to bundled skills directory
+```
+
+### Load Skills
+
+```typescript
+import { loadSkills, loadSkillsFromDir } from "@elizaos/skills";
+
+// Load from all default locations (bundled + managed + project)
+const { skills, diagnostics } = loadSkills();
+
+// Load from a specific directory
+const result = loadSkillsFromDir({
+  dir: "/path/to/skills",
+  source: "custom",
+});
+```
+
+### Format for LLM Prompt
+
+```typescript
+import { formatSkillsForPrompt } from "@elizaos/skills";
+
+const prompt = formatSkillsForPrompt(skills);
+// Returns XML-formatted skills section for system prompt
+```
+
+### Build Command Specs
+
+```typescript
+import { loadSkillEntries, buildSkillCommandSpecs } from "@elizaos/skills";
+
+const entries = loadSkillEntries();
+const commands = buildSkillCommandSpecs(entries);
+// Returns array of command specs for chat interfaces
+```
+
+## Skill Discovery
+
+Skills are loaded from multiple locations in precedence order (later overrides earlier):
+
+1. **Bundled skills** - Included in this package (`skills/`)
+2. **Managed skills** - User-installed skills (`~/.elizaos/skills/`)
+3. **Project skills** - Project-local skills (`<cwd>/.elizaos/skills/`)
+4. **Explicit paths** - Via `skillPaths` option
+
+## Skill Format
+
+Skills are markdown files with YAML frontmatter:
+
+```markdown
+---
+name: my-skill
+description: A brief description of what this skill does
+primary-env: node
+required-bins:
+  - node
+  - npm
+---
+
+# My Skill
+
+Detailed instructions for the AI agent...
+```
+
+### Frontmatter Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | Skill name (should match directory name) |
+| `description` | string | Human-readable description (required) |
+| `disable-model-invocation` | boolean | If true, skill won't appear in prompts |
+| `user-invocable` | boolean | If false, can't be invoked via commands |
+| `primary-env` | string | Primary runtime (node, python, etc.) |
+| `required-os` | string[] | Required operating systems |
+| `required-bins` | string[] | Required binaries in PATH |
+| `required-env` | string[] | Required environment variables |
+
+## API Reference
+
+### Types
+
+- `Skill` - Loaded skill with metadata
+- `SkillFrontmatter` - Parsed frontmatter
+- `SkillEntry` - Full skill entry with all metadata
+- `LoadSkillsResult` - Result from loading skills
+
+### Functions
+
+- `getSkillsDir()` - Get bundled skills path
+- `loadSkills(options?)` - Load from all locations
+- `loadSkillsFromDir(options)` - Load from single directory
+- `loadSkillEntries(options?)` - Load with full metadata
+- `formatSkillsForPrompt(skills)` - Format for LLM prompt
+- `buildSkillCommandSpecs(entries)` - Build command specs
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@elizaos/skills",
+  "version": "2.0.0-alpha.3",
+  "description": "Bundled skills and skill loading utilities for elizaOS agents",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./skills": "./skills/",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "tsgo -p tsconfig.build.json",
+    "dev": "tsgo -p tsconfig.build.json --watch --preserveWatchOutput",
+    "test": "node --test --import tsx test/*.test.ts",
+    "lint": "bunx @biomejs/biome check --write ./src",
+    "lint:check": "bunx @biomejs/biome check ./src"
+  },
+  "files": [
+    "dist/**/*",
+    "skills/**/*",
+    "README.md"
+  ],
+  "keywords": [
+    "elizaos",
+    "skills",
+    "agent",
+    "ai",
+    "llm",
+    "automation"
+  ],
+  "author": "elizaOS",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/elizaos/eliza.git",
+    "directory": "packages/skills"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "dependencies": {
+    "yaml": "^2.8.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/1password/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: 1password
+description: Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
+homepage: https://developer.1password.com/docs/cli/get-started/
+metadata:
+  {
+    "otto":
+      {
+        "emoji": "🔐",
+        "requires": { "bins": ["op"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "1password-cli",
+              "bins": ["op"],
+              "label": "Install 1Password CLI (brew)",
+            },
+          ],
+      },
+  }
+---
+
+# 1Password CLI
+
+Follow the official CLI get-started steps. Don't guess install commands.
+
+## References
+
+- `references/get-started.md` (install + app integration + sign-in flow)
+- `references/cli-examples.md` (real `op` examples)
+
+## Workflow
+
+1. Check OS + shell.
+2. Verify CLI present: `op --version`.
+3. Confirm desktop app integration is enabled (per get-started) and the app is unlocked.
+4. REQUIRED: create a fresh tmux session for all `op` commands (no direct `op` calls outside tmux).
+5. Sign in / authorize inside tmux: `op signin` (expect app prompt).
+6. Verify access inside tmux: `op whoami` (must succeed before any secret read).
+7. If multiple accounts: use `--account` or `OP_ACCOUNT`.
+
+## REQUIRED tmux session (T-Max)
+
+The shell tool uses a fresh TTY per command. To avoid re-prompts and failures, always run `op` inside a dedicated tmux session with a fresh socket/session name.
+
+Example (see `tmux` skill for socket conventions, do not reuse old session names):
+
+```bash
+SOCKET_DIR="${OTTO_TMUX_SOCKET_DIR:-${TMPDIR:-/tmp}/otto-tmux-sockets}"
+mkdir -p "$SOCKET_DIR"
+SOCKET="$SOCKET_DIR/otto-op.sock"
+SESSION="op-auth-$(date +%Y%m%d-%H%M%S)"
+
+tmux -S "$SOCKET" new -d -s "$SESSION" -n shell
+tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- "op signin --account my.1password.com" Enter
+tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- "op whoami" Enter
+tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- "op vault list" Enter
+tmux -S "$SOCKET" capture-pane -p -J -t "$SESSION":0.0 -S -200
+tmux -S "$SOCKET" kill-session -t "$SESSION"
+```
+
+## Guardrails
+
+- Never paste secrets into logs, chat, or code.
+- Prefer `op run` / `op inject` over writing secrets to disk.
+- If sign-in without app integration is needed, use `op account add`.
+- If a command returns "account is not signed in", re-run `op signin` inside tmux and authorize in the app.
+- Do not run `op` outside tmux; stop and ask if tmux is unavailable.

package/skills/1password/references/cli-examples.md

@@ -0,0 +1,29 @@
+# op CLI examples (from op help)
+
+## Sign in
+
+- `op signin`
+- `op signin --account <shorthand|signin-address|account-id|user-id>`
+
+## Read
+
+- `op read op://app-prod/db/password`
+- `op read "op://app-prod/db/one-time password?attribute=otp"`
+- `op read "op://app-prod/ssh key/private key?ssh-format=openssh"`
+- `op read --out-file ./key.pem op://app-prod/server/ssh/key.pem`
+
+## Run
+
+- `export DB_PASSWORD="op://app-prod/db/password"`
+- `op run --no-masking -- printenv DB_PASSWORD`
+- `op run --env-file="./.env" -- printenv DB_PASSWORD`
+
+## Inject
+
+- `echo "db_password: {{ op://app-prod/db/password }}" | op inject`
+- `op inject -i config.yml.tpl -o config.yml`
+
+## Whoami / accounts
+
+- `op whoami`
+- `op account list`

package/skills/1password/references/get-started.md

@@ -0,0 +1,17 @@
+# 1Password CLI get-started (summary)
+
+- Works on macOS, Windows, and Linux.
+  - macOS/Linux shells: bash, zsh, sh, fish.
+  - Windows shell: PowerShell.
+- Requires a 1Password subscription and the desktop app to use app integration.
+- macOS requirement: Big Sur 11.0.0 or later.
+- Linux app integration requires PolKit + an auth agent.
+- Install the CLI per the official doc for your OS.
+- Enable desktop app integration in the 1Password app:
+  - Open and unlock the app, then select your account/collection.
+  - macOS: Settings > Developer > Integrate with 1Password CLI (Touch ID optional).
+  - Windows: turn on Windows Hello, then Settings > Developer > Integrate.
+  - Linux: Settings > Security > Unlock using system authentication, then Settings > Developer > Integrate.
+- After integration, run any command to sign in (example in docs: `op vault list`).
+- If multiple accounts: use `op signin` to pick one, or `--account` / `OP_ACCOUNT`.
+- For non-integration auth, use `op account add`.

package/skills/apple-notes/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: apple-notes
+description: Manage Apple Notes via the `memo` CLI on macOS (create, view, edit, delete, search, move, and export notes). Use when a user asks Otto to add a note, list notes, search notes, or manage note folders.
+homepage: https://github.com/antoniorodr/memo
+metadata:
+  {
+    "otto":
+      {
+        "emoji": "📝",
+        "os": ["darwin"],
+        "requires": { "bins": ["memo"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "antoniorodr/memo/memo",
+              "bins": ["memo"],
+              "label": "Install memo via Homebrew",
+            },
+          ],
+      },
+  }
+---
+
+# Apple Notes CLI
+
+Use `memo notes` to manage Apple Notes directly from the terminal. Create, view, edit, delete, search, move notes between folders, and export to HTML/Markdown.
+
+Setup
+
+- Install (Homebrew): `brew tap antoniorodr/memo && brew install antoniorodr/memo/memo`
+- Manual (pip): `pip install .` (after cloning the repo)
+- macOS-only; if prompted, grant Automation access to Notes.app.
+
+View Notes
+
+- List all notes: `memo notes`
+- Filter by folder: `memo notes -f "Folder Name"`
+- Search notes (fuzzy): `memo notes -s "query"`
+
+Create Notes
+
+- Add a new note: `memo notes -a`
+  - Opens an interactive editor to compose the note.
+- Quick add with title: `memo notes -a "Note Title"`
+
+Edit Notes
+
+- Edit existing note: `memo notes -e`
+  - Interactive selection of note to edit.
+
+Delete Notes
+
+- Delete a note: `memo notes -d`
+  - Interactive selection of note to delete.
+
+Move Notes
+
+- Move note to folder: `memo notes -m`
+  - Interactive selection of note and destination folder.
+
+Export Notes
+
+- Export to HTML/Markdown: `memo notes -ex`
+  - Exports selected note; uses Mistune for markdown processing.
+
+Limitations
+
+- Cannot edit notes containing images or attachments.
+- Interactive prompts may require terminal access.
+
+Notes
+
+- macOS-only.
+- Requires Apple Notes.app to be accessible.
+- For automation, grant permissions in System Settings > Privacy & Security > Automation.

package/skills/apple-reminders/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: apple-reminders
+description: Manage Apple Reminders via the `remindctl` CLI on macOS (list, add, edit, complete, delete). Supports lists, date filters, and JSON/plain output.
+homepage: https://github.com/steipete/remindctl
+metadata:
+  {
+    "otto":
+      {
+        "emoji": "⏰",
+        "os": ["darwin"],
+        "requires": { "bins": ["remindctl"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "steipete/tap/remindctl",
+              "bins": ["remindctl"],
+              "label": "Install remindctl via Homebrew",
+            },
+          ],
+      },
+  }
+---
+
+# Apple Reminders CLI (remindctl)
+
+Use `remindctl` to manage Apple Reminders directly from the terminal. It supports list filtering, date-based views, and scripting output.
+
+Setup
+
+- Install (Homebrew): `brew install steipete/tap/remindctl`
+- From source: `pnpm install && pnpm build` (binary at `./bin/remindctl`)
+- macOS-only; grant Reminders permission when prompted.
+
+Permissions
+
+- Check status: `remindctl status`
+- Request access: `remindctl authorize`
+
+View Reminders
+
+- Default (today): `remindctl`
+- Today: `remindctl today`
+- Tomorrow: `remindctl tomorrow`
+- Week: `remindctl week`
+- Overdue: `remindctl overdue`
+- Upcoming: `remindctl upcoming`
+- Completed: `remindctl completed`
+- All: `remindctl all`
+- Specific date: `remindctl 2026-01-04`
+
+Manage Lists
+
+- List all lists: `remindctl list`
+- Show list: `remindctl list Work`
+- Create list: `remindctl list Projects --create`
+- Rename list: `remindctl list Work --rename Office`
+- Delete list: `remindctl list Work --delete`
+
+Create Reminders
+
+- Quick add: `remindctl add "Buy milk"`
+- With list + due: `remindctl add --title "Call mom" --list Personal --due tomorrow`
+
+Edit Reminders
+
+- Edit title/due: `remindctl edit 1 --title "New title" --due 2026-01-04`
+
+Complete Reminders
+
+- Complete by id: `remindctl complete 1 2 3`
+
+Delete Reminders
+
+- Delete by id: `remindctl delete 4A83 --force`
+
+Output Formats
+
+- JSON (scripting): `remindctl today --json`
+- Plain TSV: `remindctl today --plain`
+- Counts only: `remindctl today --quiet`
+
+Date Formats
+Accepted by `--due` and date filters:
+
+- `today`, `tomorrow`, `yesterday`
+- `YYYY-MM-DD`
+- `YYYY-MM-DD HH:mm`
+- ISO 8601 (`2026-01-04T12:34:56Z`)
+
+Notes
+
+- macOS-only.
+- If access is denied, enable Terminal/remindctl in System Settings → Privacy & Security → Reminders.
+- If running over SSH, grant access on the Mac that runs the command.

package/skills/bear-notes/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: bear-notes
+description: Create, search, and manage Bear notes via grizzly CLI.
+homepage: https://bear.app
+metadata:
+  {
+    "otto":
+      {
+        "emoji": "🐻",
+        "os": ["darwin"],
+        "requires": { "bins": ["grizzly"] },
+        "install":
+          [
+            {
+              "id": "go",
+              "kind": "go",
+              "module": "github.com/tylerwince/grizzly/cmd/grizzly@latest",
+              "bins": ["grizzly"],
+              "label": "Install grizzly (go)",
+            },
+          ],
+      },
+  }
+---
+
+# Bear Notes
+
+Use `grizzly` to create, read, and manage notes in Bear on macOS.
+
+Requirements
+
+- Bear app installed and running
+- For some operations (add-text, tags, open-note --selected), a Bear app token (stored in `~/.config/grizzly/token`)
+
+## Getting a Bear Token
+
+For operations that require a token (add-text, tags, open-note --selected), you need an authentication token:
+
+1. Open Bear → Help → API Token → Copy Token
+2. Save it: `echo "YOUR_TOKEN" > ~/.config/grizzly/token`
+
+## Common Commands
+
+Create a note
+
+```bash
+echo "Note content here" | grizzly create --title "My Note" --tag work
+grizzly create --title "Quick Note" --tag inbox < /dev/null
+```
+
+Open/read a note by ID
+
+```bash
+grizzly open-note --id "NOTE_ID" --enable-callback --json
+```
+
+Append text to a note
+
+```bash
+echo "Additional content" | grizzly add-text --id "NOTE_ID" --mode append --token-file ~/.config/grizzly/token
+```
+
+List all tags
+
+```bash
+grizzly tags --enable-callback --json --token-file ~/.config/grizzly/token
+```
+
+Search notes (via open-tag)
+
+```bash
+grizzly open-tag --name "work" --enable-callback --json
+```
+
+## Options
+
+Common flags:
+
+- `--dry-run` — Preview the URL without executing
+- `--print-url` — Show the x-callback-url
+- `--enable-callback` — Wait for Bear's response (needed for reading data)
+- `--json` — Output as JSON (when using callbacks)
+- `--token-file PATH` — Path to Bear API token file
+
+## Configuration
+
+Grizzly reads config from (in priority order):
+
+1. CLI flags
+2. Environment variables (`GRIZZLY_TOKEN_FILE`, `GRIZZLY_CALLBACK_URL`, `GRIZZLY_TIMEOUT`)
+3. `.grizzly.toml` in current directory
+4. `~/.config/grizzly/config.toml`
+
+Example `~/.config/grizzly/config.toml`:
+
+```toml
+token_file = "~/.config/grizzly/token"
+callback_url = "http://127.0.0.1:42123/success"
+timeout = "5s"
+```
+
+## Notes
+
+- Bear must be running for commands to work
+- Note IDs are Bear's internal identifiers (visible in note info or via callbacks)
+- Use `--enable-callback` when you need to read data back from Bear
+- Some operations require a valid token (add-text, tags, open-note --selected)