Template Reference

The bodies of the files you author for Polytoken (facets, subagents, and skills) are templates. A skill body renders as a template only when the skill opts in through polytoken frontmatter; without that key, Polytoken includes the body verbatim. The legal frontmatter keys for each file type are in the tables at the end of this page.

Templates catch typos at render time: referencing a variable that does not exist raises an error rather than rendering blank, so a broken prompt never reaches the model. Guard optional values with the functions below or with a conditional.

Variables

Model

Variable	Type	Holds
model_name	string	The active model’s name.
model_variant	string	The model family, for example claude, openai, or gemini.
model_provider	string	The configured provider the model runs through, for example anthropic or zai. Empty when no model is active.
model_id	string	The upstream model identifier the provider sees, for example claude-opus-4-5 or gpt-5.6. This is the model’s provider-side name, not the provider itself.
max_tool_batch_size	number	How many counted tool calls the model may issue in one assistant message.
supports_vision	boolean	Whether the model accepts images.
can_read_images	boolean	Whether Polytoken returns images from file reads to this model. True only when the model accepts images and the provider accepts image results.

Environment and session

Variable	Type	Holds
facet_name	string or null	The active facet’s name. In a subagent template, the subagent definition’s name. Null in a skill body rendered inside a subagent prompt.
subagent_name	string or null	The subagent’s name. Set in a subagent definition body and in a skill body rendered inside a subagent prompt. Null elsewhere.
project_path	string	The project’s root directory.
cwd	string	The project’s root directory in facet, AGENTS.md, and skill templates. In a subagent template, the subagent’s working directory.
session_id	string or null	The current session’s identifier. Null outside a main-session facet template.
current_date	string or null	Today’s date in YYYY-MM-DD form. Null outside a main-session facet template.
is_non_interactive	boolean	Whether the session that renders the template has no human in the loop. Main-session facet templates and skill bodies carry the session’s value; a skill body referenced from a subagent prompt inherits that parent session’s value. Subagent definition bodies and AGENTS.md templates render false.
spice_level	number	The configured daemon.spice_level: 0, 1, or 2. The default is 1.
prompt	string or null	In a subagent definition body, the subagent’s task prompt, rendered as a
template before the body renders. In a main-session facet template, the prompt that started this turn. Null in an AGENTS.md template and in a skill body.
subagent_batch	object or null	For a subagent launch, the one-based clone ordinal and shared count; a single launch carries ordinal 1 and count 1. Null outside a subagent launch.
model_group	object or null	For a group-backed subagent launch, the group name, one-based launch candidate ordinal, and candidate count. Null for direct model selections and outside a subagent launch.

What is available

Variable	Type	Holds
available_tools	list	The names of every tool the model can use this turn.
available_undeferred_tools	list	The tools whose full definitions Polytoken includes in the prompt this turn.
available_deferred_tools	list	The tools available through tool search.
tool_library	list	Each tool, with its name, description, and an example when one exists. Deferred tools carry no example.
available_mcp_servers	list	The names of the MCP servers in your configuration, whether or not Polytoken has connected to them.
available_subagents	list	Each subagent, with its name and description.
available_skills	list	Each skill, with its name and description.

Project and session

Variable	Type	Holds
project_vars	object	Project-local variables from .polytoken/project_vars.yaml.
auto_drain_notifications	boolean	Whether Polytoken delivers finished background work as soon as it is ready.
plan_integration_enabled	boolean	Whether plan handoff activates a saved-session goal. When false, a handed-off plan activates no goal, and Polytoken omits goal-related instructions from facet prompts.
source_control	string	The project’s source control system: git, jj, sl, or none. Detected from the project root. Does not change when the working directory moves or for subagents.
harness_type	string	The kind of client driving the session, as free text: tui for the terminal interface, outpost for sessions launched by Outpost, and exec for exec mode. Empty for sessions recorded before Polytoken tracked it. An attaching client can update the value.
orchestrators	list	The terminal orchestrator environments the client detected, sorted, for example tmux, zellij, or herdr; a client can supply other labels. Empty when the session runs in a plain terminal. An attaching client can update the value.

Every variable above exists in every template. A context without a value carries null or an empty list instead of omitting the key. Printing a null value emits the literal text none, so guard optional values with a conditional. session_id, current_date, and the turn prompt appear only in a main-session facet template. In a skill body, every availability list except available_skills is empty, so has_tool() and has_mcp() return false there. In an AGENTS.md template, available_deferred_tools is empty too.

Subagent task prompts

Polytoken renders every task prompt passed to a subagent before it renders the subagent definition body. The body receives the rendered task as prompt. A counted batch renders each task and body once per clone. Use a MiniJinja raw block when task data must contain literal template delimiters:

{% raw %}Keep {{ literal_syntax }} unchanged.{% endraw %}

Launch metadata is immutable. subagent_batch identifies the clone in the batch, while model_group identifies the candidate selected at launch. Provider failover and reload can change the current route without changing those recorded launch values or the rendered text.

Project Variables

Put project-specific template data in .polytoken/project_vars.yaml. You can omit the file. When Polytoken cannot use the file because the file is invalid or fails a safety check, Polytoken logs a warning and starts project_vars as an empty object. A symlinked project_vars.yaml fails the safety check when daemon.follow_symlinks_for_configs is off. When the file is absent, project_vars starts as an empty object without a warning. Write a YAML mapping at the top level.

team:
  name: Core Platform
  escalation: "#polytoken-core"
features:
  reviewer_prompt: true

Templates can read nested values with dot or bracket syntax:

Team: {{ project_vars.team.name }}
Escalation: {{ project_vars["team"]["escalation"] }}

When a template renders an object or list directly, Polytoken emits JSON. Prefer reading the scalar value you need.

If a project_vars path is missing, Polytoken logs a warning and renders an empty value instead of failing the template. This lenient missing-key behavior is specific to project_vars; other missing template variables still fail under strict rendering. Polytoken caps missing-path warnings per render and logs a suppression warning after the cap. Guard optional extension points with a conditional:

{% if project_vars.features.reviewer_prompt %}
Use the project reviewer prompt.
{% endif %}

Polytoken reads project_vars.yaml as raw project data, not as config: it never merges the file with global config, and environment variable syntax such as ${TOKEN} stays literal. YAML scalar coercion still applies, so quote values such as "yes" or "on" when you intend strings. Treat project_vars.yaml as trusted prompt input, like AGENTS.md or a skill body. Do not put secrets in project_vars.yaml; templates can render these values into model prompts.

Shipped plan facet override

The shipped plan facet reads project_vars.plan_facet.plan_spec_override when Polytoken renders the facet prompt. When the value is truthy, Polytoken uses it instead of the shipped handoff-plan format: true, a nonzero number, a nonempty string, or a nonempty list or mapping all count, and lists and mappings render as JSON. Polytoken does not merge the value with the shipped format, so write the complete plan-format instructions in the value as a nonempty string.

plan_facet:
  plan_spec_override: |
    ## Plan artifact specification

    Write a handoff plan with these sections:
    - Goal
    - Implementation steps
    - Acceptance criteria
    - Validation

The override changes only the plan format. The shipped plan facet still keeps its read-only planning behavior and its handoff workflow. To replace the whole facet, write .polytoken/facets/plan.md instead.

The override is literal text. Polytoken does not render the value as another template pass, so the model sees MiniJinja syntax inside the value as written. Use a YAML block scalar for multi-line instructions.

Functions

These functions are available in every template:

Function	Returns	Effect
has_tool(name)	boolean	Whether a tool with that name is available this turn.
get_tool(name)	object or null	The named tool’s library entry, or null when no library entry exists for the name.
has_mcp(name)	boolean	Whether an MCP server with that name appears in your configuration.
is_model_variant(variant)	boolean	Whether the active model belongs to that family.
has_skill(name)	boolean	Whether a skill with that name is available.
at_least_spice_level(level)	boolean	Whether the configured daemon.spice_level is level or higher.
is_web_search_available()	boolean	Whether a web search provider is configured for the session (configuration presence, not runtime health).
is_decision_agent_available()	boolean	Whether a decision backend is configured for the session (configuration presence, not runtime health).
using_orchestrator(name)	boolean	Whether name appears in the session’s orchestrators list. false when the session runs in a plain terminal.

The two availability functions answer truthfully wherever system prompts, subagent definitions, and skill bodies render; in AGENTS.md renders they always report false, so do not gate AGENTS.md content on them.

One function is available in facet and subagent templates when Polytoken renders system-prompt text:

Function	Returns	Effect
transclude(uri)	string	Includes a prompt fragment. The uri can be a polytoken:// shipped-resource address or a project file path. File paths resolve relative to the directory of the file that contains the transclude() call, and the included file renders as a template with the current context. Polytoken strips valid YAML frontmatter from an included file and renders only the body; a leading --- block that does not parse as YAML is content and stays. Polytoken confines file paths to the calling file’s directory subtree and rejects ../ escapes, mirroring the @file resolution rules. Using a file path inside a shipped polytoken:// resource is an error, because shipped resources have no filesystem location. An include fails the render when it forms a cycle, nests too deeply, grows past Polytoken’s size ceiling, or names a directory.

Frontmatter schemas

The frontmatter of each authored file type has its own set of legal keys. The tables below list them.

Facet frontmatter

JSON Schema: JSON | YAML

Name	Type	Description
name	string	Display name of the facet.
description	string	Optional short description shown in the daemon catalog.
polytoken.model	string	Model this facet uses, overriding the session default.
polytoken.autonomous_hint	string	Guidance for the autonomous permission classifier: in Autonomous mode, Polytoken adds this text to the classifier’s context for each tool call made in this facet, steering the allow, ask, and deny decision.
polytoken.auto_facet_hint	string	Backwards-compatible alias of autonomous_hint.
polytoken.compaction_hint	string	Guidance Polytoken appends to the compaction summary prompt when this facet is active, naming the context the summary should preserve for this facet’s work.
polytoken.color	string	Accent color for the facet, used in the sidebar and indicators.
polytoken.color_light	string	Accent color for the facet on light backgrounds.
polytoken.color_dark	string	Accent color for the facet on dark backgrounds.
polytoken.fallback_models	string list	Models Polytoken tries, in order, if the primary model is unavailable.
polytoken.tools	string list	Tools this facet exposes, as tool names or tag! groups (for example tag!ALL).
polytoken.tools_deny	string list	Tools to exclude after tools expands. Applied last.
polytoken.undeferred_tools	string list	Tools to always send in full, even under native-deferred tool loading.
polytoken.facet_transitions	map	Rules for switching to other facets from this one, keyed by target facet name.
polytoken.skills_allow	string list	Skills this facet can invoke, as skill names or tag! groups.
polytoken.skills_deny	string list	Skills to exclude from skills_allow.

Subagent frontmatter

JSON Schema: JSON | YAML

Name	Type	Description
name	string	Display name of the subagent.
description	string	Short summary of what the subagent does.
polytoken.model	string	Model this subagent uses, overriding the session default.
polytoken.autonomous_hint	string	Guidance for the autonomous permission classifier: in Autonomous mode, Polytoken adds this text to the classifier’s context for each tool call made by this subagent, steering the allow, ask, and deny decision.
polytoken.auto_facet_hint	string	Backwards-compatible alias of autonomous_hint.
polytoken.fallback_models	string list	Models Polytoken tries, in order, if the primary model is unavailable.
polytoken.tools	string list	Tools this subagent can use, as tool names or tag! groups.
polytoken.tools_deny	string list	Tools to exclude after tools expands.
polytoken.undeferred_tools	string list	Tools to always send in full, even under native-deferred tool loading.
polytoken.allow_subagent_spawn	boolean	Whether this subagent may spawn its own subagents.
polytoken.exit_tool_schema	JSON Schema object	Custom schema for the subagent’s exit tool, replacing the default. Declaring this key also makes Polytoken log a warning when the subagent finishes without calling its exit tool, and warn at load when a status/kind/outcome enum carries values the exit check does not recognize; unrecognized-status payloads are retried and then salvaged to the parent. See the Subagents page in the manual.
polytoken.skills_allow	string list	Skills this subagent can invoke, as skill names or tag! groups.
polytoken.skills_deny	string list	Skills to exclude from skills_allow.
polytoken.inherit_tools	boolean	Whether this subagent inherits the caller’s tools instead of using tools.

Skill frontmatter

JSON Schema: JSON | YAML

Name	Type	Description
name	string	Display name of the skill. Must match the skill’s directory name.
description	string	Short summary of what the skill does. Required.
license	string	License identifier for the skill.
compatibility	string	Compatibility information for the skill.
metadata	map	Free-form metadata as key-value pairs.
polytoken.jinja	boolean	Accepted for compatibility with older skill files. The presence of the polytoken key itself turns template rendering on; this value does not change that.
polytoken.disable_model_invocation	boolean	When true, the model cannot invoke this skill on its own; only explicit references load it.
polytoken.tags	string list	Tags that group this skill for tag! references.

AGENTS.md frontmatter

JSON Schema: JSON | YAML

Name	Type	Description
polytoken	true	Set to true to let Polytoken render this file as a template. Omit it to include the file verbatim.