@elizaos/skills 2.0.0-alpha.43 → 2.0.0-alpha.430

package/skills/eliza-app-development/references/repo-map.md

@@ -0,0 +1,70 @@
+# eliza app repo map
+
+## What this repository is
+
+This checkout is an **elizaOS application**: runtime, UI, connectors, and Cloud hooks bundled as the **Eliza** product (CLI `eliza`, user-facing name Eliza). Same stack patterns apply to other eliza apps; this repo is one concrete implementation.
+
+It combines:
+
+- a local-first runtime and CLI
+- a web dashboard
+- an Electrobun desktop shell
+- connector integrations
+- Eliza Cloud routing, provisioning, and billing hooks
+
+## Main edit targets
+
+### `packages/app-core/`
+
+Primary app-shell logic.
+
+- `src/runtime/` for runtime bootstrap, env shaping, provider routing, and process behavior
+- `src/cli/` for CLI wiring
+- `src/api/` for app HTTP routes
+- `src/config/` for config schemas and canonical routing/storage fields
+- `src/connectors/` for platform integrations
+- `src/providers/` for prompt/state context builders
+
+### `packages/agent/`
+
+Agent layer on elizaOS: providers, skill discovery and catalog plumbing, runtime compatibility layers, training and testing helpers.
+
+### `apps/app/`
+
+Main React UI and desktop shell: web UI, onboarding, settings, Electrobun native process under `apps/app/electrobun/`.
+
+### `eliza/cloud/`
+
+Eliza Cloud product code (git submodule nested under `eliza/`): apps, billing, earnings, auth, containers, domains, cloud-side agent runtime and plugins.
+
+### `eliza/`
+
+Repo-local upstream elizaOS checkout for linked development. Change this only when the issue is genuinely upstream or the user asks for upstream work.
+
+## Commands
+
+```bash
+bun install
+bun run verify
+bun run test
+```
+
+Useful narrower commands:
+
+```bash
+bun run dev
+bun run dev:desktop
+bun run eliza ...
+bun run test:e2e
+bun run test:coverage
+```
+
+## Non-negotiable runtime invariants
+
+- `NODE_PATH` setup is required for dynamic plugin imports.
+- The Bun exports patch is required for some published `@elizaos/*` packages.
+- Electrobun startup guards keep the desktop UI usable when the runtime fails.
+
+## Default skill seeding
+
+Shipped skills are bundled in `@elizaos/skills` and are seeded into the state-dir skills folder (e.g. `~/.eliza/skills` when `ELIZA_NAMESPACE=eliza`) by Eliza’s `scripts/ensure-skills.mjs`. They are default agent knowledge, not optional extras.

package/skills/eliza-app-development/references/runtime-and-cloud.md

@@ -0,0 +1,61 @@
+# Runtime and cloud (eliza app)
+
+## Runtime shape
+
+This app persists canonical runtime state in config fields such as:
+
+- `deploymentTarget` for where the active runtime lives: `local`, `cloud`, or `remote`
+- `linkedAccounts` for which providers and cloud accounts are connected
+- `serviceRouting` for which backend handles each capability (`llmText`, `tts`, `media`, `embeddings`, `rpc`)
+
+This separation matters. Hosting on Eliza Cloud does not require all inference to run through Eliza Cloud, and direct provider keys can still be used for selected capabilities.
+
+## Onboarding model
+
+Onboarding chooses:
+
+1. identity and persona
+2. hosting target
+3. provider/account links
+4. service routing
+5. credentials
+
+The stored config then drives runtime behavior after restart.
+
+## Providers and skills
+
+The runtime injects context through providers (workspace, admin trust, autonomous state, UI catalog or action availability, etc.).
+
+Shipped skills are separate from providers. Skills are disk-backed knowledge assets discovered from `skills/` and the managed skills directory, then selected dynamically per turn by the app’s skill provider.
+
+## Eliza Cloud in this app
+
+Eliza Cloud is treated as a first-class managed backend:
+
+- cloud login and API key persistence
+- credit balance and in-app billing proxies
+- cloud-hosted agent provisioning
+- cloud media and TTS paths
+- app platform integration
+- containers and remote runtimes
+
+If a task is about app building and Cloud is enabled or requested, prefer the Cloud backend path before inventing custom auth, billing, analytics, or hosting.
+
+## Cloud-as-backend heuristic
+
+For new app work, the default path should usually be:
+
+1. create or reuse an Eliza Cloud app
+2. use its `appId` plus API key
+3. configure origins, redirect URIs, and domains
+4. use Cloud APIs for chat/media/agent features
+5. turn on monetization if the app should earn
+6. deploy a container only if server-side code is required
+
+## Current cloud monetization reality
+
+In this repo’s implementation, app monetization is driven by markup/share fields and creator earnings tracking, not only generic per-request pricing prose. When docs drift, prefer:
+
+- schema fields in `eliza/cloud/packages/db/schemas/`
+- app monetization UI under `eliza/cloud/packages/ui/src/components/apps/`
+- billing and earnings APIs used by the UI

package/skills/eliza-cloud/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: eliza-cloud
+description: "Use when the task involves Eliza Cloud or elizaOS Cloud as a managed backend, app platform, deployment target, billing layer, or monetization surface. Covers app creation, `appId` usage, app auth flows, cloud-hosted APIs, analytics, credits, creator monetization, and custom Docker container deployments."
+---
+
+# Eliza Cloud
+
+Use this skill whenever Eliza Cloud is enabled, linked, or the task involves building an app that could use Cloud as its backend.
+
+## Default Stance
+
+Treat Eliza Cloud as the default managed backend before inventing separate auth, billing, analytics, or hosting. In this repo, Cloud already supports:
+
+- app registration and API keys
+- `appId`-based app auth flows
+- cloud-hosted chat, media, agent, and billing APIs
+- app analytics, user tracking, domains, and credits
+- creator monetization
+- Docker container deployments for server-side workloads
+
+## Read These References First
+
+- `references/cloud-backend-and-monetization.md` for apps, auth, billing, and earnings
+- `references/apps-and-containers.md` for deployment, domains, and container workflow
+
+## Default Build Flow
+
+For most app work:
+
+1. create or reuse an Eliza Cloud app
+2. capture the app's `appId` and API key
+3. configure `app_url`, allowed origins, and redirect URIs
+4. use Cloud APIs as the backend
+5. enable monetization if the app should earn
+6. deploy a container only if server-side code is required
+
+## Important Reality Check
+
+Some older docs still describe generic per-request or per-token app pricing. In this repo's current implementation, the active app monetization controls are markup/share-based. Prefer the current schema, UI, and API behavior in this repo when prose docs conflict.

package/skills/eliza-cloud/references/apps-and-containers.md

@@ -0,0 +1,73 @@
+# Eliza Cloud Apps And Containers
+
+## Apps First
+
+For most product work, start with an app.
+
+Typical flow:
+
+1. create the app
+2. store `appId`
+3. configure `app_url` and `allowed_origins`
+4. register redirect URIs
+5. wire the client to Cloud APIs
+6. add domains if the app needs a branded URL
+
+Useful app capabilities already present in this repo:
+
+- analytics
+- user tracking
+- monetization settings
+- earnings dashboard
+- domain management
+- one-time API key display and regeneration
+
+## Domains
+
+Apps can get:
+
+- a managed subdomain
+- custom domains with verification
+
+If the task needs a production URL, prefer the existing app/domain model before inventing custom deployment plumbing.
+
+## When To Use A Container
+
+Use a Cloud container when the app needs backend code that cannot live purely in the browser or through the existing managed APIs.
+
+Good reasons:
+
+- custom server logic
+- webhooks
+- background jobs tied to the app
+- an existing Dockerized service
+
+Do not default to a container just to get a backend if the built-in Cloud APIs are already enough.
+
+## Container Deployment Flow
+
+Current container flow in this repo:
+
+1. get temporary ECR credentials
+2. push a Docker image
+3. create a container with `ecr_image_uri`
+4. poll status until it is running
+5. read logs/metrics or attach domains as needed
+
+Current implementation notes:
+
+- deployments are asynchronous
+- the API returns a poll endpoint
+- deployments deduct credits
+- health checks, metrics, and logs already exist
+
+## Practical Heuristic For Agents
+
+If you are building an app:
+
+- use an app record and Cloud APIs by default
+- use the app auth flow for user login
+- turn on monetization if appropriate
+- add a container only for real server-side code
+
+That keeps the app inside the platform's identity, billing, analytics, and earnings model.

package/skills/eliza-cloud/references/cloud-backend-and-monetization.md

@@ -0,0 +1,99 @@
+# Eliza Cloud Backend And Monetization
+
+## Why Use Cloud As The Backend
+
+When Cloud is enabled, it already gives the app most of the backend primitives agents usually try to reinvent:
+
+- authentication
+- API keys
+- usage tracking
+- credits and billing
+- analytics
+- domains
+- app users
+- creator earnings
+
+For app work, the default assumption should be that Cloud is the backend unless there is a specific reason not to use it.
+
+## App As The Integration Unit
+
+The core unit is an app record.
+
+Current app fields in this repo include:
+
+- `id` / `appId`
+- `name`
+- `app_url`
+- `allowed_origins`
+- `website_url`
+- `contact_email`
+- deployment status and production URL
+- monetization fields
+
+Creating an app yields a unique API key and an app identifier. Use the app identifier for frontend/browser-facing flows and keep the API key on trusted server paths.
+
+## User Auth Flow
+
+The existing app auth flow expects:
+
+- `app_id`
+- `redirect_uri`
+- optional `state`
+
+The user signs into Eliza Cloud, the app is validated, and the user is redirected back with a token. This means users logging into the app can use Eliza Cloud as the backend identity and service layer instead of a separate auth stack.
+
+## Billing And Credits
+
+Cloud already exposes:
+
+- credit balance APIs
+- billing summary
+- checkout / top-up flows
+- payment methods
+- billing history
+
+In Eliza, billing is intended to stay inside the app where possible, with hosted URLs treated as fallback.
+
+## Current App Monetization Model In This Repo
+
+The app monetization implementation currently centers on:
+
+- `monetization_enabled`
+- `inference_markup_percentage`
+- `purchase_share_percentage`
+- `platform_offset_amount`
+- `total_creator_earnings`
+
+The UI describes this as:
+
+- creators earn from inference markups
+- creators earn a share when users buy app credits
+- users pay app-specific credits
+
+So when an agent builds an app on Cloud, it should understand that app usage can be monetized directly instead of treated as pure cost.
+
+## Redeemable Earnings
+
+Redeemable earnings in this repo explicitly include:
+
+- app creator earnings
+- agent creator earnings
+- MCP creator earnings
+- affiliate and revenue-share flows
+
+That means apps, public agents, and MCP products can all participate in monetized Cloud flows.
+
+## Affiliate And Marked-Up Usage
+
+The Cloud UI also includes affiliate markup flows where a code can add markup to usage and credit top-ups. This is separate from per-app monetization, but it reinforces the same principle: Cloud is designed to let builders earn on top of platform usage rather than only consume credits.
+
+## Source Of Truth When Docs Drift
+
+Prefer these implementation surfaces:
+
+- `eliza/cloud/packages/db/schemas/app-billing.ts`
+- `eliza/cloud/packages/db/schemas/apps.ts`
+- `eliza/cloud/packages/db/schemas/redeemable-earnings.ts`
+- `eliza/cloud/packages/ui/src/components/apps/app-monetization-settings.tsx`
+- `eliza/cloud/packages/ui/src/components/apps/app-earnings-dashboard.tsx`
+- `eliza/cloud/packages/ui/src/components/auth/authorize-content.tsx`

package/skills/elizaos/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: elizaos
+description: "Use when the task involves elizaOS core runtime concepts, plugins, actions, providers, evaluators, services, memories, state composition, or upstream elizaOS development. Covers the main abstractions and the TypeScript runtime mental model."
+---
+
+# elizaOS
+
+elizaOS is the plugin-based agent runtime that Eliza builds on top of.
+
+## Read These References First
+
+- `references/core-abstractions.md` for the runtime mental model and message flow
+- `references/plugin-development.md` for plugin extension points and implementation patterns
+
+## Use This Skill When
+
+- a change touches `eliza/`
+- you need to reason about `AgentRuntime`
+- you are implementing or debugging actions, providers, evaluators, services, or model handlers
+- you need the correct plugin lifecycle instead of guessing from Eliza wrappers
+
+## Working Rules
+
+- Treat the TypeScript runtime in `eliza/packages/typescript/src/` as the primary reference implementation.
+- Prefer elizaOS-native abstractions over product-specific wrappers when reasoning about upstream behavior.
+- Remember the split between persistent `Memory` and ephemeral `State`.
+- Remember that plugins are the main composition mechanism.

package/skills/elizaos/references/core-abstractions.md

@@ -0,0 +1,101 @@
+# elizaOS Core Abstractions
+
+## Runtime
+
+The main TypeScript runtime is `AgentRuntime`.
+
+It owns:
+
+- registered plugins
+- actions, providers, evaluators, services, routes, and model handlers
+- database adapter access
+- message processing
+- cached per-message state
+
+`runtime.initialize()` registers plugins, initializes the adapter, creates the default message service, and can run plugin migrations.
+
+## Persistent Versus Ephemeral Data
+
+### `Memory`
+
+Persistent data. Messages, documents, fragments, and other stored knowledge live here.
+
+Typical fields:
+
+- `content`
+- `embedding`
+- `metadata`
+
+### `State`
+
+Ephemeral per-turn context used for prompt composition and action execution.
+
+Typical parts:
+
+- `values`
+- `data`
+- `text`
+
+Providers build `State`; memories persist across turns.
+
+## Core Conversation Model
+
+- **Entity**: participant identity
+- **Room**: conversation space
+- **World**: container for related rooms
+
+Typical flow:
+
+1. ensure the connection (`world`, `room`, `entity`)
+2. create a message memory
+3. call the message service
+
+## Provider Model
+
+Providers build context before inference.
+
+They can contribute:
+
+- `text` for human-readable prompt context
+- `values` for template variables
+- `data` for structured cached state
+
+Providers are ordered by `position`. `private` and `dynamic` providers are excluded from the default provider set unless explicitly requested.
+
+## Action Model
+
+Actions are elizaOS tools.
+
+The default flow is:
+
+1. model emits an action plan
+2. runtime executes actions
+3. action results can feed follow-up state or callbacks
+
+Single-action and multi-action modes both exist.
+
+## Evaluators
+
+Evaluators run after response generation and action execution.
+
+Use them for:
+
+- reflection
+- extraction
+- safety checks
+- policy enforcement
+
+## End-To-End Flow
+
+The default TypeScript pipeline is:
+
+1. ingest message
+2. persist incoming memory
+3. compose state via providers
+4. optionally process attachments
+5. decide whether to respond
+6. run model inference
+7. execute actions
+8. persist/send the response
+9. run evaluators
+10. emit lifecycle events

package/skills/elizaos/references/plugin-development.md

@@ -0,0 +1,74 @@
+# elizaOS Plugin Development
+
+## Plugin Shape
+
+An elizaOS plugin is a plain object that can register:
+
+- `actions`
+- `providers`
+- `services`
+- `models`
+- `evaluators`
+- `routes`
+- `events`
+- optionally an adapter or schema
+
+## Key Extension Points
+
+### Actions
+
+Use for tool execution or side effects.
+
+- declared in `plugin.actions`
+- executed by `runtime.processActions(...)`
+- can declare structured parameters
+
+### Providers
+
+Use for state and prompt context.
+
+- declared in `plugin.providers`
+- executed during `runtime.composeState(...)`
+- return `text`, `values`, and/or `data`
+
+### Services
+
+Use for long-lived shared logic such as API clients, caches, or background connections.
+
+### Models
+
+Use to register inference handlers for text, embeddings, image description, and related model types.
+
+### Evaluators
+
+Use for post-response analysis or policy checks.
+
+### Routes
+
+Use for plugin-owned HTTP endpoints. Routes are namespaced under the plugin name.
+
+## Practical Guidance
+
+- If the feature changes prompt context, it is usually a provider.
+- If the feature performs an operation, it is usually an action.
+- If the feature needs shared lifecycle-managed resources, it is usually a service.
+- If the feature changes inference backends, it is usually a model handler.
+
+## Runtime Registration Order
+
+At plugin registration:
+
+1. `plugin.init(...)` runs first
+2. components are registered
+3. routes are namespaced
+4. services are initialized asynchronously
+
+## Eliza Context
+
+In this repo, Eliza adds product behavior around elizaOS, but the underlying runtime composition rules still come from elizaOS. When a Eliza feature behaves strangely, check whether the root cause is actually in:
+
+- provider ordering
+- action planning
+- model handler selection
+- plugin auto-enable or plugin loading
+- database adapter initialization

package/skills/github/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: github
-description: "Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries."
+description: "Interact with GitHub using the `gh` CLI to manage repositories, issues, pull requests, CI/CD workflow runs, and API queries. Use when the user asks to create, list, view, merge, or close pull requests and issues; check CI status or workflow run logs; query the GitHub API for repository data; or perform any GitHub operation from the command line. Covers `gh issue`, `gh pr`, `gh run`, `gh repo`, and `gh api` subcommands."
 metadata:
   {
     "otto":

package/skills/imsg/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: imsg
-description: iMessage/SMS CLI for listing chats, history, watch, and sending.
+description: iMessage/SMS CLI for listing chats, fetching history, watching conversations, and sending messages on macOS via the Messages app. Use when the user wants to send a text message, read iMessages, check recent texts, reply to a conversation, send an SMS, or interact with the Messages app from the terminal. Supports texting contacts by phone number or email, attaching files, and streaming incoming messages in real time.
 homepage: https://imsg.to
 metadata:
   {

package/skills/nano-banana-pro/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: nano-banana-pro
-description: Generate or edit images via Gemini 3 Pro Image (Nano Banana Pro).
+description: Generate or edit images via Gemini 3 Pro Image (Nano Banana Pro). Use when the user asks to create an image, generate a picture, produce AI-generated artwork, edit a photo, compose multiple images, or upscale an image to higher resolution. Supports text-to-image generation, single-image editing, and multi-image composition using the Gemini API.
 homepage: https://ai.google.dev/
 metadata:
   {

package/skills/nano-pdf/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: nano-pdf
-description: Edit PDFs with natural-language instructions using the nano-pdf CLI.
+description: Edits PDF files using natural-language instructions via the nano-pdf CLI. Supports modifying text, changing titles, fixing typos, and updating content on specific pages. Use when the user wants to edit a PDF, modify PDF content, update PDF text, fix a typo in a PDF, change a PDF title, or rewrite part of a PDF page.
 homepage: https://pypi.org/project/nano-pdf/
 metadata:
   {

package/skills/notion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: notion
-description: Notion API for creating and managing pages, databases, and blocks.
+description: Notion API for creating and managing pages, databases, and blocks. Use when the user wants to create a Notion page, query a Notion database, update Notion properties, search Notion, add content to Notion, manage Notion blocks, or interact with Notion data sources and workspaces via the API.
 homepage: https://developers.notion.com
 metadata:
   {

package/skills/obsidian/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: obsidian
-description: Work with Obsidian vaults (plain Markdown notes) and automate via obsidian-cli.
+description: Work with Obsidian vaults (plain Markdown notes) and automate via obsidian-cli. Use when the user asks about notes, vault management, PKM, knowledge base organization, wikilinks, or personal knowledge management in Obsidian.
 homepage: https://help.obsidian.md
 metadata:
   {

package/skills/ordercli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ordercli
-description: Foodora-only CLI for checking past orders and active order status (Deliveroo WIP).
+description: Foodora-only CLI for checking past orders and active order status (Deliveroo WIP). Use when the user asks to check food delivery orders, track a Foodora delivery, view order history, reorder a meal, look up past food orders, check delivery status, or manage Foodora sessions and authentication.
 homepage: https://ordercli.sh
 metadata:
   {

package/skills/skill-creator/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: skill-creator
-description: Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
+description: Creates, updates, and packages AgentSkills with proper SKILL.md frontmatter, bundled scripts, references, and assets. Provides guidance on skill naming, progressive disclosure, and context-efficient design. Use when building a new skill from scratch, restructuring an existing skill, writing or improving SKILL.md files, organizing skill resources into scripts/references/assets folders, packaging skills for distribution, or iterating on skill quality after testing.
 ---
 
 # Skill Creator

package/skills/slack/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: slack
-description: Use when you need to control Slack from Otto via the slack tool, including reacting to messages or pinning/unpinning items in Slack channels or DMs.
+description: Use when the agent needs to send, edit, delete, or read Slack messages, add or list emoji reactions, pin or unpin messages, fetch member info, or list custom emoji in Slack channels and DMs. Handles all Slack workspace interactions including message management, reaction workflows, pinned-item management, and user lookups via the configured bot token.
 metadata: { "otto": { "emoji": "💬", "requires": { "config": ["channels.slack"] } } }
 ---
 

package/skills/spotify-player/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: spotify-player
-description: Terminal Spotify playback/search via spogo (preferred) or spotify_player.
+description: Terminal Spotify playback/search via spogo (preferred) or spotify_player. Use when the user asks to play music, search for a song, skip a track, pause playback, check what is currently playing, control Spotify, list audio devices, or manage a Spotify queue from the terminal.
 homepage: https://www.spotify.com
 metadata:
   {

package/skills/tmux/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tmux
-description: Remote-control tmux sessions for interactive CLIs by sending keystrokes and scraping pane output.
+description: Remote-control tmux sessions for interactive CLIs by sending keystrokes, capturing pane output, and managing terminal multiplexer windows. Enables parallel coding-agent orchestration, background process management, and REPL interaction via sockets. Use when the agent needs to launch, monitor, or coordinate long-running terminal processes, run multiple agents in parallel, interact with a Python REPL, or scrape live shell output from a persistent session.
 metadata:
   { "otto": { "emoji": "🧵", "os": ["darwin", "linux"], "requires": { "bins": ["tmux"] } } }
 ---

package/skills/trello/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: trello
-description: Manage Trello boards, lists, and cards via the Trello REST API.
+description: Manages Trello boards, lists, and cards via the Trello REST API. Use when the user wants to create cards, move tasks between lists, list boards, add comments, archive cards, or check what is on a Trello board. Handles authentication, pagination, and rate-limit awareness for all Trello REST endpoints.
 homepage: https://developer.atlassian.com/cloud/trello/rest/
 metadata:
   {

package/skills/wacli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: wacli
-description: Send WhatsApp messages to other people or search/sync WhatsApp history via the wacli CLI (not for normal user chats).
+description: Send WhatsApp messages to other people or search/sync WhatsApp history via the wacli CLI (not for normal user chats). Use when the user asks to send a WhatsApp message, text someone on WhatsApp, search WhatsApp chat history, sync WhatsApp conversations, backfill message history, or forward a file via WhatsApp to a third party.
 homepage: https://wacli.sh
 metadata:
   {