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

# atlanai skill

> Manage skill artifacts, versions, governance, and repository packages.

Skill commands cover direct Registry lifecycle and repository-managed skill
dependencies. Start with `validate` or read commands before changing Registry
state.

## Commands

### list

Lists visible skill artifacts in one workspace or across the account.

**Usage**

```text theme={null}
atlanai skill list [flags]
```

| Option                         | Type                   | Default        | Description                                    |
| ------------------------------ | ---------------------- | -------------- | ---------------------------------------------- |
| `--workspace`, `-w`            | string                 | account-wide   | Scope to one workspace.                        |
| `--all-workspaces`, `-A`       | Boolean                | `false`        | Make account-wide intent explicit.             |
| `--filter`                     | expression, repeatable | none           | Filter fields with comparison operators.       |
| `--fields`                     | string list            | none           | Return selected fields.                        |
| `--sort`                       | string, repeatable     | server default | Sort by field; prefix with `-` for descending. |
| `--limit`, `-L`                | integer                | server default | Maximum results, up to `500`.                  |
| `--include-system`             | Boolean                | `false`        | Include system-owned skills.                   |
| `--json`, `--jq`, `--template` | output controls        | human table    | Select and format structured output.           |

### get

Gets the latest or a selected version of one skill artifact.

**Usage**

```text theme={null}
atlanai skill get <id> [--version <ordinal>] [output flags]
```

Shows the latest version unless `--version` is provided.

### versions

Lists every retained version for a skill ID.

**Usage**

```text theme={null}
atlanai skill versions <id> [output flags]
```

### runs

Shows governance actions recorded for a skill.

**Usage**

```text theme={null}
atlanai skill runs <id> [output flags]
```

JSON output can include `action_name`, `attempt`, `gate_outcome`, `id`,
`run_status`, `target_kind`, and `version_ordinal`.

### validate

Checks a local skill directory against server rules without contacting the
Gateway.

**Usage**

```text theme={null}
atlanai skill validate <dir>
```

Reports every validation problem in one run.

### push

Creates a Registry skill or appends a version from a local directory.

**Usage**

```text theme={null}
atlanai skill push <dir> [flags]
```

| Option              | Type    | Default        | Description                                              |
| ------------------- | ------- | -------------- | -------------------------------------------------------- |
| `--workspace`, `-w` | string  | active context | Workspace for a new skill.                               |
| `--dry-run`         | Boolean | `false`        | Show the plan and stop.                                  |
| `--auto-approve`    | Boolean | `false`        | Upload without prompting.                                |
| `--force`           | Boolean | `false`        | Upload even when the remote changed since the last push. |

The command creates a skill or appends a version. Unchanged content is not
uploaded again.

### pull

Downloads the latest or a selected skill version into a local directory.

**Usage**

```text theme={null}
atlanai skill pull <id> [dir] [flags]
```

| Option      | Type    | Default | Description                       |
| ----------- | ------- | ------- | --------------------------------- |
| `--version` | integer | latest  | Pull a version ordinal.           |
| `--force`   | Boolean | `false` | Overwrite unpushed local changes. |

The destination defaults to a directory chosen from the skill. Pull stops when
the target contains unpushed changes unless `--force` is supplied.

### link

Associates a local directory with an existing Registry skill.

**Usage**

```text theme={null}
atlanai skill link <dir> <id> [--confirm]
```

`link` associates a directory with an existing Registry skill so later pushes
append versions. It compares local and remote contents first; `--confirm`
accepts a mismatch without prompting.

### unlink

Removes the local association without deleting files or Registry data.

**Usage**

```text theme={null}
atlanai skill unlink <dir>
```

### install

Installs the repository's declared skill dependencies.

**Usage**

```text theme={null}
atlanai skill install [dir]
```

Finds `.atlan/package.json`, clones the token-scoped marketplace, verifies
registered digests, copies selected skills to `.atlan/skills`, writes the lock
file, and creates configured coding-agent links. `[dir]` defaults to the current
directory.

### publish

Publishes repository-managed skills to their configured workspaces.

**Usage**

```text theme={null}
atlanai skill publish [dir] [flags]
```

| Option              | Type               | Default                      | Description                                                                 |
| ------------------- | ------------------ | ---------------------------- | --------------------------------------------------------------------------- |
| `--workspace`, `-w` | string, repeatable | `publishConfig` destinations | Override publish destinations.                                              |
| `--changed-since`   | commit             | none                         | Publish only skills changed between this commit and `HEAD`.                 |
| `--ci`              | Boolean            | `false`                      | Never prompt, enforce the branch guard, and print an audit summary.         |
| `--branch-guard`    | string             | `publishConfig.branch`       | Refuse publishing from another branch. An explicit empty value disables it. |
| `--prune`           | Boolean            | `false`                      | Archive repo-owned skills removed from the checkout.                        |

### hooks

Installs or removes the repository's Atlan-managed publishing hook.

**Usage**

```text theme={null}
atlanai skill hooks <command>
atlanai skill hooks install [dir]
atlanai skill hooks uninstall [dir]
```

`install` adds the configured pre-push publisher and refuses to overwrite
unrelated hooks or shared hook directories. `uninstall` removes only the
Atlan-managed hook.

### rollback

Restores an earlier skill version by appending its contents as a new version.

**Usage**

```text theme={null}
atlanai skill rollback <id> --to <version> [flags]
```

| Option           | Type    | Default  | Description                                        |
| ---------------- | ------- | -------- | -------------------------------------------------- |
| `--to`           | integer | required | Version ordinal whose contents should be restored. |
| `--dry-run`      | Boolean | `false`  | Show the new-version plan and stop.                |
| `--auto-approve` | Boolean | `false`  | Append the restored version without prompting.     |

Rollback appends a new version with the selected contents. It does not rewrite
or delete later versions.

### approve

Clears the review flag on a security-blocked skill.

**Usage**

```text theme={null}
atlanai skill approve <id> [--confirm]
```

Inspect `skill runs <id>` first. Approval does not remove the finding.

### delete

Archives a skill while retaining all versions.

**Usage**

```text theme={null}
atlanai skill delete <id> [--confirm]
```

Structured artifact reads support `--json`, `--jq`, and `--template`. Valid
artifact fields are `artifact_status`, `created_at`, `description`, `id`,
`is_latest`, `is_system`, `kind`, `metadata`, `name`, `source_digest`,
`updated_at`, `version_ordinal`, and `workspace_id`.

## Examples

```bash theme={null}
atlanai skill validate ./skills/review
atlanai skill push ./skills/review --dry-run
atlanai skill list --workspace workspace_123 --json id,name,artifact_status
atlanai skill rollback skill_123 --to 3 --dry-run
atlanai skill publish --changed-since HEAD~1 --ci
```

## Output and behavior

* Read commands return tables by default and exit `0` for empty results.
* `push`, `rollback`, `approve`, and `delete` prompt before changing Registry
  state unless their explicit confirmation option is supplied.
* A blocked upload remains inspectable through `runs` and can require approval
  before use.
* Repository install and publish use the same OAuth or `ATLANAI_TOKEN`
  credential as other CLI commands.
* `--force`, `--auto-approve`, `--confirm`, and `--prune` remove safety checks;
  use them only after resolving the exact target and expected change.

## Related

* [Manage skills with the CLI](/cli/skills)
* [Sync skills from GitHub](/guides/skills/sync-from-github)
* [`atlanai context`](/cli/reference/context)
* [`atlanai file`](/cli/reference/file)