@elizaos/skills 2.0.0-alpha.15 → 2.0.0-alpha.151

package/README.md

@@ -62,6 +62,10 @@ const commands = buildSkillCommandSpecs(entries);
 // Returns array of command specs for chat interfaces
 ```
 
+## Bundled documentation skills
+
+Alongside community-oriented skills, this package ships **`elizaos`**, **`eliza-cloud`**, and **`eliza-app-development`** — concise references for elizaOS runtime concepts, Eliza Cloud as a backend, and building elizaOS-based applications (including the Eliza app repository layout).
+
 ## Skill Discovery
 
 Skills are loaded from multiple locations in precedence order (later overrides earlier):

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@elizaos/skills",
-	"version": "2.0.0-alpha.15",
+	"version": "2.0.0-alpha.151",
 	"description": "Bundled skills and skill loading utilities for elizaOS agents",
 	"type": "module",
 	"main": "dist/index.js",
@@ -18,7 +18,7 @@
 		"build": "tsc -p tsconfig.build.json",
 		"dev": "tsgo -p tsconfig.build.json --watch --preserveWatchOutput",
 		"test": "node --test --import tsx test/*.test.ts",
-		"prepublishOnly": "npm run clean && npm run build",
+		"prepublishOnly": "bun run clean && bun run build",
 		"lint": "bunx @biomejs/biome check --write ./src",
 		"lint:check": "bunx @biomejs/biome check ./src"
 	},
@@ -48,8 +48,11 @@
 	"dependencies": {
 		"yaml": "^2.8.2"
 	},
+	"devDependencies": {
+		"tsx": "^4.19.2"
+	},
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "64c3776b97ecd672df468fc872a36822c8edcc51"
+	"gitHead": "a424696fc95ebafbac5e818a61f69406072e9fb5"
 }

package/skills/eliza-app-development/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: eliza-app-development
+description: "Use when building or changing an elizaOS-based application in this repository. Covers eliza app architecture, monorepo layout, local versus remote versus cloud routing, where to edit features, and non-negotiable runtime constraints. Eliza is the product name of this particular eliza app checkout."
+---
+
+# eliza app development
+
+This repository is an **elizaOS application**: a local-first assistant with CLI, dashboard, Electrobun desktop shell, connectors, and Eliza Cloud integration. **Eliza** is this app’s product and CLI name—not a separate platform from elizaOS.
+
+## Read These References First
+
+- `references/repo-map.md` for layout, edit targets, and common commands
+- `references/runtime-and-cloud.md` for runtime flow, onboarding, service routing, skills, and Eliza Cloud behavior
+
+## Editing Heuristics
+
+- Prefer `packages/app-core/` for app shell behavior (API, CLI, onboarding, config).
+- Prefer `packages/agent/` for agent providers, services, and runtime glue around elizaOS.
+- Prefer `apps/app/` for UI and Electrobun work.
+- Treat `eliza/cloud/` as the Eliza Cloud product and backend surface.
+- Treat `eliza/` as upstream elizaOS. Edit it only when the bug or feature is genuinely upstream.
+
+## Hard Constraints
+
+- Do not remove `NODE_PATH` setup.
+- Do not remove the Bun exports patch.
+- Do not remove Electrobun startup error guards.
+- Keep Node and Bun paths working.
+
+## Repo Workflow
+
+```bash
+bun install
+bun run verify
+bun run test
+```
+
+Narrower commands when useful:
+
+```bash
+bun run eliza ...
+bun run dev
+bun run dev:desktop
+bun run test:e2e
+```
+
+## Where to Look First
+
+- Product and runtime behavior: `packages/app-core/src/`
+- Prompt, provider, and skill plumbing: `packages/agent/src/`
+- Onboarding and routing: `packages/app-core/src/onboarding/` and `packages/app-core/src/runtime/`
+- Shipped default skills: bundled in `@elizaos/skills`, seeded into the state-dir skills folder by `scripts/ensure-skills.mjs`
+- Eliza Cloud backend or monetization: `eliza/cloud/` and the shipped `eliza-cloud` skill
+
+## Cloud Default
+
+If the task involves building an app and Eliza Cloud is enabled, linked, or explicitly requested, treat Cloud as the default managed backend before inventing custom auth, billing, analytics, or hosting. Use the `eliza-cloud` skill for app, monetization, and container details.
+
+## Related Skills
+
+- `elizaos` — core runtime abstractions and upstream plugin patterns
+- `eliza-cloud` — apps, billing, monetization, auth, containers

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