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 supplies path reminders in persisted history, and the model reads the named files with its file tools. 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 naming files to read	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 persists a reminder that lists their paths and asks the model to read them before working. 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. A chain fingerprint prevents an unchanged session resume from adding the same reminder again. /clear, compaction, and a changed chain allow the reminder to return.

Tool activity can discover an additional instruction file outside the current chain. Polytoken adds a path-only discovery reminder after the complete tool batch finishes. Each file gets one discovery reminder per context. A context reset can remind the model about a previously discovered file again. A linked file referenced with @path/to/file.md follows the same discovery and file-tool reading model.

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.

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 path chain reminder 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. The compaction record also keeps the project-root instruction file body and a small set of recent instruction-file bodies selected from files the session encountered. A complete current file read can let Polytoken omit that file’s body because the model can read it again. Partial, paginated, stale, or decorated reads do not qualify. Polytoken lists the remaining chain and ledger hits by path 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 appear once.

Native compaction keeps the provider’s opaque context state instead of using this local text payload. Native compaction still receives the instruction-file chain reminder after a context boundary, 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.