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

# Skills

> Upload, update, and download agent skills as files.

`gumloop skills` lets you manage agent [skills](/core-concepts/skills) as files on disk. Each skill is one or more files (markdown, JSON, anything) that an agent can read at runtime.

## List skills

```bash theme={"dark"}
gumloop skills list
gumloop skills list --search retrieval --limit 50
```

Prints `ID`, `NAME`, `TEAM`, `USAGE` (usage count), and `UPDATED`. If the response is paginated, the next cursor is printed at the bottom.

| Flag       | Description                                           |
| ---------- | ----------------------------------------------------- |
| `--search` | Filter skills by query string.                        |
| `--server` | Filter to skills related to a specific MCP server ID. |
| `--limit`  | Maximum number of skills to return.                   |
| `--cursor` | Pagination cursor from a previous list call.          |
| `--json`   | Print the raw response payload.                       |

## Create a skill

Upload one or more files as a new skill:

```bash theme={"dark"}
gumloop skills create ./my-skill.md
gumloop skills create skills/*.md
```

The skill is created with all of the provided files atomically. The new skill ID is printed on success.

## Update a skill

Replace the files attached to an existing skill:

```bash theme={"dark"}
gumloop skills update skill_abc ./new-version.md
```

<Warning>
  `update` is a **full replace**, not a merge. Any file that was attached to the skill but isn't in the new upload is removed. To add a file without losing the existing ones, pass all of them: `gumloop skills update skill_abc existing.md new.md`.
</Warning>

<Tip>Grab the skill ID from `gumloop skills list`.</Tip>

## Download a skill

```bash theme={"dark"}
gumloop skills download skill_abc
```

By default the file is written to the current directory under its original filename. Override the destination with `-o`:

| Flag             | Description                                                |
| ---------------- | ---------------------------------------------------------- |
| `-o`, `--output` | File or directory to write to. Use `-` to write to stdout. |
| `--version-id`   | Download a specific skill version.                         |
| `--json`         | Print download metadata as JSON (path + bytes).            |

```bash theme={"dark"}
gumloop skills download skill_abc -o ./local-name.md
gumloop skills download skill_abc -o -                    # write to stdout
gumloop skills download skill_abc --version-id skv_xyz
```