---
title: "alis skills"
url: "https://docs.alisx.com/reference/cli/skills/"
---
# alis skills

Discover and load Alis Build skills: curated instruction documents, each teaching an agent how to do one thing well. Author, evaluate, share, install and improve your own.

## Synopsis

```bash
alis skills apply <id> --into <folder> [flags]
alis skills capture <id> [flags]
alis skills contribute <id> [flags]
alis skills create <id> [flags]
alis skills edit <id> [flags]
alis skills evaluate <id> [flags]
alis skills explain [flags]
alis skills feedback <id> [message...] [flags]
alis skills history <id> [flags]
alis skills import <github-folder-url> [flags]
alis skills improve <id> [flags]
alis skills install <id> [flags]
alis skills installed [flags]
alis skills list [flags]
alis skills load <id> [flags]
alis skills open <id> [flags]
alis skills preview <id> [flags]
alis skills propose <id> [flags]
alis skills publish <id> [flags]
alis skills request [flags]
alis skills resource <id> <path> | resource <id> --all --out <folder> [flags]
alis skills search <query> [flags]
alis skills share <id> [flags]
alis skills owners <id>
alis skills owners add|remove|transfer <id> <email>
alis skills suggest [prompt] [flags]
alis skills sync [flags]
alis skills uninstall <id> [flags]
alis skills unpublish <id> [flags]
alis skills upgrade [<id>...] [flags]
```

Aliases: `skills`, `skill`.

## Description

The agent workflow is search, load, resource: `search` ranks the catalogue semantically, `load` prints the chosen skill's markdown to follow, `resource` fetches a file the instructions reference. `list` is for human browsing. When nothing fits, `request` asks the Alis Build team for a new skill.

Skills load live from the registry; `install` installs a complete copy into a coding agent's native skill directory. A skill is a document: buildable code belongs in a code block, whose `.skill/` folder is published as `block-<block-id>`. A skill that carries `templates/` is materialised with `apply`.

Without the skills surface on the backend every `alis skills` command exits 1 with `backend_outdated`; use the MCP skills tools then.

## Discovery

### alis skills search

Search the skills catalogue semantically and print the matching skills, best match first. Quote multi-word queries.

```bash
alis skills search <query> [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--limit <n>` | int | `8` | Maximum results to print (0 = everything the registry returns). |

`--json` returns `queriedSkills[]` with `id`, `description`, `displayName`, `version`, `loadCount`, `source` (`USER`, `BLOCK`, `EXTERNAL_REPO`, …), `snippet`, `vetVerdict`, `vetScore`, `sourceUri` and `samplePrompt`; empty fields are omitted.

### alis skills load

Load the skill's markdown instructions and print them verbatim. When the registry is unreachable, a previously loaded copy is served from the local cache with a staleness note on stderr.

```bash
alis skills load <id> [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--session <id>` | string | the coding agent session that ran the command | Coding-session id to attribute this load to. |
| `--via <surface>` | string | | Discovery surface that routed this load: `stub`, `dispatcher`, `hook_hint`. |

`--json` returns `{"markdown": "…"}`.

### alis skills resource

Fetch one resource file belonging to a skill; `<path>` is the file's path exactly as written in the instructions. `--all --out <folder>` writes the skill's complete bundle into a folder instead.

```bash
alis skills resource <id> <path> | resource <id> --all --out <folder> [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--all` | bool | false | Write the whole bundle to `--out` instead of printing one file. |
| `--out <folder>` | string | | Folder to write the bundle into (with `--all`). |

### alis skills preview

Print a skill's description, heading outline, the first part of its instructions and its resource files: enough to decide whether it fits, at a fraction of the tokens of a full load. Not counted as a load.

```bash
alis skills preview <id> [flags]
```

No flags beyond the global flags.

### alis skills list

List every skill you can access, sorted by id, for human browsing.

```bash
alis skills list [flags]
```

No flags beyond the global flags.

### alis skills explain

Print a caller-scoped explanation of the Skills system: what skills are, the loop, how many skills exist, the most popular ones, and a catalogue of every capability with its command. `--json` returns the structured contract; agents enumerate its `capabilities` list.

```bash
alis skills explain [flags]
```

No flags beyond the global flags.

### alis skills request

Ask the Alis Build team for a skill that does not exist yet. Non-interactive.

```bash
alis skills request [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--description <text>` | string | | What the skill should teach (required). |
| `--name <title>` | string | | Short title for the requested skill (required). |
| `--notes <text>` | string | | Anything else the skill author should know. |
| `--use-case <text>` | string | | The concrete situation that needed this skill. |

## Ambient discovery

### alis skills suggest

Suggest up to a few skills relevant to a prompt, from the local catalogue snapshot. The default path is purely local; plan mode spends a bounded call on the registry and falls back locally. `--hook` reads a Claude Code `UserPromptSubmit` JSON payload from stdin and emits hook output; it never fails.

```bash
alis skills suggest [prompt] [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--harness <name>` | string | `claude` | Hook output shape: `claude`/`gemini` (JSON envelope) or `codex`/`opencode` (plain text). |
| `--hook` | bool | false | Read a `UserPromptSubmit` payload from stdin and emit hook output. |
| `--limit <n>` | int | `3` | Maximum suggestions for the direct form. |
| `--mode <mode>` | string | | Override the permission mode for the direct form (`plan` = server-backed). |

### alis skills sync

Refresh the local catalogue snapshot used by ambient suggestions when its 24-hour cache is stale. Run by coding agent plugins at session start; it never changes the coding agent's native skills beyond removing retired sync-managed entries.

```bash
alis skills sync [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--force` | bool | false | Refresh from the registry even when the cache is fresh. |
| `--harness <name>` | string | `claude` | Coding agent whose local entries are inspected. |
| `--status` | bool | false | Show installed skills and catalogue cache age. |

## Local copies

### alis skills install

Install a skill's complete package into the native skill directory of every supported coding agent selected in your build profile: Antigravity (`~/.gemini/config/skills`), Claude (`~/.claude/skills`), Codex (`~/.agents/skills`), Gemini (`~/.gemini/skills`), OpenCode (`~/.config/opencode/skills`) and Cursor (`~/.cursor/skills`).

```bash
alis skills install <id> [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--force` | bool | false | Replace an existing unmanaged folder at the target. |
| `--harness <name>` | strings | every supported agent in your profile | Coding agent to install into (repeatable). |
| `--project` | bool | false | Install into the current repo's project scope instead of your user scope. |

Errors: `harness_not_found`, `unmanaged_target` (`--force` takes it over).

### alis skills installed

List every skill this CLI installed into a local coding agent.

```bash
alis skills installed [flags]
```

No flags beyond the global flags.

### alis skills upgrade

Refresh installed copies whose published content moved on.

```bash
alis skills upgrade [<id>...] [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--all` | bool | false | Update every installed skill. |

### alis skills uninstall

Remove the CLI-managed local entries for a skill. The skill stays in the catalogue.

```bash
alis skills uninstall <id> [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--harness <name>` | string | | Only remove from this coding agent. |
| `--project` | bool | false | Only remove project-scope entries. |

Error: `not_installed`.

## Authoring

### alis skills create

Create a local workspace for a new skill you own at `~/.alis/skills/workspaces/<id>/`: a starter `SKILL.md` plus optional `references/`, `scripts/` and `assets/`. Ids are global (`skill_exists`). Every skill carries a "try it out" prompt as `metadata.sample-prompt` in the front matter; publish refuses the starter's TODO placeholder until you write it or remove the key. If the workspace already exists the command prints its path again.

```bash
alis skills create <id> [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--description <text>` | string | | One-sentence description seeded into `SKILL.md`. |
| `--from <path>` | string | | Seed the workspace from an existing local skill folder (a directory with a root `SKILL.md`). |
| `--name <name>` | string | the id | Display name for the skill. |
| `--sample-prompt <text>` | string | | The "try it out" prompt (`metadata.sample-prompt`). |

### alis skills capture

Start a skill from work you or your agent just finished. Registers the draft, scaffolds a capture-tuned workspace (distillation rubric and eval cases file) and prints where to write the distilled steps. `--session` drafts the skill from a past agent session.

```bash
alis skills capture <id> [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--description <text>` | string | | What it does plus "Use when …" triggers, seeded into `SKILL.md`. |
| `--focus <text>` | string | | One line on what the skill should teach (with `--session`). |
| `--mode <mode>` | string | `auto` in a terminal | With `--session`: `auto` (headless resume), `resume` (interactive) or `brief` (print the brief only). |
| `--name <name>` | string | the id | Display name. |
| `--session <id>` | string | | Draft from this agent session: a coding agent session id, or `last`. |

### alis skills edit

Install a skill you own or edit into a local workspace for editing. Only USER-source skills on which you are an owner or editor can be edited (`not_editable` otherwise; ask an owner for `alis skills share <id> --email <you> --role editor`). An existing workspace is kept as-is.

```bash
alis skills edit <id> [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--refresh` | bool | false | Discard the local workspace and reinstall the published version. |

### alis skills open

Print the skill's local workspace path and open it in your IDE.

```bash
alis skills open <id> [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--print` | bool | false | Print the workspace path without opening an IDE. |

### alis skills import

Import a skill from a public GitHub repository: point at the folder holding `SKILL.md` (the `/tree/` URL) and the whole folder becomes a skill of your own, published and ready to install, load or share. The source is remembered for `--refresh`.

```bash
alis skills import <github-folder-url> [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--draft` | bool | false | Import into the local workspace without publishing. |
| `--id <id>` | string | the folder name, slugified | Skill id. |
| `--name <name>` | string | the id | Display name. |
| `--refresh` | bool | false | Re-fetch a previously imported skill's source (the argument is then the skill id). |

### alis skills publish

Validate, package and publish the local workspace. The front matter's description becomes the searchable description. If the published skill changed since the workspace was installed the command exits 3 with `remote_changed`. Publish blocks on detected secrets and warns on home paths and emails. Local git history (never pushed) gets a commit tagged with the version. `evals/` never publishes. A block-derived skill is not published to the registry: publish applies the patch to the block's `.skill/` folder instead.

```bash
alis skills publish <id> [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--clean` | bool | false | Remove the local workspace after a successful publish (discards the wiki). |
| `--force` | bool | false | Publish even if the registry changed since the workspace was installed. |
| `--name <name>` | string | | Update the skill's display name. |
| `--no-notify` | bool | false | Do not draft a note on the feedback conversations this revision answered. |
| `--summary <text>` | string | the newest `wiki/log.md` entry | One line on what this version changes. |

### alis skills unpublish

Unpublish a USER-source skill you administer: it disappears from search, list and load; local files stay; publishing the id again restores it. `--forever` erases the registry copy and frees the id, irreversibly.

```bash
alis skills unpublish <id> [flags]
```

Aliases: `unpublish`, `delete`.

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--forever` | bool | false | Erase the skill from the registry and free the id (irreversible). |

### alis skills share

Share a skill you own with a colleague, with everyone at your email domain, with another build environment's domain or (Alis Build staff only) with every builder. With no flags, print who maintains the skill (owners, editors) and who it is shared with. Sharing with another domain asks for approval, and the domain must belong to an Alis Build account; public email providers are refused (`domain_share_refused`).

`--role` says what the share grants. The default, `user`, is read access: find and load. `editor` also grants edit and publish (`edit`, `publish`, `improve`), so a team maintains one skill together; publish still refuses a stale workspace (`remote_changed`), which is the concurrency guard co-maintainers rely on. `owner` makes a named person a co-owner with full control (see `alis skills owners`). Owners are always people (`--email`); the platform only ever gets read access. On a backend that predates roles the command fails with `backend_outdated` rather than report a grant that did not land.

```bash
alis skills share <id> [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--domain [<domain>]` | bool or string | | Share with everyone at your email domain; `--domain example.com` names another. |
| `--email <addr>` | string | | Share with the existing builder at this email address (`builder_not_found` when they are not a builder yet). |
| `--platform` | bool | false | Share with every builder on the platform (Alis Build staff only; `not_curator` otherwise). |
| `--role <role>` | string | user | What the share grants: `user` (find and load), `editor` (also edit and publish) or `owner` (full control; `--email` only). |
| `--remove` | bool | false | Remove the given access instead of granting it; `--role` names which grant. Removing the last owner is refused (`last_owner`). |

### alis skills owners

List, add, remove or transfer a skill's owners. Owners hold full control: they edit, publish, share and delete the skill and manage its owners and editors; skill feedback conversations route to the owners and the editors. With just an id, print the owners and editors. Only an owner can run the mutations (`not_owner` otherwise).

```bash
alis skills owners <id>
alis skills owners add <id> <email>       # make a builder a co-owner
alis skills owners remove <id> <email>    # take ownership away; the last owner stays (last_owner)
alis skills owners transfer <id> <email>  # hand the skill over; you stay on as an editor
```

A transfer is a destructive-class action under the automation tiers: it takes your own control away. For edit-and-publish access without ownership, use `alis skills share <id> --email <addr> --role editor`.

### alis skills contribute

Open a GitHub pull request back to the repo a skill was imported from, as you (GitHub connects once through your Alis profile; `github_not_connected` carries the auth URL). The PR is cut from the published content, so publish first. Re-running refreshes the open PR.

```bash
alis skills contribute <id> [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--body <text>` | string | | Extra pull request description, prepended to the generated summary. |
| `--dry-run` | bool | false | Show what would be contributed without opening a pull request. |
| `--force` | bool | false | Contribute even though upstream changed since your import. |
| `--title <text>` | string | derived from the skill | Pull request title. |
| `--yes` | bool | false | Skip the confirmation prompt. |

### alis skills apply

Copy a skill's `templates/` into a folder in one command. Dry-run by default: prints the plan (files to create, files that already exist, inputs still missing); `--yes` writes it. `--set name=value` fills `{{ .name }}` placeholders. An optional `generator.yaml` at the skill root declares typed `inputs`, a `files` map and post-apply `checks` (listed in `next[]`, never run). Unfilled placeholders are reported per file (`placeholdersRemaining`).

```bash
alis skills apply <id> --into <folder> [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--force` | bool | false | Overwrite files that already exist in the folder. |
| `--into <folder>` | string | | Folder to materialise into (created if missing). |
| `--set name=value` | stringArray | | Input value (repeatable); fills `{{ .name }}` placeholders. |
| `--yes` | bool | false | Write the files (default: print the plan only). |

Errors: `nothing_to_apply`, `inputs_missing` (`retry` carries the `--set` flags), `invalid_generator`.

## Quality loop

### alis skills evaluate

Run the workspace's eval cases (`evals/cases.yaml`): each case runs your coding agent headlessly in a clean sandbox with the skill available, and an LLM judge scores the output against the case's rubrics. Results land in `<workspace>/evals/runs/<timestamp>/`. Each coding agent runs with whatever credentials it already has; one without usable credentials is skipped.

```bash
alis skills evaluate <id> [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--baseline` | bool | false | Also run every case without the skill, for comparison. |
| `--case <id>` | string | | Run a single case by id. |
| `--harness <list>` | string | your preferred coding agent | Coding agents to run: comma-separated (`claude`, `codex`, `gemini`, `opencode`) or `all`. |
| `--init` | bool | false | Scaffold a starter `evals/cases.yaml` and exit. |
| `--timeout <duration>` | duration | `5m` | Timeout per headless run. |

Errors: `no_workspace`, `no_cases` (run `--init`).

### alis skills feedback

Send feedback about a skill. The platform routes it to the skill's owner (the Alis Build team for platform skills) as a conversation; repeat feedback lands on your existing open conversation. `--rating` with no message records just the rating. Continue the conversation in the TUI's support page.

```bash
alis skills feedback <id> [message...] [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--rating <up\|down>` | string | | Quick quality signal. |

### alis skills improve

Turn feedback into a skill revision. The workspace is prepared with the evidence (feedback conversations, the agent sessions shared on them, a local session, your notes) and your coding agent is handed a brief: record what went wrong in the skill's wiki, apply one minimal patch to `SKILL.md`, add an eval case per gap, and write the reply. The workspace keeps `raw/` (evidence, git-ignored), `wiki/` (the skill's memory, never published) and the skill itself. A skill you cannot publish is forked instead (`--propose`).

```bash
alis skills improve <id> [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--force` | bool | false | Proceed although the registry changed since the workspace was installed. |
| `--mode <mode>` | string | `auto` in a terminal | `auto` (headless run), `resume` (interactive) or `brief` (print the brief only). |
| `--note <text>` | stringArray | | A gap in your own words (repeatable). |
| `--propose` | bool | false | Fork a skill you cannot publish and prepare a proposal for its owner. |
| `--refresh` | bool | false | Re-install the skill layer (`wiki/`, `evals/` and `raw/` are kept). |
| `--session <id>` | string | | A local agent session that used the skill: a coding agent session id, or `last`. |
| `--source <folder>` | string | | Block-derived skills: the block's source service folder when it is not among your cloned products. |
| `--ticket <id>` | stringArray | | Feedback conversation to learn from (`tickets/<id>` or bare id; repeatable). |
| `--timeout <duration>` | duration | `15m` | Time limit for the headless run. |

Errors: `not_editable` (add `--propose`), `remote_changed` (exit 3), `improve_timeout`, `improve_failed` (`--mode resume`).

### alis skills propose

Post the changes in your local fork of a skill (made with `improve --propose`) to the skill's owner: a unified diff plus the pattern notes from your wiki, on your feedback conversation for that skill.

```bash
alis skills propose <id> [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--ticket <id>` | string | | Post on this conversation instead of your feedback conversation. |
| `--yes` | bool | false | Skip the confirmation prompt (same as `--approve`). |

### alis skills history

List a skill's revisions, newest first: version, publisher, a one-line summary, the feedback conversations it answered and the publisher's eval state at the time.

```bash
alis skills history <id> [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--limit <n>` | int32 | `20` | Maximum revisions to list. |

## Examples

```bash title="Terminal"
alis skills search "deploy a service to production" --json
alis skills preview dbd-add-protos
alis skills load dbd-add-protos --json
alis skills resource dbd-add-protos references/checklist.md
alis skills create my-skill --description "…" --sample-prompt "…"
alis skills evaluate my-skill --init
alis skills evaluate my-skill --baseline --json
alis skills publish my-skill
alis skills share my-skill --domain
alis skills install my-skill --harness claude
alis skills feedback my-skill --rating down "the deploy step skips --plan-only"
alis skills improve my-skill --ticket <id> --json
```

## Notes

- `unpublish`, `share --domain <another domain>` and `owners transfer` are destructive-class actions under the automation tiers.
- The skill bundle is capped at 8 MiB.
- Suggestions match the id, the display name and the double-quoted trigger phrases in a skill's description; quote what people type.