Where Instructions Live

Polytoken places instructions in the system prompt or in the conversation history. The active facet supplies the system prompt. An AGENTS.md file reaches the model through persisted history: Polytoken delivers the file’s full contents as a system reminder, so the model receives the instructions directly. A skill contributes guidance to the conversation when the model invokes it. The active plan also travels in history, so plan changes do not change the system prompt unless a facet template renders the plan explicitly.

Surface	Where the instructions land	When they take effect
Facet	The system prompt	While the facet is active
AGENTS.md	Persisted history reminders carrying the file contents	Before provider requests and after relevant context changes
Skill	The conversation, as a tool result	On invocation
Active plan	The conversation, as tail guidance after a plan write or edit	After each successful plan change

The system prompt: write a facet

A facet is a Markdown file whose body becomes the system prompt while the facet is active. Its frontmatter declares the tools, the model, and skill access. Facets covers the full key list and the shipped plan, execute, and orchestrate facets.

You can compose the body from other files instead of writing it whole. transclude renders another file as a template with the facet’s context and splices the result in; a shared fragment can branch on the active model or test whether a tool is available. Transclude paths are relative to the facet file and confined to its directory tree. Keep shared fragments in that tree for any facet to reference:

---
name: scribe
---
{{ transclude("polytoken://system_prompts/facet.md") }}

{{ transclude("shared/house-style.md") }}

Your job is to help the user with their documents.

The first transclude brings in the shipped base prompt, which carries the tool-use guidance the model depends on; skip it only if you intend to write that guidance yourself. The second references shared/house-style.md, a file any number of facets can share.

@file works at load time instead: before any rendering, Polytoken reads the referenced file and embeds its literal text in a labeled envelope that names the source file. Polytoken bounds and escapes the embedded text, so template markers inside the included file arrive as literal markers rather than executable template code. A reference Polytoken cannot read stays in the body as written. Templating covers both mechanisms.

Project instructions: write an AGENTS.md

An AGENTS.md file says what the work is: how to build the project, which conventions to follow, and what to avoid. Polytoken discovers the applicable files and injects their full contents into conversation history through system reminders, so the model never has to fetch what Polytoken could deliver. AGENTS.md is the preferred name; Polytoken also recognizes CLAUDE.md and GEMINI.md, case-insensitively and in that order of preference, and each directory contributes at most one file. Polytoken does not add AGENTS.md bodies or paths to the provider system prompt.

The ordered reminder chain starts with the global config directory, continues through filesystem ancestors and the project root, and ends with the current working-directory stack. Polytoken orders the chain from least specific to most specific, and one chain reminder carries every file’s body in that order. A chain fingerprint over the resolved file paths prevents an unchanged session resume from re-delivering the chain. /clear, compaction, and a changed chain (a file joining or leaving it) allow the reminder to return. Editing a file’s contents mid-session does not re-deliver the file: Polytoken identifies the chain by file paths rather than by contents, so a content edit leaves the fingerprint unchanged.

Tool activity can discover an additional instruction file outside the current chain. Polytoken adds a discovery reminder carrying the file’s full contents after the complete tool batch finishes. When a read tool in that batch already returned the file, the read result itself delivered the contents, so Polytoken skips the reminder and counts the file as delivered. Each file gets one delivery per context. A context reset can re-deliver a previously discovered file. Polytoken delivers a linked file referenced with @path/to/file.md the same way. An oversized file degrades to a path reminder so one pathological file cannot flood every request.

Put an instruction file at the project root for project-wide guidance. A file at $XDG_CONFIG_HOME/polytoken/ (default: ~/.config/polytoken/) applies in every project alongside the project’s own file. Files above the project root can provide guidance shared across nested workspaces.

Instruction reminders stay in history when you switch facets; only the facet body changes. Polytoken uses a plain file as written. With a polytoken: true frontmatter key, or a polytoken: mapping, Polytoken renders the file as a template whenever it loads the body: for a chain or discovery reminder, for retained context after compaction, and at startup. When the frontmatter is invalid or the render fails, Polytoken loads the file as raw text instead. The rendered body does not enter the provider system prompt. Project Context shows the discovery and templating behavior.

The conversation: write a skill

A skill is a body of instructions with a name and a one-line description. The model reads the descriptions and calls the skill tool when a task matches one. Polytoken puts the body into the conversation as guidance. Only the description is present until that call, so a large collection of skills costs little context. You can also invoke a skill yourself by typing @skill:<name> in a prompt. After context compaction, Polytoken keeps a list of previously loaded skill names in the conversation. When a skill’s instructions matter again, the model can call the skill tool with that name to load them.

Skills go in .polytoken/skills/ in a project, or globally in $XDG_CONFIG_HOME/polytoken/skills/. Skills covers the format, the polytoken controls, and chained @skill: references.

The conversation: active plan updates

After a successful write_plan call, Polytoken adds the complete active plan to the conversation. A successful edit_plan call adds a compact replacement instruction. The latest complete plan supersedes earlier plan content, and the replacement instruction applies to that latest text. Polytoken re-injects the complete plan after context compaction and restores the plan when you resume a session whose visible history lacks the current plan. When you rewind the conversation to a context-clear boundary that carried a plan, Polytoken restores the complete plan in the retained conversation.

By default, the active plan does not become a section of the system prompt. A custom facet template can deliberately opt in by rendering the active plan body through template variables. Facets remain the surface for instructions that must shape the system prompt itself. AGENTS.md files use history reminders and file reads instead.

Subagent definitions

A subagent definition frames a delegated run. Polytoken gives every subagent its shipped base prompt and appends your body after that. The subagent receives its own AGENTS.md chain reminder, with file bodies, in history. The subagent also keeps an isolated inventory of instruction-file paths discovered during its run. When the subagent run is retained, that inventory survives as paths without AGENTS.md bodies, and a forked subagent carries the inventory into its new run. The body can transclude the same fragments a facet body can. Subagents explains the subagent-only keys.

Project instructions after compaction

Local text compaction retains a bounded recent portion of the conversation verbatim, outstanding todos, and a summary of the earlier history. The summary covers only content before the retained literal portion. After the boundary, Polytoken re-delivers instruction content through history reminders: the full project-instruction chain, plus the bodies of the root instruction file (the file at the bottom of the working-directory stack) and a bounded selection of the most recently used instruction files the session encountered. A complete current file read can let Polytoken omit a non-root body because the model can read the file again. The root file keeps its body whenever Polytoken can read it: a complete read never removes it. Partial, paginated, stale, or decorated reads do not qualify. The compaction record itself stays body-free, and the remaining chain files and previously used instruction files travel as a path list so the model can read them when their rules matter. The list contains files the session actually used, not untouched sibling directories. Within that body selection, a file whose contents duplicate an already delivered body stays in the path list rather than arriving as a second copy.

Native compaction keeps the provider’s opaque context state instead of using this local text payload. After a native boundary, Polytoken re-delivers the instruction-file chain reminder with bodies plus the same bounded re-injection of recent instruction files, and no provider system prompt ever contains AGENTS.md bodies or paths.

Reminder cards in the interface

Polytoken stores these reminders for the model in session history. The TUI renders them as generic system-reminder cards only when tui.show_system_reminders is true. The setting defaults to false, so the cards stay hidden during ordinary use. It affects display only: Polytoken persists and sends the same reminders whether the setting is on or off.

When changes load

Polytoken discovers facets, skills, and project instruction files at startup and when you reload its configuration. An edit to a facet or skill definition takes effect on the next reload. Instruction files follow the delivery rules on this page. Polytoken checks chain membership when a turn starts: when a file has joined or left the chain, Polytoken delivers a fresh chain reminder before the next provider request. A file that joins or leaves the chain during a turn can wait until the next turn for its reminder. A content-only edit produces no new reminder, because Polytoken tracks the chain by file identity, not by contents. Polytoken reads a fragment referenced with a filesystem transclude path when it renders the prompt, so an edit to the fragment takes effect without a reload.