Skills

A skill is a named block of instructions the model can invoke when a task needs it. The model invokes a skill by name through the skill tool, and Polytoken returns the skill’s body as guidance for the work at hand. See Where Instructions Live to weigh a skill against a facet or an AGENTS.md file.

A skill uses the Agent Skills format that other tools share, so a skill you already have works as written. Polytoken reads the same files and adds an optional polytoken frontmatter key for its own controls.

In a skill’s metadata frontmatter, Polytoken accepts unquoted YAML scalar values and stores each value in its string form; it rejects sequences, mappings, tagged values, and entries that carry no value. An explicit empty string is valid.

Where skills live

A skill is a directory containing a SKILL.md file: triage/SKILL.md defines a skill named triage. The directory, rather than a single file, leaves room for companion files, such as a script or a reference document, alongside the SKILL.md. A skill takes its name from its directory, so keep the name usable as a reference: Polytoken ignores skill directories whose names start with a dot, and the polytoken: name prefix is reserved for skills Polytoken itself ships.

Skills go in .polytoken/skills/ in your project, or in $XDG_CONFIG_HOME/polytoken/skills/ (default: ~/.config/polytoken/skills/) for ones you want everywhere.

Polytoken also discovers skills from .agents/skills/ in your project. This is the convention shared by other AI agent tools, so skills you already have for those tools work without copying. When a skill with the same name exists in both .agents/skills/ and .polytoken/skills/, the .polytoken/skills/ version wins.

The same .agents/skills/ convention works globally: Polytoken searches ~/.agents/skills/ and $XDG_CONFIG_HOME/polytoken/skills/ before project definitions. Polytoken then searches each daemon.discovery.extra_skills_dirs entry in config order, followed by each --skills-dir directory supplied when you create a session, and finally project .agents/skills/ and .polytoken/skills/. A later directory replaces a skill with the same name, so project skills take precedence over session extras, session extras take precedence over config extras, and config extras take precedence over global and shipped skills. Polytoken skips missing directories. exec --skills-dir adds skills for that invocation only.

The daemon.follow_symlinks_for_configs setting is on by default and controls whether Polytoken follows symlinks while loading definitions. With the setting off, Polytoken skips a symlinked skill directory or file and warns about each skip.

The daemon.discovery.extra_skills_dirs setting is available in your global configuration file, not in the interactive configurator and not in a project .polytoken/ config. Each entry must be an absolute path or a path that begins with ~.

When the daemon starts with HERDR_ENV=1, Polytoken adds the shipped herdr skill to the session skill library. The skill guides the model through inspecting panes and coordinating with other agents. A project skill at .polytoken/skills/herdr/SKILL.md replaces the shipped instructions for that project, just like other project skills replace shipped skills. See TUI Orchestrators for pane status, session restore, and orchestrator detection.

Writing a skill

A skill needs a description in its frontmatter. The model reads the description to decide when the skill applies, so write it for that purpose. A description may span several lines, and Polytoken normalizes the text to one line for the model. The body below the frontmatter holds the instructions themselves, and a skill with frontmatter and no body is still valid.

---
description: Steps for cutting a release, including the version bump and changelog.
---
To cut a release:

1. Bump the version in `Cargo.toml`.
2. Update the changelog with the changes since the last tag.
3. Open a release PR and wait for review.

Polytoken uses the body as written. To render it as a template first, as described in Templating, add a polytoken frontmatter key set to true:

---
description: Steps for cutting a release.
polytoken: true
---

The polytoken key is what turns templating on: with the key set, Polytoken renders the skill body as a template, and without the key, Polytoken returns the body verbatim. Polytoken does not expose the transclude function in a skill body. With templating on, a body that calls transclude fails to render.

Polytoken controls

Set the polytoken key to true when templating is all you want. To configure tags or model invocation as well, give it an object instead; the object form enables templating just as true does.

polytoken:
  tags: [release, ops]
  disable_model_invocation: false

Older skill files may set polytoken.jinja. Polytoken accepts the key so those files keep working, and it ignores the value: the presence of the polytoken key itself turns templating on. A skill that sets polytoken.jinja: false still renders its body as a template.

polytoken.tags groups skills. A facet or subagent that lists tag!release in its polytoken.skills_allow allows every skill tagged release; the same tag!<name> references work in polytoken.skills_deny, and tag!ALL stands for every skill the model can invoke. See Facets for how skill access works.

When polytoken.disable_model_invocation is true, Polytoken hides the skill from the model: Polytoken omits the skill from the model’s skill list, and the skill tool refuses it. You invoke it yourself by referencing @skill:<name> in a prompt; @s:<name> is a shorter spelling of the same reference. Use this for a skill you want to invoke deliberately rather than let the model call on its own.

Chained skill references

A skill body may include @skill:<name> to reference another skill. Polytoken resolves chained references transitively and renders the complete chain as one instruction set. Each skill renders once, so cycles do not repeat content. The active facet, or the subagent definition for a subagent run, applies its skill policy to every referenced skill. When any skill in the chain is denied, hidden with polytoken.disable_model_invocation: true, or unresolvable, the whole invocation fails. Polytoken bounds the total rendered size of a chain: when the complete rendered output, including the wrapper Polytoken places around each skill, exceeds the bound, Polytoken rejects the chain and reports the measured size instead of truncating an instruction.

Polytoken records the name of every skill in the chain. After a later compaction removes the skill instructions from the conversation, that record lets Polytoken remind the model which skills the session already used, and the model can call the skill tool again to reload the instructions it still needs.

Frontmatter keys

Key	Type	Default	Meaning
description	string	required	Tells the model when the skill applies.
polytoken	true or object	absent	Turns the skill body into a template when present, as true or an object; absent leaves the body verbatim.
polytoken.tags	list	none	Tags for grouping, referenced as tag!<name> in a facet’s or subagent’s skill access. Each tag starts with a lowercase letter and continues with lowercase letters, digits, or hyphens, and a skill cannot list a tag twice.
polytoken.disable_model_invocation	boolean	false	Hides the skill from the model. You invoke it with @skill:<name>.

Polytoken also accepts the Agent Skills optional name, license, and compatibility frontmatter fields. The name field is advisory: the directory name stays the skill’s name, and Polytoken warns when the two differ. Polytoken stores license and compatibility without interpreting them. A frontmatter key Polytoken does not recognize produces a warning, and the skill still loads.

Loading changes

Polytoken loads skills at startup and when you reload its configuration with /daemon-reload; an edit to a skill takes effect only on the next reload. If one SKILL.md file is invalid, Polytoken skips that file, shows a warning card in the TUI, and keeps loading the other skills. polytoken validate skill takes a skill name or a file path and runs a strict check that fails the command on an invalid file; a name that resolves from an .agents/skills/ directory warns instead of failing. polytoken doctor fails its skills check when the skill load skipped an invalid file.