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

> ## Agent Instructions
> To act on Atlan objects, use the Atlan MCP server at https://api.atlan.com/mcp or the atlanai CLI; `atlanai --map json` prints its command map. Run a read-only identity check before any write.
> The docs MCP server at /mcp searches these docs only. It cannot read or change Atlan objects.
> SDK packages: Python `atlanai` (PyPI) and TypeScript `@atlanai/sdk` (npm). Show Python first, then TypeScript.

# 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`. |
| `--branch-guard` | string | none | Refuse publishing unless this branch is checked out. This is a caller-supplied check, not manifest configuration. |
| `--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
```

## 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.
* `publish` waits up to 60 seconds for each security scan. A blocked scan fails;
  an unsettled scan warns and returns success while the skill remains unavailable.
* Repository install and publish use the same OAuth or `ATLANAI_TOKEN`
  credential as other CLI commands.
* In GitHub, configure branch and trigger policy in `on.push.branches` and
  protect that branch in GitHub. `--branch-guard` is only an explicit
  caller-supplied check; there is no manifest branch field or separate CI mode.
* `--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](/tools/cli/how-tos/skills)
* [Sync skills from GitHub](/registry/skills/how-tos/sync-from-github)
* [`atlanai context`](/tools/cli/references/commands/context)
* [`atlanai file`](/tools/cli/references/commands/file)