Create a new agent with the CLI:

This creates .stencila/agents/my-agent/AGENT.md in your workspace with a template you can edit. To create a user-level agent (shared across all workspaces), add --user:

An agent is a directory containing an AGENT.md file. The file has two parts:

Frontmatter property names can be written in camelCase, snake_case, or kebab-case. We recommend kebab-case for readability.

Here is a minimal example:

And a fully configured example:

Agent names must be lowercase kebab-case:

By convention, names follow a thing-role pattern describing the agent's domain and function:

The agent's directory name must match the name field in the frontmatter. Validation will flag mismatches.

Agent definitions live in an agents/ directory under .stencila/ (workspace) or ~/.config/stencila/ (user). Each agent gets its own subdirectory:

The models, providers, and model-size fields control which LLM the agent uses. All are optional:

Both models and providers also support the special value any as a fallback marker:

This lets you express preferences without making routing fail if those exact models or providers are unavailable. For example, models: [mistral-large-latest, any] means “try this model first, but if it is not available with the current credentials, continue with model-size, providers, or the default routing behavior”. Likewise, providers: [anthropic, any] means “prefer Anthropic, but fall back to any other configured provider if needed”.

The singular model and provider keys still work for backward compatibility:

Use model-size when you want to express a broad tradeoff such as “use a small, fast, cheap model” without hard-coding a specific model ID. Stencila treats model size as a cross-provider classification, grouping provider models into broad tiers such as small, medium, and large.

These tiers are a Stencila abstraction, not a provider-standard guarantee. A small model from one provider is not expected to be exactly equivalent to a small model from another provider; the classification is intended to normalize rough cost, latency, and capability tradeoffs across providers.

If you combine model-size with providers, the provider list constrains which providers Stencila can choose from, and model-size selects the preferred tier within those providers.

any is most useful in combination with these fields. For example, this configuration prefers a specific model, then any small model, then any configured provider:

For example:

Supported providers: anthropic, openai, gemini (or google), mistral, deepseek.

For CLI-backed sessions, set the provider to the CLI variant: claude-cli, codex-cli, or gemini-cli.

When a manager agent decides which agent to delegate to, it uses the agent's description, keywords, when-to-use, and when-not-to-use fields to make its choice. Adding these fields improves delegation accuracy.

The keywords field helps managers find and rank agents. Include terms that reflect the agent's domain, capabilities, and likely user intents:

The when-to-use and when-not-to-use fields provide explicit selection signals that help managers choose between agents with overlapping descriptions:

Each entry should be a short, specific sentence describing a scenario. Avoid vague signals like "when appropriate" — be concrete about the situations that match or don't match.

By default, agents have access to all tools registered for their provider. Use allowed-tools to restrict an agent to specific tools:

This is useful for agents that should only read (not write) files, or agents that should not have shell access.

If you want an agent to focus on one workflow only, set allowed-skills to a single skill name:

When an agent has exactly one allowed skill, Stencila automatically 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 to load the only permitted skill and makes single-skill agents more reliable.

If you list multiple skills, only their metadata is included initially and the model can load the full content of a skill on demand with use_skill.

The trust-level field controls how strictly the agent's tool calls are guarded:

Control how much the model reasons before responding with the reasoning-effort field:

Valid values: low, medium, high. When not set, the provider's default is used. Higher reasoning effort uses more tokens but can improve quality on complex tasks.

reasoning-effort and model-size control different things:

In other words, model-size is about model capability tier and cost/latency tradeoffs, while reasoning-effort is about how hard the selected model should think.

Control how long an agent can run:

Agents can use tools from MCP (Model Context Protocol) servers. Two modes are available:

Codemode (default, token-efficient): A single mcp_codemode tool lets the model write JavaScript to orchestrate MCP calls in a sandboxed environment.

Direct registration: Each MCP server tool is registered individually. Simpler but uses more tokens.

Restrict which MCP servers an agent can access:

Control which domains the agent can access with web_fetch:

Wildcard subdomains (*.example.com) are supported. When both lists are set, the allowlist takes precedence.

Validate an agent definition before using it:

Validation checks for errors (the agent cannot be used):

Validation also checks for warnings (advisory, the agent can still be used):

An agent does not need a Markdown body. A frontmatter-only AGENT.md is valid and simply configures which model, provider, and settings to use without adding custom system instructions:

This is useful for creating model/provider shortcuts or for agents where the project docs (AGENTS.md, CLAUDE.md, etc.) already provide sufficient instructions.