Template Reference

The bodies of the files you author for Polytoken (facets, subagents, and skills) are templates. The frontmatter schema for each file type is at the bottom of the 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_id	string	The provider the model runs through, for example anthropic or openai.
max_tool_batch_size	number	How many counted tool calls the model may issue in a turn.
supports_vision	boolean	Whether the model accepts images.
can_read_images	boolean	Whether image reading is turned on for this model.

Environment and session

Variable	Type	Holds
facet_name	string	The active facet’s name. Absent in a subagent template.
subagent_name	string	The subagent’s name. Present only in a subagent template.
project_path	string	The project’s root directory.
cwd	string	The current working directory.
session_id	string	The current session’s identifier.
current_date	string	Today’s date.
is_non_interactive	boolean	Whether the current run has no human in the loop.
prompt	string	The prompt that started this turn. Absent in an AGENTS.md template.

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 the model reaches through tool search.
tool_library	list	Each tool, with its name, description, and an example.
available_mcp_servers	list	The names of the connected MCP servers.
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, no goal lifecycle is active and goal-related instructions are omitted 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.

The per-row notes above mark which variables a given template omits.

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. 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. Polytoken does not merge 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 contains text, Polytoken uses that text instead of the shipped handoff-plan format. Polytoken does not merge the value with the shipped format, so write the complete plan-format instructions in the value.

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	The named tool’s library entry, or an empty object if the tool is unavailable.
has_mcp(name)	boolean	Whether an MCP server with that name is connected.
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.

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. File paths are confined to the calling file’s directory subtree: ../ escapes are rejected, mirroring the @file resolution rules. Using a file path inside a shipped polytoken:// resource is an error, because shipped resources have no filesystem location.

Frontmatter schemas

The frontmatter of each authored file type has its own set of legal keys. The tables below are generated from the same schemas that parse your files.

Facet frontmatter

JSON Schema: JSON | YAML

Name	Type	Description
name	string	Display name of the facet.
polytoken.model	string	Model this facet uses, overriding the session default.
polytoken.autonomous_hint	string	Hint text Polytoken shows when suggesting this facet for autonomous use.
polytoken.auto_facet_hint	string	Backwards-compatible alias of autonomous_hint.
polytoken.compaction_hint	string	Guidance Polytoken uses when summarizing the conversation during compaction. When set, this text helps the summarization preserve the context most relevant to this facet’s purpose, so the compacted summary retains what matters for the 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	Hint text Polytoken shows when suggesting this subagent.
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.
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.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.