> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heylua.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Publish and install marketplace skills

> List one of your agent's skills on the marketplace, publish versions of it, and install skills from the marketplace onto an agent

After this guide, one of your [skills](/concepts/skills-and-tools) is listed on the marketplace with a published version, and a skill installed from the marketplace runs on an agent of yours. To share a whole agent rather than one skill, [publish an agent template](/marketplace/publish-a-template) instead.

*Verified against lua-cli 3.33.0.*

A marketplace skill is one skill version frozen by value: its `context`, tools (name, description, schemas, code), condition, changelog, and metadata for the env variables it reads (`{ description, required, example? }` per name), never values. Versions carry the skill's semver and each is reviewed before it can be installed. It carries no persona, jobs, or webhooks; an [agent template](/concepts/agent-templates) does.

**Before you begin**

* A project connected to the agent and a signed-in CLI.
* To publish: the skill pushed with `lua push skill --name <skill-name>`, so a server-side version exists.
* To install: an agent that does not already have the skill, as its own source or as an earlier install.

<Steps>
  <Step title="List the skill">
    `list` creates the listing from one of the agent's pushed skills and prints its marketplace id.

    ```bash theme={null}
    lua marketplace skill list --skill-name order-lookup --display-name "Order Lookup" \
      --visibility private --ci
    ```

    The default visibility is `public`; a `private` listing is visible and installable only inside your organization, and anyone else gets not-found. A skill that is already listed is refused with `Skill "<name>" is already listed as "<display name>".` (exit 1).
  </Step>

  <Step title="Publish a version">
    `publish` submits one pushed version of the skill for review.

    ```bash theme={null}
    lua marketplace skill publish --marketplace-id <marketplace-id> --version-id <version-id> \
      --changelog "Adds EU VAT lookup" \
      --env-vars-json '{"SHOP_API_KEY":{"description":"Shop API key","required":true}}' --ci
    ```

    `--version-id` is the skill version's id, not its semver, and no non-interactive command prints it: `lua skills versions` shows semvers only. Without the flag the action exits 2 with `Missing required options`. The one path that resolves it for you is the interactive menu: run `lua marketplace skill` with no action, choose *Publish a new version of a skill*, then pick the skill and the version. `--env-vars-json` maps each env variable the skill reads to `{ description, required, example? }`. The CLI prints `✅ Version <semver> published successfully!` and the version waits for review. A version that is still published is refused with `Version is already published`; one you withdrew with `unpublish` is re-published from the stored skill version with the new changelog and metadata, without another review; a pending or rejected duplicate is refused with `Version <semver> already exists in marketplace but is not approved`.
  </Step>

  <Step title="Manage the listing">
    The rest of the publisher actions each take `--marketplace-id`.

    ```bash theme={null}
    lua marketplace skill edit --marketplace-id <marketplace-id> --display-name "Order Lookup Pro" --ci
    lua marketplace skill unlist --marketplace-id <marketplace-id> --force --ci
    lua marketplace skill unpublish --marketplace-id <marketplace-id> --version-id <version-id> --force --ci
    lua marketplace skill transfer --marketplace-id <marketplace-id> --new-org-id <org-id> --force --ci
    lua marketplace skill mine --json --ci
    lua marketplace skill org --json --ci
    ```

    `unlist` hides the listing and refuses fresh installs; `list` re-lists it. `unpublish` withdraws one version; withdrawing the last unlists the skill. `transfer` hands the listing to another organization. `mine` lists skills you authored; `org` lists your organization's. `unlist`, `unpublish`, and `transfer` exit 2 without `--force`.
  </Step>

  <Step title="Find a skill to install">
    `search` lists published skills you may see; `view` prints one listing with its versions.

    ```bash theme={null}
    lua marketplace skill search --query "CRM" --json --ci
    lua marketplace skill view --marketplace-id <marketplace-id> --ci
    ```

    `search` takes `--page` (default 1) and `--limit` (default 10) and returns only skills with an approved, published version. `view` prints `Latest: v<semver> (ID: <version-id>)`; that marketplace version id is what `install` takes.
  </Step>

  <Step title="Install it">
    `install` creates the skill on the current agent from the frozen version, activates it, and writes the env values.

    ```bash theme={null}
    lua marketplace skill install --marketplace-id <marketplace-id> --version-id <version-id> \
      --env-vars "SHOP_API_KEY=sk_live_abc123" --force --ci
    ```

    Without `--force` the CLI prints the summary and exits 2. A required env variable without a value, an unapproved version, or a skill already on the agent is refused. The skill is created active; on an agent with [agent versions](/concepts/releases-and-versions), run `lua version create` and `lua version promote <n>` so the live agent version includes it ([Releasing](/ship/releasing)).
  </Step>

  <Step title="Update or remove it">
    `update` changes an installed skill's version or env values; `uninstall` removes it.

    ```bash theme={null}
    lua marketplace skill update --skill-name order-lookup --version-id <version-id> --ci
    lua marketplace skill update --skill-name order-lookup --env-vars "SHOP_API_KEY=sk_live_def456" --ci
    lua marketplace skill uninstall --skill-name order-lookup --force --ci
    ```

    `--skill-name` matches the installed skill's name or title. `update` needs `--version-id` or `--env-vars`, and exits 2 with `No update specified. Provide --version-id or --env-vars.` without either.
  </Step>

  <Step title="Verify">
    `installed` lists the marketplace skills on the current agent.

    ```bash theme={null}
    lua marketplace skill installed --json --ci
    ```

    With installs, `--json` prints one object per skill, each including `id`, `name`, `title`, `marketplaceSkillId`, `activeVersionId`, and `description`. With none, it prints a text line rather than `[]`.

    ```text Output theme={null}
    📦 No marketplace skills installed on this agent.
    ```
  </Step>
</Steps>

## If it isn't working

<Accordion title="✖ not_found: Installed skill not found: order-lookup">
  `update` and `uninstall` match `--skill-name` against installed marketplace skills only; the hint lists them. A skill your project pushed is not a marketplace install.
</Accordion>

<Accordion title="A private skill returns not-found">
  A private listing is visible only to its owning organization; `search`, `view`, and `install` answer not-found elsewhere. Ask the owner to transfer it or list a public copy.
</Accordion>

<Accordion title="Can only install approved versions">
  The version is still in review or was rejected. `view` shows how many versions are published; install one of those, or wait for the review.
</Accordion>

## Next steps

<Columns cols={2}>
  <Card title="lua marketplace" href="/reference/cli/marketplace">Every skill action, flag, and exit code.</Card>
  <Card title="Skills and tools" href="/concepts/skills-and-tools">What a skill is and how its context reaches the prompt.</Card>
  <Card title="Publish a template" href="/marketplace/publish-a-template">Publish a whole agent instead of one skill.</Card>
  <Card title="Releasing" href="/ship/releasing">Make an installed skill live with an agent version.</Card>
</Columns>