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

# Skills

> Install skills from a Markdown file, a folder or a git URL, keep some for your own use, and pin skills into a person's runs.

A skill is a written procedure that Stampede stores, versions and offers to the model: a name, a description, optional triggers and a Markdown body such as "how we cut a release". A run finds relevant skills on its own, and the model can search and load them with the `skill_search` and `skill_load` tools. A skill is text for the model; it cannot add a tool or relax a policy.

## Scopes and persons

Each skill lives in one scope:

| Scope | Who sees it |
| - | - |
| `project` | The person that installed it, in the project it was installed from (the git repository that holds the current directory). |
| `user` | The person that installed it, in every project. |
| `global` | Every person. |

Project and user skills belong to one person. To install a skill for a person other than the default, select it with `--person`:

```bash theme={null}
stampede --person builder skills install ./deploy-release.md
```

## Installing a skill

`stampede skills install SOURCE` takes a skill from one of three sources:

* a Markdown file;
* a folder holding `SKILL.md` (the Agent Skills layout);
* an `https://` or `ssh://` git URL.

```bash theme={null}
stampede skills install ./deploy-release.md --dry-run
stampede skills install ./skills/deploy-release
stampede skills install https://example.com/acme/skills.git --name deploy-release
stampede skills install ssh://git@example.com/acme/skills.git --path skills/deploy-release --ref v2
```

| Flag | Meaning |
| - | - |
| `--scope user` or `--scope project` | Where the skill goes. The default is `user`. |
| `--name NAME` | The skill's name, or which skill to take when the source holds several. |
| `--trigger T` | A phrase that should bring the skill up. Repeatable. |
| `--path SUBDIR` | A relative folder inside the source. It may not contain `..`. |
| `--ref REF` | A git branch or tag to clone instead of the default branch. |
| `--dry-run` | Print the summary without the body and write nothing. |
| `--confirm-install` | Answer yes without a terminal. The same text is printed first. |

Install prints the skill's name, scope, source, commit (for git), the sha256 of the body, its invocation, description and license, the front matter keys it ignored, each file of a folder it leaves out, and the active version it replaces. It says that the body is sent to your model profile for a smoke test, prints the body between fixed lines with every line prefixed `| `, and asks `install NAME? [y/N]`.

On yes it proposes the skill, runs a short smoke test on the evaluator model (four requests, no tools), approves it and activates it. Your confirmation is the review. The smoke test needs a working model profile. Installing again with content equal to the active version prints `NAME vN already installed, unchanged`; any difference makes the next version.

Install runs only from a shell. `/skills install` in the console or the TUI is refused.

### Front matter

The front matter keys read are `name`, `description`, `license`, `invocation` and `disable-model-invocation`. A file without front matter takes its name from `--name` or the file name, and its description from its first non-empty line.

```text theme={null}
---
name: deploy-release
description: Cut a release from main and verify the tag
invocation: any
---
1. Check that main is green.
2. ...
```

### What install refuses

Only the Markdown is kept. No script or other file from the source runs or is stored, and a folder that ships code says so. Install refuses:

* a symbolic link anywhere in a file or folder source (in a git source, links are checked out as plain files and never followed);
* a source of more than 256 entries;
* `file://`, `ext::`, scp-style and other URL schemes;
* an https URL with a user name or token, and an ssh URL with a password (use a git credential helper);
* a host, user name or `--ref` that begins with `-`.

git runs with your own git configuration, in a new `0700` temporary directory that is removed afterwards, cloning at depth 1 without submodules, hooks or symlinks, and is stopped after 120 seconds. The clone has no size limit, so a very large repository fills the temporary directory before it is refused. `stampede skills show` records the provenance: the source without credentials, the commit and the body's sha256.

## User-only skills

A skill's `invocation` says who may start it:

| Value | Meaning |
| - | - |
| `any` | The default. The model may find and load it, and you may start it. |
| `user` | Only you start it. The model never retrieves it, `skill_search` never returns it, and `skill_load` refuses it with "skill\_load refused: NAME is user-only". |
| `model` | Only the model uses it. `/skill` refuses it. |

Install maps the Agent Skills key `disable-model-invocation: true` to `user`.

Start a skill yourself in the console or the TUI:

```text theme={null}
/skill deploy-release cut 1.4.0 from main
```

`/skill NAME [text]` loads the skill for the next turn and sends the text, or "Use the NAME skill." when there is none, as your message. A scheduled task whose first line is `/skill NAME` does the same when it fires. To change a skill's invocation, install it again with the new value.

## Pinned skills

A skill can be pinned into every model request of one person's runs with `auto_load` in that person's table in `~/.stampede/config.toml`:

```toml theme={null}
[persons.builder]
auto_load = ["deploy-release", "house-style"]

[persons.main]
auto_load = ["review-release-state"]
```

Pins apply to console, TUI, agent, scheduled, mailbox and gateway runs, and a run resumed after a crash keeps them. `[persons.main]` pins skills into your own runs.

* Each name is looked up in the person's `project`, `user` and `global` scopes, in that order.
* At most two skills load, and their bodies together stay within 16,384 bytes. The list order decides.
* A name that is missing, not active, user-only, or over either cap is left out whole, never cut. A name listed twice loads once.
* The console and the TUI print one line at session start for each pin left out, `pinned skill NAME not loaded: REASON (N bytes)`. `stampede doctor` warns with the person's name and the reason, and when the pins cost more than half of `turn_input_tokens`.
* Sub-agents carry no pins.

A console or TUI session resolves its pins when it starts, so an edit to `auto_load` or a newly installed skill applies to sessions and runs started after it. 16 KiB of pins costs about 4,100 tokens of every model call's input. See [Limits](https://stampede.autonomousorganizations.ai/models/limits.md).

## Listing skills

```bash theme={null}
stampede skills list
stampede skills list --scope project --state active
stampede skills candidates
stampede skills show SKILL_ID VERSION
```

`skills list` prints one line per skill version:

```text theme={null}
SKILL_ID VERSION STATE scope=SCOPE name=NAME revision=N catalog_revision=N invocation=INVOCATION
```

`--scope` takes `project`, `user` or `global`; `--state` takes `candidate`, `approved`, `canary`, `active`, `superseded`, `rejected`, `deprecated` or `rolled_back`, and may be repeated. `--limit N` and `--after CURSOR` page through long lists. `skills show` prints the full version, body included, after a warning.

## Removing a skill

Stored versions are kept for history, so a skill is taken out of use by deprecating its active version:

```bash theme={null}
printf '%s\n' 'Replaced by deploy-release-v2.' | \
  stampede skills deprecate SKILL_ID VERSION --rationale-stdin --confirm-deprecate
```

A deprecated version leaves the catalog, so runs started afterwards no longer see it. A stable version cannot be deprecated while a canary of the same skill is active. To go back to an earlier version instead, use `stampede skills rollback SKILL_ID CURRENT_VERSION TARGET_VERSION --rationale-stdin --confirm-rollback`. The other lifecycle commands (`propose`, `test`, `approve`, `activate`) are in the [CLI reference](https://stampede.autonomousorganizations.ai/reference/cli.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.