---
title: "Discover and load skills"
url: "https://docs.alisx.com/how-to/skill-store/discover-and-load-skills/"
---
# Discover and load skills

Find the skill that covers a task, load it for your agent, and author, evaluate, share and improve skills of your own.

## Prerequisites

- A signed-in CLI.
- For authoring: a coding agent installed, for evaluations.

## Find and load a skill

1. Search by meaning, not keywords. Quote the query:

    ```bash title="Terminal"
    alis skills search "deploy a service to production" --json --limit 3
    ```

    The result's `queriedSkills[]` carries `id`, `displayName`, `description`, `version`, `source` and `samplePrompt`.

2. Check the fit cheaply before spending tokens on the whole document:

    ```bash title="Terminal"
    alis skills preview <id>
    ```

3. Load it. The markdown prints verbatim; an agent reads it and follows it over guesswork:

    ```bash title="Terminal"
    alis skills load <id> --json
    ```

    ```json
    {"markdown": "…"}
    ```

    Inside a coding session the load is attributed to the session automatically (`$CLAUDE_SESSION_ID`, then `$ALIS_SESSION_ID`). Offline, a previously loaded copy is served from the cache with a note on stderr.

4. Fetch a file the instructions reference, with the path exactly as written:

    ```bash title="Terminal"
    alis skills resource <id> references/checklist.md
    ```

    `alis skills resource <id> --all --out <folder>` writes the whole bundle.

5. Nothing fits? Ask the Alis Build team for one:

    ```bash title="Terminal"
    alis skills request --name "…" --description "…" --use-case "…"
    ```

`alis skills list` is for browsing by eye; `alis skills explain` describes the whole system and, with `--json`, lists every capability with its command.

## Keep a local copy for your agent

Skills load live, so nothing needs installing. When you want a complete copy in your agent's native skill folder:

```bash title="Terminal"
alis skills install <id> --harness claude
alis skills installed
alis skills upgrade --all
alis skills uninstall <id>
```

## Author a skill

1. Create a workspace. It lives under `~/.alis/skills/workspaces/<id>/`:

    ```bash title="Terminal"
    alis skills create my-skill --description "…" --sample-prompt "…"
    ```

    Or start from work you just finished: `alis skills capture my-skill --session last`. Or import a public GitHub folder: `alis skills import https://github.com/<owner>/<repo>/tree/<branch>/<folder>`.

2. Edit `SKILL.md` (and optional `references/`, `scripts/`, `assets/`). Put the phrases people would type in double quotes in the description.

3. Evaluate it with real headless agent runs:

    ```bash title="Terminal"
    alis skills evaluate my-skill --init
    alis skills evaluate my-skill --baseline --json
    ```

    Results land in `evals/runs/<timestamp>/`; `evals/` never publishes.

4. Publish:

    ```bash title="Terminal"
    alis skills publish my-skill
    ```

    Publish validates the front matter, blocks on detected secrets and refuses the starter's TODO sample prompt. Exit 3 with `remote_changed` means the registry moved since you installed the workspace: `--force` overwrites, or `alis skills edit my-skill --refresh` rebases.

5. Share it. New skills start private:

    ```bash title="Terminal"
    alis skills share my-skill --domain
    alis skills share my-skill --email ana@example.com
    ```

Buildable code (templates, a Dockerfile, Terraform) belongs in a code block, not in a skill; the block's `.skill/` folder becomes its skill. A skill that does carry `templates/` is materialised with `alis skills apply <id> --into <folder> --set name=value --yes`.

## Give feedback and improve a skill

1. Report a gap. It opens a conversation with the skill's maintainers:

    ```bash title="Terminal"
    alis skills feedback <id> --rating down "the deploy step skips --plan-only"
    ```

    `alis specialist send-session --ticket <t>` attaches the agent session that hit it.

2. As the owner, turn the feedback into a revision with your agent, then evaluate and publish:

    ```bash title="Terminal"
    alis skills improve <id> --ticket <t> --json
    alis skills evaluate <id> --baseline
    alis skills publish <id>
    ```

    Publish drafts a note on each answered feedback conversation. Not the owner? `alis skills improve <id> --propose` forks it and `alis skills propose <id>` sends the owner your patch.

3. Read the trail:

    ```bash title="Terminal"
    alis skills history <id>
    ```

In the TUI, ++shift+l++ opens the Skills page and ++plus++ starts the guided create, edit, evaluate, publish, share walkthrough.

Related: [How skills work](https://docs.alisx.com/explanation/skills.md), [alis skills](https://docs.alisx.com/reference/cli/skills.md), [Agents, skills and the CLI](https://docs.alisx.com/explanation/agents-skills-cli.md).