Where Instructions Live

Polytoken places instructions in the system prompt or in the conversation history. A facet supplies the system prompt while the facet remains active. An AGENTS.md file delivers its full contents into persisted history as a system reminder, so the model receives the instructions directly. A skill supplies conversation guidance when the model invokes the skill. Polytoken also carries the active plan 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: Polytoken inlines the raw text before any rendering, and template markers inside the included file pass through unchanged. 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 — the model never has to fetch what the harness could deliver. Polytoken does not add AGENTS.md bodies or paths to the provider system prompt; delivery is history, not 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 it — the edit was made with Polytoken’s own file tools, so the model already knows the new content.

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. Each file gets one delivery per context. A context reset can re-deliver a previously discovered file. A linked file referenced with @path/to/file.md is delivered the same way. A single file larger than 64 KiB 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.

Switching facets changes the facet body and leaves the instruction reminders in history. Polytoken uses a plain file as written. With a polytoken: true frontmatter key, Polytoken renders the file when it prepares retained context for local text compaction. 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.

The conversation: active plan updates

Polytoken adds the complete active plan to the conversation after a successful write_plan call. Polytoken adds a compact replacement instruction after a successful edit_plan call. 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. After a conversation rewind to a plan-bearing context-clear boundary, Polytoken restores a full plan carrier 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.

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.

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. A subagent fencepost carries that inventory 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 and the two 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 body is always re-delivered: a complete read never removes it. Partial, paginated, stale, or decorated reads do not qualify. The compaction record itself stays body-free, and any remaining chain and ledger hits travel as a path list so the model can read them when their rules matter. The list contains files the session hit, not untouched sibling directories, and repeated identical bodies are delivered once.

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 every provider system prompt keeps the same AGENTS.md purity rule.

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. The setting changes display only; it does not change which reminders Polytoken persists or sends to the model.

When changes load

Polytoken discovers facets, skills, and project instruction files at startup and when you reload its configuration. An edit takes effect on the next reload. The next provider request receives the updated instruction-file path reminder.