See all discovered agents (stencila agents is shorthand for stencila agents list):

This shows agents from all three sources (workspace, user, CLI-detected) with their names, descriptions, source, and configuration summary.

Filter by source:

Output as JSON or YAML:

View the full definition of an agent:

Run an agent with a prompt from the CLI:

Text arguments and file paths can be mixed — file paths are automatically detected, read, and included as content:

Write the agent's output to a file:

Preview how an agent would be configured without actually running it:

This shows the agent metadata, prompt, instructions (from the AGENT.md body), and the full session configuration — useful for debugging agent behavior.

See how an agent session would be routed (API vs CLI, which provider and model):

Example output:

Add --why for extended details including provider priority, credential sources, and alias resolution:

If an agent uses any in models or providers, the explanation also helps you see when routing fell through to the next stage. For example, an agent with models: [mistral-large-latest, any] may show that the preferred model was skipped and selection continued via model-size, providers, or the default provider.

When no agent name is specified (e.g. in the TUI), Stencila uses the "default" agent. The default is resolved in this order:

Configure the default in your project's stencila.toml:

Or in the user-level config at ~/.config/stencila/stencila.toml.

The Stencila TUI uses the default agent for its chat interface. Start the TUI with:

The agent session provides the same agentic loop as the CLI — tool calls are executed, results are displayed, and the model continues reasoning until the task is complete.

Agents automatically discover and include project documentation in their system prompt. The following files are recognized:

These files are loaded from the git root through every directory on the path to the working directory. Root-level files load first; subdirectory files are appended with higher precedence. The total budget is configurable (default 32KB) and content is truncated with a marker if exceeded.

This means existing CLAUDE.md or .codex/instructions.md files work automatically — agents read the project instructions that were written for the model's native CLI tool.

Agents can use workspace skills — reusable instruction sets stored in .stencila/skills/. Skills are discovered at session start, and their metadata (name and description) is included in the system prompt. The model can then load full skill content on demand using the use_skill tool.

Skills are also discovered from provider-specific directories (e.g. .claude/skills/ for Anthropic agents). On name conflicts, the provider-specific source wins. See Creating Skills for how to write skills and Using Skills for how agents load them at runtime.

When an agent's allowed-skills contains exactly one skill, Stencila also preloads that skill's full instructions into the initial system prompt in addition to making it available via use_skill. This avoids spending an extra model turn just to load the only permitted skill.

Disable skills for an agent by setting allowed-skills to an empty array in the agent definition:

Or restrict to specific skills:

When agents make git commits, Stencila can be attributed in the commit. Configure this globally:

Agents are always instructed not to make commits unless explicitly asked to by the user.