stella skill
Run a skill by its slug as a scoped one-shot — the skill's own invoke directives decide the context, tool grant, model, and effort it runs under.
Run a skill as a scoped one-shot (stella skill run <slug>). The skill's own
frontmatter declares how it runs — this is the skill-function invocation
surface: there is no invoke_skill tool (the 12-tool cap
retired it), so no model call can invoke a skill. A skill function runs when
you ask — this verb, or an in-session /slug expansion — and when recall
auto-selects it for a turn, where it expands the same way: its allowed-tools
grant narrows that turn and its effort is honored. A grant can only narrow
the tool surface you configured, never widen it, which is what makes the
auto path safe without anyone approving it.
For what skills are and how they are mined, selected, and versioned, see Memory. This page is the command reference.
Synopsis
stella skill run <slug> [args...]
stella skill run generate-quarter-seed -- --quarter 2025-Q3What it does
Skills load from .stella/skills/ and ~/.stella/skills/ — the same
directories recall selects from and the SKILLS tab manages. stella skill run
resolves the slug, substitutes the trailing arguments for $ARGUMENTS in the
skill body, and launches one scoped run through the ordinary one-shot door.
How the run is scoped comes from the skill's own frontmatter, never from a flag — a tool parameter may scope an operation, never select one:
| Directive | Effect |
|---|---|
context: fork | Run in a fresh context. At this door every run is already fresh, so the mode is reported rather than branched on; in a session, a fork-mode skill runs scoped in place. |
allowed-tools: bash, read_file | A tool grant, enforced at execution time as the intersection with operator policy — it can only narrow the surface, never re-enable a tool an operator or org scope denied. A call outside the grant is refused, naming the skill. |
model: <provider/slug> | The model the skill asks to run under, resolved exactly as --model is. An explicit --model flag still wins. |
effort: low|medium|high|xhigh|max | Reasoning-effort override for the run. |
A skill with none of these runs unscoped — plain injected context on the
session's full surface, exactly as skills have always behaved. Unusable
directive values (an unknown context: or effort:) degrade to the default
with a printed diagnostic; they never refuse the run.
Scopes are decided when a turn opens, and only then. A turn mounts the
grants of every skill it opened with, and holds them until it ends. Recall
runs again mid-turn as the work drifts, and a directive-carrying skill that
surfaces at one of those boundaries is injected as context alone: it does not
narrow the turn already running, and its effort does not apply to it. The
next turn that opens with the skill selected mounts it normally. A grant that
appeared mid-loop would change the tool surface underneath calls already in
flight, which is the one thing a narrowing must never do — and an explicit
/slug obeys the same boundary.
Arguments
Everything after the slug replaces $ARGUMENTS in the skill body. A body
with no placeholder gets the arguments appended under an ARGUMENTS:
trailer, so what you passed is never silently dropped. Use -- before
arguments that begin with a dash.
Flags
| Flag | Effect |
|---|---|
--output-format <text|json|stream-json> | The one-shot door's own output promise, same as stella run. |
Exit codes
Same as stella run: 0 on a completed run, non-zero
on an aborted one or on a refused plan — an unknown slug fails before any
provider call, naming the skills that are loaded.