Skip to main content
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: Project and user skills belong to one person. To install a skill for a person other than the default, select it with --person:

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.
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.

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: Install maps the Agent Skills key disable-model-invocation: true to user. Start a skill yourself in the console or the TUI:
/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:
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.

Listing skills

skills list prints one line per skill version:
--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:
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.