Skills

A skill is a named block of instructions the model can call up when a task calls for 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.

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 front-matter key for its own controls.

Where skills live

A skill is a directory containing a SKILL.md file: triage/SKILL.md defines a skill named triage. It is a directory rather than a single file so a skill can include companion files, such as a script or a reference document, alongside its SKILL.md. The directory name is the skill’s name.

Skills go in .polytoken/skills/ in your project, or in the skills/ directory of your global Polytoken config for ones you want everywhere.

Writing a skill

A skill needs a description in its front matter and a body. The description is one line; the model reads it to decide when the skill applies, so write it for that purpose. The body is the instructions themselves.

---
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 `CHANGELOG.md` 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 front-matter key set to true:

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

The polytoken key is what turns templating on: a skill with the key set is rendered as a template, and one without it is delivered verbatim. Polytoken does not expose the transclude function in a skill body.

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

polytoken.tags groups skills. A facet or subagent that lists tag!release in its polytoken.skills_allow allows every skill tagged release. See Facets for how skill access works.

When polytoken.disable_model_invocation is true, Polytoken hides the skill from the model: it is not listed among the skills the model can see, and the skill tool refuses it. You invoke it yourself by referencing @skill:<name> in a prompt. Use this for a skill you want to invoke deliberately rather than let the model call on its own.

Front-matter keys

Key	Type	Default	Meaning
description	string	required	Tells the model when the skill applies.
polytoken	true or object	absent	Present (as true or an object) renders the skill body as a template. 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.
polytoken.disable_model_invocation	boolean	false	Hides the skill from the model. You invoke it with @skill:<name>.

Loading changes

Polytoken loads skills at startup and when you reload its configuration; an edit to a skill takes effect only on the next reload.