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

# Skills

> Create, version, and manage reusable skill packages with the Guild CLI.

Skills are reusable content packages that teach agents how to perform specific tasks. Each skill contains markdown instructions that get injected into an agent's context at runtime, giving it domain-specific knowledge — like a tone guide, a compliance checklist, or a debugging runbook. The agent only sees the title and description, allowing for it to understand when to inject the body content into its context.

Skills are **owner-scoped** (owned by a user or organization), **versioned** with semantic versioning, and **private by default**.

## Create a skill

```bash theme={null} theme={null}
guild skill create <name>
```

In interactive mode, the CLI prompts you for an overview. You can also pass it directly:

```bash theme={null} theme={null}
guild skill create tone-guide --overview "Brand voice and messaging guidelines"
```

| Flag                | Description                                                                 |
| ------------------- | --------------------------------------------------------------------------- |
| `--owner <account>` | Owner account name or ID. Defaults to your account.                         |
| `--overview <text>` | Short description for display and search. Required in non-interactive mode. |
| `--public`          | Make the skill visible to all users. Requires admin privileges.             |

The skill is created with a **qualified name** in the format `owner~skill-name` (e.g. `myorg~tone-guide`). Use this name to reference the skill in other commands.

Skill names must start with a lowercase letter (`a-z`). After the first character, names can contain lowercase letters, numbers, hyphens (`-`), underscores (`_`), and periods (`.`). Names are limited to 100 characters.

## Add a version

Skills use semantic versioning. Each version contains the markdown body — the actual instructions an agent receives at runtime.

```bash theme={null} theme={null}
guild skill version create myorg~tone-guide \
  --version-number 1.0.0 \
  --description "Guides the agent to use brand-appropriate tone and messaging" \
  --body-file tone-guide.md
```

| Flag                        | Description                                                                                                  |
| --------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `--version-number <semver>` | Semantic version (e.g. `1.0.0`). Must be greater than the latest existing version.                           |
| `--description <text>`      | Tells the runtime when to activate this skill. This is what the LLM sees to decide if the skill is relevant. |
| `--body <text>`             | Inline markdown content.                                                                                     |
| `--body-file <path>`        | Read the markdown content from a file.                                                                       |

<Tip>
  The **description** is runtime-facing — it tells the agent *when* to use the
  skill. The skill's **overview** is human-facing — it appears in search results
  and listings. Keep them distinct.
</Tip>

In interactive mode (TTY without flags), the CLI prompts for each field.

### List versions

```bash theme={null} theme={null}
guild skill version list myorg~tone-guide
```

Versions are listed newest-first. Use `--limit` and `--offset` for pagination.

### Get version details

```bash theme={null} theme={null}
guild skill version get <version-id>
```

## Manage skills

### Get skill details

```bash theme={null} theme={null}
guild skill get myorg~tone-guide
```

You can also pass a skill UUID instead of the qualified name.

### List skills

```bash theme={null} theme={null}
guild skill list
guild skill list --search "tone"
guild skill list --sort updated
guild skill list --owner myorg
```

| Flag                | Description                                       |
| ------------------- | ------------------------------------------------- |
| `--search <query>`  | Search by name, overview, or owner.               |
| `--sort <field>`    | Sort by `name` (default), `updated`, or `newest`. |
| `--owner <id>`      | Filter by owner account.                          |
| `--limit <number>`  | Results per page (default 20).                    |
| `--offset <number>` | Pagination offset.                                |

### Search skills

Use `guild skill search` to find skills by keyword across names, overviews, and owners.

```bash theme={null}
guild skill search "compliance"
guild skill search "tone guide" --published
guild skill search "runbook" --sort newest --limit 10
```

| Flag                | Description                                       |
| ------------------- | ------------------------------------------------- |
| `--sort <field>`    | Sort by `updated` (default), `newest`, or `name`. |
| `--published`       | Only show published skills.                       |
| `--limit <number>`  | Number of results to return (default: 20).        |
| `--offset <number>` | Offset for pagination (default: 0).               |

The default output is a formatted table. Pass `--json` to receive a JSON response with `items` and `pagination` fields.

### Update a skill

```bash theme={null} theme={null}
guild skill update myorg~tone-guide --overview "Updated brand voice guidelines"
guild skill update myorg~tone-guide --public
guild skill update myorg~tone-guide --no-public
```

| Flag                | Description                             |
| ------------------- | --------------------------------------- |
| `--overview <text>` | Update the description.                 |
| `--public`          | Make the skill public (requires admin). |
| `--no-public`       | Make the skill private.                 |

### Archive and unarchive a skill

Archiving a skill removes it from the catalog. Agents can no longer discover or activate it until you unarchive it.

```bash theme={null}
guild skill archive myorg~tone-guide
guild skill unarchive myorg~tone-guide
```

Archived skills are not deleted. All versions remain intact and the qualified name is preserved.

## Visibility and permissions

Skills are **private by default**. Only the owner and their organization members can view and use them.

Making a skill public requires **account admin** privileges. Public skills are visible to all Guild users.

| Action            | Who can do it                                        |
| ----------------- | ---------------------------------------------------- |
| Create            | Owner or account admin                               |
| View              | Owner, organization members, or everyone (if public) |
| Update            | Owner or account admin                               |
| Create version    | Owner or account admin                               |
| Archive/Unarchive | Owner or account admin                               |

## Typical workflow

```bash theme={null} theme={null}
# 1. Create the skill
guild skill create compliance-checklist \
  --overview "SOC 2 compliance checks for code review"

# 2. Write your skill content
# (create a markdown file with the instructions)

# 3. Publish the first version
guild skill version create myorg~compliance-checklist \
  --version-number 1.0.0 \
  --description "Use when reviewing code for SOC 2 compliance violations" \
  --body-file compliance-checklist.md

# 4. Iterate — update content and bump the version
guild skill version create myorg~compliance-checklist \
  --version-number 1.1.0 \
  --description "Use when reviewing code for SOC 2 compliance violations" \
  --body-file compliance-checklist-v2.md
```

## JSON output

All skill commands support `--json` for machine-readable output:

```bash theme={null} theme={null}
guild skill list --json
guild skill get myorg~tone-guide --json
guild skill version list myorg~tone-guide --json
```