> ## 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.

# lua skills

> List local and production skills, make a pushed skill version live, or delete a skill

`lua skills` lists the [skills](/concepts/skills-and-tools) in `lua.skill.yaml` and on the server, makes a pushed skill version live in production, and deletes skills. `deploy` and `delete` change what the agent can do for every end user as soon as they succeed.

*Verified against lua-cli 3.33.0.*

## Synopsis

```bash theme={null}
lua skills [sandbox|production] [view|versions|deploy|delete] [--skill-name <name>] [--skill-version <ver>|latest]
```

## Description

The first argument is an environment or an action. With no arguments the command asks for an environment and opens a menu. An action given without an environment runs against production and never prompts; that is the form for scripts and coding agents.

`view` lists every skill in `lua.skill.yaml` with its ID, whether a version is deployed, and when. `lua skills sandbox view` prints one line per local skill (`📦 <name>  (<skillId>)`) and exits. Any other `sandbox` form opens a menu that only refreshes the list and points you to [`lua compile`](/reference/cli/compile) and [`lua push skill`](/reference/cli/push).

`lua skills production` opens the production menu. An action after `production` is validated but does not skip the menu, so `lua skills production view` still prompts and fails under `--ci`. Use `lua skills view`.

`versions` does not list skill versions. Per-primitive history is managed by [agent versions](/concepts/releases-and-versions), so it prints a pointer to [`lua version list`](/reference/cli/version).

`deploy` makes one pushed version of the skill live from the agent's next turn. It is the same operation as `lua deploy skill --name <name> --set-version <ver> --force`; [`lua deploy`](/reference/cli/deploy) additionally records the deployed version in `lua.skill.yaml`. Neither creates an agent version, so the next `lua version promote` resets the skill to the version pinned in the promoted agent version; for a durable change, or when a change touches more than one primitive, run `lua version create` and `lua version promote` (see [Release an agent](/ship/releasing)). Non-interactive `deploy` runs without a confirmation prompt.

`delete` removes the skill from the server. A skill that has pushed versions is deactivated instead of deleted and stays in `lua.skill.yaml` until you remove it. `delete` also resolves skills that exist only on the server.

Every form needs a project directory (`lua.skill.yaml` with an `agentId`) and a credential; see [`lua auth`](/reference/cli/auth).

## Arguments

| Argument      | Values                                                          | Description                                                                         |
| ------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `actionOrEnv` | `sandbox`, `production`, `view`, `versions`, `deploy`, `delete` | An environment opens its menu; an action runs against production without prompting. |
| `action`      | `view`, `versions`, `deploy`, `delete`                          | Only `sandbox view` runs non-interactively.                                         |

Accepted spellings: `staging`, `stage`, `sb` → `sandbox`; `prod`, `prd`, `live` → `production`; `show`, `info` → `view`; `list-versions`, `history` → `versions`; `publish` → `deploy`; `rm`, `remove`, `del` → `delete`. Anything else exits `2` with the valid values.

## Options

| Option                  | Description                                                                          | Default |
| ----------------------- | ------------------------------------------------------------------------------------ | ------- |
| `--skill-name <name>`   | Skill name or ID. Required for `versions`, `deploy`, and `delete`.                   | —       |
| `--skill-version <ver>` | Version to deploy, or `latest` for the newest pushed version. Required for `deploy`. | —       |
| `--ci`                  | Global flag. Refuse any prompt with exit `1` instead of waiting for input.           | off     |

## Examples

List the production skills and whether each is deployed.

```bash theme={null}
lua skills view
```

```text Output theme={null}
============================================================
⚙️  Production Skills
============================================================

📦 tickets
   Skill ID: 0c7927ec-ffc5-40ad-b76e-63cba81e1390
   Deployed ⭐
   Deployed: 12/09/2026, 13:49:44

============================================================
```

Print the skills in `lua.skill.yaml`, one per line.

```bash theme={null}
lua skills sandbox view
```

```text Output theme={null}
📦 tickets  (0c7927ec-ffc5-40ad-b76e-63cba81e1390)
```

Ask for a skill's version history; the answer points at agent versions.

```bash theme={null}
lua skills versions --skill-name tickets
```

```text Output theme={null}
============================================================
📜 Versions for tickets
============================================================

ℹ️  Primitive versions are managed by agent versioning. Run `lua version list` to view agent versions.

============================================================
```

Make the newest pushed version live from CI.

```bash theme={null}
lua skills deploy --skill-name tickets --skill-version latest --ci
```

Delete a skill from CI; a skill with versions is deactivated instead.

```bash theme={null}
lua skills delete --skill-name tickets --ci
```

## Exit codes

| Code | Meaning     | When                                                                                                                                 |
| ---- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `0`  | OK          | The action completed, including `delete` that deactivated instead.                                                                   |
| `1`  | Error       | The server refused the deploy or delete, `--skill-version` names a version that does not exist, or a prompt was needed under `--ci`. |
| `2`  | Usage       | Unknown action or environment, or a required `--skill-name` / `--skill-version` is missing.                                          |
| `3`  | Not found   | The skill is not in `lua.skill.yaml` (nor on the server, for `delete`), or it has no pushed versions to deploy.                      |
| `9`  | Auth        | No valid credential.                                                                                                                 |
| `10` | Forbidden   | The credential cannot manage this agent.                                                                                             |
| `11` | Unavailable | Network error or a server 5xx.                                                                                                       |

The full table, including the error line format, is in [Errors and exit codes](/reference/cli/errors-and-exit-codes).

## See also

* [`lua deploy`](/reference/cli/deploy) — the same deploy with the agent version reported
* [`lua push`](/reference/cli/push) — push a skill version
* [`lua version`](/reference/cli/version) — agent versions, promote, and rollback
* [`lua production`](/reference/cli/production) — production summary including skill versions
* [Release an agent](/ship/releasing)