Slash commands, skills & MCP

Extend stepper's capabilities through three mechanisms: built-in and custom slash commands that run in-process, skills that load on demand to keep context lean, and MCP servers that provide sandboxed tool access. All custom content is permission-gated with fail-closed semantics — sensitive operations require explicit allow rules.

Built-in slash commands

The following commands are handled in-process and run no agent turn:

• /help — list all available commands
• /clear — reset the conversation/session
• /model [provider/model-id] — show the active model or switch to a new one (validated before applying to every layer)
• /context — display the active model's context window
• /rename <name> — rename the current session (persisted to its session file)
• /export [path] — write the session conversation to a Markdown transcript (defaults to .stepper/exports/<id>.md)
• /rewind [code|conversation] — restore a prior snapshot; scope to the file tree or the conversation, or both with no argument

Custom slash commands

Custom commands live in .stepper/commands/<name>.md files. Each file contains YAML frontmatter (metadata) followed by a template body that supports substitutions.

File format and invocation

In the TUI, typing / opens a palette where you can select, navigate with ↑↓, complete with Tab, and run with Enter. Invoke as /name args. Built-in commands take precedence over same-named custom command files.

Substitution syntax

Command templates support the following substitutions:

• !shell — inline shell code blocks
• $1, $2, … — positional arguments from the command invocation
• {file:path} or @include path — read a file at the given path
• {env:VAR} — expand an environment variable

Permission gating (fail-closed)

• !shell blocks run only if an explicit allow rule matches (e.g., "allow": ["Bash(git diff)"])
• {file:…} and @include reads are gated by Read rules
• Environment variables matching secret patterns (*_API_KEY, *_TOKEN, AWS_*, …) are never expanded via {env:…}
• Writes under .stepper/ always require explicit approval — even in accept-edits mode — because this directory controls the agent's own security

Skills

Skills follow a Claude-Code-style progressive disclosure pattern: the system prompt only advertises a skill's name and description, and the model loads its full body on demand. This keeps the base context window lean.

File format

Skills are stored in .stepper/skills/<name>/SKILL.md with YAML frontmatter containing name and description keys, followed by the skill body.

Declaring and using skills

A layer declares which skills it may use in its frontmatter skills: list. When the model needs a skill, it calls the skill tool with {"name":"<skill>"} to load the full body. The skill tool is scoped per layer and only serves that layer's declared skills. Skills are available to fan-out workers as well.

MCP (Model Context Protocol) servers

MCP servers provide tools and resources to stepper layers. They are configured globally in setting.json under mcpServers and can run as stdio or HTTP servers.

Configuration

Define MCP servers in .stepper/setting.json:

"mcpServers": {
  "context7": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@upstash/context7-mcp", "--api-key", "{env:CONTEXT7_KEY}"],
    "alwaysLoad": true                  // visible to every layer regardless of mcp.allow
  },
  "my-http": {
    "type": "http",
    "url": "https://example/mcp",
    "headers": { "Authorization": "Bearer {env:MY_TOKEN}" }
  }
}

Tool namespacing and scoping

• Tools from MCP servers are namespaced as mcp__<server>__<tool>
• All MCP tool use is gated by permission rules
• Per-layer scoping: layers declare which MCP servers they can use via the mcp.allow list in their layer config
• alwaysLoad: true — bypasses per-layer scoping, making the server visible to every layer regardless of mcp.allow

HTTP server headers

HTTP servers support a headers object. The Authorization header is routed specially; other headers are included in requests to the server.