How to use
- Copy the installation command and review the source package before installing it in your own agent environment.
- Check the source document for required tools, credentials and supported hosts.
- Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/ariestools/ariestools-skills --skill ariestools-actorBefore you start
- Installation does not include a model subscription, API allowance or permission to access your files.
- Repository stars and installation counts describe activity, not an independent quality or security test.
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
Aries Tools Actors
Authority. This skill is maintained only in `ariestools/ariestools-skills`; edit there, not in installed copies.
Versions. Verified against actor-kit 2.0.0 (@ariestools/actor, actor-model, actor-engine, actor-system, provider, provider-model), @ariestools/cli-kit 2.1.0 and @ariestools/browser-kit 2.0.0, with @ariestools/sdk 9.0.1. The sources are the private `ariestools/actor-kit`, `ariestools/cli-kit` and `ariestools/browser-kit` repositories; their READMEs lag the code (stale upstream docs).
Skill identity. When you present a plan, an acknowledgement, or a completion summary, state which skills informed it as ariestools-actor v<version>, and list each other active skill from this pack the same way. Read the version from this file's metadata.version, never from an example.
Scope. The six actor-kit packages, the four @ariestools/cli-kit* packages and the five @ariestools/browser-kit* packages, plus migration from @ariestools/actor-system, host-kit 1.x, the retired @ariestools/actor-cli and the npm-deprecated @xyo-network/actor-cli-kit* shims. Not covered: @ariestools/sdk utilities and their peers (ariestools-sdk); build, lint, deplint, Vitest and Chromium setup (xy-toolchain); React UI on @ariestools/sdk-react* (ariestools-sdk-react); and XL1 specializations such as chain locator wiring, ChainActor, wallet resolution and @xyo-network/xl1-browser-system (xyo-skills).
@ariestools/cli, the aries operator CLI, is a product built with cli-kit, not a kit, and is out of scope: see what this skill does not cover and aries --help.
Model. One host-agnostic engine, @ariestools/actor-engine, compiles config, resolves one provider graph, constructs actors and supervises them. Domain code depends on @ariestools/actor and @ariestools/actor-engine, never on a host kit. cli-kit adds the Node process boundary and makes supervision sequential; browser-kit adds realm boundaries and keeps the engine's parallel default. Both 2.x host kits still need the deprecated @ariestools/actor-system alias beside them (host kits still on actor-system).
Distributed responsibilities. Before assigning application work across processes or hosts, introducing a controller, or choosing recovery and effect rules, consult ariestools-architecture when available. Local lifecycle supervision remains useful: assess separately who owns business obligations, outcome acceptance, and recoverable progress. Prefer independently discovering, replaceable workers with safe concurrent effects; justify coordinated authority by its invariant or resource constraint. This policy does not alter the kit APIs or reopen an accepted application protocol during routine lifecycle work.
Traps.
- Create actors with
await X.create(params)under@creatable();newthrows.nameis the brandedCreatableName, so cast it ('heartbeat' as CreatableName). - Engine-launched actors get no logger, meter or tracer by default, and
AccountProviderActorthrows without a logger. Supply alocatorContextthrough the provisioner (logging and telemetry). @ariestools/actor-enginedoes not re-export the actor classes: importActor,PeriodicActorandProviderActorfrom@ariestools/actor, andNoProviderConnectionfrom@ariestools/provider.- A lookup of a moniker the actor or provider did not declare throws
ActorEngineDependencyAccessError, andtryGetInstancedoes not bypass the check. - A compiled engine or browser system holds factories and never crosses a realm; only a
BrowserSystemManifestdoes.
Runtime. Treat Node 26 as the floor for the whole family (26.9 for @ariestools/cli-kit-daemon); actor-kit's declared >=18 understates it (runtime floors).
This skill builds on xy-development, xy-toolchain and ariestools-sdk. Load only the reference needed for the task:
References
Overview, packages and install
Read first when choosing which actor-kit, cli-kit or browser-kit packages a package needs or which package exports a name; installing the 2.x family with its peers (@ariestools/sdk, zod, @opentelemetry/api, and yargs for cli-kit-yargs) while keeping one copy of the SDK and of the engine; checking the runtime floors; judging whether an upstream README is stale; or deciding whether a topic belongs to another skill.
Actors
Read when writing an Actor, PeriodicActor, ProviderActor or AccountProviderActor: creating one with await X.create() under @creatable(), overriding startHandler / stopHandler, registering timers, implementing runPass or run and readiness, choosing a trigger (runOnce, runToCompletion, wake or scheduling), handling fatal errors and maxConsecutiveFailures, recording metrics and spans, or booting and stopping actors without an engine (createMemoryLocator, bootActors, stopOrShutdown, the installed-actor catalog).
Providers and resolution
Read when defining a Provider and its moniker; writing a provider descriptor (monikers, connectionTypes such as NoProviderConnection, dependencies) and its engine create / dispose factory; binding monikers to connections or pinned providers in config; declaring optional dependencies; or diagnosing a resolution error (UnboundProviderError, AmbiguousProviderError, …) or an ActorEngineDependencyAccessError from an undeclared lookup.
Actor engine
Read when registering actors in an ActorEngineCatalog; compiling config with compileActorEngine and describing the plan with describeActorEnginePlan; launching with launchActorEngine, launchCompiledActorEngine or, for actors the host built, launchActors; running one-shot actors (runMode: 'one-shot'); choosing parallel or sequential supervision; handling whenTerminal() failures and session stop; tracing boot with startActorEngine and renderActorEngineBoot; writing a custom provisioner; or giving engine-launched actors the logger, meter and tracer they lack by default (logging and telemetry).
CLI hosts (cli-kit)
Read when running an engine in a Node command-line or service process: launchCliSystem and runCliSystemUntilInterrupt, process hosts from @ariestools/cli-kit-node, runProcessApplication and SYS_EXITS exit codes from createSysExitFailureMapper and CliConfigError, yargs command catalogs with @ariestools/cli-kit-yargs, long-running service helpers, local daemons with createDaemonKit from @ariestools/cli-kit-daemon, or shaping a bin package and its launcher.
Browser hosts (browser-kit)
Read when hosting actors in a browser: BrowserActorCatalog, BrowserSystemConfig, compileBrowserSystem and launchCompiledBrowserSystem in the owner realm, assigning actors to realms with host, page lifecycle, dedicated or shared workers over a MessagePort, service workers, extension background and port realms with an authorize callback, typed provider proxies, the realm security boundary, testing realm code, or why only a BrowserSystemManifest, never a compiled system, crosses a realm.
Migration
Read when moving actor-kit 1.3 to 2.0 (enforced dependency access, closing scopes, SDK 9), renaming @ariestools/actor-system imports to @ariestools/actor-engine, upgrading cli-kit or browser-kit from 1.x to 2.x, replacing the retired @ariestools/actor-cli 1.3.0 helpers (runActorsService, runActorOnce, …) or the npm-deprecated @xyo-network/actor-cli-kit* shims, or keeping one engine copy while the host kits pull in actor-system.
Related skills
These are navigation links, not dependencies; each skill installs separately.
- [ariestools-architecture](../ariestools-architecture/SKILL.md) — design and review application authority, independent discovery, worker replacement, effect concurrency, and scoped coordination across actors or hosts.
- [xy-development](../xy-development/SKILL.md) — TypeScript, Git, testing principles and the Definition of Done; this skill builds on it. Install:
npx skills add ariestools/ariestools-skills --skill xy-development. - [xy-toolchain](../xy-toolchain/SKILL.md) — the
xyCLI, Vitest (including Chromium for browser specs), deplint package roles for bin and library packages, and thetslibthat decorators such as@creatable()need; this skill builds on it. Install:npx skills add ariestools/ariestools-skills --skill xy-toolchain. - [ariestools-sdk](../ariestools-sdk/SKILL.md) — the
@ariestools/sdkutilities actors use (creatable,CreatableName, loggers), itszodand OpenTelemetry peers, and the root-barrel import rule; this skill builds on it. Install:npx skills add ariestools/ariestools-skills --skill ariestools-sdk. - [ariestools-sdk-react](../ariestools-sdk-react/SKILL.md) — React UI on
@ariestools/sdk-react*, for apps whose pages also host browser-kit realms. Install:npx skills add ariestools/ariestools-skills --skill ariestools-sdk-react. - XL1 browser and CLI specializations live in the separate xyo-skills pack.
Install this skill with npx skills add ariestools/ariestools-skills --skill ariestools-actor, or in an xy repository with pnpm xy skills pick --skill ariestools-actor, which also records it as required. Since toolchain 10.1.4 it is in the toolchain's skills catalog: xy skills lint requires it, together with ariestools-sdk, wherever a workspace package produces or depends on an actor-kit, cli-kit or browser-kit package, and version-checks it. Through 10.1.3 it is outside the catalog, so xy skills pick and the commands.skillsLint keys reject it; install it there with pnpm xy skills add ariestools/ariestools-skills --skill ariestools-actor -y. See skills and work tracking for the other routes and their caveats.