Skip to main content
After this guide, one promoted version of your agent is a published agent template that your other clients, or other organizations, can install. To share one skill rather than a whole agent, publish a marketplace skill instead. Verified against lua-cli 3.33.0. Before you begin
  • A project connected to the source agent (lua.skill.yaml carries its agentId) and a signed-in CLI. See Install.
  • Everything pushed and an active agent version on the source agent: lua push all --ci --force (the source backup lua version create needs), lua version create, then lua version promote <n>. Publishing freezes that version.
  • No voice binding and no device triggers on the source agent; such a publish is refused with UNSUPPORTED_SOURCE.
  • Every secret read through env('KEY'), never a literal in code; publishing scans the frozen code for credentials.
1

Create the template

create registers the listing against the current agent and prints its id. Under --ci, pass all four flags: the CLI prompts for any missing one, including the optional --description, and --ci refuses prompts.
The listing is private (your organization only) unless you pass --visibility public. Each version of a public template is reviewed; other organizations are offered approved versions only, while yours can install a pending one to test it.
2

Draft the template: section

draft asks the server to compose the template: section of lua.skill.yaml from the active agent version and writes it.
It writes six sections: connections, personaTemplate, triggerPresets, and paramsMeta inferred from the agent’s code, persona, jobs, and latest env contract, plus onInstall and onUninstall copied from your latest published version. It never composes hooks or installPolicy, and replaces the section as a whole, so re-add a hand-written installPolicy after every draft. A re-run merges additively and prints what it added and kept; --force replaces your edits.An agent with no active version is refused with exit 10: ✖ http_400: Source agent has no active version — run `lua version create` + `lua version promote` first.
3

Review the template: section

Edit the drafted section. Every installer-facing entry needs displayName and description; keys are the identity installers keep their settings under, so keep them stable across versions. draft declares a persona var for every {{NAME}} token (upper-case names) in the promoted persona, as a required string with an empty description: write {{COMPANY_NAME}} into the source persona before lua version create and lua version promote, or add the token and its var to the drafted personaTemplate by hand, then fill in each description. Give a required var a default if installers use the CLI, which cannot answer persona variables.
lua.skill.yaml
A publish sends all seven sections; an absent or empty one clears the server’s copy. Fields are on the template manifest and, for the hooks and installPolicy, Lifecycle hooks.
4

Publish a version

publish freezes the active agent version (skills, webhooks, jobs, processors, triggers, workflows, model), the template: section, and the env contract into an integer-numbered version.
KEY?= marks an optional variable; the contract carries names and descriptions, never values. On success the CLI prints ✅ Published v1, Frozen from agent version v<n>, an Auto-update: line, and a manifest summary; --json prints the version instead, with id, version, sourceAgentVersion, contentHash, consentSurfaceHash, the authored sections, approvalStatus on a public template, and autoApplyRunId with autoApplyTargetCount when a fan-out started. A publish that clears or narrows an authored section prints the consequence and asks to proceed; --yes confirms only that prompt, and --ci proceeds with the diff printed.
Publishing a private template pushes the version onto every consenting install that is behind. Pass --skip-auto-apply to hold it back and roll out later with apply.
5

Verify

Read the listing and its versions.
view prints the listing with Latest version: v1; versions prints one line per version, newest first, as v1 — from agent v<n> — <date>. view --version 1 prints the frozen primitives, env contract, and persona vars.

​
Read the Auto-update line

  • pushing to <n> consenting installs — run <id>: a private template applied the version to every install that allows creator updates and was behind; follow it with lua marketplace template status.
  • deferred until this version is approved: a public template’s version is pending review; the push happens at approval.
  • no consenting installs below v<n>, or skipped (--skip-auto-apply).
A version that changes the consent surface is refused per install with RECONSENT_REQUIRED until that installer accepts it, whether or not they opted in; see What installers agree to and keep.

​
If it isn’t working

Nothing is promoted. Run lua push all --ci --force, lua version create, then lua version promote <n>, and retry.
Frozen code or a description matches a credential pattern; the location is named, never the value. Read it through env('KEY'), declare KEY with --env-contract, push, promote, and publish again.
A lint refused the section and took no version number; every violation is in the one message. Codes and fixes are on Lints and consent.

​
Next steps

Template manifest

Every field of the section you edited.

Install and apply

What installers run, and how to roll a version out to a fleet.

Fleet health

Per-install workflow health after the rollout.

lua marketplace

Every template action, flag, and exit code.